create-rigline-plugin 1.0.0-alpha.0 → 1.0.0-alpha.2

package/dist/index.js

@@ -1,37 +1,21 @@
 #!/usr/bin/env node
-/**
- * `create-rigline-plugin`: scaffolds a workspace holding one plugin (decisions.md, D50).
- *
- * A pnpm workspace with `plugins/*` rather than a single-plugin repository, because the multi-plugin
- * shape is a superset: it scaffolds correctly for one plugin, and a second plugin is then a
- * directory copy rather than a restructure.
- *
- * The template is real files under `template/`, copied and substituted, rather than strings in this
- * module. It stays readable and reviewable that way, and the example plugin's own source is a file
- * an editor can check rather than a string literal with its backticks escaped. Two things that
- * takes care of, both of which have caught people out before: `.gitignore` is shipped as
- * `gitignore`, because npm renames a `.gitignore` inside a published tarball and the scaffolded
- * repository would arrive without one; and `generated.ts` is shipped as a placeholder, so the
- * scaffold typechecks before `rigline codegen` has ever run, which is the promise D40 makes and the
- * one moment it is easiest to break.
- */
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-/** The manifest's own rule for a name, which is also npm's for an unscoped package. */
 const NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,213}$/;
 export class ScaffoldError extends Error {
 }
-/** The template shipped with this package. */
 export function defaultTemplateDir() {
     return resolve(dirname(fileURLToPath(import.meta.url)), "..", "template");
 }
