create-rigline-plugin 1.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lionell Pack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# create-rigline-plugin
+
+Scaffolds a workspace for [Rigline](https://github.com/Rigline/Rigline) plugins — plugins for the
+Claude Code VS Code extension.
+
+    npm create rigline-plugin my-plugins
+
+## What you get
+
+A pnpm workspace with `plugins/*` and one plugin in it, rather than a single-plugin repository. The
+multi-plugin shape scaffolds correctly for one plugin and a second is then a directory copy, where a
+single-plugin template could not grow into a workspace without a restructure.
+
+    my-plugins/
+      generated.ts              the harvested identifiers, shared by every plugin here
+      pnpm-workspace.yaml       with the supply-chain settings written down rather than inherited
+      tsconfig.base.json        pulls the root harvest into every plugin's program
+      plugins/my-plugin/
+        rigline.json            what the plugin declares it needs from the extension
+        src/index.ts            the plugin
+        src/index.test.ts
+
+Then:
+
+    pnpm install
+    pnpm codegen                # harvest your installed extension, and commit the result
+    pnpm build
+    pnpm rigline add plugins/my-plugin
+
+and *Developer: Reload Webviews*.
+
+`generated.ts` ships as a placeholder so a fresh scaffold typechecks before `codegen` has ever run.
+Once you run `codegen` it holds the identifiers *your* extension version actually has; commit it,
+and the diff when you run against a newer extension is how you find out what moved.
+
+## Why a workspace root at all
+
+The identifiers are harvested once, at the root, and imported by every plugin in the repository,
+because they all compile against the same installed extension. Module augmentation is per-program,
+so each plugin's tsconfig has to pull that harvest in — which the shared base config does, and which
+is the one ordering dependency in the whole arrangement.
+
+[Authoring guide](https://github.com/Rigline/Rigline/blob/main/docs/authoring.md)
+
+MIT.

package/dist/index.js

@@ -0,0 +1,160 @@
+#!/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 scaffold(options) {
+    const dir = resolve(options.target);
+    const name = options.name ?? basename(dir);
+    if (!NAME_PATTERN.test(name)) {
+        throw new ScaffoldError(`"${name}" is not a usable plugin name. It must start with a letter or digit and hold only ` +
+            "lowercase letters, digits, dot, dash and underscore.");
+    }
+    if (existsSync(dir) && readdirSync(dir).length > 0) {
+        throw new ScaffoldError(`${dir} is not empty`);
+    }
+    const templateDir = options.templateDir ?? defaultTemplateDir();
+    if (!existsSync(templateDir)) {
+        throw new ScaffoldError(`the template is missing from this package: ${templateDir}`);
+    }
+    const substitutions = {
+        NAME: name,
+        DESCRIPTION: options.description ?? `A Rigline plugin called ${name}.`,
+    };
+    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 });
+        writeFileSync(target, substitute(readFileSync(source, "utf8"), substitutions));
+        files.push(written.split("\\").join("/"));
+    }
+    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))) {
+        const path = join(root, entry.name);
+        if (entry.isDirectory())
+            found.push(...walk(path));
+        else
+            found.push(path);
+    }
+    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)) {
+        out = out.split(`__${key}__`).join(value);
+    }
+    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 [
+        `Created ${result.files.length} files in ${result.dir}`,
+        "",
+        "Next:",
+        `  cd ${here}`,
+        "  pnpm install",
+        "  pnpm codegen      # harvest the installed extension, and commit the result",
+        "  pnpm build",
+        `  pnpm rigline add plugins/${result.name}`,
+        "",
+        "Then reload the webview: Developer: Reload Webviews.",
+        "",
+        `${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;
+    let description;
+    for (let at = 0; at < argv.length; at++) {
+        const argument = argv[at];
+        if (argument === "--name")
+            name = argv[++at];
+        else if (argument === "--description")
+            description = argv[++at];
+        else if (argument === "-h" || argument === "--help") {
+            console.log(USAGE);
+            return 0;
+        }
+        else if (argument.startsWith("-")) {
+            console.error(`create-rigline-plugin: unknown option "${argument}"\n\n${USAGE}`);
+            return 1;
+        }
+        else
+            positionals.push(argument);
+    }
+    if (positionals.length !== 1) {
+        console.error(`create-rigline-plugin: expected one directory\n\n${USAGE}`);
+        return 1;
+    }
+    try {
+        console.log(nextSteps(scaffold({ target: positionals[0], name, description })));
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof ScaffoldError) {
+            console.error(`create-rigline-plugin: ${error.message}`);
+            return 1;
+        }
+        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
+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));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC1F,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,uFAAuF;AACvF,MAAM,YAAY,GAAG,8BAA8B,CAAC;AAwBpD,MAAM,OAAO,aAAc,SAAQ,KAAK;CAAG;AAE3C,8CAA8C;AAC9C,MAAM,UAAU,kBAAkB;IAChC,OAAO,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAwB;IAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,aAAa,CACrB,IAAI,IAAI,oFAAoF;YAC1F,sDAAsD,CACzD,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,aAAa,CAAC,GAAG,GAAG,eAAe,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,kBAAkB,EAAE,CAAC;IAChE,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,aAAa,CAAC,8CAA8C,WAAW,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,MAAM,aAAa,GAAkB;QACnC,IAAI,EAAE,IAAI;QACV,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,2BAA2B,IAAI,GAAG;KACvE,CAAC;IAEF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QACvC,MAAM,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,aAAa,CAAC,CAAC;QAC9E,+FAA+F;QAC/F,wFAAwF;QACxF,MAAM,OAAO,GAAG,YAAY,KAAK,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC;QAC3E,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAClC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,aAAa,CAAC,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC;QAC/E,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,IAAI,EAAE,CAAC;IACb,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC;AAED,+DAA+D;AAC/D,SAAS,IAAI,CAAC,IAAY;IACxB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAC3E,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAC7B,EAAE,CAAC;QACF,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,KAAK,CAAC,WAAW,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;;YAC9C,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,2EAA2E;AAC3E,SAAS,UAAU,CAAC,IAAY,EAAE,aAA4B;IAC5D,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;QACzD,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,SAAS,CAAC,MAAsB;IAC9C,iGAAiG;IACjG,sDAAsD;IACtD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3E,OAAO;QACL,WAAW,MAAM,CAAC,KAAK,CAAC,MAAM,aAAa,MAAM,CAAC,GAAG,EAAE;QACvD,EAAE;QACF,OAAO;QACP,QAAQ,IAAI,EAAE;QACd,gBAAgB;QAChB,8EAA8E;QAC9E,cAAc;QACd,8BAA8B,MAAM,CAAC,IAAI,EAAE;QAC3C,EAAE;QACF,sDAAsD;QACtD,EAAE;QACF,GAAG,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,8DAA8D;KACzF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,IAAuB;IAC1C,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,IAAI,IAAwB,CAAC;IAC7B,IAAI,WAA+B,CAAC;IAEpC,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC;QACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAW,CAAC;QACpC,IAAI,QAAQ,KAAK,QAAQ;YAAE,IAAI,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;aACxC,IAAI,QAAQ,KAAK,eAAe;YAAE,WAAW,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;aAC3D,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACpD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACnB,OAAO,CAAC,CAAC;QACX,CAAC;aAAM,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpC,OAAO,CAAC,KAAK,CAAC,0CAA0C,QAAQ,QAAQ,KAAK,EAAE,CAAC,CAAC;YACjF,OAAO,CAAC,CAAC;QACX,CAAC;;YAAM,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,KAAK,CAAC,oDAAoD,KAAK,EAAE,CAAC,CAAC;QAC3E,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,CAAC;QACH,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAW,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC;QAC1F,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;YACnC,OAAO,CAAC,KAAK,CAAC,0BAA0B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACzD,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,KAAK,GAAG;;;;;4EAK8D,CAAC;AAE7E,mGAAmG;AACnG,mGAAmG;AACnG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "create-rigline-plugin",
+  "version": "1.0.0-alpha.0",
+  "description": "Scaffold a workspace for Claude Code VS Code extension plugins",
+  "keywords": [
+    "rigline",
+    "claude-code",
+    "vscode",
+    "plugin",
+    "scaffold",
+    "create"
+  ],
+  "homepage": "https://github.com/Rigline/Rigline#readme",
+  "bugs": "https://github.com/Rigline/Rigline/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rigline/Rigline.git",
+    "directory": "packages/create-plugin"
+  },
+  "author": "Lionell Pack",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "template"
+  ],
+  "bin": {
+    "create-rigline-plugin": "./dist/index.js"
+  },
+  "devDependencies": {
+    "@rigline/plugin-api": "1.0.0-alpha.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}

package/template/README.md

@@ -0,0 +1,67 @@
+# __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.

package/template/generated.ts

@@ -0,0 +1,13 @@
+// A placeholder, so that this workspace typechecks before it has ever harvested anything.
+//
+// Replace it by running `pnpm codegen`, which reads the Claude Code extension installed on this
+// machine and writes the real file: a module augmentation naming every CSS module, class, message
+// type and payload field that extension has, plus the harvest the install flow diffs the next
+// version against. Commit the result the way you commit a lockfile.
+//
+// Until you do, `ctx.cls`, `ctx.onMessage` and `ctx.rewrite` accept any string rather than the
+// identifiers that exist. Everything still compiles and everything still runs; what you lose is
+// being told about a typo at your desk instead of at install time. A plugin written entirely
+// against curated anchors needs no harvest at all.
+
+export const EXTENSION_VERSION = "not harvested yet";

package/template/gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+*.log

package/template/package.json

@@ -0,0 +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"
+  }
+}

package/template/plugins/__NAME__/README.md

@@ -0,0 +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.

package/template/plugins/__NAME__/package.json

@@ -0,0 +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"
+  }
+}

package/template/plugins/__NAME__/rigline.json

@@ -0,0 +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
+  }
+}

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

@@ -0,0 +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");
+  });
+});

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

@@ -0,0 +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();
+    };
+  },
+});

package/template/plugins/__NAME__/tsconfig.json

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

package/template/pnpm-workspace.yaml

@@ -0,0 +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: {}

package/template/tsconfig.base.json

@@ -0,0 +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
+  }
+}

package/template/tsconfig.plugin.json

@@ -0,0 +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"]
+}