create-rigline-plugin 1.0.0-alpha.1 → 1.0.0-alpha.10

package/README.md

@@ -5,6 +5,10 @@ Claude Code VS Code extension.
 
     npm create rigline-plugin my-plugins
 
+A plugin runs inside a modification of Anthropic's extension, so the
+[plugin policy](https://github.com/Rigline/Rigline/blob/main/docs/plugin-policy.md) applies to it —
+whether or not you ever publish it. One page, and the scaffolded README points at it too.
+
 ## What you get
 
 A pnpm workspace with `plugins/*` and one plugin in it, rather than a single-plugin repository. The
@@ -29,6 +33,11 @@ Then:
 
 and *Developer: Reload Webviews*.
 
+The workspace declares `@rigline/core` — the engine, which carries the `rigline-engine` command its
+`build` and `codegen` scripts run — and never `rigline`, which is the layer a *user* installs to
+fetch that engine. `pnpm rigline <verb>` here is a script forwarding to the engine in your own
+`node_modules`, so the loop above needs nothing installed globally.
+
 `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.
@@ -42,4 +51,7 @@ is the one ordering dependency in the whole arrangement.
 
 [Authoring guide](https://github.com/Rigline/Rigline/blob/main/docs/authoring.md)
 
+[Changelog](https://github.com/Rigline/Rigline/blob/main/CHANGELOG.md) — every package in this
+workspace shares it, and one version number.
+
 MIT.

package/dist/index.js

@@ -30,10 +30,12 @@ export function scaffold(options) {
     if (!existsSync(templateDir)) {
         throw new ScaffoldError(`the template is missing from this package: ${templateDir}`);
     }
+    const range = options.riglineRange ?? riglineRange();
     const substitutions = {
         NAME: name,
         DESCRIPTION: options.description ?? `A Rigline plugin called ${name}.`,
-        RIGLINE_RANGE: options.riglineRange ?? riglineRange(),
+        RIGLINE_RANGE: range,
+        RIGLINE_VERSION: range.replace(/^\^/, ""),
     };
     const files = [];
     for (const source of walk(templateDir)) {
@@ -81,6 +83,10 @@ export function nextSteps(result) {
         "Then reload the webview: Developer: Reload Webviews.",
         "",
         `${join(here, "README.md")} has the rest, including the four rules worth reading first.`,
+        "",
+        "Read the plugin policy once — what Rigline promises Anthropic, and the part your plugin has",
+        "to hold up. It applies whether or not you ever publish this:",
+        "  https://github.com/Rigline/Rigline/blob/main/docs/plugin-policy.md",
     ].join("\n");
 }
 export function main(argv) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rigline-plugin",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.10",
   "description": "Scaffold a workspace for Claude Code VS Code extension plugins",
   "keywords": [
     "rigline",
@@ -20,6 +20,9 @@
   "author": "Lionell Pack",
   "type": "module",
   "license": "MIT",
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "files": [
     "dist",
     "!dist/**/*.map",
@@ -29,10 +32,10 @@
     "create-rigline-plugin": "./dist/index.js"
   },
   "devDependencies": {
-    "@rigline/plugin-api": "1.0.0-alpha.1"
+    "@rigline/plugin-api": "1.0.0-alpha.10"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json"
   }
 }

package/template/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+# Your plugins, checked on every push and every pull request. The release workflow runs the same
+# steps again before it stages anything, so this is the copy that tells you early — and the copy a
+# contributor's pull request gets, which is the whole reason it is separate.
+#
+# There is no lint step because this workspace ships no linter. Add one here if you add one.
+name: CI
+
+on:
+  push:
+    # GitHub takes no expression here, so your default branch cannot be filled in for you. These
+    # are the two common names; edit if yours is neither.
+    branches: [main, master]
+  pull_request:
+
+permissions:
+  contents: read
+
+# A push supersedes the run before it on the same ref, and a pull request supersedes its own last
+# push. Two runs of one ref prove the same thing, and the newer one is what is being asked about.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: Node ${{ matrix.node }}
+    runs-on: ubuntu-latest
+    strategy:
+      # Every rung reports. A failure on the floor and a failure on the newest runtime are
+      # different bugs, and cancelling the rest hides which one this is.
+      fail-fast: false
+      matrix:
+        # The first is the floor this workspace's package.json declares in `engines`, pinned
+        # exactly so that the number claimed is a number something ran; the others float to the
+        # latest of their major, which says the major is supported rather than that a patch was
+        # tested. Cutting this to one rung is a reasonable thing to do — then drop the `engines`
+        # claim to match, because a floor nothing runs on is a guess.
+        node: ["22.12.0", "24", "26"]
+    steps:
+      - uses: actions/checkout@v5
+
+      # Pinned exactly rather than to the major: this action's `v6` tag still resolves to the last
+      # release before pnpm v12 support, and `v4` runs on a runner runtime GitHub has deprecated.
+      - uses: pnpm/action-setup@v6.1.0
+
+      # After pnpm, never before: `cache: pnpm` asks pnpm where its store is.
+      - uses: actions/setup-node@v5
+        with:
+          node-version: ${{ matrix.node }}
+          cache: pnpm
+
+      # Needs `pnpm-lock.yaml` committed, which is why nothing ignores it. Installing what the
+      # lockfile says is the point: a run that resolved its own dependencies would be testing
+      # something nobody has.
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm typecheck
+
+      # Before the tests, because a test that imports a built entry should import this build.
+      - run: pnpm build
+
+      - run: pnpm test

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

@@ -0,0 +1,130 @@
+# 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
+
+      # npm binds a provenance attestation to the package's `repository` field, so a package
+      # without one cannot be staged with `--provenance` at all. Asked here, before the build, so
+      # that the answer is a package name rather than an error about attestations two minutes in.
+      # A dry run is checked too: a rehearsal that skips this rehearses a different release.
+      - name: Refuse a publishable package with no repository
+        run: |
+          node -e '
+            const fs = require("fs");
+            const dirs = fs.existsSync("plugins") ? fs.readdirSync("plugins") : [];
+            const missing = [];
+            for (const dir of dirs) {
+              const path = `plugins/${dir}/package.json`;
+              if (!fs.existsSync(path)) continue;
+              const manifest = JSON.parse(fs.readFileSync(path, "utf8"));
+              if (!manifest.private && !manifest.repository) missing.push(manifest.name || dir);
+            }
+            if (missing.length === 0) process.exit(0);
+            console.log(`::error::No "repository" field in ${missing.join(", ")}. npm binds a provenance attestation to it, so --provenance cannot stage a package without one.`);
+            process.exit(1);
+          '
+
+      # Pinned exactly rather than to the major: this action's `v6` tag still resolves to the last
+      # release before pnpm v12 support, and `v4` runs on a runner runtime GitHub has deprecated.
+      - uses: pnpm/action-setup@v6.1.0
+      - 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 pnpm's publish output carries no stage id
+      # to quote (the registry has one; `npm stage list` shows it). 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

@@ -37,20 +37,73 @@ which is the whole reason to declare rather than to reach.
 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.
 
+## The plugin policy
+
+**This applies whether or not you ever publish.** A plugin you wrote for yourself and will never
+share still runs inside a modification of Anthropic's extension, and Anthropic's terms still apply
+to what it does on your machine. Read it once, at
+[docs/plugin-policy.md](https://github.com/Rigline/Rigline/blob/main/docs/plugin-policy.md); it
+takes a minute.
+
+Rigline modifies Anthropic's extension and publishes a compliance position saying what it does and
+does not do. Your plugin runs inside that modification, so the position has to hold for it too.
+
+Most of it is not left to you — the webview has no network egress, no filesystem, and no way into
+the extension host, so the usual ways to do harm are absent rather than forbidden. What the policy
+asks is the part the architecture cannot cover: do not deceive the person using it, do not reach for
+credentials, do not carry conversation content off the machine by a path the closed network does not
+cover, and keep any host patch to switching on a capability the extension already has.
+
 ## 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.
 
+`.github/workflows/ci.yml` runs typecheck, build and test on every push and every pull request,
+over three Node versions — the same set the release workflow runs, so nothing reaches a release
+that a pull request would not already have failed on. Commit `pnpm-lock.yaml`: CI installs what it
+says rather than resolving its own.
+
 ## 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
+installed with `rigline add <name>`. Nothing about publishing is special: `rigline-engine build`
+bundles everything the entry imports, so a published plugin has no runtime dependency to install,
+and both `@rigline/core` and `@rigline/plugin-api` stay *devDependencies*.
+
+`.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
+
+**One field to fill in before the first publish: `repository`.** npm binds a provenance attestation
+to it, and this workflow stages with provenance, so a package without one cannot be staged at all.
+Nothing can scaffold it for you — a guessed URL would be a wrong one in the registry rather than a
+missing one — so the workflow refuses by name, before it builds anything, until it is there:
+
+    "repository": {
+      "type": "git",
+      "url": "git+https://github.com/you/your-repo.git",
+      "directory": "plugins/__NAME__"
+    }
+
+`homepage` and `bugs` are worth the same minute; npm shows them on the package page. A `LICENSE`
+file is not scaffolded either, because the copyright line is yours to write — the manifest says
+MIT, and npm ships a licence file whatever `files` says, so adding one is the whole job. The
+`rigline-plugin` keyword is already there: it is how somebody finds a plugin on npm.
+
+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
 

package/template/gitignore

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

package/template/package.json

@@ -3,16 +3,18 @@
   "private": true,
   "type": "module",
   "packageManager": "pnpm@12.3.4",
-  "engines": { "node": ">=26" },
+  "engines": { "node": ">=22.12.0" },
   "scripts": {
-    "codegen": "rigline codegen",
+    "rigline": "rigline-engine",
+    "codegen": "rigline-engine codegen",
     "build": "pnpm -r build",
     "typecheck": "pnpm -r typecheck",
     "test": "vitest run"
   },
   "devDependencies": {
+    "@rigline/core": "__RIGLINE_RANGE__",
     "@rigline/plugin-api": "__RIGLINE_RANGE__",
-    "rigline": "__RIGLINE_RANGE__",
+    "rolldown": "^1.2.8",
     "typescript": "^7.0.2",
     "vitest": "^5.0.0"
   }

package/template/plugins/__NAME__/package.json

@@ -2,15 +2,17 @@
   "name": "rigline-plugin-__NAME__",
   "version": "0.1.0",
   "description": "__DESCRIPTION__",
+  "keywords": ["rigline-plugin", "rigline", "claude-code", "vscode"],
   "type": "module",
   "license": "MIT",
+  "publishConfig": { "access": "public" },
   "files": ["dist", "rigline.json"],
   "scripts": {
-    "build": "rigline build",
+    "build": "rigline-engine build",
     "typecheck": "tsc -p tsconfig.json"
   },
   "devDependencies": {
-    "@rigline/plugin-api": "__RIGLINE_RANGE__",
-    "rigline": "__RIGLINE_RANGE__"
+    "@rigline/core": "__RIGLINE_RANGE__",
+    "@rigline/plugin-api": "__RIGLINE_RANGE__"
   }
 }

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