-/**
- * Writes the template into `target`, substituted.
- *
- * It refuses a directory that already has anything in it. A scaffold is not a merge, and a
- * half-overwritten workspace is worse than either a new one or the one that was there.
- */
+export function riglineRange() {
+    const path = resolve(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    const { version } = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof version !== "string" || version.length === 0) {
+        throw new ScaffoldError(`this package's own version is missing from ${path}`);
+    }
+    return `^${version}`;
+}
 export function scaffold(options) {
     const dir = resolve(options.target);
     const name = options.name ?? basename(dir);
@@ -49,12 +33,11 @@ export function scaffold(options) {
     const substitutions = {
         NAME: name,
         DESCRIPTION: options.description ?? `A Rigline plugin called ${name}.`,
+        RIGLINE_RANGE: options.riglineRange ?? riglineRange(),
     };
     const files = [];
     for (const source of walk(templateDir)) {
         const relativePath = substitute(relative(templateDir, source), substitutions);
-        // npm renames a `.gitignore` inside a published tarball, so the template ships it undotted and
-        // it is put back here. Without this the scaffolded repository arrives with none at all.
         const written = relativePath === "gitignore" ? ".gitignore" : relativePath;
         const target = join(dir, written);
         mkdirSync(dirname(target), { recursive: true });
@@ -64,7 +47,6 @@ export function scaffold(options) {
     files.sort();
     return { dir, name, files };
 }
-/** Every file under `root`, recursively, in a stable order. */
 function walk(root) {
     const found = [];
     for (const entry of readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
@@ -76,7 +58,6 @@ function walk(root) {
     }
     return found;
 }
-/** `__NAME__` and `__DESCRIPTION__`, in a path or in a file's contents. */
 function substitute(text, substitutions) {
     let out = text;
     for (const [key, value] of Object.entries(substitutions)) {
@@ -84,10 +65,7 @@ function substitute(text, substitutions) {
     }
     return out;
 }
-/** Everything this scaffold wants said afterwards, in the order it wants doing. */
 export function nextSteps(result) {
-    // The relative path, unless it is the worse of the two: a target several directories up produces
-    // a run of `..` nobody wants to read, let alone type.
     const from = relative(process.cwd(), result.dir);
     const here = from === "" ? "." : from.startsWith("..") ? result.dir : from;
     return [
@@ -105,10 +83,6 @@ export function nextSteps(result) {
         `${join(here, "README.md")} has the rest, including the four rules worth reading first.`,
     ].join("\n");
 }
-/**
- * The command. One positional, the directory; `--name` where it should differ from the directory's
- * own, and `--description` for the sentence that lands in three files.
- */
 export function main(argv) {
     const positionals = [];
     let name;
@@ -146,14 +120,12 @@ export function main(argv) {
         throw error;
     }
 }
-const USAGE = `create-rigline-plugin
-
-  pnpm create rigline-plugin <directory> [--name NAME] [--description TEXT]
-
-Scaffolds a pnpm workspace holding one Rigline plugin. The directory's own name is the plugin's
+const USAGE = `create-rigline-plugin
+
+  pnpm create rigline-plugin <directory> [--name NAME] [--description TEXT]
+
+Scaffolds a pnpm workspace holding one Rigline plugin. The directory's own name is the plugin's
 unless --name says otherwise; a second plugin later is a copy of the first.`;
-// Only when run as the command, so that a test may import `scaffold` without scaffolding anything.
-// Compared as resolved paths rather than by suffix, which a directory named after the bin defeats.
 if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
     process.exitCode = main(process.argv.slice(2));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rigline-plugin",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.2",
   "description": "Scaffold a workspace for Claude Code VS Code extension plugins",
   "keywords": [
     "rigline",
@@ -22,13 +22,14 @@
   "license": "MIT",
   "files": [
     "dist",
+    "!dist/**/*.map",
     "template"
   ],
   "bin": {
     "create-rigline-plugin": "./dist/index.js"
   },
   "devDependencies": {
-    "@rigline/plugin-api": "1.0.0-alpha.0"
+    "@rigline/plugin-api": "1.0.0-alpha.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/template/.github/workflows/release.yml

@@ -0,0 +1,105 @@
+# Publish your plugins to npm, without an npm token ever being stored here.
+#
+# GitHub authenticates to npm over OIDC, so the secret this workflow would otherwise need does not
+# exist. What it does is *stage*: a staged version sits in a queue that nobody can install until you
+# approve it from your own machine with 2FA. Approving says you meant to ship it.
+#
+#     pnpm stage approve
+#
+# Before this works, once per package, on npmjs.com:
+#
+#   1. Publish the first version by hand. A package that does not exist yet has nothing for a
+#      trusted publisher to attach to: `pnpm publish -r --otp <code>` (a one-time password, not a
+#      token — there is then nothing to store or revoke).
+#   2. Add a trusted publisher under the package's settings, naming this repository and this file
+#      by path. Renaming this file breaks the exchange until the entry is edited to match.
+#      Set its permission to stage-only.
+#
+# `-r` stages every package in the workspace whose version is not already on the registry, in
+# dependency order, so bumping one plugin releases one plugin.
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      dist_tag:
+        description: The tag these versions go to. A prerelease belongs on `next`, not `latest`.
+        type: choice
+        options: [latest, next]
+        default: latest
+      dry_run:
+        description: Build, test and pack, but stage nothing
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  stage:
+    name: Stage to npm
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # What lets the runner ask GitHub for the token npm exchanges for a publishing one. Without
+      # it there is nothing to send, and pnpm falls back to looking for a credential that is not
+      # here — reporting that as a warning, not an error, so read the log rather than the tick.
+      id-token: write
+    steps:
+      - name: Refuse anything but the default branch
+        if: github.ref_name != github.event.repository.default_branch
+        run: |
+          echo "::error::Releases go from ${{ github.event.repository.default_branch }}."
+          exit 1
+
+      - uses: actions/checkout@v5
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 26
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm typecheck
+      - run: pnpm build
+      - run: pnpm test
+
+      # `generated.ts` is committed, so this needs no installed extension. `rigline codegen` is
+      # something you run locally against your own editor and commit the result of.
+      - name: Stage
+        if: ${{ !inputs.dry_run }}
+        run: pnpm stage publish -r --tag ${{ inputs.dist_tag }} --provenance --report-summary --no-git-checks
+
+      - name: Pack only
+        if: ${{ inputs.dry_run }}
+        run: pnpm stage publish -r --tag ${{ inputs.dist_tag }} --dry-run --report-summary --no-git-checks
+
+      # Nothing notifies you that a stage is waiting, and npm returns no stage id to quote, so the
+      # run summary names what went up and the one command that finishes the job.
+      - name: Summarise
+        if: always()
+        run: |
+          if [ ! -f pnpm-publish-summary.json ]; then
+            echo "## Nothing was staged" >> "$GITHUB_STEP_SUMMARY"
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo "Either the run stopped before staging, or every version is already on the registry." >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+          node -e '
+            const s = JSON.parse(require("fs").readFileSync("pnpm-publish-summary.json", "utf8"));
+            const out = [];
+            const staged = s.publishedPackages ?? [];
+            if (staged.length === 0) {
+              out.push("## Nothing was staged", "", "Every version is already on the registry. Bump one to release it.");
+            } else {
+              out.push("## Staged, and awaiting approval", "", "| package | version |", "| --- | --- |");
+              for (const p of staged) out.push(`| \`${p.name}\` | \`${p.version}\` |`);
+              out.push("", "**Nobody can install these yet.** On a machine with your npm 2FA:", "", "```", "pnpm stage approve", "```", "",
+                "It lists what is queued and takes the batch under one one-time password. A version you would rather not ship needs no action — do not approve it, and it expires.");
+            }
+            require("fs").appendFileSync(process.env.GITHUB_STEP_SUMMARY, out.join("\n") + "\n");
+          '

package/template/README.md

@@ -1,67 +1,82 @@
-# __NAME__
-
-Plugins for the Claude Code VS Code extension, built with [Rigline](https://github.com/Rigline/Rigline).
-
-A plugin is one browser ES module and a `rigline.json` manifest. This workspace holds one to start
-with; adding a second is a directory copy.
-
-## First run
-
-    pnpm install
-    pnpm codegen      # harvest the installed extension, and commit the result
-    pnpm build
-    pnpm rigline add plugins/__NAME__
-
-Then reload the webview: **Developer: Reload Webviews** in the command palette. The badge appears
-in the composer footer.
-
-`pnpm codegen` writes `generated.ts` at this workspace's root: the identifiers the installed
-extension actually has, as types every plugin here compiles against. Commit it. It is replaced when
-you run against a newer extension, and the diff is how you find out what moved.
-
-## The loop while you work
-
-    pnpm rigline dev plugins/__NAME__
-
-Rebuilds and re-injects on every save. Reload webviews to see each change.
-
-## What a plugin declares
-
-Everything in `uses` is a dependency on the installed extension still having something. An update
-that retires one refuses this plugin by name, at install, rather than leaving it subtly broken —
-which is the whole reason to declare rather than to reach.
-
-    pnpm rigline check     # what this extension version would refuse, and why
-    pnpm rigline list      # every plugin installed, and what each says it can do
-
-Put a dependency you can do without under `uses.optional`: it is checked the same way and costs the
-plugin that one decoration rather than the whole plugin.
-
-## Testing
-
-`pnpm test` runs the pure half — the functions that do not touch the DOM. Whether a decoration
-lands in the right place, survives a re-render, or costs a row a line of height is a question only
-the app can answer: build, add, reload, look.
-
-## Publishing
-
-A plugin is published as an ordinary npm package carrying `rigline.json` and its built entry, and
-installed with `rigline add <name>`. Nothing about publishing is special: `rigline build` bundles
-everything the entry imports, so a published plugin has no runtime dependency to install, and
-`@rigline/plugin-api` stays a *devDependency*.
-
-    pnpm --filter rigline-plugin-__NAME__ publish
-
-## Rules that will cost you if you break them
-
-- **Never name a class from the bundle by hand.** They are minifier output and change every build.
-  Use `ctx.anchor("footerSpacer")` for curated names, and `ctx.cls(module, local)` — declared in the
-  manifest — for anything not curated yet.
-- **Never scope a stylesheet rule to an anchor's bare class.** One class is applied wherever that
-  look is wanted, so a rule written against it lands on every control wearing it. Scope to something
-  you placed.
-- **Ask what a container does about its children before decorating it.** The composer footer
-  measures its own element children and re-measures on any foreign change inside it; footer
-  decorations go beside `footerSpacer`, with `ctx.mountBefore`.
-- **Do not poll for an element.** `ctx.watch(name, …)` hands it over when it appears and again when
-  the app replaces it.
+# __NAME__
+
+Plugins for the Claude Code VS Code extension, built with [Rigline](https://github.com/Rigline/Rigline).
+
+A plugin is one browser ES module and a `rigline.json` manifest. This workspace holds one to start
+with; adding a second is a directory copy.
+
+## First run
+
+    pnpm install
+    pnpm codegen      # harvest the installed extension, and commit the result
+    pnpm build
+    pnpm rigline add plugins/__NAME__
+
+Then reload the webview: **Developer: Reload Webviews** in the command palette. The badge appears
+in the composer footer.
+
+`pnpm codegen` writes `generated.ts` at this workspace's root: the identifiers the installed
+extension actually has, as types every plugin here compiles against. Commit it. It is replaced when
+you run against a newer extension, and the diff is how you find out what moved.
+
+## The loop while you work
+
+    pnpm rigline dev plugins/__NAME__
+
+Rebuilds and re-injects on every save. Reload webviews to see each change.
+
+## What a plugin declares
+
+Everything in `uses` is a dependency on the installed extension still having something. An update
+that retires one refuses this plugin by name, at install, rather than leaving it subtly broken —
+which is the whole reason to declare rather than to reach.
+
+    pnpm rigline check     # what this extension version would refuse, and why
+    pnpm rigline list      # every plugin installed, and what each says it can do
+
+Put a dependency you can do without under `uses.optional`: it is checked the same way and costs the
+plugin that one decoration rather than the whole plugin.
+
+## Testing
+
+`pnpm test` runs the pure half — the functions that do not touch the DOM. Whether a decoration
+lands in the right place, survives a re-render, or costs a row a line of height is a question only
+the app can answer: build, add, reload, look.
+
+## Publishing
+
+A plugin is published as an ordinary npm package carrying `rigline.json` and its built entry, and
+installed with `rigline add <name>`. Nothing about publishing is special: `rigline build` bundles
+everything the entry imports, so a published plugin has no runtime dependency to install, and
+`@rigline/plugin-api` stays a *devDependency*.
+
+`.github/workflows/release.yml` does it from CI, with no npm token stored anywhere: GitHub
+authenticates to npm over OIDC, and what the workflow does is *stage* — a version nobody can
+install until you approve it from your own machine with 2FA.
+
+    pnpm stage approve
+
+Two things to set up once per package, the first time. Publish version one by hand, because a
+package that does not exist yet has nothing for a trusted publisher to attach to — `pnpm publish -r
+--otp <code>`, supplying a one-time password rather than creating a token, so there is nothing to
+store or to revoke afterwards. Then add a trusted publisher in the package's settings on npmjs.com,
+naming this repository and `release.yml` by path, with its permission set to stage-only. The
+workflow's own header repeats both, where you will be when you need them.
+
+Adding a second plugin later means one more of each: npm's exchange is per package, so a trusted
+publisher is too. That is friction on a second plugin, never on a second release — `-r` stages only
+what you bumped.
+
+## Rules that will cost you if you break them
+
+- **Never name a class from the bundle by hand.** They are minifier output and change every build.
+  Use `ctx.anchor("footerSpacer")` for curated names, and `ctx.cls(module, local)` — declared in the
+  manifest — for anything not curated yet.
+- **Never scope a stylesheet rule to an anchor's bare class.** One class is applied wherever that
+  look is wanted, so a rule written against it lands on every control wearing it. Scope to something
+  you placed.
+- **Ask what a container does about its children before decorating it.** The composer footer
+  measures its own element children and re-measures on any foreign change inside it; footer
+  decorations go beside `footerSpacer`, with `ctx.mountBefore`.
+- **Do not poll for an element.** `ctx.watch(name, …)` hands it over when it appears and again when
+  the app replaces it.

package/template/gitignore

@@ -1,3 +1,4 @@
-node_modules/
-dist/
-*.log
+node_modules/
+dist/
+*.log
+pnpm-publish-summary.json

package/template/package.json

@@ -1,19 +1,19 @@
-{
-  "name": "__NAME__-plugins",
-  "private": true,
-  "type": "module",
-  "packageManager": "pnpm@12.3.4",
-  "engines": { "node": ">=26" },
-  "scripts": {
-    "codegen": "rigline codegen",
-    "build": "pnpm -r build",
-    "typecheck": "pnpm -r typecheck",
-    "test": "vitest run"
-  },
-  "devDependencies": {
-    "@rigline/plugin-api": "^1.0.0",
-    "rigline": "^1.0.0",
-    "typescript": "^7.0.2",
-    "vitest": "^5.0.0"
-  }
-}
+{
+  "name": "__NAME__-plugins",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@12.3.4",
+  "engines": { "node": ">=26" },
+  "scripts": {
+    "codegen": "rigline codegen",
+    "build": "pnpm -r build",
+    "typecheck": "pnpm -r typecheck",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@rigline/plugin-api": "__RIGLINE_RANGE__",
+    "rigline": "__RIGLINE_RANGE__",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  }
+}

package/template/plugins/__NAME__/README.md

@@ -1,19 +1,19 @@
-# __NAME__
-
-__DESCRIPTION__
-
-## Depends on
-
-- `uses.anchors: ["footerSpacer"]` — the flexible gap dividing the composer footer's left cluster
-  from its right, and the anchor every footer decoration uses. The footer measures the widths of its
-  own element children to pick a fit stage; the spacer renders in every stage, so a decoration
-  beside it contributes a constant width and the measurement settles.
-- `uses.mount` — `ctx.watch` and `ctx.mountBefore`, which place the badge and keep it placed across
-  a re-render.
-- `uses.style` — one stylesheet, scoped to the class this plugin puts on its own element.
-- `uses.tools` — `ctx.onToolUse`, every completed tool call the assistant makes.
-
-## Notes
-
-`badgeText` is exported and tested because it is the half a plain test run can hold. Everything
-else is a question about the app, and only the app can answer it.
+# __NAME__
+
+__DESCRIPTION__
+
+## Depends on
+
+- `uses.anchors: ["footerSpacer"]` — the flexible gap dividing the composer footer's left cluster
+  from its right, and the anchor every footer decoration uses. The footer measures the widths of its
+  own element children to pick a fit stage; the spacer renders in every stage, so a decoration
+  beside it contributes a constant width and the measurement settles.
+- `uses.mount` — `ctx.watch` and `ctx.mountBefore`, which place the badge and keep it placed across
+  a re-render.
+- `uses.style` — one stylesheet, scoped to the class this plugin puts on its own element.
+- `uses.tools` — `ctx.onToolUse`, every completed tool call the assistant makes.
+
+## Notes
+
+`badgeText` is exported and tested because it is the half a plain test run can hold. Everything
+else is a question about the app, and only the app can answer it.

package/template/plugins/__NAME__/package.json

@@ -1,16 +1,16 @@
-{
-  "name": "rigline-plugin-__NAME__",
-  "version": "0.1.0",
-  "description": "__DESCRIPTION__",
-  "type": "module",
-  "license": "MIT",
-  "files": ["dist", "rigline.json"],
-  "scripts": {
-    "build": "rigline build",
-    "typecheck": "tsc -p tsconfig.json"
-  },
-  "devDependencies": {
-    "@rigline/plugin-api": "^1.0.0",
-    "rigline": "^1.0.0"
-  }
-}
+{
+  "name": "rigline-plugin-__NAME__",
+  "version": "0.1.0",
+  "description": "__DESCRIPTION__",
+  "type": "module",
+  "license": "MIT",
+  "files": ["dist", "rigline.json"],
+  "scripts": {
+    "build": "rigline build",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@rigline/plugin-api": "__RIGLINE_RANGE__",
+    "rigline": "__RIGLINE_RANGE__"
+  }
+}

package/template/plugins/__NAME__/rigline.json

@@ -1,14 +1,14 @@
-{
-  "$schema": "../../node_modules/@rigline/plugin-api/schema/manifest.json",
-  "api": 1,
-  "name": "__NAME__",
-  "description": "__DESCRIPTION__",
-  "entry": "dist/index.js",
-  "surfaces": ["editor", "sidebar"],
-  "uses": {
-    "anchors": ["footerSpacer"],
-    "mount": true,
-    "style": true,
-    "tools": true
-  }
-}
+{
+  "$schema": "../../node_modules/@rigline/plugin-api/schema/manifest.json",
+  "api": 1,
+  "name": "__NAME__",
+  "description": "__DESCRIPTION__",
+  "entry": "dist/index.js",
+  "surfaces": ["editor", "sidebar"],
+  "uses": {
+    "anchors": ["footerSpacer"],
+    "mount": true,
+    "style": true,
+    "tools": true
+  }
+}

package/template/plugins/__NAME__/src/index.test.ts

@@ -1,21 +1,21 @@
-/**
- * The pure half of the plugin, under plain `vitest`.
- *
- * Verification splits three ways, and knowing which tier a question belongs to is most of writing
- * a test that is worth having. A pure function is this tier. Whether a decoration lands in the
- * right place, survives a re-render, or costs the row a line of height is a question about the app,
- * and only the app can answer it: build, `rigline add`, reload the webview, look.
- */
-import { describe, expect, it } from "vitest";
-import { badgeText } from "./index.ts";
-
-describe("badgeText", () => {
-  it("says something before anything has happened", () => {
-    expect(badgeText(0)).toBe("no tools yet");
-  });
-
-  it("does not make a reader read (s)", () => {
-    expect(badgeText(1)).toBe("1 tool call");
-    expect(badgeText(2)).toBe("2 tool calls");
-  });
-});
+/**
+ * The pure half of the plugin, under plain `vitest`.
+ *
+ * Verification splits three ways, and knowing which tier a question belongs to is most of writing
+ * a test that is worth having. A pure function is this tier. Whether a decoration lands in the
+ * right place, survives a re-render, or costs the row a line of height is a question about the app,
+ * and only the app can answer it: build, `rigline add`, reload the webview, look.
+ */
+import { describe, expect, it } from "vitest";
+import { badgeText } from "./index.ts";
+
+describe("badgeText", () => {
+  it("says something before anything has happened", () => {
+    expect(badgeText(0)).toBe("no tools yet");
+  });
+
+  it("does not make a reader read (s)", () => {
+    expect(badgeText(1)).toBe("1 tool call");
+    expect(badgeText(2)).toBe("2 tool calls");
+  });
+});

package/template/plugins/__NAME__/src/index.ts

@@ -1,64 +1,64 @@
-/**
- * __DESCRIPTION__
- *
- * A worked example of the loop every plugin is: declare what you depend on in `rigline.json`, wait
- * to be handed the element you decorate, and put something beside it. Replace the body; keep the
- * shape.
- */
-import { definePlugin, type PluginContext, type Teardown } from "@rigline/plugin-api";
-
-/**
- * What the badge reads, for a given number of tool calls.
- *
- * Pure, and exported, because this is the half a plain `vitest` run can hold: anything that touches
- * the DOM wants the app itself, and anything that does not should not need it. See
- * `src/index.test.ts`.
- */
-export function badgeText(calls: number): string {
-  if (calls === 0) return "no tools yet";
-  return `${calls} tool ${calls === 1 ? "call" : "calls"}`;
-}
-
-export default definePlugin({
-  setup(ctx: PluginContext): Teardown {
-    let calls = 0;
-    const badge = document.createElement("span");
-    badge.className = "example-badge";
-    badge.textContent = badgeText(calls);
-
-    // Scoped to a class this plugin put on its own element. Never scope a rule to an anchor's bare
-    // class: one class is applied wherever that look is wanted, so a rule written against it lands
-    // on every control wearing it. See the anchors guide.
-    const stopStyle = ctx.style(`
-      .example-badge {
-        font-size: 11px;
-        opacity: 0.7;
-        padding: 0 6px;
-        white-space: nowrap;
-      }
-    `);
-
-    // Every completed tool call the assistant makes. `uses.tools` is what makes this fire; without
-    // the declaration it throws and disables the plugin, which is the point of declaring.
-    const stopTools = ctx.onToolUse(() => {
-      calls += 1;
-      badge.textContent = badgeText(calls);
-    });
-
-    // `watch` hands over the element for an anchor whenever one is in the document, and again if
-    // the app replaces it. No plugin polls for an element.
-    //
-    // `footerSpacer` and `mountBefore` together, rather than any other footer anchor: the composer
-    // footer measures the widths of its own element children to pick a fit stage, and resets that
-    // measurement on any foreign change inside it. A decoration whose membership of the footer
-    // changes with the stage fights the ladder that moved it. The spacer renders in every stage, so
-    // a decoration beside it contributes a constant width and the ladder settles.
-    const stopWatch = ctx.watch("footerSpacer", (spacer) => ctx.mountBefore(spacer, () => badge));
-
-    return () => {
-      stopWatch();
-      stopTools();
-      stopStyle();
-    };
-  },
-});
+/**
+ * __DESCRIPTION__
+ *
+ * A worked example of the loop every plugin is: declare what you depend on in `rigline.json`, wait
+ * to be handed the element you decorate, and put something beside it. Replace the body; keep the
+ * shape.
+ */
+import { definePlugin, type PluginContext, type Teardown } from "@rigline/plugin-api";
+
+/**
+ * What the badge reads, for a given number of tool calls.
+ *
+ * Pure, and exported, because this is the half a plain `vitest` run can hold: anything that touches
+ * the DOM wants the app itself, and anything that does not should not need it. See
+ * `src/index.test.ts`.
+ */
+export function badgeText(calls: number): string {
+  if (calls === 0) return "no tools yet";
+  return `${calls} tool ${calls === 1 ? "call" : "calls"}`;
+}
+
+export default definePlugin({
+  setup(ctx: PluginContext): Teardown {
+    let calls = 0;
+    const badge = document.createElement("span");
+    badge.className = "example-badge";
+    badge.textContent = badgeText(calls);
+
+    // Scoped to a class this plugin put on its own element. Never scope a rule to an anchor's bare
+    // class: one class is applied wherever that look is wanted, so a rule written against it lands
+    // on every control wearing it. See the anchors guide.
+    const stopStyle = ctx.style(`
+      .example-badge {
+        font-size: 11px;
+        opacity: 0.7;
+        padding: 0 6px;
+        white-space: nowrap;
+      }
+    `);
+
+    // Every completed tool call the assistant makes. `uses.tools` is what makes this fire; without
+    // the declaration it throws and disables the plugin, which is the point of declaring.
+    const stopTools = ctx.onToolUse(() => {
+      calls += 1;
+      badge.textContent = badgeText(calls);
+    });
+
+    // `watch` hands over the element for an anchor whenever one is in the document, and again if
+    // the app replaces it. No plugin polls for an element.
+    //
+    // `footerSpacer` and `mountBefore` together, rather than any other footer anchor: the composer
+    // footer measures the widths of its own element children to pick a fit stage, and resets that
+    // measurement on any foreign change inside it. A decoration whose membership of the footer
+    // changes with the stage fights the ladder that moved it. The spacer renders in every stage, so
+    // a decoration beside it contributes a constant width and the ladder settles.
+    const stopWatch = ctx.watch("footerSpacer", (spacer) => ctx.mountBefore(spacer, () => badge));
+
+    return () => {
+      stopWatch();
+      stopTools();
+      stopStyle();
+    };
+  },
+});

package/template/plugins/__NAME__/tsconfig.json

@@ -1,5 +1,5 @@
-{
-  "extends": "../../tsconfig.plugin.json",
-  "include": ["src/**/*.ts"],
-  "exclude": ["src/**/*.test.ts"]
-}
+{
+  "extends": "../../tsconfig.plugin.json",
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts"]
+}

package/template/pnpm-workspace.yaml

@@ -1,21 +1,21 @@
-packages:
-  - plugins/*
-
-# Supply-chain settings, written down rather than inherited.
-#
-# Three of these are pnpm's own defaults today. They are stated anyway, because a default is not a
-# position: a fresh clone on a different pnpm, or a default that moves, would quietly change what
-# this repository is willing to install without anyone deciding to.
-#
-# minimumReleaseAge is the rule rigline applies to plugins, applied here to your own dependencies:
-# a day is where a compromised publish is usually caught, and a day of latency costs nothing.
-minimumReleaseAge: 1440
-
-# Only a direct dependency may come from a git repository or a tarball URL. A transitive dependency
-# that resolves outside the registry is the shape of a supply-chain problem rather than of an
-# ordinary package.
-blockExoticSubdeps: true
-
-# No dependency may run an install script. Empty because nothing here needs one; the day something
-# does, a person decides about it by name, here.
-allowBuilds: {}
+packages:
+  - plugins/*
+
+# Supply-chain settings, written down rather than inherited.
+#
+# Three of these are pnpm's own defaults today. They are stated anyway, because a default is not a
+# position: a fresh clone on a different pnpm, or a default that moves, would quietly change what
+# this repository is willing to install without anyone deciding to.
+#
+# minimumReleaseAge is the rule rigline applies to plugins, applied here to your own dependencies:
+# a day is where a compromised publish is usually caught, and a day of latency costs nothing.
+minimumReleaseAge: 1440
+
+# Only a direct dependency may come from a git repository or a tarball URL. A transitive dependency
+# that resolves outside the registry is the shape of a supply-chain problem rather than of an
+# ordinary package.
+blockExoticSubdeps: true
+
+# No dependency may run an install script. Empty because nothing here needs one; the day something
+# does, a person decides about it by name, here.
+allowBuilds: {}

package/template/tsconfig.base.json

@@ -1,19 +1,19 @@
-{
-  "compilerOptions": {
-    "target": "esnext",
-    "module": "nodenext",
-    "moduleResolution": "nodenext",
-    "moduleDetection": "force",
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noFallthroughCasesInSwitch": true,
-    "isolatedModules": true,
-    "verbatimModuleSyntax": true,
-    "erasableSyntaxOnly": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true
-  }
-}
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "moduleDetection": "force",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}

package/template/tsconfig.plugin.json

@@ -1,11 +1,11 @@
-{
-  "//": "The base every plugin here extends. `files` names the committed harvest so that its module augmentation is in each plugin's own program: augmentation is per-program, so a plugin whose tsconfig does not pull generated.ts in compiles with every extension identifier widened to `string`. Relative paths in an extended config resolve against the config that declared them, so this one entry serves every plugin however deep it sits. A plugin's own tsconfig overrides `include` and leaves `files` alone. That augmentation resolves `@rigline/plugin-api` from this directory rather than from the plugin's, which is why the workspace root depends on it too.",
-  "extends": "./tsconfig.base.json",
-  "compilerOptions": {
-    "lib": ["esnext", "dom"],
-    "types": [],
-    "noEmit": true,
-    "allowImportingTsExtensions": true
-  },
-  "files": ["generated.ts"]
-}
+{
+  "//": "The base every plugin here extends. `files` names the committed harvest so that its module augmentation is in each plugin's own program: augmentation is per-program, so a plugin whose tsconfig does not pull generated.ts in compiles with every extension identifier widened to `string`. Relative paths in an extended config resolve against the config that declared them, so this one entry serves every plugin however deep it sits. A plugin's own tsconfig overrides `include` and leaves `files` alone. That augmentation resolves `@rigline/plugin-api` from this directory rather than from the plugin's, which is why the workspace root depends on it too.",
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["esnext", "dom"],
+    "types": [],
+    "noEmit": true,
+    "allowImportingTsExtensions": true
+  },
+  "files": ["generated.ts"]
+}

package/dist/index.js.map

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