@synoikia/create-plugin 0.1.0

package/templates/plugin/websocket-rpc/src/client.ts

@@ -0,0 +1,96 @@
+import { ErrorCodes, joinApiPath, PendingRequests, PluginError, singleFlight } from '@synoikia/plugin-sdk';
+import WebSocket from 'ws';
+
+/**
+ * JSON-RPC 2.0 over one WebSocket: connects lazily (authenticating on the upgrade), reconnects on the
+ * next call after a drop, and fails pending calls when the socket closes. Errors name the method,
+ * never its params or the credentials.
+ */
+
+export interface RpcConnection {
+  baseUrl: string;
+  path: string;
+  verifyTls: boolean;
+  headers: () => Record<string, string>;
+  timeoutMs: number;
+}
+
+interface RpcError {
+  code?: number;
+  message?: string;
+}
+
+export class RpcClient {
+  private ws?: WebSocket;
+  private readonly pending = new PendingRequests();
+  private readonly connect = singleFlight(() => this.open());
+
+  constructor(private readonly conn: RpcConnection) {
+    joinApiPath(conn.baseUrl, conn.path, { websocket: true }); // validate early
+  }
+
+  async call(method: string, params: unknown, timeoutMs = this.conn.timeoutMs): Promise<unknown> {
+    const ws = this.ws?.readyState === WebSocket.OPEN ? this.ws : await this.connect();
+    const { id, promise } = this.pending.start(method, timeoutMs);
+    ws.send(JSON.stringify({ jsonrpc: '2.0', id, method, params: params ?? {} }), (err) => {
+      if (err) this.pending.fail(id, new PluginError(ErrorCodes.UpstreamError, `${method}: could not send`));
+    });
+    return promise;
+  }
+
+  close(): void {
+    this.ws?.terminate();
+    this.ws = undefined;
+    this.pending.failAll(new PluginError(ErrorCodes.UpstreamError, 'Connection closed'));
+  }
+
+  private open(): Promise<WebSocket> {
+    const url = joinApiPath(this.conn.baseUrl, this.conn.path, { websocket: true });
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(url, {
+        headers: this.conn.headers(),
+        rejectUnauthorized: this.conn.verifyTls,
+        handshakeTimeout: this.conn.timeoutMs,
+      });
+      ws.once('open', () => {
+        this.ws = ws;
+        resolve(ws);
+      });
+      ws.once('unexpected-response', (_req, res) => {
+        const denied = res.statusCode === 401 || res.statusCode === 403;
+        reject(
+          new PluginError(
+            denied ? ErrorCodes.UpstreamDenied : ErrorCodes.UpstreamError,
+            denied ? 'The upstream denied the connection: the credentials were rejected' : `The upstream refused the connection (HTTP ${res.statusCode})`,
+          ),
+        );
+        ws.terminate();
+      });
+      ws.once('error', () =>
+        reject(new PluginError(ErrorCodes.UpstreamError, `The upstream is unreachable at ${new URL(url).host}`)),
+      );
+      ws.on('close', () => {
+        if (this.ws === ws) this.ws = undefined;
+        this.pending.failAll(new PluginError(ErrorCodes.UpstreamError, 'The upstream closed the connection'));
+      });
+      ws.on('message', (data) => {
+        let msg: { id?: unknown; result?: unknown; error?: RpcError };
+        try {
+          msg = JSON.parse(data.toString()) as typeof msg;
+        } catch {
+          return;
+        }
+        const p = this.pending.take(msg.id);
+        if (!p) return;
+        if (!msg.error) return p.resolve(msg.result ?? null);
+        const code =
+          msg.error.code === -32601
+            ? ErrorCodes.UnknownOperation
+            : msg.error.code === -32602
+              ? ErrorCodes.InvalidParams
+              : ErrorCodes.UpstreamError;
+        p.reject(new PluginError(code, `${p.label}: ${msg.error.message ?? 'error'}`));
+      });
+    });
+  }
+}

package/templates/plugin/websocket-rpc/src/plugin.ts

