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

package/README.md

@@ -42,4 +42,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rigline-plugin",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.4",
   "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,7 +32,7 @@
     "create-rigline-plugin": "./dist/index.js"
   },
   "devDependencies": {
-    "@rigline/plugin-api": "1.0.0-alpha.1"
+    "@rigline/plugin-api": "1.0.0-alpha.4"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.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

@@ -43,6 +43,11 @@ plugin that one decoration rather than the whole plugin.
 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
@@ -50,7 +55,38 @@ installed with `rigline add <name>`. Nothing about publishing is special: `rigli
 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
+`.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,7 +3,7 @@
   "private": true,
   "type": "module",
   "packageManager": "pnpm@12.3.4",
-  "engines": { "node": ">=26" },
+  "engines": { "node": ">=22.12.0" },
   "scripts": {
     "codegen": "rigline codegen",
     "build": "pnpm -r build",

package/template/plugins/__NAME__/package.json

@@ -2,8 +2,10 @@
   "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",

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();