@synoikia/create-plugin 0.1.0

package/templates/repo/claude/_claude/hooks/guard-paths.mjs

@@ -0,0 +1,43 @@
+// PreToolUse hook: stops edits to generated files and asks before edits to the signing key.
+// Reads the tool call from stdin; prints a permission decision for matching paths, nothing otherwise.
+import path from 'node:path';
+
+const RULES = [
+  {
+    match: /(^|\/)pnpm-lock\.yaml$/,
+    decision: 'deny',
+    reason: 'pnpm-lock.yaml is generated. Change package.json and run `pnpm install` instead.',
+  },
+  {
+    match: /^plugins\/[^/]+\/dist\//,
+    decision: 'deny',
+    reason: 'dist/ is the esbuild bundle. Edit src/ and run `pnpm --filter ./plugins/<id> build`.',
+  },
+  {
+    match: /^minisign\.pub$/,
+    decision: 'ask',
+    reason:
+      'minisign.pub is the key every Synoikia install pins for this repository. Changing it blocks installs until each admin confirms the new key; only for a compromised key.',
+  },
+];
+
+let input = '';
+for await (const chunk of process.stdin) input += chunk;
+const { tool_input: toolInput = {}, cwd } = JSON.parse(input || '{}');
+const file = toolInput.file_path ?? toolInput.notebook_path;
+if (!file) process.exit(0);
+
+const root = process.env.CLAUDE_PROJECT_DIR ?? cwd ?? process.cwd();
+const rel = path.relative(root, path.resolve(root, file)).split(path.sep).join('/');
+const rule = RULES.find((r) => r.match.test(rel));
+if (!rule) process.exit(0);
+
+console.log(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: rule.decision,
+      permissionDecisionReason: `${rel}: ${rule.reason}`,
+    },
+  }),
+);

package/templates/repo/claude/_claude/hooks/session-start.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# SessionStart hook: installs workspace dependencies in Claude Code cloud sessions, so lint, typecheck
+# and tests work straight away. Local sessions are left alone.
+set -euo pipefail
+
+if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then
+  exit 0
+fi
+
+cd "$CLAUDE_PROJECT_DIR"
+command -v pnpm >/dev/null 2>&1 || corepack enable
+# stdout becomes session context; keep the install log out of it.
+pnpm install --frozen-lockfile >&2

package/templates/repo/claude/_claude/settings.json

@@ -0,0 +1,21 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-start.sh" }]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [{ "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-paths.mjs" }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [{ "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.mjs" }]
+      }
+    ]
+  }
+}

package/templates/repo/claude/_claude/skills/add-plugin/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: add-plugin
+description: Scaffold a new Synoikia plugin under plugins/<id> with `pnpm new`, then fill in its plugin.yaml rules, discovery and tests. Use when asked to add, create or start a plugin for a new upstream service.
+---
+
+# Add a plugin
+
+## 1. Settle the basics
+
+- **`<id>`**: lowercase, the directory name and manifest `id`; the sandbox namespace defaults to it in camelCase.
+- **Archetype**: `openapi-rest` (the upstream serves an OpenAPI spec), `static-rest` (a REST API without one; operations are declared in `plugin.yaml`), `websocket-rpc` (JSON-RPC over WebSocket), or `blank`.
+- **Auth**: `bearer`, `api-key` (with its header), `basic` or `none`.
+- **Destructive operations**: which ones are `locked` (always a human who types a confirmation literal), and what that literal is.
+- **Secrets**: which connection fields are credentials, and which fields the upstream returns hold secrets.
+
+## 2. Scaffold
+
+```sh
+pnpm new --id <id> --name "<Name>" --archetype <archetype> --auth <auth> --yes
+```
+
+This writes `plugins/<id>/` (manifest, `plugin.yaml`, `src/`, a fake upstream, unit and e2e tests) and runs `pnpm install`. The generated plugin already builds and passes its tests.
+
+## 3. Describe the upstream
+
+- `manifest.json`: connection fields and help, `sensitiveKeys` (add every secret field the upstream returns), `network.hosts`.
+- `plugin.yaml`: `rules` for locks, splits, classification overrides, `sensitiveParams`, `sensitiveResult`, `confirm` literals and summary notes; `exclude` for plumbing the model has no business calling. A rule's `classification` can never unlock a locked operation, and anything unclassified is a write.
+- `src/plugin.ts`: only what needs logic, such as a `splitWhen` predicate or a custom confirm source.
+
+## 4. Tests
+
+Extend `test/fake-upstream.ts` to answer what the plugin calls, including responses with secrets. Keep `checkPluginContract` in `test/e2e.test.ts` passing, and add unit tests for every rule that locks or masks something.
+
+```sh
+pnpm --filter ./plugins/<id> test
+pnpm typecheck && pnpm lint && pnpm format:check
+```
+
+Then run the `security-reviewer` subagent on the diff.