@@ -0,0 +1,98 @@
+import {
+  baseKey,
+  compileRules,
+  definePlugin,
+  ErrorCodes,
+  isPlainObject,
+  parsePluginSettings,
+  PluginError,
+  requireString,
+  staticCatalog,
+  stringOr,
+  truncate,
+} from '@synoikia/plugin-sdk';
+import type { PluginHandlers } from '@synoikia/plugin-sdk';
+import raw from '../plugin.yaml';
+import { authHeaders } from './auth.js';
+import { RpcClient } from './client.js';
+
+/**
+ * The {{name}} plugin: JSON-RPC methods declared in plugin.yaml. The sandbox calls
+ * `{{namespace}}.call(method, params)`.
+ */
+
+const SERVICE = '{{name}}';
+
+export const settings = parsePluginSettings(raw, {
+  parse(value) {
+    const p = isPlainObject(value) ? value : {};
+    if (typeof p.path !== 'string') throw new Error('plugin.yaml plugin.path must be a string');
+    return { path: p.path };
+  },
+});
+
+export function create{{Pascal}}Plugin(): PluginHandlers {
+  return definePlugin({
+    connect: (init) =>
+      new RpcClient({
+        baseUrl: requireString(init.config, 'baseUrl'),
+        path: settings.plugin.path,
+        verifyTls: init.config.verifyTls !== false,
+        headers: authHeaders(init),
+        timeoutMs: settings.defaults.timeouts.request,
+      }),
+    close: (client) => client.close(),
+
+    async version(kit) {
+      const info = await kit.client().call('system.info', {});
+      const version = isPlainObject(info) ? stringOr(info.version) : undefined;
+      if (!version) throw new PluginError(ErrorCodes.UpstreamError, `${SERVICE} reported no version`);
+      return version;
+    },
+
+    handlers(kit) {
+      const rules = compileRules(settings, {
+        // Confirmation lookups may only call declared reads.
+        lookup: (op, args, timeoutMs) => {
+          if (settings.operations.find((o) => o.key === op)?.classification !== 'read')
+            throw new PluginError(ErrorCodes.InvalidParams, `plugin.yaml lookup ${op} is not a read`);
+          return kit.client().call(op, args[0] ?? {}, timeoutMs);
+        },
+      });
+      const operations = staticCatalog(rules);
+      const known = new Set(settings.operations.map((o) => o.key));
+      return {
+        async syncCatalog() {
+          return { upstreamVersion: await kit.version(), operations };
+        },
+
+        resolveOperation({ fn, args }) {
+          if (fn !== 'call')
+            throw new PluginError(ErrorCodes.UnknownOperation, `{{namespace}}.${fn} is not a binding function`);
+          const [method, params] = args;
+          if (typeof method !== 'string' || !known.has(method))
+            throw new PluginError(ErrorCodes.UnknownOperation, `${String(method)} is not a ${SERVICE} method`);
+          if (params !== undefined && !isPlainObject(params))
+            throw new PluginError(ErrorCodes.InvalidParams, 'params must be an object');
+          // A split twin declared in plugin.yaml is locked; take it unless code here decides the call is safe.
+          const split = rules.splits(method)[0];
+          return { key: split ? `${method}#${split}` : method, params: params ?? {} };
+        },
+
+        async summarize({ key, params, targets }) {
+          const json = JSON.stringify(params ?? {});
+          const notes = rules.summaryNotes(key).map((n) => ` ${n}`).join('');
+          const text = `${SERVICE} ${key}(${json === '{}' ? '' : truncate(json, 400)})${notes}`;
+          const literal = await rules.confirmLiteral({ key, params, targets });
+          return literal ? { text, confirmLiteral: literal } : { text };
+        },
+
+        async invoke({ key, params, context }) {
+          const method = baseKey(key);
+          if (!known.has(method)) throw new PluginError(ErrorCodes.UnknownOperation, `${method} is not a ${SERVICE} method`);
+          return rules.maskResult(key, await kit.client().call(method, params, kit.timeout(context)));
+        },
+      };
+    },
+  });
+}

