@synoikia/create-plugin 0.1.0

package/dist/scaffold.js

@@ -0,0 +1,296 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { RESERVED_NAMESPACES, SDK_VERSION } from '@synoikia/plugin-sdk';
+import { dependencyRange, TEMPLATES_DIR } from './repo-root.js';
+/**
+ * Scaffolding: a new plugin repository (`pnpm create @synoikia/plugin`) and a new plugin inside one
+ * (`pnpm new`). Templates are plain files with `{{name}}` placeholders; only known names are replaced
+ * and nothing in a template runs. Files whose name starts with `_` are written with a leading `.`
+ * (npm drops some dotfiles from published packages). Generated code uses only the published SDK and
+ * core APIs, and the generated manifest already follows the secret rules `synoikia-plugin check`
+ * enforces.
+ */
+export const ARCHETYPES = {
+    'openapi-rest': 'REST API that serves an OpenAPI spec: the catalog is the spec, rules lock and describe',
+    'static-rest': 'REST API without a spec: operations are declared in plugin.yaml',
+    'websocket-rpc': 'JSON-RPC 2.0 over WebSocket: methods declared in plugin.yaml',
+    blank: 'A minimal plugin to fill in by hand',
+};
+export const AUTH_KINDS = {
+    bearer: 'Bearer token (Authorization: Bearer …)',
+    'api-key': 'API key header (e.g. X-Api-Key)',
+    basic: 'Username and password (HTTP Basic)',
+    none: 'No authentication',
+};
+export const ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,62}$/;
+const JS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+export const camelCase = (id) => id.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+export const pascalCase = (id) => camelCase(id).replace(/^./, (c) => c.toUpperCase());
+/** Problems with a plugin id or namespace, or undefined. */
+export function validateId(id, root) {
+    if (!ID_PATTERN.test(id))
+        return 'Use 2–63 lowercase letters, digits and dashes, starting with a letter or digit';
+    if (root && existsSync(path.join(root, 'plugins', id)))
+        return `plugins/${id} already exists`;
+    return undefined;
+}
+/**
+ * Display names and descriptions land in generated code (`const SERVICE = '…'`), YAML and Markdown:
+ * plain text only, so no quote, backslash or newline can break out of them.
+ */
+const SAFE_TEXT = /^[\p{L}\p{N}][\p{L}\p{N} .,:()&+_/-]*$/u;
+export function validateName(name) {
+    if (name.length > 64 || !SAFE_TEXT.test(name))
+        return 'Use letters, digits, spaces and . , : ( ) & + _ / - (up to 64 characters)';
+    return undefined;
+}
+export function validateDescription(text) {
+    if (text.length > 200 || !SAFE_TEXT.test(text))
+        return 'Use plain text without quotes or newlines (up to 200 characters)';
+    return undefined;
+}
+export function validateNamespace(ns) {
+    if (!JS_IDENTIFIER.test(ns))
+        return 'Must be a JavaScript identifier';
+    if (RESERVED_NAMESPACES.includes(ns))
+        return `"${ns}" is reserved by core`;
+    return undefined;
+}
+const PLACEHOLDER = /\{\{([a-zA-Z]+)\}\}/g;
+/** Replaces `{{name}}` for the names in `vars`; anything else (e.g. `{{connection.baseUrl}}`) stays. */
+export function fill(text, vars) {
+    return text.replace(PLACEHOLDER, (whole, name) => (Object.hasOwn(vars, name) ? vars[name] : whole));
+}
+const outName = (name) => (/^_[a-zA-Z]/.test(name) ? `.${name.slice(1)}` : name);
+/** Copies a template directory, filling placeholders. Refuses to overwrite an existing file. */
+export function renderTemplate(from, to, vars, written = []) {
+    for (const entry of readdirSync(from).sort()) {
+        const src = path.join(from, entry);
+        const dest = path.join(to, outName(entry));
+        if (statSync(src).isDirectory()) {
+            renderTemplate(src, dest, vars, written);
+            continue;
+        }
+        if (existsSync(dest))
+            throw new Error(`${dest} already exists`);
+        mkdirSync(path.dirname(dest), { recursive: true });
+        writeFileSync(dest, fill(readFileSync(src, 'utf8'), vars));
+        written.push(dest);
+    }
+    return written;
+}
+const write = (file, text, written) => {
+    if (existsSync(file))
+        throw new Error(`${file} already exists`);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, text);
+    written.push(file);
+};
+const AUTH = {
+    bearer: {
+        secret: {
+            name: 'token',
+            title: 'API token',
+            help: 'A long-lived API token for a dedicated, least-privileged user.',
+        },
+        source: () => `/** Authenticates every request with the connection's API token. */
+export function authHeaders({ secrets }: InitParams): () => Record<string, string> {
+  const token = requireString(secrets, 'token');
+  return () => ({ authorization: \`Bearer \${token}\` });
+}
+`,
+        fake: () => `export const CREDENTIALS = { token: 'fake-api-token-abcdef' };
+
+export const authorized = (headers: IncomingHttpHeaders) => headers.authorization === \`Bearer \${CREDENTIALS.token}\`;
+`,
+    },
+    'api-key': {
+        secret: { name: 'apiKey', title: 'API key', help: 'An API key for a dedicated, least-privileged user.' },
+        source: (header) => `/** Authenticates every request with the connection's API key. */
+export function authHeaders({ secrets }: InitParams): () => Record<string, string> {
+  const apiKey = requireString(secrets, 'apiKey');
+  return () => ({ '${header}': apiKey });
+}
+`,
+        fake: (header) => `export const CREDENTIALS = { apiKey: 'fake-api-key-abcdef' };
+
+export const authorized = (headers: IncomingHttpHeaders) => headers['${header}'] === CREDENTIALS.apiKey;
+`,
+    },
+    basic: {
+        secret: { name: 'password', title: 'Password', help: 'The password of a dedicated, least-privileged user.' },
+        user: true,
+        source: () => `/** Authenticates every request with the connection's username and password (HTTP Basic). */
+export function authHeaders({ config, secrets }: InitParams): () => Record<string, string> {
+  const credentials = Buffer.from(\`\${requireString(config, 'username')}:\${requireString(secrets, 'password')}\`).toString('base64');
+  return () => ({ authorization: \`Basic \${credentials}\` });
+}
+`,
+        fake: () => `export const CREDENTIALS = { username: 'synoikia', password: 'fake-password-abcdef' };
+
+export const authorized = (headers: IncomingHttpHeaders) =>
+  headers.authorization === \`Basic \${Buffer.from(\`\${CREDENTIALS.username}:\${CREDENTIALS.password}\`).toString('base64')}\`;
+`,
+    },
+    none: {
+        source: () => `/** The upstream needs no authentication. */
+export function authHeaders(_init: InitParams): () => Record<string, string> {
+  return () => ({});
+}
+`,
+        fake: () => `export const CREDENTIALS = {};
+
+export const authorized = (_headers: IncomingHttpHeaders) => true;
+`,
+    },
+};
+function authModule(auth, header) {
+    const spec = AUTH[auth];
+    const usesRequire = auth !== 'none';
+    return `${usesRequire ? "import { requireString } from '@synoikia/plugin-sdk';\n" : ''}import type { InitParams } from '@synoikia/plugin-sdk';
+
+${spec.source(header)}`;
+}
+function fakeAuthModule(auth, header) {
+    return `import type { IncomingHttpHeaders } from 'node:http';
+
+/** The connection the tests use, and how the fake upstream checks it. */
+${AUTH[auth].fake(header)}`;
+}
+/** The generated manifest: connection form, secrets, network hosts and binding. */
+export function manifestFor(opts, namespace) {
+    const spec = AUTH[opts.auth];
+    const properties = {
+        baseUrl: { type: 'string', format: 'uri', title: 'Base URL' },
+        ...(spec.user ? { username: { type: 'string', title: 'Username' } } : {}),
+        ...(spec.secret ? { [spec.secret.name]: { type: 'string', title: spec.secret.title, writeOnly: true } } : {}),
+        verifyTls: { type: 'boolean', title: 'Verify TLS certificate', default: true },
+    };
+    const ui = {
+        baseUrl: { widget: 'url', placeholder: `https://${opts.id}.internal.lan` },
+        ...(spec.user ? { username: { widget: 'text' } } : {}),
+        ...(spec.secret ? { [spec.secret.name]: { widget: 'secret', help: spec.secret.help } } : {}),
+        verifyTls: { widget: 'bool' },
+    };
+    const required = ['baseUrl', ...(spec.user ? ['username'] : []), ...(spec.secret ? [spec.secret.name] : [])];
+    const sensitiveKeys = [
+        ...new Set([...(spec.secret ? [spec.secret.name] : []), 'apiKey', 'api_key', 'token', 'password', 'secret']),
+    ];
+    return {
+        id: opts.id,
+        name: opts.name,
+        version: '0.1.0',
+        sdk: `^${SDK_VERSION}`,
+        description: opts.description ?? `${opts.name} for Synoikia.`,
+        entry: 'dist/index.js',
+        binding: { namespace, functions: [opts.archetype === 'openapi-rest' ? 'request' : 'call'] },
+        connection: {
+            schema: { type: 'object', required, properties },
+            ui,
+            help: `1. In ${opts.name}, create a dedicated user with only the access Synoikia should have${spec.secret ? `, and its ${spec.secret.title.toLowerCase()}` : ''}.\n2. Enter the base URL and credentials, then **Test connection**.\n3. Keep *Verify TLS* on unless ${opts.name} uses a self-signed certificate on a trusted network.\n\nAfter the first sync, raise groups on the Access page as needed.`,
+        },
+        sensitiveKeys,
+        network: { hosts: ['{{connection.baseUrl}}'] },
+    };
+}
+function packageFor(opts) {
+    const range = (k, name) => opts.ranges?.[k] ?? dependencyRange(name);
+    const ws = opts.archetype === 'websocket-rpc';
+    return {
+        name: `@synoikia/plugin-${opts.id}`,
+        version: '0.1.0',
+        private: true,
+        type: 'module',
+        main: 'dist/index.js',
+        scripts: {
+            build: 'synoikia-plugin build',
+            check: 'synoikia-plugin check',
+            typecheck: 'tsc -p tsconfig.json --noEmit',
+            test: 'synoikia-plugin check && synoikia-plugin build && vitest run',
+        },
+        dependencies: {
+            '@synoikia/plugin-sdk': range('sdk', '@synoikia/plugin-sdk'),
+            ...(ws ? { ws: '^8.22.0' } : {}),
+        },
+        devDependencies: {
+            '@synoikia/core': range('core', '@synoikia/core'),
+            '@synoikia/create-plugin': range('cli', '@synoikia/create-plugin'),
+            ...(ws ? { '@types/ws': '^8.18.1' } : {}),
+        },
+    };
+}
+/** Writes `plugins/<id>/` from the archetype's template. Returns the files written. */
+export function newPlugin(opts) {
+    const idProblem = validateId(opts.id, opts.root);
+    if (idProblem)
+        throw new Error(`Plugin id: ${idProblem}`);
+    const namespace = opts.namespace ?? camelCase(opts.id);
+    const nsProblem = validateNamespace(namespace);
+    if (nsProblem)
+        throw new Error(`Namespace: ${nsProblem}`);
+    const nameProblem = validateName(opts.name);
+    if (nameProblem)
+        throw new Error(`Name: ${nameProblem}`);
+    const descProblem = opts.description === undefined ? undefined : validateDescription(opts.description);
+    if (descProblem)
+        throw new Error(`Description: ${descProblem}`);
+    if (!ARCHETYPES[opts.archetype])
+        throw new Error(`Unknown archetype ${opts.archetype}`);
+    if (!AUTH[opts.auth])
+        throw new Error(`Unknown auth ${opts.auth}`);
+    const header = (opts.apiKeyHeader ?? 'X-Api-Key').toLowerCase();
+    if (!/^[a-z0-9-]+$/.test(header))
+        throw new Error('The API key header may only hold letters, digits and dashes');
+    const dir = path.join(opts.root, 'plugins', opts.id);
+    const vars = {
+        id: opts.id,
+        name: opts.name,
+        namespace,
+        Pascal: pascalCase(opts.id),
+        description: opts.description ?? `${opts.name} for Synoikia.`,
+        fn: opts.archetype === 'openapi-rest' ? 'request' : 'call',
+        archetype: opts.archetype,
+    };
+    const written = [];
+    renderTemplate(path.join(TEMPLATES_DIR, 'plugin', 'common'), dir, vars, written);
+    renderTemplate(path.join(TEMPLATES_DIR, 'plugin', opts.archetype), dir, vars, written);
+    write(path.join(dir, 'manifest.json'), `${JSON.stringify(manifestFor(opts, namespace), null, 2)}\n`, written);
+    write(path.join(dir, 'package.json'), `${JSON.stringify(packageFor(opts), null, 2)}\n`, written);
+    write(path.join(dir, 'src', 'auth.ts'), authModule(opts.auth, header), written);
+    if (opts.archetype !== 'blank')
+        write(path.join(dir, 'test', 'fake-auth.ts'), fakeAuthModule(opts.auth, header), written);
+    return written;
+}
+/** Writes a new plugin repository. Returns the files written. */
+export function createRepo(opts) {
+    const dir = path.resolve(opts.dir);
+    if (existsSync(dir) && readdirSync(dir).length)
+        throw new Error(`${dir} is not empty`);
+    const name = path.basename(dir);
+    // The directory name becomes the package name and appears in generated files.
+    if (!/^[a-z0-9][a-z0-9._-]{0,213}$/.test(name))
+        throw new Error(`${name}: use a lowercase directory name (letters, digits, . _ -), as for an npm package`);
+    const repository = opts.repository ?? `OWNER/${name}`;
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository))
+        throw new Error('repository must look like owner/name');
+    const vars = {
+        repoName: name,
+        repository,
+        coreRange: opts.ranges?.core ?? dependencyRange('@synoikia/core'),
+        cliRange: opts.ranges?.cli ?? dependencyRange('@synoikia/create-plugin'),
+    };
+    const written = [];
+    renderTemplate(path.join(TEMPLATES_DIR, 'repo', 'base'), dir, vars, written);
+    if (opts.release)
+        renderTemplate(path.join(TEMPLATES_DIR, 'repo', 'release'), dir, vars, written);
+    if (opts.claude)
+        renderTemplate(path.join(TEMPLATES_DIR, 'repo', 'claude'), dir, vars, written);
+    mkdirSync(path.join(dir, 'plugins'), { recursive: true });
+    return written;
+}
+/** `pnpm install` in the repository (links a new plugin, updates the lockfile). */
+export function install(root) {
+    execFileSync('pnpm', ['install'], { cwd: root, stdio: 'inherit' });
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"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"}

