Rebuild the addon browser on runSession; no hand-rolled collectors left

paginateAddonPages was the last hand-rolled component collector: it repeated
the ownership check, the timeout and the disable-on-end pass that
framework/session.ts already does. It is now a runSession whose state is the
selected index, and its select menu carries a session-owned custom id so the
dispatcher leaves it to the collector.

Three bugs fell out of the conversion.

1. `/addons search` with no matches threw. string-similarity's findBestMatch
   rejects an empty candidate list ("Bad arguments"), so a search that matched
   nothing surfaced as the dispatcher's generic "Something went wrong" rather
   than "no results". It now answers before ranking.

2. An empty addon list built an illegal select menu. Discord requires between
   1 and 25 options; createNavigation([]) produced zero, so `/addons top` and
   friends would have been rejected at send time whenever the cache was empty
   — the same shape as the selfroles setMaxValues(0) crash. paginateAddonPages
   now answers with a notice instead, and callers pass a fitting message.

3. `/addons random` on an empty cache indexed past the end and rendered
   `undefined`. Guarded.

The selection handler also loses `addons.find(...)!`; an unrecognised value
now leaves the selection alone rather than asserting the lookup cannot fail.

Two follow-ons:

- paginateAddonPages takes a RepliableInteraction rather than a
  ChatInputCommandInteraction. It only defers and edits, so the tighter type
  was claiming more than the code uses.
- tags.ts was still calling awaitModalSubmit directly inside a try/catch that
  treated any throw as a timeout — including a database failure, which the
  user would have been told was a submission timeout. It uses the framework's
  awaitModal now, which returns null only on timeout. src/ no longer contains
  a hand-rolled collector or modal wait.

16 new tests cover the browser (rendering, selection moving the tick and the
page, an unknown value being ignored, ownership, disable-on-end, V2 flags on
every render), list separators, sorting, and the conditional support-server
button. Writing them exposed two gaps in the shared session harness — no
select-menu type guards and no collector.stop() — both now fixed, so the
harness can drive select menus and exercise runSession's error path.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015hDX4g1EjTN7424A5wnptE

Author: claude

src/commands/addons.ts