@@ -4,7 +4,7 @@
  * 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.
+ * and only the app can answer it: `pnpm build`, `pnpm rigline add`, reload the webview, look.
  */
 import { describe, expect, it } from "vitest";
 import { badgeText } from "./index.ts";

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

@@ -55,7 +55,25 @@ export default definePlugin({
     // a decoration beside it contributes a constant width and the ladder settles.
     const stopWatch = ctx.watch("footerSpacer", (spacer) => ctx.mountBefore(spacer, () => badge));
 
+    // One line in Rigline's diagnostics panel, under this plugin's name. It declares nothing: the
+    // host calls it, hands it nothing, and gets a verdict back.
+    //
+    // Worth the four lines from the first day, because the failure a plugin has is normally silent.
+    // An extension update can leave this one loaded, declared, styled and drawing nothing, and
+    // every other line in that panel will say it is fine. Ask the question only your own state can
+    // answer — here, whether the badge is actually in the document — and say `n/a` with a reason
+    // when there is nothing to report yet.
+    //
+    // The host runs this about once a second for the life of the window, so read state you already
+    // keep. Do not walk the DOM or recompute an answer here; do that work where it already happens.
+    const stopCheck = ctx.check("badge is mounted", () =>
+      badge.isConnected
+        ? { verdict: "pass", detail: badgeText(calls) }
+        : { verdict: "fail", detail: "the badge is not in the document" },
+    );
+
     return () => {
+      stopCheck();
       stopWatch();
       stopTools();
       stopStyle();

package/template/pnpm-workspace.yaml

@@ -3,14 +3,24 @@ packages:
 
 # 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.
+# Two of these restate a pnpm default. 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 is the third and is not a restatement. pnpm applies the same cutoff by default
+# but merely records anything younger; writing it down is what makes it refuse. That is the rule
+# rigline applies to plugins, applied here to your own dependencies: a day is where a compromised
+# publish is usually caught.
 minimumReleaseAge: 1440
 
+# The exception, and the reason for it: pnpm resolves to the newest version in range that is old
+# enough, and these two ranges have no older version in them to fall back on. Scaffolding you ran
+# minutes ago is this same release, so waiting a day for the rest of it protects nothing. Drop these
+# once the versions are a day old; a later Rigline release is gated like anything else.
+minimumReleaseAgeExclude:
+  - "@rigline/core@__RIGLINE_VERSION__"
+  - "@rigline/plugin-api@__RIGLINE_VERSION__"
+
 # 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.