package/dist/vitest.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Vite/Vitest plugin that loads `.yaml` and `.md` imports the way `synoikia-plugin build` bundles
+ * them, so unit tests see exactly what the bundle does. Add it to the repository's `vitest.shared.ts`.
+ */
+export declare function pluginFiles(): {
+    name: string;
+    enforce: "pre";
+    transform(code: string, id: string): {
+        code: string;
+        map: null;
+    } | undefined;
+};

package/dist/vitest.js

@@ -0,0 +1,17 @@
+import { moduleSource } from './files.js';
+/**
+ * Vite/Vitest plugin that loads `.yaml` and `.md` imports the way `synoikia-plugin build` bundles
+ * them, so unit tests see exactly what the bundle does. Add it to the repository's `vitest.shared.ts`.
+ */
+export function pluginFiles() {
+    return {
+        name: 'synoikia-plugin-files',
+        enforce: 'pre',
+        transform(code, id) {
+            const file = id.split('?')[0];
+            const source = moduleSource(file, file.endsWith('.md') ? code : undefined);
+            return source === undefined ? undefined : { code: source, map: null };
+        },
+    };
+}
+//# sourceMappingURL=vitest.js.map

package/dist/vitest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.js","sourceRoot":"","sources":["../src/vitest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;GAGG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO;QACL,IAAI,EAAE,uBAAuB;QAC7B,OAAO,EAAE,KAAc;QACvB,SAAS,CAAC,IAAY,EAAE,EAAU;YAChC,MAAM,IAAI,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;YAC/B,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YAC3E,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;QACxE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@synoikia/create-plugin",
+  "version": "0.1.0",
+  "description": "Create Synoikia plugin repositories and plugins, then build, check and publish them",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/via-justa/synoikia-core.git",
+    "directory": "packages/create-plugin"
+  },
+  "type": "module",
+  "bin": {
+    "create-plugin": "./dist/create.js",
+    "synoikia-plugin": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "synoikia-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vitest": {
+      "synoikia-source": "./src/vitest.ts",
+      "types": "./dist/vitest.d.ts",
+      "import": "./dist/vitest.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "esbuild": "^0.28.2",
+    "yaml": "^2.9.1",
+    "@synoikia/plugin-sdk": "^0.2.1"
+  },
+  "peerDependencies": {
+    "@synoikia/core": "^0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@synoikia/core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "ws": "^8.22.0",
+    "@synoikia/core": "^0.4.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}

package/templates/plugin/blank/plugin.yaml

@@ -0,0 +1,22 @@
+# yaml-language-server: $schema=./node_modules/@synoikia/plugin-sdk/plugin-settings.schema.json
+#
+# What {{name}} tells Synoikia about its operations. Declare them here (or discover them in
+# src/plugin.ts and keep only the rules). Core decides what is allowed. Reference: docs/plugin-authoring.md.
+
+defaults:
+  timeouts: { request: 15000, lookup: 10000 }
+
+operations:
+  - key: example.read
+    group: example
+    classification: read
+    summary: An example read. Replace it with the upstream's operations.
+  - key: example.delete
+    group: example
+    classification: write
+    summary: An example destructive write.
+
+rules:
+  - match: example.delete
+    locked: true
+    confirm: { param: /name }

package/templates/plugin/blank/src/plugin.ts

@@ -0,0 +1,74 @@
+import {
+  compileRules,
+  definePlugin,
+  ErrorCodes,
+  isPlainObject,
+  parsePluginSettings,
+  PluginError,
+  requireString,
+  staticCatalog,
+  truncate,
+} from '@synoikia/plugin-sdk';
+import type { PluginHandlers } from '@synoikia/plugin-sdk';
+import raw from '../plugin.yaml';
+import { authHeaders } from './auth.js';
+
+/**
+ * The {{name}} plugin. The sandbox calls `{{namespace}}.call(operation, params)`. Fill in the client
+ * (`connect`), the version, and `invoke`; operations and their rules live in plugin.yaml.
+ */
+
+const SERVICE = '{{name}}';
+
+export const settings = parsePluginSettings(raw);
+
+interface Client {
+  baseUrl: string;
+  headers: () => Record<string, string>;
+}
+
+export function create{{Pascal}}Plugin(): PluginHandlers {
+  return definePlugin<Client>({
+    // TODO: build a real client (HttpJsonClient for HTTP APIs, PendingRequests for socket protocols).
+    connect: (init) => ({ baseUrl: requireString(init.config, 'baseUrl'), headers: authHeaders(init) }),
+
+    // TODO: ask the upstream for its version.
+    version: async () => '0.0.0',
+
+    handlers(kit) {
+      const rules = compileRules(settings);
+      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 [key, params] = args;
+          if (typeof key !== 'string' || !known.has(key))
+            throw new PluginError(ErrorCodes.UnknownOperation, `${String(key)} is not a ${SERVICE} operation`);
+          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(key)[0];
+          return { key: split ? `${key}#${split}` : key, params: params ?? {} };
+        },
+
+        async summarize({ key, params, targets }) {
+          const json = JSON.stringify(params ?? {});
+          const text = `${SERVICE} ${key}${json === '{}' ? '' : ` ${truncate(json, 400)}`}`;
+          const literal = await rules.confirmLiteral({ key, params, targets });
+          return literal ? { text, confirmLiteral: literal } : { text };
+        },
+
+        invoke({ key }) {
+          // TODO: call the upstream with kit.client(), then return rules.maskResult(key, result).
+          throw new PluginError(ErrorCodes.NotImplemented, `${key} is not implemented yet`);
+        },
+      };
+    },
+  });
+}