package/templates/repo/claude/_claude/skills/release-plugin/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: release-plugin
+description: Prepare a plugin release by bumping its version in manifest.json and package.json together, and optionally its minimum Synoikia version. Use when asked to release, publish, ship or bump the version of a plugin.
+---
+
+# Release a plugin
+
+A release is a version bump merged to `main`; the Release workflow packs, signs, verifies and publishes every plugin whose version isn't in the published index yet (see `RELEASING.md`).
+
+1. **Pick the version** with semver against the last release (`git log --oneline -- plugins/<id>`):
+   - patch: fixes, catalog corrections, wording;
+   - minor: new operations, connection fields or capabilities; also any `plugin.yaml` change that unlocks an operation, drops a `sensitiveParams`/`sensitiveResult` rule or overrides a classification to read (call it out in the PR);
+   - major: a change that breaks existing instances, such as a renamed operation key or a removed connection field.
+2. **Bump both files to the same version**: `plugins/<id>/manifest.json` and `plugins/<id>/package.json`.
+3. **Minimum Synoikia version**, only when the change needs a newer core: `"synoikia": { "minCoreVersion": "x.y.z" }` in `package.json`. A newer SDK means bumping the manifest `sdk` range together with the `@synoikia/plugin-sdk` range, then `pnpm install`.
+4. **Verify**: `pnpm --filter ./plugins/<id> test`, then `pnpm typecheck && pnpm lint && pnpm format:check`.
+
+Released versions are immutable. Never touch `minisign.pub` or the signing steps of the workflow.

package/templates/repo/release/RELEASING.md

@@ -0,0 +1,27 @@
+# Releasing
+
+This repository publishes a **signed plugin repository** that Synoikia installs from. Add it on Synoikia's Plugins → Repositories page as a signed repository:
+
+- Index: `https://github.com/{{repository}}/releases/download/index/index.json`
+- Public key: the key in `minisign.pub`
+
+## One-time setup
+
+1. Generate a password-less minisign key pair on a trusted machine: `minisign -G -W -p minisign.pub -s minisign.key`.
+2. Commit `minisign.pub`. Store the whole `minisign.key` file (both lines) as the `MINISIGN_SECRET_KEY` Actions secret, then delete the local copy or keep it offline.
+3. Check that `package.json` `synoikia.repository` is `{{repository}}`.
+
+Never commit the secret key. Changing the key later makes every Synoikia install block this repository until its admin confirms the new key, so a new key is for a compromised key only.
+
+## Releasing a plugin
+
+Bump `version` in both the plugin's `manifest.json` and `package.json` (they must match) and merge to `main`. The Release workflow then:
+
+1. runs every plugin's tests;
+2. packs each plugin whose version isn't in the published index yet, as a deterministic tarball (`synoikia-plugin repo pack`);
+3. signs each tarball and checks it against `minisign.pub`;
+4. merges the new versions into the index (`repo index`);
+5. installs each new version with Synoikia's own repository service, with `minisign.pub` pinned (`repo verify`);
+6. only then creates the `<id>-v<version>` releases and replaces `index.json` on the `index` release (`repo publish`).
+
+A released version is never changed: to ship a fix, bump the version again. A plugin can require a minimum Synoikia version with `"synoikia": { "minCoreVersion": "x.y.z" }` in its `package.json`.

package/templates/repo/release/_github/workflows/release.yml

@@ -0,0 +1,89 @@
+name: Release
+
+# Publishes the signed plugin repository Synoikia installs from (RELEASING.md). A plugin version is
+# released when its manifest version isn't in the published index yet: each gets a `<id>-v<version>`
+# release with its tarball and minisign signature, and index.json on the `index` release is replaced.
+# Released versions are never rebuilt or removed.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Nothing here pushes with git; keep the token out of .git/config while dev dependencies run.
+          persist-credentials: false
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test
+
+      - name: Download the published index
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Start a new index only when there really is none: on any other error (rate limit, network)
+          # stop, rather than rebuild every released version.
+          if out=$(gh release view index 2>&1); then
+            gh release download index --pattern index.json --dir .repo-current
+          elif grep -qi 'release not found' <<<"$out"; then
+            echo "No index release yet: starting a new index."
+          else
+            echo "::error::Could not read the index release: $out"
+            exit 1
+          fi
+
+      - name: Pack new plugin versions
+        id: pack
+        run: |
+          pnpm exec synoikia-plugin repo pack
+          echo "count=$(node -p "require('./.repo/releases.json').length")" >> "$GITHUB_OUTPUT"
+
+      - name: Sign
+        if: steps.pack.outputs.count != '0'
+        env:
+          MINISIGN_SECRET_KEY: ${{ secrets.MINISIGN_SECRET_KEY }}
+        run: |
+          if [ -z "$MINISIGN_SECRET_KEY" ]; then
+            echo "::error::The MINISIGN_SECRET_KEY secret is not set."
+            exit 1
+          fi
+          sudo apt-get update -qq && sudo apt-get install -y -qq minisign
+          key="$RUNNER_TEMP/minisign.key"
+          (umask 077; printf '%s\n' "$MINISIGN_SECRET_KEY" > "$key")
+          trap 'rm -f "$key"' EXIT
+          for f in .repo/*.tgz; do
+            minisign -S -s "$key" -m "$f" -t "$(basename "$f")"
+            minisign -V -p minisign.pub -m "$f"
+          done
+
+      - name: Build the index
+        if: steps.pack.outputs.count != '0'
+        run: pnpm exec synoikia-plugin repo index
+
+      # Synoikia's own repository service installs every new version with minisign.pub pinned, before
+      # anything is uploaded.
+      - name: Verify with Synoikia
+        if: steps.pack.outputs.count != '0'
+        run: pnpm exec synoikia-plugin repo verify
+
+      - name: Publish
+        if: steps.pack.outputs.count != '0'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: pnpm exec synoikia-plugin repo publish