package/templates/plugin/websocket-rpc/test/e2e.test.ts

@@ -0,0 +1,46 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkPluginContract, startPluginHarness } from '@synoikia/core/testing';
+import type { PluginHarness } from '@synoikia/core/testing';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { CREDENTIALS } from './fake-auth.js';
+import { startFake{{Pascal}}, UPSTREAM_SECRET } from './fake-upstream.js';
+import type { Fake{{Pascal}} } from './fake-upstream.js';
+
+/**
+ * The real Synoikia core running this plugin's built bundle (a permission-confined child, as in
+ * production) against the fake {{name}}, through core's plugin harness.
+ */
+
+const PLUGIN_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+let h: PluginHarness;
+let fake: Fake{{Pascal}};
+
+beforeAll(async () => {
+  fake = await startFake{{Pascal}}();
+  h = await startPluginHarness({ pluginDir: PLUGIN_DIR, connection: { baseUrl: fake.url, ...CREDENTIALS } });
+}, 60_000);
+
+afterAll(async () => {
+  await h?.stop();
+  await fake?.close();
+});
+
+describe('{{name}} end to end (fake {{name}})', () => {
+  it('keeps the plugin contract', async () => {
+    expect(
+      await checkPluginContract(h, {
+        read: { key: 'items.list', code: `return await {{namespace}}.call('items.list');` },
+        write: { key: 'items.create', code: `return await {{namespace}}.call('items.create', { name: 'x' });` },
+        locked: {
+          key: 'items.delete',
+          code: `return await {{namespace}}.call('items.delete', { id: 1 });`,
+          confirm: 'First item',
+        },
+        secrets: { code: `return await {{namespace}}.call('settings.get');`, values: [UPSTREAM_SECRET] },
+      }),
+    ).toEqual([]);
+    expect(fake.items.has(1)).toBe(false);
+  });
+});

package/templates/plugin/websocket-rpc/test/fake-upstream.ts

@@ -0,0 +1,63 @@
+import type { AddressInfo } from 'node:net';
+import { WebSocketServer } from 'ws';
+import { authorized } from './fake-auth.js';
+
+/**
+ * A fake {{name}} speaking JSON-RPC 2.0 over WebSocket: just enough to exercise the plugin, including
+ * a response that holds a secret, so the tests prove it never reaches the sandbox.
+ */
+
+export const UPSTREAM_SECRET = 'fake-upstream-secret-123';
+
+export interface Fake{{Pascal}} {
+  url: string;
+  items: Map<number, { id: number; name: string }>;
+  close(): Promise<void>;
+}
+
+export async function startFake{{Pascal}}(): Promise<Fake{{Pascal}}> {
+  const items = new Map([[1, { id: 1, name: 'First item' }]]);
+  let next = 2;
+  const methods: Record<string, (p: Record<string, unknown>) => unknown> = {
+    'system.info': () => ({ name: 'Home {{name}}', version: '1.2.3' }),
+    'items.list': () => [...items.values()],
+    'items.get': (p) => items.get(Number(p.id)) ?? null,
+    'items.create': (p) => {
+      const item = { id: next++, name: String(p.name ?? 'Unnamed') };
+      items.set(item.id, item);
+      return item;
+    },
+    'items.delete': (p) => items.delete(Number(p.id)),
+    'settings.get': () => ({ title: 'Home', apiKey: UPSTREAM_SECRET }),
+  };
+  const wss = new WebSocketServer({
+    port: 0,
+    host: '127.0.0.1',
+    path: '/rpc',
+    verifyClient: ({ req }: { req: { headers: Record<string, string | string[] | undefined> } }) =>
+      authorized(req.headers),
+  });
+  wss.on('connection', (ws) => {
+    ws.on('message', (data) => {
+      const msg = JSON.parse(data.toString()) as { id: number; method: string; params?: Record<string, unknown> };
+      const fn = methods[msg.method];
+      ws.send(
+        JSON.stringify(
+          fn
+            ? { jsonrpc: '2.0', id: msg.id, result: fn(msg.params ?? {}) }
+            : { jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: 'Method not found' } },
+        ),
+      );
+    });
+  });
+  await new Promise<void>((resolve) => wss.once('listening', resolve));
+  return {
+    url: `http://127.0.0.1:${(wss.address() as AddressInfo).port}`,
+    items,
+    close: () =>
+      new Promise((resolve) => {
+        for (const c of wss.clients) c.terminate();
+        wss.close(() => resolve());
+      }),
+  };
+}