package/templates/plugin/blank/test/plugin.test.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { checkConformance } from '@synoikia/plugin-sdk';
+import { describe, expect, it } from 'vitest';
+import { create{{Pascal}}Plugin, settings } from '../src/plugin.js';
+
+const manifest: unknown = JSON.parse(readFileSync(new URL('../manifest.json', import.meta.url), 'utf8'));
+
+// Fill in a connection for your auth, and point baseUrl at a fake upstream (see @synoikia/core/testing's
+// startFakeHttp) once the plugin talks to one.
+const init = {
+  instanceId: '{{id}}',
+  config: { baseUrl: 'http://127.0.0.1:1', username: 'synoikia' },
+  secrets: { token: 't', apiKey: 'k', password: 'p' },
+};
+
+describe('{{name}} plugin', () => {
+  it('passes the SDK conformance checks', async () => {
+    const plugin = create{{Pascal}}Plugin();
+    const issues = await checkConformance({
+      manifest,
+      settings,
+      handlers: plugin,
+      init,
+      samples: [
+        { fn: 'call', args: ['example.read'], expectKey: 'example.read' },
+        { fn: 'call', args: ['example.delete', { name: 'thing' }], expectKey: 'example.delete' },
+      ],
+      rejects: [{ fn: 'call', args: ['example.nope'] }],
+    });
+    expect(issues).toEqual([]);
+    await plugin.shutdown?.();
+  });
+});

