Add a test suite and run it in CI

80 tests across 8 files, using `bun test`. This is the step 6 item I kept
flagging: everything verified during the refactor was throwaway scripts, so
none of it protected the next change.

  tests/ids.test.ts         codec round-trips (separators, percent signs,
                            non-ascii, empty values), the 100-character cap,
                            snowflake and oneOf validation, and the two
                            decode failures that mean "stale id"
  tests/dispatch.test.ts    command, autocomplete and component routing;
                            guildOnly and ownerOnly gating; duplicate
                            registration; a throwing handler being reported
  tests/session.test.ts     the session state machine and the ownership guard
  tests/paginator.test.ts   navigation, clamping at both ends, empty lists,
                            and the disable-on-end pass
  tests/messages.test.ts    notice flags and structure, modlog entries in both
                            avatar shapes, tag container and modal rendering
  tests/loader.test.ts      the real command and event directories load; a
                            file may export several listeners; a malformed
                            module throws naming the file
  tests/commands.test.ts    a snapshot of every deployed command payload
  tests/regressions.test.ts one test per bug fixed during the refactor

The payload snapshot is the one I most wanted. Each refactor step was checked
by dumping every command's deployed JSON before and after and diffing it by
hand; tests/fixtures/command-payloads.json makes CI do that. Confirmed it
works by changing one character of a command description and watching it
fail. When a change is intended,
`bun run tests/fixtures/regenerate-payloads.ts` rewrites the fixture and the
diff becomes the review.

The regression file names the failure each test guards:

- the /g regex that made /cleanname server skip members, asserted stable
  across repeated calls
- the config ids, asserted well-formed and distinct
- notices being plain objects that need no cast, and interpolation happening
  in the template rather than in markup, which is what produced "$updated"

Two helpers keep the tests free of gateway or network setup:
tests/helpers/interactions.ts stubs the type guards and reply methods the
dispatcher actually calls, and tests/helpers/session.ts stands in for the
message collector. Both confine their casts to one file. The session harness
waits for runSession to attach its collector before emitting, since a press
issued immediately would otherwise land before the listener exists — that
cost three failing tests before I spotted it.

silenceConsole() marks the tests that deliberately provoke a log so a real
failure still stands out in the output.

CI now runs test, typecheck and lint. Verified all three from an empty
node_modules on the pinned Bun.

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

Author: claude

.github/workflows/ci.yml

@@ -7,7 +7,7 @@ on:
 
 jobs:
   check:
-    name: Typecheck and lint
+    name: Test, typecheck and lint
     runs-on: ubuntu-latest
 
     steps:
@@ -23,6 +23,9 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
+      - name: Test
+        run: bun test
+
       - name: Typecheck
         run: bun run typecheck
 

bun.lock