@@ -46,29 +46,40 @@ async function browse(interaction: ChatInputCommandInteraction) {
 
 async function search(interaction: ChatInputCommandInteraction) {
     const name = interaction.options.getString("name", true).toLowerCase();
-    let results: BdWebAddon[] = [];
+    const results: BdWebAddon[] = [];
     for (const addon of cache) {
         if (addon.name.toLowerCase().includes(name) || (addon.description?.toLowerCase().includes(name))) {
             results.push(addon);
         }
     }
 
-    results = Similarity.findBestMatch(name, results.map(a => a.name)).ratings
+    // findBestMatch throws on an empty candidate list, so a search that matched
+    // nothing used to surface as the dispatcher's generic error.
+    if (!results.length) {
+        return await interaction.editReply(notices.info(`No addons matched \`${name}\`.`));
+    }
+
+    const ranked = Similarity.findBestMatch(name, results.map(addon => addon.name)).ratings
         .sort((a, b) => b.rating - a.rating)
         .slice(0, 10)
-        .map(rating => results.find(a => a.name === rating.target)!)
-        .filter(a => !!a);
+        .map(rating => results.find(addon => addon.name === rating.target))
+        .filter((addon): addon is BdWebAddon => addon !== undefined);
 
-    await paginateAddonPages(interaction, results);
+    await paginateAddonPages(interaction, ranked, `No addons matched \`${name}\`.`);
 }
 
 
 async function top10(interaction: ChatInputCommandInteraction, sortBy: "likes" | "downloads" | "initial_release_date" | "latest_release_date") {
-    await paginateAddonPages(interaction, sortAddons(Array.from(cache), sortBy).slice(0, 10));
+    await paginateAddonPages(interaction, sortAddons(Array.from(cache), sortBy).slice(0, 10), "The addon store is empty right now. Please try again shortly.");
 }
 
 async function random(interaction: ChatInputCommandInteraction) {
     const addonsArray = Array.from(cache);
+    // An empty cache would otherwise index past the end and render `undefined`.
+    if (!addonsArray.length) {
+        return await interaction.editReply(notices.info("The addon store is empty right now. Please try again shortly."));
+    }
+
     const randomAddon = addonsArray[Math.floor(Math.random() * addonsArray.length)];
     return await interaction.editReply({components: [createAddonComponent(randomAddon)], flags: MessageFlags.IsComponentsV2});
 }

src/commands/tags.ts

@@ -3,7 +3,7 @@ import {
     AutocompleteInteraction, ChatInputCommandInteraction, ComponentType, InteractionContextType,
     MessageFlags, type RESTPostAPIChatInputApplicationCommandsJSONBody
 } from "discord.js";
-import {defineCommand} from "../framework";
+import {awaitModal, defineCommand} from "../framework";
 import type {AtLeast, Tag} from "../types";
 import {tagsDB} from "../db";
 import {msInMinute} from "../util/time";
@@ -108,28 +108,21 @@ async function list(interaction: ChatInputCommandInteraction<"cached">) {
 async function showTagModal(interaction: ChatInputCommandInteraction<"cached">, tag: AtLeast<Tag, "name">) {
     const isUpdating = !!tag.content;
 
-    await interaction.showModal(updateTagModal(tag));
+    // awaitModal returns null only on timeout, so a database failure below is no
+    // longer reported to the user as "submission timed out".
+    const submitted = await awaitModal(interaction, updateTagModal(tag), ["title", "content", "thumbnail"], {time: msInMinute * 5});
+    if (!submitted) return await interaction.followUp(error("Modal submission timed out!"));
 
-    try {
-        const modalInteraction = await interaction.awaitModalSubmit({time: msInMinute * 5});
-        const title = modalInteraction.fields.getTextInputValue("title");
-        const content = modalInteraction.fields.getTextInputValue("content");
-        const thumbnailUrl = modalInteraction.fields.getTextInputValue("thumbnail");
+    const guildTags = await tagsDB.get(interaction.guildId) ?? {};
+    guildTags[tag.name] = {
+        name: tag.name,
+        title: submitted.values.title || undefined,
+        content: submitted.values.content,
+        thumbnailUrl: submitted.values.thumbnail || undefined
+    };
+    await tagsDB.set(interaction.guildId, guildTags);
 
-        const guildTags = await tagsDB.get(interaction.guildId) ?? {};
-        guildTags[tag.name] = {
-            name: tag.name,
-            title: title || undefined,
-            content,
-            thumbnailUrl: thumbnailUrl || undefined,
-        };
-        await tagsDB.set(interaction.guildId, guildTags);
-
-        await modalInteraction.reply(success(`Tag \`${tag.name}\` has been ${isUpdating ? "updated" : "created"} successfully!`));
-    }
-    catch {
-        await interaction.followUp(error("Modal submission timed out!"));
-    }
+    await submitted.submission.reply(success(`Tag \`${tag.name}\` has been ${isUpdating ? "updated" : "created"} successfully!`));
 }
 
 

src/util/addons.ts

@@ -1,10 +1,11 @@
 import {
-    ButtonStyle, ChatInputCommandInteraction, ComponentType, MessageFlags, SeparatorSpacingSize,
-    StringSelectMenuInteraction,
+    ButtonStyle, ComponentType, MessageFlags, SeparatorSpacingSize,
     type ActionRowData, type ComponentInContainerData, type ContainerComponentData,
-    type MessageActionRowComponentData, type SectionComponentData, type TextDisplayComponentData
+    type MessageActionRowComponentData, type RepliableInteraction, type SectionComponentData,
+    type TextDisplayComponentData
 } from "discord.js";
-import {container, row, text} from "../framework";
+import {container, row, runSession, sessionId, text} from "../framework";
+import * as notices from "./notices";
 import type {BdWebAddon} from "../types";
 
 import Web from "../util/web";
@@ -152,10 +153,13 @@ export function createAddonList(title: string, addons: BdWebAddon[]): [TextDispl
 }
 
 
+/** The select menu action, as carried in its session-owned custom id. */
+const NAVIGATE = "addons-navigate";
+
 export function createNavigation(addons: BdWebAddon[], selectedIndex = 0, disabled = false): ActionRowData<MessageActionRowComponentData> {
     return row({
         type: ComponentType.StringSelect,
-        customId: "addons-navigation",
+        customId: sessionId(NAVIGATE),
         disabled,
         options: addons.map((addon, index) => ({
             "label": `${index + 1}. ${addon.name}`,
@@ -166,28 +170,37 @@ export function createNavigation(addons: BdWebAddon[], selectedIndex = 0, disabl
 }
 
 
-export async function paginateAddonPages(interaction: ChatInputCommandInteraction, addons: BdWebAddon[]) {
-    const navigation = createNavigation(addons);
-    const pages = addons.map(addon => createAddonComponent(addon));
+/**
+ * An addon browser: a select menu that swaps which addon is shown.
+ *
+ * Built on runSession, so the ownership check, the timeout and disabling the
+ * menu when it expires are the framework's job rather than this file's.
+ */
+export async function paginateAddonPages(interaction: RepliableInteraction, addons: BdWebAddon[], emptyMessage = "No addons matched.") {
+    // A select menu needs between 1 and 25 options; Discord rejects an empty
+    // one, so an empty result set has to be answered rather than rendered.
+    if (!addons.length) {
+        await interaction.editReply(notices.info(emptyMessage));
+        return;
+    }
 
-    const msg = await interaction.fetchReply();
-    const collector = msg.createMessageComponentCollector({time: 5 * msInMinute});
+    await runSession<number>({
+        interaction,
+        initial: 0,
+        timeout: 5 * msInMinute,
 
-    let selectedIndex = 0;
-    collector.on("collect", async (i: StringSelectMenuInteraction) => {
-        if (i.user.id !== interaction.user.id) return await i.reply({content: "You cannot interact with this menu.", flags: MessageFlags.Ephemeral});
+        render: (selectedIndex, {ended}) => ({
+            flags: MessageFlags.IsComponentsV2,
+            components: [createNavigation(addons, selectedIndex, ended), createAddonComponent(addons[selectedIndex])]
+        }),
 
-        const selectedAddonName = i.values[0];
-        const selectedAddon = addons.find(a => a.name === selectedAddonName)!;
-        selectedIndex = addons.indexOf(selectedAddon);
-        const newPage = pages[selectedIndex];
-        const newNavigation = createNavigation(addons, selectedIndex);
-        await i.update({components: [newNavigation, newPage], flags: MessageFlags.IsComponentsV2});
-    });
+        reduce(action, _selectedIndex, component) {
+            if (action !== NAVIGATE || !component.isStringSelectMenu()) return undefined;
 
-    collector.on("end", async () => {
-        await interaction.editReply({components: [createNavigation(addons, selectedIndex, true), pages[selectedIndex]], flags: MessageFlags.IsComponentsV2});
+            // An unrecognised value leaves the state alone instead of throwing;
+            // the previous version asserted the lookup could not fail.
+            const next = addons.findIndex(addon => addon.name === component.values[0]);
+            return next === -1 ? undefined : next;
+        }
     });
-
-    await interaction.editReply({components: [navigation, pages[0]], flags: MessageFlags.IsComponentsV2});
-}
+}

tests/addons.test.ts

@@ -0,0 +1,188 @@
+import {describe, expect, test} from "bun:test";
+
+import {createAddonComponent, createAddonList, createNavigation, paginateAddonPages, sortAddons} from "../src/util/addons";
+import {isSessionId} from "../src/framework";
+import type {BdWebAddon} from "../src/types";
+import {sessionHarness} from "./helpers/session";
+
+
+function addon(over: Partial<BdWebAddon> = {}): BdWebAddon {
+    return {
+        id: 7,
+        name: "CoolPlugin",
+        file_name: "c.plugin.js",
+        type: "plugin",
+        description: "Does things",
+        version: "1.2.3",
+        likes: 1234,
+        downloads: 56789,
+        tags: [],
+        thumbnail_url: "/resources/x.png",
+        latest_source_url: "u",
+        initial_release_date: new Date("2020-01-02T00:00:00Z"),
+        latest_release_date: new Date("2024-03-04T00:00:00Z"),
+        author: {
+            github_id: "1",
+            github_name: "g",
+            display_name: "d",
+            discord_name: "dn",
+            discord_avatar_hash: null,
+            discord_snowflake: "1",
+            guild: null
+        },
+        guild: null,
+        ...over
+    };
+}
+
+const IS_COMPONENTS_V2 = 1 << 15;
+
+interface Row {type: number; components: Array<{options?: Array<{label: string; value: string; default: boolean}>; disabled?: boolean}>}
+const navOf = (shown: Record<string, unknown>) => (shown.components as unknown[])[0] as Row;
+const menu = (shown: Record<string, unknown>) => navOf(shown).components[0];
+
+
+describe("navigation menu", () => {
+    const list = [addon({name: "Alpha"}), addon({name: "Beta"}), addon({name: "Gamma"})];
+
+    test("is session-owned so the dispatcher leaves it alone", () => {
+        const control = createNavigation(list).components[0] as {customId: string};
+        expect(isSessionId(control.customId)).toBe(true);
+    });
+
+    test("numbers the options and marks the selected one", () => {
+        const options = menu({components: [createNavigation(list, 1)]}).options ?? [];
+        expect(options.map(option => option.label)).toEqual(["1. Alpha", "2. Beta", "3. Gamma"]);
+        expect(options.map(option => option.default)).toEqual([false, true, false]);
+    });
+});
+
+
+describe("addon browser", () => {
+    const list = [addon({name: "Alpha"}), addon({name: "Beta"}), addon({name: "Gamma"})];
+
+    function browse(addons: BdWebAddon[]) {
+        const harness = sessionHarness();
+        const done = paginateAddonPages(harness.interaction, addons);
+        return {harness, done, latest: () => harness.shown.at(-1) ?? {}};
+    }
+
+    test("an empty list answers instead of building an illegal select menu", async () => {
+        // Discord rejects a string select with zero options.
+        const {harness, done} = browse([]);
+        await done;
+        const shown = harness.shown.at(-1) ?? {};
+        expect(Number(shown.flags) & IS_COMPONENTS_V2).toBe(IS_COMPONENTS_V2);
+        expect(JSON.stringify(shown)).toContain("No addons matched");
+    });
+
+    test("renders the first addon with its menu", async () => {
+        const {harness, done} = browse(list);
+        await harness.press("addons-navigate", {values: ["Alpha"]});
+        const options = menu(harness.shown[0]).options ?? [];
+        expect(options).toHaveLength(3);
+        expect(options[0]?.default).toBe(true);
+        await harness.end();
+        await done;
+    });
+
+    test("the menu is disabled once the session ends", async () => {
+        const {harness, done} = browse(list);
+        await harness.press("addons-navigate", {values: ["Alpha"]});
+        await harness.end();
+        await done;
+        expect(menu(harness.shown.at(-1) ?? {}).disabled).toBe(true);
+    });
+
+    test("every render carries IsComponentsV2", async () => {
+        const {harness, done} = browse(list);
+        await harness.press("addons-navigate", {values: ["Alpha"]});
+        await harness.end();
+        await done;
+        expect(harness.shown.every(shown => Number(shown.flags) === IS_COMPONENTS_V2)).toBe(true);
+    });
+
+    test("a stranger cannot drive the browser", async () => {
+        const {harness, done} = browse(list);
+        const refusals = await harness.press("addons-navigate", {userId: "someone-else", values: ["Beta"]});
+        expect(String(refusals[0]?.content)).toContain("belongs to someone else");
+        await harness.end();
+        await done;
+    });
+
+    test("selecting an addon swaps the page and moves the tick", async () => {
+        const {harness, done} = browse(list);
+        await harness.press("addons-navigate", {values: ["Gamma"]});
+
+        const options = menu(harness.shown.at(-1) ?? {}).options ?? [];
+        expect(options.map(option => option.default)).toEqual([false, false, true]);
+        expect(JSON.stringify(harness.shown.at(-1))).toContain("# Gamma v1.2.3");
+
+        await harness.end();
+        await done;
+    });
+
+    // The previous version did `addons.find(...)!` and would have thrown.
+    test("an unknown value leaves the selection alone", async () => {
+        const {harness, done} = browse(list);
+        await harness.press("addons-navigate", {values: ["NoSuchAddon"]});
+        const options = menu(harness.shown.at(-1) ?? {}).options ?? [];
+        expect(options.map(option => option.default)).toEqual([true, false, false]);
+        await harness.end();
+        await done;
+    });
+});
+
+
+describe("list rendering", () => {
+    test("separates entries but does not trail one", () => {
+        const [, page] = createAddonList("Plugins", [addon({name: "A"}), addon({name: "B"})]);
+        const types = (page.components as Array<{type: number}>).map(component => component.type);
+        expect(types).toEqual([9, 14, 9]);
+    });
+
+    test("a single entry gets no separator", () => {
+        const [, page] = createAddonList("Plugins", [addon()]);
+        expect(page.components).toHaveLength(1);
+    });
+
+    test("the heading is a separate top-level text display", () => {
+        const [heading] = createAddonList("Plugins sorted by downloads", [addon()]);
+        expect(heading.content).toBe("## Plugins sorted by downloads");
+    });
+});
+
+
+describe("sorting", () => {
+    test("orders by the numeric field, descending", () => {
+        const list = [addon({name: "a", likes: 1}), addon({name: "b", likes: 9}), addon({name: "c", likes: 5})];
+        expect(sortAddons(list, "likes").map(a => a.name)).toEqual(["b", "c", "a"]);
+    });
+
+    test("orders by date, newest first", () => {
+        const list = [
+            addon({name: "old", latest_release_date: new Date("2020-01-01T00:00:00Z")}),
+            addon({name: "new", latest_release_date: new Date("2024-01-01T00:00:00Z")})
+        ];
+        expect(sortAddons(list, "latest_release_date").map(a => a.name)).toEqual(["new", "old"]);
+    });
+});
+
+
+describe("addon page", () => {
+    test("adds a support-server button only when the author has a guild", () => {
+        const withoutGuild = createAddonComponent(addon());
+        const withGuild = createAddonComponent(addon({
+            author: {...addon().author, guild: {name: "G", snowflake: "1", invite_link: "https://discord.gg/abc"}}
+        }));
+        const labels = (page: {components: readonly unknown[]}) =>
+            JSON.stringify(page.components).match(/"label":"[^"]+"/g) ?? [];
+        expect(labels(withoutGuild)).toHaveLength(2);
+        expect(labels(withGuild)).toHaveLength(3);
+    });
+
+    test("falls back when an addon has no description", () => {
+        const page = createAddonComponent(addon({description: undefined as unknown as string}));
+        expect(JSON.stringify(page)).toContain("No description provided.");
+    });
+});