package/templates/plugin/common/README.md

@@ -0,0 +1,23 @@
+# {{name}}
+
+{{description}}
+
+The sandbox calls `{{namespace}}.{{fn}}(…)`. Every call goes through Synoikia's permission gate, approvals, redaction and audit log; this plugin only describes {{name}}'s API.
+
+## Files
+
+| File            | What                                                                                     |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| `manifest.json` | Binding, connection form, `sensitiveKeys` and network hosts                              |
+| `plugin.yaml`   | Locked operations, split twins, sensitive params and results, confirmation literals      |
+| `src/plugin.ts` | Discovery and anything that needs logic                                                  |
+| `src/auth.ts`   | How requests authenticate                                                                |
+| `test/`         | A fake {{name}}, unit tests, and e2e tests on Synoikia's harness                         |
+
+## Connection
+
+See the manifest's `connection.help`. Use a dedicated {{name}} user with only the access Synoikia should have.
+
+## Locked operations
+
+List the operations `plugin.yaml` locks, and why, here.

package/templates/plugin/common/RUNBOOK.md

@@ -0,0 +1,10 @@
+# {{name}} runbook
+
+A manual checklist against a real {{name}} before a release.
+
+1. Add an instance with a dedicated user; **Test connection** reports the version.
+2. Sync: the catalog appears, and every group starts at the default level.
+3. Run a read at Read. Check that secrets in its result show as `[REDACTED]`.
+4. A write stays refused until its group is raised.
+5. A locked operation asks for approval and requires the typed confirmation literal.
+6. Check the audit log lists each call.

