From ec0ee81cef50c96d989b863c4b3b9840254bfd2c Mon Sep 17 00:00:00 2001 From: ArthurErlich Date: Sat, 3 Oct 2026 20:58:55 +0200 Subject: [PATCH 1/3] docs: record registry install check and document the install steps Co-Authored-By: Claude Sonnet 5.5 --- README.md | 14 +++++++++++--- docs/runtime-checks.md | 19 ++++++++++++++++--- 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 07509f7..ab80a56 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,21 @@ The plugin registers a search provider with id `fastcrw` and makes it the defaul ## Install -The package is published to the Gitea npm registry. Map the scope to it in your `.npmrc`: +The package is published to the Gitea npm registry. Map the scope to it in your user-level `~/.npmrc`: ``` @haylan:registry=https://git.arthurerlich.de/api/packages/haylan/npm/ ``` -Then add the plugin to your `opencode.json`: +It has to be the user-level file (or the equivalent `npm_config_@haylan:registry` environment variable): opencode installs plugins from its own cache folder and ignores a project-level `.npmrc`, and without the mapping it looks for the package on npmjs.com and fails with a 404. + +Then install it with opencode, which also adds it to your config: + +```bash +opencode plugin add @haylan/opencode-fastcrw +``` + +A plugin that is only listed in `opencode.json` is not installed automatically. Add your options to the entry that `plugin add` created: ```jsonc { @@ -25,7 +33,7 @@ Then add the plugin to your `opencode.json`: } ``` -Installing by name from the Gitea registry has not been verified end to end yet; see [docs/runtime-checks.md](docs/runtime-checks.md). +Verified with 0.0.1 against opencode v2.0.22; see [docs/runtime-checks.md](docs/runtime-checks.md). ### Local build diff --git a/docs/runtime-checks.md b/docs/runtime-checks.md index 29339f7..32fea84 100644 --- a/docs/runtime-checks.md +++ b/docs/runtime-checks.md @@ -9,8 +9,8 @@ Results of the verification list in `docs/spec.md`. Run on 2026-10-03 against op | 1 | Built-in providers removable or disableable | Done: not removable by a plugin, but never used as a fallback | | 2 | Throwing `setup` disables only this plugin | Done: yes, loudly | | 3 | Config `websearch.provider` vs `editor.default.set` | Done: config wins | -| 4 | Install by name from the Gitea registry | Not run (needs a published release) | -| 5 | Release job token has package-write rights | Not run (needs a release run) | +| 4 | Install by name from the Gitea registry | Done: works with a user-level scope mapping | +| 5 | Release job token has package-write rights | Not verified: the release used the `PACKAGE_TOKEN` secret | | 6 | `@opencode/plugin` install weight | Done | | 7 | `npm run smoke` against the real fastCRW server | Done | | 8 | Typings, `time` shape, 429 cooldown | Done: a 429 from our plugin triggers no cooldown | @@ -46,6 +46,19 @@ With `baseURL: "nope"`, only this plugin ended up in state `failed`, with our me Config `websearch.provider` wins over the plugin's `editor.default.set`: with the config set to `exa`, a query without a provider id went to Exa (and worked without a key, so the query left the machine). With the config unset or set to `fastcrw`, the plugin's provider was used. Consequence: do not set `websearch.provider` to anything else; setting it to `fastcrw` is harmless and explicit. +### 4. Install by name from the Gitea registry + +Release 0.0.1 is in the registry, linked to this repository, with tag `v0.0.1` (workflow run succeeded). Verified in an isolated profile: + +- `npm install @haylan/opencode-fastcrw` with the scoped `.npmrc` mapping works anonymously, and the installed package imports as plugin id `fastcrw.websearch`. +- `opencode plugin add @haylan/opencode-fastcrw` with the mapping set through `npm_config_@haylan:registry` installs it and adds `"@haylan/opencode-fastcrw"` to the config. Without the mapping it queries registry.npmjs.org and fails with a 404. +- opencode ignores a project-level `.npmrc` (it installs from its own cache folder), so the mapping must be in the user-level `~/.npmrc` or the environment. +- A `plugins` entry by name is **not** installed automatically on startup; only `plugin add` installs. After adding options to the entry and starting the server, a search without a provider id went to `fastcrw` and returned 3 results (`limit` 3) from the real server `http://crw.home`. + +### 5. Release token + +The release workflow succeeded, but the repository has a `PACKAGE_TOKEN` secret and the workflow prefers it over the job token, so the job-token fallback is untested. Tag creation and the package link worked with that token. + ### 6. `@opencode/plugin` install weight `npm install` of `@opencode/plugin@2.0.22` adds about 100 MB of transitive dependencies (mainly `effect`, OpenTelemetry, `@redis`). Its peers `solid-js`, `@opentui/core`, `@opentui/solid` and `@opencode/theme` are optional and not installed. Decision for the first release: keep it in `dependencies` as the docs say; revisit if install size matters. @@ -63,7 +76,7 @@ From `@opencode/schema` 2.0.22: a result is `{ url: string, title?: string, cont - **Local installs need a root `index.js`.** Add `index.js` (`export { default } from "./dist/index.js"`) to the package and `files`, so a config entry pointing at an unpacked package directory works as well as an npm-name install. The release script stages `package.json` and `dist/` only and would need to include it. - Update the README and spec examples: no `~` paths, and a directory (not a file) for local `plugins` entries. - Optional: decide whether the generic user-facing error is acceptable, since our detailed messages are not surfaced. -- Still to verify after the first release: check 4 (install by name with a scoped `.npmrc`) and check 5 (job token package-write rights). +- Optional: remove the `PACKAGE_TOKEN` secret and run the release workflow once more to test the job-token fallback. ## Useful for later runs From 3a15c73e95cf60bb261f47ae000ae1525f90c149 Mon Sep 17 00:00:00 2001 From: ArthurErlich Date: Sat, 3 Oct 2026 20:59:18 +0200 Subject: [PATCH 2/3] docs: update follow-ups after the root index.js decision Co-Authored-By: Claude Sonnet 5.5 --- docs/runtime-checks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/runtime-checks.md b/docs/runtime-checks.md index 32fea84..b552fc8 100644 --- a/docs/runtime-checks.md +++ b/docs/runtime-checks.md @@ -73,8 +73,8 @@ From `@opencode/schema` 2.0.22: a result is `{ url: string, title?: string, cont ## Follow-ups this implies -- **Local installs need a root `index.js`.** Add `index.js` (`export { default } from "./dist/index.js"`) to the package and `files`, so a config entry pointing at an unpacked package directory works as well as an npm-name install. The release script stages `package.json` and `dist/` only and would need to include it. -- Update the README and spec examples: no `~` paths, and a directory (not a file) for local `plugins` entries. +- Decided against a root `index.js`: local testing uses a drop-in shim (see the README), and the package is installed by name through the registry. +- Done: README install section and examples corrected (no `~` paths, directories only for local entries). - Optional: decide whether the generic user-facing error is acceptable, since our detailed messages are not surfaced. - Optional: remove the `PACKAGE_TOKEN` secret and run the release workflow once more to test the job-token fallback. From 68d22e28fece1ce12b75507d8a4ad7f51f1506ec Mon Sep 17 00:00:00 2001 From: ArthurErlich Date: Sat, 3 Oct 2026 21:01:52 +0200 Subject: [PATCH 3/3] ci: use only the PACKAGE_TOKEN secret for releases Co-Authored-By: Claude Sonnet 5.5 --- .gitea/workflows/release.yml | 2 +- README.md | 2 +- docs/runtime-checks.md | 5 ++--- docs/spec.md | 2 +- 4 files changed, 5 insertions(+), 6 deletions(-) diff --git a/.gitea/workflows/release.yml b/.gitea/workflows/release.yml index 2af5b83..1440215 100644 --- a/.gitea/workflows/release.yml +++ b/.gitea/workflows/release.yml @@ -19,4 +19,4 @@ jobs: SERVER_URL: ${{ gitea.server_url }} REPOSITORY: ${{ gitea.repository }} SHA: ${{ gitea.sha }} - TOKEN: ${{ secrets.PACKAGE_TOKEN || secrets.GITHUB_TOKEN }} + TOKEN: ${{ secrets.PACKAGE_TOKEN }} diff --git a/README.md b/README.md index ab80a56..8ed7956 100644 --- a/README.md +++ b/README.md @@ -98,4 +98,4 @@ Releases are published by the manually started `release` workflow on Gitea Actio Every step skips itself when done, so starting the workflow again completes a release that only partly succeeded. -To release: add a dated `## [x.y.z]` entry to `CHANGELOG.md`, merge it to `main`, then start the workflow. It needs a token with `write:package` and `write:repository` rights: the job token if it has them, otherwise a `PACKAGE_TOKEN` secret. +To release: add a dated `## [x.y.z]` entry to `CHANGELOG.md`, merge it to `main`, then start the workflow. It needs the `PACKAGE_TOKEN` repository secret, a token with `write:package` and `write:repository` rights. diff --git a/docs/runtime-checks.md b/docs/runtime-checks.md index b552fc8..af7d84b 100644 --- a/docs/runtime-checks.md +++ b/docs/runtime-checks.md @@ -10,7 +10,7 @@ Results of the verification list in `docs/spec.md`. Run on 2026-10-03 against op | 2 | Throwing `setup` disables only this plugin | Done: yes, loudly | | 3 | Config `websearch.provider` vs `editor.default.set` | Done: config wins | | 4 | Install by name from the Gitea registry | Done: works with a user-level scope mapping | -| 5 | Release job token has package-write rights | Not verified: the release used the `PACKAGE_TOKEN` secret | +| 5 | Release token has package-write rights | Done: the release uses the `PACKAGE_TOKEN` secret | | 6 | `@opencode/plugin` install weight | Done | | 7 | `npm run smoke` against the real fastCRW server | Done | | 8 | Typings, `time` shape, 429 cooldown | Done: a 429 from our plugin triggers no cooldown | @@ -57,7 +57,7 @@ Release 0.0.1 is in the registry, linked to this repository, with tag `v0.0.1` ( ### 5. Release token -The release workflow succeeded, but the repository has a `PACKAGE_TOKEN` secret and the workflow prefers it over the job token, so the job-token fallback is untested. Tag creation and the package link worked with that token. +The release workflow succeeded with the `PACKAGE_TOKEN` repository secret (rights `write:package` and `write:repository`): publishing, tag creation and the package link all worked. Decision: that secret stays, and the workflow uses it alone; the untested job-token fallback was removed. ### 6. `@opencode/plugin` install weight @@ -76,7 +76,6 @@ From `@opencode/schema` 2.0.22: a result is `{ url: string, title?: string, cont - Decided against a root `index.js`: local testing uses a drop-in shim (see the README), and the package is installed by name through the registry. - Done: README install section and examples corrected (no `~` paths, directories only for local entries). - Optional: decide whether the generic user-facing error is acceptable, since our detailed messages are not surfaced. -- Optional: remove the `PACKAGE_TOKEN` secret and run the release workflow once more to test the job-token fallback. ## Useful for later runs diff --git a/docs/spec.md b/docs/spec.md index 6bcce00..bcd4f5a 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -103,7 +103,7 @@ Run once on a real opencode v2 install; a failed check reopens the design as a n 2. Does a throwing `setup` disable only this plugin, not opencode startup? 3. Precedence of config `websearch.provider` vs `editor.default.set`. 4. Does install-by-name from the Gitea registry work with a scoped `.npmrc` (`@haylan:registry=...`)? Fallback: tarball or local path. -5. Does the release workflow's job token have package-write rights? Fallback: a `write:package` secret. +5. Release token rights. Settled: the workflow uses a `PACKAGE_TOKEN` secret with `write:package` and `write:repository`; there is no job-token fallback. 6. Does `npm install` of `@opencode/plugin` drag in `solid-js` and the OpenTUI peers? If heavy, move it to `peerDependencies` plus `devDependencies`. 7. `npm run smoke` against the real fastCRW server (`CRW_API_URL`/`CRW_API_KEY`): record the real response shape (`data[]` vs `data.results`). 8. Confirm the exact `@opencode/plugin` TypeScript types, the shape of `time`, and that a 429 status in an error message triggers opencode's provider cooldown.