package/templates/plugin/websocket-rpc/test/plugin.test.ts

@@ -0,0 +1,67 @@
+import { readFileSync } from 'node:fs';
+import { checkConformance, ErrorCodes } from '@synoikia/plugin-sdk';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { create{{Pascal}}Plugin, settings } from '../src/plugin.js';
+import { CREDENTIALS } from './fake-auth.js';
+import { startFake{{Pascal}} } from './fake-upstream.js';
+import type { Fake{{Pascal}} } from './fake-upstream.js';
+
+const manifest: unknown = JSON.parse(readFileSync(new URL('../manifest.json', import.meta.url), 'utf8'));
+
+let fake: Fake{{Pascal}};
+const plugin = create{{Pascal}}Plugin();
+
+beforeAll(async () => {
+  fake = await startFake{{Pascal}}();
+});
+afterAll(async () => {
+  await plugin.shutdown?.();
+  await fake?.close();
+});
+
+const connection = () => {
+  const { username, ...secrets } = CREDENTIALS as Record<string, string>;
+  return { instanceId: '{{id}}', config: { baseUrl: fake.url, ...(username ? { username } : {}) }, secrets };
+};
+
+describe('{{name}} plugin', () => {
+  it('passes the SDK conformance checks against the fake', async () => {
+    const issues = await checkConformance({
+      manifest,
+      settings,
+      handlers: plugin,
+      init: connection(),
+      samples: [
+        { fn: 'call', args: ['items.list'], expectKey: 'items.list' },
+        { fn: 'call', args: ['items.delete', { id: 1 }], expectKey: 'items.delete' },
+      ],
+      rejects: [{ fn: 'call', args: ['items.nope'] }, { fn: 'other', args: [] }],
+    });
+    expect(issues).toEqual([]);
+  });
+
+  it('locks deletes and names the item in the confirmation', async () => {
+    await plugin.init({ ...connection(), sdkVersion: '1' });
+    const { operations } = await plugin.syncCatalog();
+    expect(operations.find((o) => o.key === 'items.delete')).toMatchObject({ locked: true });
+    expect(await plugin.summarize({ key: 'items.delete', params: { id: 1 }, targets: [] })).toEqual({
+      text: '{{name}} items.delete({"id":1})',
+      confirmLiteral: 'First item',
+    });
+  });
+
+  it('reports rejected credentials without throwing', async () => {
+    const wrong = Object.fromEntries(Object.keys(connection().secrets).map((k) => [k, 'wrong']));
+    if (!Object.keys(wrong).length) return; // nothing to reject without authentication
+    const bad = create{{Pascal}}Plugin();
+    await bad.init({ ...connection(), secrets: wrong, sdkVersion: '1' });
+    expect(await bad.testConnection()).toMatchObject({ ok: false, message: expect.stringContaining('denied') });
+    await bad.shutdown?.();
+  });
+
+  it('refuses a connection without a base URL', async () => {
+    await expect(create{{Pascal}}Plugin().init({ ...connection(), config: {}, sdkVersion: '1' })).rejects.toMatchObject({
+      code: ErrorCodes.InvalidParams,
+    });
+  });
+});

package/templates/repo/base/README.md