package/templates/plugin/common/src/index.ts

@@ -0,0 +1,4 @@
+import { runPlugin } from '@synoikia/plugin-sdk';
+import { create{{Pascal}}Plugin } from './plugin.js';
+
+runPlugin(create{{Pascal}}Plugin());

package/templates/plugin/common/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "customConditions": []
+  },
+  "include": ["src", "../../plugin-files.d.ts"]
+}

package/templates/plugin/common/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src", "test", "../../plugin-files.d.ts"]
+}

package/templates/plugin/common/vitest.config.ts

@@ -0,0 +1 @@
+export { default } from '../../vitest.shared.ts';

package/templates/plugin/openapi-rest/plugin.yaml

@@ -0,0 +1,49 @@
+# yaml-language-server: $schema=./node_modules/@synoikia/plugin-sdk/plugin-settings.schema.json
+#
+# What {{name}} tells Synoikia about its operations. The OpenAPI spec lists them (GET reads, every other
+# verb writes, an action-shaped GET is a write flagged for review); these rules lock, split, classify
+# and describe them on top. Core decides what is allowed. Reference: docs/plugin-authoring.md.
+
+defaults:
+  # The literal an approver types for a locked operation with no `confirm` of its own.
+  confirm: instance
+  timeouts: { request: 15000, lookup: 10000 }
+
+# Names this instance for `confirm: instance`. Lookups are GETs only.
+instanceName: { op: 'GET /status', field: name, fallback: '{{name}}' }
+
+# Operations left out of the catalog entirely (session plumbing, debug endpoints).
+exclude:
+  - 'POST /auth/*'
+
+rules:
+  # Destructive or irreversible: always a human who types the confirmation literal.
+  - match: 'DELETE /items/{itemId}'
+    locked: true
+    # The approver types the item's name, looked up by the id in the call (or the id if that fails).
+    confirm:
+      lookup:
+        op: 'GET /items/{itemId}'
+        args: [{ itemId: { $param: /path/itemId } }]
+        field: name
+
+  # A secret the upstream returns under a name too common for the manifest's sensitiveKeys:
+  # - match: GET /backups/*
+  #   sensitiveResult: { keys: [key], deep: true }
+
+  # A GET the heuristic flagged that was reviewed and only reads:
+  # - match: GET /sync/status
+  #   classification: read
+  #   reason: reviewed:read
+  #   needsReview: false
+
+plugin:
+  # Path of the API under the base URL.
+  apiPath: /api
+  # Where the instance serves its OpenAPI spec, under the API path.
+  specPath: /openapi.json
+  # Endpoint and field that report the version.
+  versionPath: /status
+  versionField: version
+  # Refuse a spec with fewer operations: a truncated one must not replace the catalog.
+  minOperations: 3