From 5f8e0f6649e455a02b947bd929e5408c714f4c59 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 00:10:41 +0000 Subject: [PATCH] docs: update AGENTS.md to reflect recent changes Notes the build-then-exec test pattern plugin-subcommands-advanced uses (tests/older-framework.test.ts) to guard its runtime namespace lookup of runPreconditions, which keeps it working on peer framework releases before 6.3.0, mirroring plugin-opentelemetry's preload-test convention. --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index b9b7816a..ee86d846 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -87,6 +87,7 @@ pnpm exec knip # unused code/dependency check (CI's - Non-trivial structural work (cross-package parity ports, manager/API redesigns, new plugin scaffolding) gets a design doc under `docs/superpowers/` before implementation: a plan at `docs/superpowers/plans/-.md` and, for anything with real design decisions, a matching spec at `docs/superpowers/specs/--design.md` (e.g. `docs/superpowers/specs/2026-10-05-message-types-parity-design.md`). PR descriptions for such changes link the spec/plan instead of re-explaining the design. Check this directory for prior art before redesigning an area that already has one. - Activation has two paths. `plugin-scheduled-tasks` and `plugin-opentelemetry` are module-only (their `./register` is a no-op); `plugin-opentelemetry` also ships a third entrypoint, `./preload` (loaded with `--import`), which starts the OpenTelemetry SDK before the bot's own imports run — `./register` cannot do this, since it only runs after the bot has already started importing. The older plugins ship `./module` (default export: `defineModule` from `@wolfstar/kit`, optional peer) and, for those with runtime hooks, `./plugin` (default export: a `definePlugin` factory); `./register` stays the legacy class + `Client.plugins.register*Hook` path for framework v3/v5/v6. Both call the same functions in `src/hooks.ts`, so change behaviour there. The `stars` CLI never imports `/register` itself; it only preloads the sources registered through `ctx.addPlugin`, so a user's own `import "/register"` (or passing the `./plugin` factory to `plugins` while also importing `/register`) still double-installs the hooks. `tests/module-entries.test.ts` checks that every `src/module.ts` (except `plugin-scheduled-tasks`, excluded on purpose) is exported, built and has kit and schema as optional peers. - `plugin-opentelemetry` has process-level tests (`tests/preload.test.ts`: worker thread, `SIGTERM`, WebSocket handshake) that spawn Node with the preload. The CI unit job runs vitest with no build, so the test builds `src/preload.ts` itself with `tsdown` into `packages/plugin-opentelemetry/node_modules/.cache/preload-test/`. The `SIGTERM` cases are skipped on Windows (a Windows process cannot handle the signal); run them in WSL or Linux. Interaction spans are made the active span with `context.attach` (`@opentelemetry/api` 1.10), because the framework's `*Run` events do not wrap the command. Hooks a plugin adds to a `GatewayClient` from `postInitialization` run inside the base `Client` constructor, before the subclass fields exist, so `GatewayClient` keeps its dispatch wrappers and destroy hooks in module-level `WeakMap`s, not private fields. `protobufjs` is denied in `allowBuilds` (its postinstall is not needed). +- The same build-then-exec pattern also guards optional use of a framework function that postdates part of a package's own peer range: `plugin-subcommands-advanced` reads `runPreconditions` from the `@wolfstar/http-framework` namespace at call time, not as a named import, because its peer range (`^3.1.0 || ^5.0.0 || ^6.0.0`) also covers framework releases before `6.3.0`, which added that function. `tests/older-framework.test.ts` mocks `runPreconditions` away with `vi.mock` for its own assertions, and separately builds `src/index.ts`/`src/register.ts` with `tsdown` into `node_modules/.cache/older-framework-test/` and execs the output in a child Node process through `tests/fixtures/load-without-run-preconditions.mjs` — a named import would fail to link there even though vitest's own transform hides the mistake. - Module config keys: every `defineModule` sets `meta.configKey`, so a project writes the options under that top-level key of `stars.config` instead of the `[specifier, options]` tuple (the tuple is merged over the key and wins). Needs `@wolfstar/kit` `^0.2.0 || ^0.3.0` as the peer range (dev range `^0.2.0`) of every package with a `src/module.ts`, and each `module.ts` augments `StarsConfig` from `@wolfstar/schema` (an optional peer and devDependency) to type the key. Keys: `plugin-api` `api`, `plugin-broker` `broker`, `plugin-cache` `cache`, `plugin-gateway` `gateway`, `plugin-i18next` `i18n`, `plugin-logger` `logger`, `plugin-opentelemetry` `opentelemetry`, `plugin-scheduled-tasks` `scheduledTasks`, `plugin-sharder` `sharder`, `plugin-subcommands-advanced` `subcommandsAdvanced`; `cache`, `gateway`, `sharder` and `subcommandsAdvanced` take no options yet and only reserve the name. A key must be unique and not a built-in key (`BUILT_IN_CONFIG_KEYS` of `@wolfstar/schema`); renaming one is a breaking change. `tests/module-config-keys.test.ts` runs every module through kit's `setupModules`. What sits under a key is written into the build, so it must be JSON. ## Notes for agents