@@ -5,7 +5,7 @@
   "main": "src/index.ts",
   "type": "module",
   "scripts": {
-    "test": "echo \"No test suite yet\" && exit 0",
+    "test": "bun test",
     "start": "bun run --bun src/index.ts",
     "deploy": "bun run --bun scripts/deploy-commands.ts",
     "clear": "bun run --bun scripts/deploy-commands.ts --clear",
@@ -16,6 +16,7 @@
   "author": "Zerebos",
   "license": "MIT",
   "devDependencies": {
+    "@types/bun": "^1.4.0",
     "@types/string-similarity": "^4.0.2",
     "@zerebos/eslint-config": "^1.0.3",
     "@zerebos/eslint-config-typescript": "^1.1.1",

package.json

@@ -0,0 +1,68 @@
+import path from "node:path";
+import {describe, expect, test} from "bun:test";
+import {loadCommands} from "../src/framework";
+import expected from "./fixtures/command-payloads.json";
+
+
+/**
+ * A snapshot of exactly what gets deployed to Discord.
+ *
+ * Refactors are supposed to leave this untouched; when one legitimately
+ * changes a command, the diff here is the review. Regenerate with:
+ *
+ *     bun run tests/fixtures/regenerate-payloads.ts
+ */
+
+const sortKeys = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(sortKeys);
+    if (value && typeof value === "object") {
+        const record = value as Record<string, unknown>;
+        return Object.fromEntries(Object.keys(record).sort().map(key => [key, sortKeys(record[key])]));
+    }
+    return value;
+};
+
+async function currentPayloads(): Promise<Record<string, unknown>> {
+    const payloads: Record<string, unknown> = {};
+    for (const command of await loadCommands(path.join(import.meta.dir, "..", "src", "commands"))) {
+        const data: unknown = JSON.parse(JSON.stringify(command.data));
+        payloads[command.name] = sortKeys({data, ownerOnly: command.ownerOnly});
+    }
+    return payloads;
+}
+
+
+describe("deployed command payloads", () => {
+    test("match the committed snapshot", async () => {
+        expect(await currentPayloads()).toEqual(expected as Record<string, unknown>);
+    });
+
+    test("the snapshot covers every command that loads", async () => {
+        expect(Object.keys(await currentPayloads()).sort()).toEqual(Object.keys(expected).sort());
+    });
+});
+
+
+describe("payload invariants", () => {
+    test("owner-only commands are deployed to the guild, not globally", async () => {
+        const commands = await loadCommands(path.join(import.meta.dir, "..", "src", "commands"));
+        expect(commands.filter(command => command.ownerOnly).map(command => command.name)).toEqual(["botadmin"]);
+    });
+
+    test("no command still uses the deprecated dm_permission field", async () => {
+        for (const command of await loadCommands(path.join(import.meta.dir, "..", "src", "commands"))) {
+            expect(command.data).not.toHaveProperty("dm_permission");
+        }
+    });
+
+    test("subcommand options come last, as the API requires", async () => {
+        for (const command of await loadCommands(path.join(import.meta.dir, "..", "src", "commands"))) {
+            for (const option of command.data.options ?? []) {
+                const nested = (option as {options?: Array<{required?: boolean}>}).options ?? [];
+                const firstOptional = nested.findIndex(child => child.required !== true);
+                if (firstOptional === -1) continue;
+                expect(nested.slice(firstOptional).every(child => child.required !== true)).toBe(true);
+            }
+        }
+    });
+});

tests/commands.test.ts

@@ -0,0 +1,196 @@
+import {beforeEach, describe, expect, test} from "bun:test";
+import {Dispatcher} from "../src/framework/dispatch";
+import {defineCommand, defineComponent} from "../src/framework/registry";
+import {Num, oneOf} from "../src/framework/ids";
+import {sessionId} from "../src/framework/session";
+import {lastReply, silenceConsole, stubInteraction} from "./helpers/interactions";
+
+
+const calls: string[] = [];
+
+const picker = defineComponent({
+    id: "demo.pick",
+    kind: "button",
+    guildOnly: true,
+    params: {mode: oneOf("user", "admin"), page: Num},
+    run: (_interaction, {mode, page}) => {calls.push(`pick:${mode}:${page}`); return Promise.resolve();}
+});
+
+const anywhere = defineComponent({
+    id: "demo.any",
+    kind: "button",
+    params: {},
+    run: () => {calls.push("any"); return Promise.resolve();}
+});
+
+const guildCommand = defineCommand({
+    guildOnly: true,
+    data: {name: "demo", description: "d"},
+    execute: () => {calls.push("demo"); return Promise.resolve();},
+    autocomplete: () => {calls.push("demo:auto"); return Promise.resolve();}
+});
+
+const ownerCommand = defineCommand({
+    ownerOnly: true,
+    data: {name: "secret", description: "d"},
+    execute: () => {calls.push("secret"); return Promise.resolve();}
+});
+
+
+function build() {
+    const dispatcher = new Dispatcher({ownerId: "owner-1"});
+    dispatcher.addCommand(guildCommand);
+    dispatcher.addCommand(ownerCommand);
+    dispatcher.addComponent(picker);
+    dispatcher.addComponent(anywhere);
+    return dispatcher;
+}
+
+beforeEach(() => {calls.length = 0;});
+
+
+describe("command routing", () => {
+    test("runs a registered command", async () => {
+        await build().dispatch(stubInteraction({kind: "chat", commandName: "demo"}).interaction);
+        expect(calls).toEqual(["demo"]);
+    });
+
+    test("guildOnly is enforced before the handler runs", async () => {
+        const stub = stubInteraction({kind: "chat", commandName: "demo", cached: false});
+        await build().dispatch(stub.interaction);
+        expect(calls).toEqual([]);
+        expect(lastReply(stub)).toContain("can't use that command here");
+    });
+
+    test("ownerOnly is enforced before the handler runs", async () => {
+        const stub = stubInteraction({kind: "chat", commandName: "secret", userId: "someone-else"});
+        await build().dispatch(stub.interaction);
+        expect(calls).toEqual([]);
+
+        const owner = stubInteraction({kind: "chat", commandName: "secret", userId: "owner-1"});
+        await build().dispatch(owner.interaction);
+        expect(calls).toEqual(["secret"]);
+    });
+
+    test("an unregistered command says so rather than failing silently", async () => {
+        const restore = silenceConsole();
+        const stub = stubInteraction({kind: "chat", commandName: "ghost"});
+        await build().dispatch(stub.interaction);
+        restore();
+        expect(lastReply(stub)).toContain("isn't registered");
+    });
+
+    test("onCommandRun fires for stats, once per command", async () => {
+        const seen: string[] = [];
+        const dispatcher = new Dispatcher({ownerId: "owner-1", onCommandRun: i => {seen.push(i.commandName); return Promise.resolve();}});
+        dispatcher.addCommand(guildCommand);
+        await dispatcher.dispatch(stubInteraction({kind: "chat", commandName: "demo"}).interaction);
+        expect(seen).toEqual(["demo"]);
+    });
+});
+
+
+describe("autocomplete routing", () => {
+    test("reaches the command's autocomplete handler", async () => {
+        await build().dispatch(stubInteraction({kind: "autocomplete", commandName: "demo"}).interaction);
+        expect(calls).toEqual(["demo:auto"]);
+    });
+
+    test("responds empty rather than throwing when there is no handler", async () => {
+        const stub = stubInteraction({kind: "autocomplete", commandName: "secret"});
+        await build().dispatch(stub.interaction);
+        expect(stub.autocompleteResponses).toEqual([[]]);
+    });
+});
+
+
+describe("component routing", () => {
+    test("decodes params and passes them typed", async () => {
+        await build().dispatch(stubInteraction({kind: "button", customId: picker.customId({mode: "admin", page: 7})}).interaction);
+        expect(calls).toEqual(["pick:admin:7"]);
+    });
+
+    test("guildOnly components are gated too", async () => {
+        const stub = stubInteraction({kind: "button", customId: picker.customId({mode: "user", page: 1}), cached: false});
+        await build().dispatch(stub.interaction);
+        expect(calls).toEqual([]);
+        expect(lastReply(stub)).toContain("can't use that");
+    });
+
+    test("a component registered for one kind refuses another", async () => {
+        const restore = silenceConsole();
+        await build().dispatch(stubInteraction({kind: "stringSelect", customId: anywhere.customId({})}).interaction);
+        restore();
+        expect(calls).toEqual([]);
+    });
+
+    test("a stale id from before a deploy explains itself", async () => {
+        const restore = silenceConsole();
+        const stub = stubInteraction({kind: "button", customId: "demo.pick:admin"});
+        await build().dispatch(stub.interaction);
+        restore();
+        expect(calls).toEqual([]);
+        expect(lastReply(stub)).toContain("out of date");
+    });
+
+    test("a malformed param value explains itself the same way", async () => {
+        const restore = silenceConsole();
+        const stub = stubInteraction({kind: "button", customId: "demo.pick:sudo:1"});
+        await build().dispatch(stub.interaction);
+        restore();
+        expect(lastReply(stub)).toContain("out of date");
+    });
+
+    // This silence is the contract that lets sessions and registered
+    // components share one custom-id space.
+    test("session-owned ids are left to their own collector", async () => {
+        const stub = stubInteraction({kind: "button", customId: sessionId("next")});
+        await build().dispatch(stub.interaction);
+        expect(calls).toEqual([]);
+        expect(stub.replies).toEqual([]);
+    });
+
+    test("an unknown namespace is ignored, not treated as an error", async () => {
+        const stub = stubInteraction({kind: "button", customId: "nobody.knows:1"});
+        await build().dispatch(stub.interaction);
+        expect(stub.replies).toEqual([]);
+    });
+
+    // The pre-framework router matched on customId.split("-")[0].
+    test("hyphenated ids no longer route anywhere", async () => {
+        const stub = stubInteraction({kind: "roleSelect", customId: "cleanname-whatever"});
+        await build().dispatch(stub.interaction);
+        expect(calls).toEqual([]);
+        expect(stub.replies).toEqual([]);
+    });
+});
+
+
+describe("registration and failure", () => {
+    test("duplicate command names throw at startup", () => {
+        const dispatcher = build();
+        expect(() => dispatcher.addCommand(guildCommand)).toThrow(/duplicate command/);
+    });
+
+    test("duplicate component namespaces throw at startup", () => {
+        const dispatcher = build();
+        expect(() => dispatcher.addComponent(picker)).toThrow(/duplicate component/);
+    });
+
+    test("a throwing handler is reported to the user, not swallowed", async () => {
+        const restore = silenceConsole();
+        const dispatcher = new Dispatcher({ownerId: "owner-1"});
+        dispatcher.addCommand(defineCommand({
+            data: {name: "boom", description: "d"},
+            execute: () => {throw new Error("kaboom");}
+        }));
+        const stub = stubInteraction({kind: "chat", commandName: "boom"});
+        await dispatcher.dispatch(stub.interaction);
+        restore();
+        expect(lastReply(stub)).toContain("Something went wrong");
+    });
+
+    test("counts report what is registered", () => {
+        expect(build().counts).toEqual({commands: 2, components: 2});
+    });
+});

tests/dispatch.test.ts

@@ -0,0 +1,2 @@
+/** A module that exports nothing the loader can use. */
+export const somethingElse = 42;