@@ -0,0 +1,27 @@
+# {{repoName}}
+
+Plugins for [Synoikia](https://github.com/via-justa/synoikia-core), the self-hosted MCP control plane.
+
+A plugin only describes its upstream API: the operations it has, which ones read and which ones write, which are destructive, and which fields hold secrets. Synoikia's core decides what is allowed and runs every call through its sandbox, permission gate, approvals, redaction and audit log. See the [plugin authoring guide](https://github.com/via-justa/synoikia-core/blob/main/docs/plugin-authoring.md).
+
+## Layout
+
+| Path                         | What                                                                                     |
+| ---------------------------- | ---------------------------------------------------------------------------------------- |
+| `plugins/<id>/manifest.json` | Binding, connection form, `sensitiveKeys`, network hosts                                 |
+| `plugins/<id>/plugin.yaml`   | What the plugin tells core about its operations: locks, splits, secrets, confirm literals |
+| `plugins/<id>/src/`          | Discovery, auth and anything that needs logic                                            |
+| `plugins/<id>/test/`         | A fake upstream, unit tests and e2e tests on Synoikia's harness                          |
+
+## Development
+
+Requires Node ≥ 22.12 and pnpm 10 (`corepack enable`).
+
+```sh
+pnpm install
+pnpm new          # add a plugin
+pnpm test         # check, build and test every plugin
+pnpm typecheck && pnpm lint && pnpm format:check
+```
+
+Work on one plugin with `pnpm --filter ./plugins/<id> test`.

package/templates/repo/base/_github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm format:check
+      - run: pnpm typecheck
+      # Each plugin's test checks its manifest and plugin.yaml, builds its bundle, then runs its unit tests and
+      # its e2e tests on core's harness under the permission model.
+      - run: pnpm test

package/templates/repo/base/_gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+.repo/
+.repo-current/

package/templates/repo/base/_nvmrc

@@ -0,0 +1 @@
+22

package/templates/repo/base/_prettierignore

@@ -0,0 +1,3 @@
+dist
+coverage
+pnpm-lock.yaml

package/templates/repo/base/_prettierrc

@@ -0,0 +1,5 @@
+{
+  "singleQuote": true,
+  "printWidth": 120,
+  "trailingComma": "all"
+}

package/templates/repo/base/eslint.config.js

@@ -0,0 +1,17 @@
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  { ignores: ['**/dist/**', '**/node_modules/**', '**/coverage/**', '.repo/**', '.repo-current/**'] },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.mjs'],
+    languageOptions: { globals: { console: 'readonly', process: 'readonly' } },
+  },
+  {
+    rules: {
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+    },
+  },
+);

package/templates/repo/base/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "{{repoName}}",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@10.33.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "new": "synoikia-plugin new",
+    "build": "pnpm -r --filter './plugins/*' build",
+    "check": "synoikia-plugin check",
+    "typecheck": "pnpm -r --filter './plugins/*' typecheck",
+    "test": "pnpm -r --filter './plugins/*' test",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "synoikia": {
+    "repository": "{{repository}}",
+    "name": "{{repoName}}"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@synoikia/core": "{{coreRange}}",
+    "@synoikia/create-plugin": "{{cliRange}}",
+    "@types/node": "^22.19.0",
+    "eslint": "^10.11.0",
+    "prettier": "^3.6.2",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.70.1",
+    "vitest": "^5.0.2"
+  }
+}

package/templates/repo/base/plugin-files.d.ts

@@ -0,0 +1,10 @@
+// Data files a plugin imports; `synoikia-plugin build` inlines them into the bundle.
+declare module '*.yaml' {
+  const value: unknown;
+  export default value;
+}
+
+declare module '*.md' {
+  const text: string;
+  export default text;
+}

package/templates/repo/base/pnpm-workspace.yaml

