From 53a68e703946ea90e66e17ac4a20292c6610f952 Mon Sep 17 00:00:00 2001 From: Naveen Kumar Date: Thu, 10 Sep 2026 21:03:32 +0800 Subject: [PATCH] README: what adding a plugin actually takes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The old two-line note covered the first step and stopped, which is roughly where this repo's second plugin ran into trouble. Publishing opencode-git-stats turned up three things the instructions did not mention, each of which cost a release attempt: - npm trusted publishing cannot be set up before the package exists; the record fails to attach and the exchange says "package not found". The first version has to go out by hand. - that manual publish needs --ignore-scripts, because npm aborts with EUNSUPPORTED PROTOCOL on the `workspace:*` specifiers inside @opentui's own published metadata — which is also why the build has to be explicit rather than left to prepack. - the trust record binds to the package, not the repo, so each plugin needs its own, and it has to name the `npm` environment the publish job declares or the OIDC claims do not match. Also records that `bump=` ignores a prerelease suffix and so skips the version a beta already claimed, and that neither workflow going green means anything reached npm. --- README.md | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1200149..7e1203b 100644 --- a/README.md +++ b/README.md @@ -13,9 +13,32 @@ plugins. Each publishable package lives under `packages//` with its own | [`packages/context-tree`](packages/context-tree/README.md) | Pi-style context tree for OpenCode: branch, merge, crop, undo, plus a trajectory view | | [`packages/git-stats`](packages/git-stats/README.md) | Sidebar card: working-tree diff figures, plus a GitHub-coloured chip per pull request the session touched | -To add a new plugin, create `packages//` with its own `package.json` and -release scripts, then add it to the `workflow_dispatch.inputs.package` choice -list in `.github/workflows/release.yml` and `publish.yml`. +## Adding a plugin + +1. Create `packages//` with its own `package.json` and release scripts, and + add it to the `workflow_dispatch.inputs.package` choice list in + `.github/workflows/release.yml` and `publish.yml`. +2. **Publish its first version by hand.** npm's trusted publishing cannot be set up + for a package that does not exist yet — the trust record silently fails to attach + and the exchange reports "package not found". From `packages//`: + `npm version --no-git-tag-version --ignore-scripts && bun run build && npm publish --access public --ignore-scripts`, + then reset the version (`git checkout -- package.json`) since the tag is the + source of truth. `--ignore-scripts` is required: npm chokes on the `workspace:*` + specifiers inside `@opentui`'s own published metadata, which is also why the build + is explicit rather than left to `prepack`. +3. **Then create the trust record**, once per package — it binds to the package, not + the repo, so a second plugin needs its own: + `npm trust github --file publish.yml --repo navbytes/opencode-plugins`, + with environment `npm` (the publish job declares one; a record without it will not + match the OIDC claims). +4. After that, `gh workflow run release.yml -f package= -f bump=patch` does the + rest. Note `bump=` computes off the newest `-v*` tag and ignores a prerelease + suffix, so the release a beta anticipated must be cut with an explicit + `-f version=`, not `bump=`. + +A green `release.yml` only means it tagged and dispatched, and a green `publish.yml` +only means npm accepted the upload — the registry lags by a minute or two. Check the +registry, not the workflow. ## Development