@quantumclaw/quantumclaw 2026.3.22

package/docs/plugins/sdk-setup.md

@@ -0,0 +1,331 @@
+---
+title: "Plugin SDK Setup"
+sidebarTitle: "Setup and Config"
+summary: "Setup wizards, setup-entry.ts, config schemas, and package.json metadata"
+read_when:
+  - You are adding a setup wizard to a plugin
+  - You need to understand setup-entry.ts vs index.ts
+  - You are defining plugin config schemas or package.json quantumclaw metadata
+---
+
+# Plugin Setup and Config
+
+Reference for plugin packaging (`package.json` metadata), manifests
+(`quantumclaw.plugin.json`), setup entries, and config schemas.
+
+<Tip>
+  **Looking for a walkthrough?** The how-to guides cover packaging in context:
+  [Channel Plugins](/plugins/sdk-channel-plugins#step-1-package-and-manifest) and
+  [Provider Plugins](/plugins/sdk-provider-plugins#step-1-package-and-manifest).
+</Tip>
+
+## Package metadata
+
+Your `package.json` needs an `quantumclaw` field that tells the plugin system what
+your plugin provides:
+
+**Channel plugin:**
+
+```json
+{
+  "name": "@myorg/quantumclaw-my-channel",
+  "version": "1.0.0",
+  "type": "module",
+  "quantumclaw": {
+    "extensions": ["./index.ts"],
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "my-channel",
+      "label": "My Channel",
+      "blurb": "Short description of the channel."
+    }
+  }
+}
+```
+
+**Provider plugin:**
+
+```json
+{
+  "name": "@myorg/quantumclaw-my-provider",
+  "version": "1.0.0",
+  "type": "module",
+  "quantumclaw": {
+    "extensions": ["./index.ts"],
+    "providers": ["my-provider"]
+  }
+}
+```
+
+### `quantumclaw` fields
+
+| Field        | Type       | Description                                                                                |
+| ------------ | ---------- | ------------------------------------------------------------------------------------------ |
+| `extensions` | `string[]` | Entry point files (relative to package root)                                               |
+| `setupEntry` | `string`   | Lightweight setup-only entry (optional)                                                    |
+| `channel`    | `object`   | Channel metadata: `id`, `label`, `blurb`, `selectionLabel`, `docsPath`, `order`, `aliases` |
+| `providers`  | `string[]` | Provider ids registered by this plugin                                                     |
+| `install`    | `object`   | Install hints: `npmSpec`, `localPath`, `defaultChoice`                                     |
+| `startup`    | `object`   | Startup behavior flags                                                                     |
+
+### Deferred full load
+
+Channel plugins can opt into deferred loading with:
+
+```json
+{
+  "quantumclaw": {
+    "extensions": ["./index.ts"],
+    "setupEntry": "./setup-entry.ts",
+    "startup": {
+      "deferConfiguredChannelFullLoadUntilAfterListen": true
+    }
+  }
+}
+```
+
+When enabled, QuantumClaw loads only `setupEntry` during the pre-listen startup
+phase, even for already-configured channels. The full entry loads after the
+gateway starts listening.
+
+<Warning>
+  Only enable deferred loading when your `setupEntry` registers everything the
+  gateway needs before it starts listening (channel registration, HTTP routes,
+  gateway methods). If the full entry owns required startup capabilities, keep
+  the default behavior.
+</Warning>
+
+## Plugin manifest
+
+Every native plugin must ship an `quantumclaw.plugin.json` in the package root.
+QuantumClaw uses this to validate config without executing plugin code.
+
+```json
+{
+  "id": "my-plugin",
+  "name": "My Plugin",
+  "description": "Adds My Plugin capabilities to QuantumClaw",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "webhookSecret": {
+        "type": "string",
+        "description": "Webhook verification secret"
+      }
+    }
+  }
+}
+```
+
+For channel plugins, add `kind` and `channels`:
+
+```json
+{
+  "id": "my-channel",
+  "kind": "channel",
+  "channels": ["my-channel"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}
+```
+
+Even plugins with no config must ship a schema. An empty schema is valid:
+
+```json
+{
+  "id": "my-plugin",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false
+  }
+}
+```
+
+See [Plugin Manifest](/plugins/manifest) for the full schema reference.
+
+## Setup entry
+
+The `setup-entry.ts` file is a lightweight alternative to `index.ts` that
+QuantumClaw loads when it only needs setup surfaces (onboarding, config repair,
+disabled channel inspection).
+
+```typescript
+// setup-entry.ts
+import { defineSetupPluginEntry } from "quantumclaw/plugin-sdk/core";
+import { myChannelPlugin } from "./src/channel.js";
+
+export default defineSetupPluginEntry(myChannelPlugin);
+```
+
+This avoids loading heavy runtime code (crypto libraries, CLI registrations,
+background services) during setup flows.
+
+**When QuantumClaw uses `setupEntry` instead of the full entry:**
+
+- The channel is disabled but needs setup/onboarding surfaces
+- The channel is enabled but unconfigured
+- Deferred loading is enabled (`deferConfiguredChannelFullLoadUntilAfterListen`)
+
+**What `setupEntry` must register:**
+
+- The channel plugin object (via `defineSetupPluginEntry`)
+- Any HTTP routes required before gateway listen
+- Any gateway methods needed during startup
+
+**What `setupEntry` should NOT include:**
+
+- CLI registrations
+- Background services
+- Heavy runtime imports (crypto, SDKs)
+- Gateway methods only needed after startup
+
+## Config schema
+
+Plugin config is validated against the JSON Schema in your manifest. Users
+configure plugins via:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "my-plugin": {
+        config: {
+          webhookSecret: "abc123",
+        },
+      },
+    },
+  },
+}
+```
+
+Your plugin receives this config as `api.pluginConfig` during registration.
+
+For channel-specific config, use the channel config section instead:
+
+```json5
+{
+  channels: {
+    "my-channel": {
+      token: "bot-token",
+      allowFrom: ["user1", "user2"],
+    },
+  },
+}
+```
+
+### Building channel config schemas
+
+Use `buildChannelConfigSchema` from `quantumclaw/plugin-sdk/core` to convert a
+Zod schema into the `ChannelConfigSchema` wrapper that QuantumClaw validates:
+
+```typescript
+import { z } from "zod";
+import { buildChannelConfigSchema } from "quantumclaw/plugin-sdk/core";
+
+const accountSchema = z.object({
+  token: z.string().optional(),
+  allowFrom: z.array(z.string()).optional(),
+  accounts: z.object({}).catchall(z.any()).optional(),
+  defaultAccount: z.string().optional(),
+});
+
+const configSchema = buildChannelConfigSchema(accountSchema);
+```
+
+## Setup wizards
+
+Channel plugins can provide interactive setup wizards for `quantumclaw onboard`.
+The wizard is a `ChannelSetupWizard` object on the `ChannelPlugin`:
+
+```typescript
+import type { ChannelSetupWizard } from "quantumclaw/plugin-sdk/channel-setup";
+
+const setupWizard: ChannelSetupWizard = {
+  channel: "my-channel",
+  status: {
+    configuredLabel: "Connected",
+    unconfiguredLabel: "Not configured",
+    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),
+  },
+  credentials: [
+    {
+      inputKey: "token",
+      providerHint: "my-channel",
+      credentialLabel: "Bot token",
+      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",
+      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",
+      keepPrompt: "Keep current token?",
+      inputPrompt: "Enter your bot token:",
+      inspect: ({ cfg, accountId }) => {
+        const token = (cfg.channels as any)?.["my-channel"]?.token;
+        return {
+          accountConfigured: Boolean(token),
+          hasConfiguredValue: Boolean(token),
+        };
+      },
+    },
+  ],
+};
+```
+
+The `ChannelSetupWizard` type supports `credentials`, `textInputs`,
+`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize`, and more.
+See bundled plugins (e.g. `extensions/discord/src/channel.setup.ts`) for
+full examples.
+
+For optional setup surfaces that should only appear in certain contexts, use
+`createOptionalChannelSetupSurface` from `quantumclaw/plugin-sdk/channel-setup`:
+
+```typescript
+import { createOptionalChannelSetupSurface } from "quantumclaw/plugin-sdk/channel-setup";
+
+const setupSurface = createOptionalChannelSetupSurface({
+  channel: "my-channel",
+  label: "My Channel",
+  npmSpec: "@myorg/quantumclaw-my-channel",
+  docsPath: "/channels/my-channel",
+});
+// Returns { setupAdapter, setupWizard }
+```
+
+## Publishing and installing
+
+**External plugins:** publish to [ClawHub](/tools/clawhub) or npm, then install:
+
+```bash
+quantumclaw plugins install @myorg/quantumclaw-my-plugin
+```
+
+QuantumClaw tries ClawHub first and falls back to npm automatically. You can also
+force a specific source:
+
+```bash
+quantumclaw plugins install clawhub:@myorg/quantumclaw-my-plugin   # ClawHub only
+quantumclaw plugins install npm:@myorg/quantumclaw-my-plugin       # npm only
+```
+
+**In-repo plugins:** place under `extensions/` and they are automatically
+discovered during build.
+
+**Users can browse and install:**
+
+```bash
+quantumclaw plugins search <query>
+quantumclaw plugins install <package-name>
+```
+
+<Info>
+  For npm-sourced installs, `quantumclaw plugins install` runs
+  `npm install --ignore-scripts` (no lifecycle scripts). Keep plugin dependency
+  trees pure JS/TS and avoid packages that require `postinstall` builds.
+</Info>
+
+## Related
+
+- [SDK Entry Points](/plugins/sdk-entrypoints) -- `definePluginEntry` and `defineChannelPluginEntry`
+- [Plugin Manifest](/plugins/manifest) -- full manifest schema reference
+- [Building Plugins](/plugins/building-plugins) -- step-by-step getting started guide

package/docs/plugins/sdk-testing.md

@@ -0,0 +1,263 @@
+---
+title: "SDK Testing"
+sidebarTitle: "Testing"
+summary: "Testing utilities and patterns for QuantumClaw plugins"
+read_when:
+  - You are writing tests for a plugin
+  - You need test utilities from the plugin SDK
+  - You want to understand contract tests for bundled plugins
+---
+
+# Plugin Testing
+
+Reference for test utilities, patterns, and lint enforcement for QuantumClaw
+plugins.
+
+<Tip>
+  **Looking for test examples?** The how-to guides include worked test examples:
+  [Channel plugin tests](/plugins/sdk-channel-plugins#step-6-test) and
+  [Provider plugin tests](/plugins/sdk-provider-plugins#step-6-test).
+</Tip>
+
+## Test utilities
+
+**Import:** `quantumclaw/plugin-sdk/testing`
+
+The testing subpath exports a narrow set of helpers for plugin authors:
+
+```typescript
+import {
+  installCommonResolveTargetErrorCases,
+  shouldAckReaction,
+  removeAckReactionAfterReply,
+} from "quantumclaw/plugin-sdk/testing";
+```
+
+### Available exports
+
+| Export                                 | Purpose                                                |
+| -------------------------------------- | ------------------------------------------------------ |
+| `installCommonResolveTargetErrorCases` | Shared test cases for target resolution error handling |
+| `shouldAckReaction`                    | Check whether a channel should add an ack reaction     |
+| `removeAckReactionAfterReply`          | Remove ack reaction after reply delivery               |
+
+### Types
+
+The testing subpath also re-exports types useful in test files:
+
+```typescript
+import type {
+  ChannelAccountSnapshot,
+  ChannelGatewayContext,
+  QuantumClawConfig,
+  PluginRuntime,
+  RuntimeEnv,
+  MockFn,
+} from "quantumclaw/plugin-sdk/testing";
+```
+
+## Testing target resolution
+
+Use `installCommonResolveTargetErrorCases` to add standard error cases for
+channel target resolution:
+
+```typescript
+import { describe } from "vitest";
+import { installCommonResolveTargetErrorCases } from "quantumclaw/plugin-sdk/testing";
+
+describe("my-channel target resolution", () => {
+  installCommonResolveTargetErrorCases({
+    resolveTarget: ({ to, mode, allowFrom }) => {
+      // Your channel's target resolution logic
+      return myChannelResolveTarget({ to, mode, allowFrom });
+    },
+    implicitAllowFrom: ["user1", "user2"],
+  });
+
+  // Add channel-specific test cases
+  it("should resolve @username targets", () => {
+    // ...
+  });
+});
+```
+
+## Testing patterns
+
+### Unit testing a channel plugin
+
+```typescript
+import { describe, it, expect, vi } from "vitest";
+
+describe("my-channel plugin", () => {
+  it("should resolve account from config", () => {
+    const cfg = {
+      channels: {
+        "my-channel": {
+          token: "test-token",
+          allowFrom: ["user1"],
+        },
+      },
+    };
+
+    const account = myPlugin.setup.resolveAccount(cfg, undefined);
+    expect(account.token).toBe("test-token");
+  });
+
+  it("should inspect account without materializing secrets", () => {
+    const cfg = {
+      channels: {
+        "my-channel": { token: "test-token" },
+      },
+    };
+
+    const inspection = myPlugin.setup.inspectAccount(cfg, undefined);
+    expect(inspection.configured).toBe(true);
+    expect(inspection.tokenStatus).toBe("available");
+    // No token value exposed
+    expect(inspection).not.toHaveProperty("token");
+  });
+});
+```
+
+### Unit testing a provider plugin
+
+```typescript
+import { describe, it, expect } from "vitest";
+
+describe("my-provider plugin", () => {
+  it("should resolve dynamic models", () => {
+    const model = myProvider.resolveDynamicModel({
+      modelId: "custom-model-v2",
+      // ... context
+    });
+
+    expect(model.id).toBe("custom-model-v2");
+    expect(model.provider).toBe("my-provider");
+    expect(model.api).toBe("openai-completions");
+  });
+
+  it("should return catalog when API key is available", async () => {
+    const result = await myProvider.catalog.run({
+      resolveProviderApiKey: () => ({ apiKey: "test-key" }),
+      // ... context
+    });
+
+    expect(result?.provider?.models).toHaveLength(2);
+  });
+});
+```
+
+### Mocking the plugin runtime
+
+For code that uses `createPluginRuntimeStore`, mock the runtime in tests:
+
+```typescript
+import { createPluginRuntimeStore } from "quantumclaw/plugin-sdk/runtime-store";
+import type { PluginRuntime } from "quantumclaw/plugin-sdk/runtime-store";
+
+const store = createPluginRuntimeStore<PluginRuntime>("test runtime not set");
+
+// In test setup
+const mockRuntime = {
+  agent: {
+    resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),
+    // ... other mocks
+  },
+  config: {
+    loadConfig: vi.fn(),
+    writeConfigFile: vi.fn(),
+  },
+  // ... other namespaces
+} as unknown as PluginRuntime;
+
+store.setRuntime(mockRuntime);
+
+// After tests
+store.clearRuntime();
+```
+
+### Testing with per-instance stubs
+
+Prefer per-instance stubs over prototype mutation:
+
+```typescript
+// Preferred: per-instance stub
+const client = new MyChannelClient();
+client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" });
+
+// Avoid: prototype mutation
+// MyChannelClient.prototype.sendMessage = vi.fn();
+```
+
+## Contract tests (in-repo plugins)
+
+Bundled plugins have contract tests that verify registration ownership:
+
+```bash
+pnpm test -- src/plugins/contracts/
+```
+
+These tests assert:
+
+- Which plugins register which providers
+- Which plugins register which speech providers
+- Registration shape correctness
+- Runtime contract compliance
+
+### Running scoped tests
+
+For a specific plugin:
+
+```bash
+pnpm test -- extensions/my-channel/
+```
+
+For contract tests only:
+
+```bash
+pnpm test -- src/plugins/contracts/shape.contract.test.ts
+pnpm test -- src/plugins/contracts/auth.contract.test.ts
+pnpm test -- src/plugins/contracts/runtime.contract.test.ts
+```
+
+## Lint enforcement (in-repo plugins)
+
+Three rules are enforced by `pnpm check` for in-repo plugins:
+
+1. **No monolithic root imports** -- `quantumclaw/plugin-sdk` root barrel is rejected
+2. **No direct `src/` imports** -- plugins cannot import `../../src/` directly
+3. **No self-imports** -- plugins cannot import their own `plugin-sdk/<name>` subpath
+
+External plugins are not subject to these lint rules, but following the same
+patterns is recommended.
+
+## Test configuration
+
+QuantumClaw uses Vitest with V8 coverage thresholds. For plugin tests:
+
+```bash
+# Run all tests
+pnpm test
+
+# Run specific plugin tests
+pnpm test -- extensions/my-channel/src/channel.test.ts
+
+# Run with a specific test name filter
+pnpm test -- extensions/my-channel/ -t "resolves account"
+
+# Run with coverage
+pnpm test:coverage
+```
+
+If local runs cause memory pressure:
+
+```bash
+QUANTUMCLAW_TEST_PROFILE=low QUANTUMCLAW_TEST_SERIAL_GATEWAY=1 pnpm test
+```
+
+## Related
+
+- [SDK Overview](/plugins/sdk-overview) -- import conventions
+- [SDK Channel Plugins](/plugins/sdk-channel-plugins) -- channel plugin interface
+- [SDK Provider Plugins](/plugins/sdk-provider-plugins) -- provider plugin hooks
+- [Building Plugins](/plugins/building-plugins) -- getting started guide