@@ -0,0 +1,11 @@
+packages:
+  - plugins/*
+
+onlyBuiltDependencies:
+  - esbuild
+  # @synoikia/core (the plugin harness) runs isolated-vm; node-gyp-build picks the shipped prebuild.
+  - isolated-vm
+
+# better-sqlite3 ships prebuilt N-API binaries for all supported platforms; skip its node-gyp fallback.
+ignoredBuiltDependencies:
+  - better-sqlite3

package/templates/repo/base/tsconfig.base.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": false,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "sourceMap": true,
+    "types": ["node"]
+  }
+}

package/templates/repo/base/vitest.shared.ts

@@ -0,0 +1,9 @@
+import { pluginFiles } from '@synoikia/create-plugin/vitest';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  // plugin.yaml and guides load as the bundle sees them.
+  plugins: [pluginFiles()],
+  // The plugin harness (@synoikia/core/testing) runs isolated-vm, which requires --no-node-snapshot on Node >= 20.
+  test: { include: ['test/**/*.test.ts'], execArgv: ['--no-node-snapshot'] },
+});

package/templates/repo/claude/CLAUDE.md

@@ -0,0 +1,38 @@
+# {{repoName}}
+
+Plugins for [Synoikia](https://github.com/via-justa/synoikia-core). Authoring guide: `https://github.com/via-justa/synoikia-core/blob/main/docs/plugin-authoring.md`.
+
+**A plugin only describes its upstream API; core decides what is allowed.** Core's sandbox, permission gate, approvals, redaction and audit apply to every plugin. A plugin supplies the catalog, the classification (read, write, locked), targets, summaries, confirmation literals and `sensitiveKeys`. It never adds its own allow/deny switch, approval prompt or secret handling.
+
+## Layout
+
+| Path                         | What                                                                                       |
+| ---------------------------- | ------------------------------------------------------------------------------------------ |
+| `plugins/<id>/manifest.json` | Validated by the SDK schema: binding, connection form, `sensitiveKeys`, network hosts      |
+| `plugins/<id>/plugin.yaml`   | Policy as data: locked operations, split twins, sensitive params/results, confirm literals |
+| `plugins/<id>/src/`          | `index.ts` calls `runPlugin()`; `plugin.ts` holds discovery and logic; `auth.ts` the auth  |
+| `plugins/<id>/test/`         | A fake upstream, unit tests, and `e2e.test.ts` on core's harness                           |
+
+Policy data (locks, splits, sensitive params and results, confirm literals, guidance) goes in `plugin.yaml`; only decisions that need logic go in `src/`. `plugin.yaml` is validated and inlined at build time, so rebuild before e2e tests.
+
+## Commands
+
+Node 22.12+, pnpm 10.
+
+```sh
+pnpm new                                   # add a plugin (see the add-plugin skill)
+pnpm lint && pnpm format:check && pnpm typecheck && pnpm test   # what CI runs
+pnpm --filter ./plugins/<id> test          # one plugin: check, build, unit + e2e
+pnpm check                                 # manifests, plugin.yaml and versions
+```
+
+## Rules that break releases or installs
+
+- **Self-contained bundle.** The plugin reads nothing outside its own package directory at runtime; `synoikia-plugin build` bundles every dependency and data file.
+- **Network hosts.** The plugin reaches only the hosts in `manifest.json` `network.hosts`.
+- **Secrets.** Every credential field is `writeOnly: true`, uses the `secret` widget and is in `sensitiveKeys`, along with every secret field the upstream returns. `synoikia-plugin check` enforces the first part; an e2e `secrets` contract check covers the second.
+- **Versions.** `version` in `manifest.json` and `package.json` must match, and a released version never changes. Bump only when asked; the `release-plugin` skill covers it.
+
+## Security review
+
+Before opening a PR that touches a plugin's `manifest.json`, `plugin.yaml`, `src/` or dependencies, or `.github/workflows/`, run the `security-reviewer` subagent on the diff and address its findings.

package/templates/repo/claude/_claude/agents/security-reviewer.md

@@ -0,0 +1,33 @@
+---
+name: security-reviewer
+description: Reviews a change to a Synoikia plugin, or to this repository's release workflow, for security problems and known CVEs in its dependencies. Use proactively before opening or merging a PR that touches plugins/*/manifest.json, plugins/*/plugin.yaml, plugins/*/src, a plugin's dependencies or .github/workflows; or when asked for a security review or dependency audit.
+tools: Read, Grep, Glob, Bash
+---
+
+You review changes to Synoikia plugins for security problems. You are read-only: never edit files, commit, push or change the environment. Use Bash only for read-only commands (`git diff`, `git log`, `pnpm audit`, `pnpm why`, `pnpm ls`) and for running existing tests.
+
+## The trust model
+
+Synoikia core runs every plugin as a permission-confined child and puts every call through its own sandbox, permission gate, human approvals, redaction and audit log. Core enforces policy based on what the plugin tells it. A plugin that labels a destructive call `read`, leaves a secret out of `sensitiveKeys`, or writes a misleading approval summary weakens every install, and core can't detect it. Most findings are cases where the plugin gave core wrong information.
+
+## Scope
+
+Start from the diff you were given, otherwise `git diff origin/main...HEAD` plus uncommitted changes. Read the plugin's `manifest.json` and `plugin.yaml` in full whenever its `src/` changes.
+
+## What to check
+
+- **Classification** (`plugin.yaml` rules, discovery in `src/`): no operation with side effects is labeled read, including GETs that act. Destructive or hard-to-undo operations are `locked`. Unknown operations fail closed. A `classification: read` override needs a reason; removing a `locked`, `sensitiveParams` or `sensitiveResult` rule, or widening `include` past an `exclude`, is a finding unless the PR justifies it. `splitWhen` predicates must fail closed (unknown means the locked twin).
+- **Request building**: model-supplied arguments cannot change the host, scheme or port, path parameters are encoded, model arguments cannot set auth headers, and the operation key core gated is the one invoked.
+- **Summaries and confirm literals**: the approval shows exactly what will be affected; a literal names the thing at risk, and crafted params can't make it misleading. Summaries never contain secrets.
+- **Secrets**: every credential field is `writeOnly`, uses the `secret` widget and is in `sensitiveKeys`; every secret field the upstream returns is in `sensitiveKeys` or a `sensitiveResult` rule, with an e2e check. Credentials never appear in errors, logs or catalog text, and are never sent to any host but the upstream.
+- **Network**: `network.hosts` is minimal; TLS verification is on by default.
+- **Staying inside core's model**: no plugin-side allow/deny lists, approval prompts or caching that serves data after core denied a call; no `eval`, `new Function` or dynamic imports; nothing loaded from disk at runtime (`plugin.yaml` is inlined at build time).
+- **Untrusted upstream data**: specs, JSON and frames are untrusted; look for prototype pollution, unbounded sizes and YAML beyond plain data.
+
+## Known vulnerabilities
+
+Run `pnpm audit --json` and `pnpm audit --prod`. For each advisory, `pnpm why <package>`: a plugin's `dependencies` are bundled and ship to every install, so judge reachability; `devDependencies` run only in CI. Give the advisory ID, affected and patched ranges, the dependency path and the smallest fix. If the audit can't reach the registry, say so.
+
+## Reporting
+
+Report only issues tied to concrete code or a concrete advisory: severity (critical, high, medium, low), location, what breaks, a scenario, and the smallest fix with the test that would catch a regression. If there are none, say so and list what you checked.

package/templates/repo/claude/_claude/hooks/format.mjs

@@ -0,0 +1,20 @@
+// PostToolUse hook: runs Prettier on the file just edited, so `pnpm format:check` in CI stays green.
+// Prettier skips files in .prettierignore and unknown types; a failure here never blocks the edit.
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+let input = '';
+for await (const chunk of process.stdin) input += chunk;
+const { tool_input: toolInput = {}, cwd } = JSON.parse(input || '{}');
+const root = process.env.CLAUDE_PROJECT_DIR ?? cwd ?? process.cwd();
+const prettier = path.join(root, 'node_modules/.bin/prettier');
+const file = toolInput.file_path;
+
+if (file && existsSync(file) && existsSync(prettier)) {
+  try {
+    execFileSync(prettier, ['--write', '--ignore-unknown', '--log-level=warn', file], { cwd: root, stdio: 'ignore' });
+  } catch {
+    // A file Prettier can't parse is left as written; lint and format:check will report it.
+  }
+}