Merge pull request 'ci: tag the release commit and link the package to the repository' (#18) from ci/tag-and-link-release into main

Reviewed-on: haylan/fastcrw-opencode-websarch#18

.claude/skills/opencode-v2-plugin/SKILL.md

@@ -45,26 +45,27 @@ await ctx.websearch.transform((editor) => {
 {
   "plugins": [
     {
-      "package": "~/.config/opencode/plugins/fastcrw",
+      "package": "@haylan/opencode-fastcrw",
       "options": { "baseURL": "http://crw.home:3000", "limit": 8 },
     },
   ],
-  "websearch": { "provider": "fastcrw" },
 }
 ```
 
 - Key is plural `plugins` (v1: `plugin`). Entries are a string or `{ package, options }`.
-- `package` may be an npm name (`name`, `name@1.2.0`, `@scope/name`), `./local`, an absolute path or `file://`.
-- Auto-discovered: `.ts`/`.js` files and packages in `.opencode/plugins/` and `~/.config/opencode/plugins/`.
-- `websearch.provider` is a provider id or `"random"`; `"websearch": false` disables search. Built-in ids: exa, firecrawl, parallel, tavily, tinyfish.
-- CLI: `opencode plugin add|list|check|update|remove`.
+- `package` may be an npm name (`name`, `name@1.2.0`, `@scope/name`), `./relative` (resolved from the config file), an absolute path or `file://`. `~` is not expanded.
+- **Local paths must be directories**, resolved by file path (`<dir>/server`, then `<dir>/index`); `package.json` `exports` are ignored. A file entry is ignored with a warning, and a directory without a root `index`/`server` file loads silently nothing. npm names resolve through `exports`.
+- Auto-discovered: `.ts`/`.js` files (not `.mjs`) and directories in `.opencode/plugins/` and `~/.config/opencode/plugins/`. Drop-in files get no options.
+- `websearch.provider` is a provider id or `"random"`; `"websearch": false` disables search. Built-in ids: exa, firecrawl, parallel, tavily, tinyfish. A provider named here **wins** over a plugin's `editor.default.set`; with it unset, the plugin's default applies.
+- CLI: `opencode plugin add|list|check|update|remove` (`add` writes the global config).
+- Loading is lazy: after startup or reload the plugin list fills in after several seconds. Load errors show as `state.status: "failed"` in `GET /api/plugin` (private server: `opencode serve`, Basic auth user `opencode`).
 
 ## Packaging (npm)
 
 `"type": "module"`, `exports["."]` pointing at the entry, dependency on `@opencode/plugin`.
 
-## Unverified: check at runtime, do not assume
+## Still unverified
 
-- Exact TypeScript types for the editor, `time` and `execute` args (read `@opencode/plugin` typings after install).
-- Inner shape of `time`, and whether extra result fields are allowed.
-- Precedence between config `websearch.provider` and `editor.default.set(id)`.
+- Installing by name from the Gitea registry with a scoped `.npmrc`.
+
+Verified results: `docs/runtime-checks.md`.

.gitea/workflows/release.yml

@@ -16,5 +16,7 @@ jobs:
       - run: npm run build
       - run: node scripts/release.ts
         env:
-          REGISTRY_URL: ${{ gitea.server_url }}/api/packages/${{ gitea.repository_owner }}/npm
+          SERVER_URL: ${{ gitea.server_url }}
+          REPOSITORY: ${{ gitea.repository }}
+          SHA: ${{ gitea.sha }}
           TOKEN: ${{ secrets.PACKAGE_TOKEN || secrets.GITHUB_TOKEN }}

CHANGELOG.md

@@ -5,3 +5,13 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
+
+## [0.0.1] - 2026-10-03
+
+### Added
+
+- opencode v2 plugin `fastcrw.websearch` that registers a `fastcrw` search provider backed by a self-hosted fastCRW server (`POST /v1/search`) and makes it the default websearch provider.
+- Plugin options `baseURL`, `apiKey`, `limit`, `lang` and `tbs`, with `CRW_API_URL` and `CRW_API_KEY` as environment fallbacks.
+- Validation at plugin load: a bad option makes the plugin fail with a message naming the option.
+- Mapping of both fastCRW response shapes (`data[]` and `data.results`) and descriptive errors for API failures, non-JSON responses, unreachable servers and timeouts.
+- Gitea Actions workflows for pull request checks and for publishing releases to the Gitea npm registry.

README.md

@@ -0,0 +1,93 @@
+# @haylan/opencode-fastcrw
+
+An [opencode](https://opencode.ai) v2 plugin that makes a self-hosted [fastCRW](https://docs.fastcrw.com) server opencode's websearch. It calls `POST {baseURL}/v1/search` directly; it does not use the `crw-mcp` MCP server.
+
+The plugin registers a search provider with id `fastcrw` and makes it the default. If fastCRW fails, searches fail; they never fall back to the built-in providers (Exa, Firecrawl, Parallel, Tavily, TinyFish).
+
+## Install
+
+The package is published to the Gitea npm registry. Map the scope to it in your `.npmrc`:
+
+```
+@haylan:registry=https://git.arthurerlich.de/api/packages/haylan/npm/
+```
+
+Then add the plugin to your `opencode.json`:
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "@haylan/opencode-fastcrw",
+      "options": { "baseURL": "http://crw.home:3000" },
+    },
+  ],
+}
+```
+
+Installing by name from the Gitea registry has not been verified end to end yet; see [docs/runtime-checks.md](docs/runtime-checks.md).
+
+### Local build
+
+To try the plugin without a registry:
+
+```bash
+npm ci
+npm run build
+```
+
+opencode loads local plugins as directories, resolved by file path (`<dir>/server`, then `<dir>/index`), and ignores `package.json` `exports`, so this package cannot be pointed at directly. Use a small shim instead. Create `~/.config/opencode/plugins/fastcrw.js` (a `.js` or `.ts` file; `.mjs` is ignored) with:
+
+```js
+export { default } from "file:///ABSOLUTE/PATH/TO/fastcrw-opencode-websarch/dist/index.js"
+```
+
+A drop-in file cannot receive plugin options, so configure the plugin with the environment variables below (`CRW_API_URL`, `CRW_API_KEY`). To use options instead, put the same line in an `index.js` inside a directory and reference that directory as `"package": "./that-dir"` (a relative path is resolved from the config file; `~` is not expanded).
+
+## Configuration
+
+Plugin options come from `opencode.json`. Precedence is option, then environment variable, then default.
+
+| Option    | Environment variable | Default                 | Notes                                                                                   |
+| --------- | -------------------- | ----------------------- | --------------------------------------------------------------------------------------- |
+| `baseURL` | `CRW_API_URL`        | `http://localhost:3000` | Base URL of the fastCRW server, `http` or `https`. Trailing slashes are removed.        |
+| `apiKey`  | `CRW_API_KEY`        | none                    | Optional. Sent as a Bearer token. Prefer the environment variable over `opencode.json`. |
+| `limit`   | none                 | `8`                     | Results per search, clamped to 1 to 20. An invalid value falls back to 8.               |
+| `lang`    | none                 | unset                   | Search language, for example `en` or `de`. Omitted from the request when unset.         |
+| `tbs`     | none                 | unset                   | Time range: `qdr:h`, `qdr:d`, `qdr:w`, `qdr:m` or `qdr:y`.                              |
+
+A bad `baseURL`, `tbs`, `lang` or `apiKey` makes the plugin fail to load, with a message naming the option. opencode keeps running and shows the plugin as failed.
+
+### Choosing the provider
+
+Do not set `websearch.provider` to another provider. In opencode, a provider named in `opencode.json` wins over the one a plugin sets as default, so `"websearch": { "provider": "exa" }` would send your searches to Exa. Leaving it unset, or setting it to `"fastcrw"`, uses this plugin.
+
+## Errors
+
+Failures are thrown as `fastCRW <status> <error_code>: <message>`, with a hint for a missing or invalid key (401) and for a server without a search backend (503 `search_disabled`). A server that is unreachable, times out (30 s) or returns something that is not JSON gets its own message. opencode currently shows only a generic "Web search request failed: fastcrw", so check the server when searches fail.
+
+A self-hosted fastCRW server needs a SearXNG-style search backend (`CRW_SEARCH__SEARCH_BACKEND_URL`); without one, searches return 503.
+
+## Development
+
+```bash
+npm ci
+npm run check   # Prettier and type check
+npm test        # node --test, needs Node 22.18 or later
+npm run build   # compile to dist/
+npm run smoke -- "query"   # one real search against CRW_API_URL (manual)
+```
+
+`docs/spec.md` is the build spec, `docs/runtime-checks.md` records what was verified against a real opencode, and `CONTEXT.md` defines the vocabulary.
+
+### Releasing
+
+Releases are published by the manually started `release` workflow on Gitea Actions. It reads the latest version heading in `CHANGELOG.md` (the repository keeps the dev version `0.0.0-dev` in `package.json`) and then:
+
+1. publishes that version to the Gitea npm registry, unless it already exists;
+2. tags the workflow's commit `v<version>`, unless the tag already exists;
+3. links the package to this repository, unless it is already linked.
+
+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.

scripts/release.ts

@@ -1,5 +1,8 @@
-// Publishes the latest CHANGELOG.md version to a Gitea npm registry without `npm publish`.
-// Env: REGISTRY_URL (e.g. https://host/api/packages/<owner>/npm), TOKEN (needs write:package).
+// Publishes the latest CHANGELOG.md version to a Gitea npm registry without `npm publish`, tags the
+// commit `v<version>` and links the package to this repository. Every step is idempotent, so a
+// rerun repairs a release that is only partly done.
+// Env: SERVER_URL, REPOSITORY (owner/repo), SHA (from the workflow), TOKEN (needs write:package
+// and write:repository).
 import { execFileSync } from "node:child_process"
 import { createHash } from "node:crypto"
 import { cpSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
@@ -43,10 +46,57 @@ export function publishBody(pkg: { name: string; version: string }, tarball: Buf
   }
 }
 
+type Api = { base: string; headers: Record<string, string>; fetchFn?: typeof fetch }
+
+async function call(api: Api, method: string, path: string, body?: object) {
+  return (api.fetchFn ?? fetch)(`${api.base}${path}`, {
+    method,
+    headers: { ...api.headers, "Content-Type": "application/json" },
+    body: body && JSON.stringify(body),
+  })
+}
+
+const fail = async (what: string, res: Response) =>
+  new Error(`${what} failed: ${res.status} ${await res.text()}`)
+
+export async function ensureTag(api: Api, repo: string, version: string, sha: string) {
+  const tag = `v${version}`
+  const existing = await call(api, "GET", `/repos/${repo}/tags/${tag}`)
+  if (existing.ok) return "exists"
+  if (existing.status !== 404) throw await fail("tag lookup", existing)
+  const res = await call(api, "POST", `/repos/${repo}/tags`, {
+    tag_name: tag,
+    target: sha,
+    message: `Release ${version}`,
+  })
+  if (!res.ok) throw await fail("tag creation", res)
+  return "created"
+}
+
+export async function ensureLinked(
+  api: Api,
+  owner: string,
+  name: string,
+  version: string,
+  repoName: string,
+) {
+  const pkg = `/packages/${owner}/npm/${encodeURIComponent(name)}`
+  const existing = await call(api, "GET", `${pkg}/${version}`)
+  if (!existing.ok) throw await fail("package lookup", existing)
+  if (((await existing.json()) as { repository?: unknown }).repository) return "already linked"
+  const res = await call(api, "POST", `${pkg}/-/link/${repoName}`)
+  if (!res.ok) throw await fail("package link", res)
+  return "linked"
+}
+
 async function main() {
-  const registry = process.env.REGISTRY_URL?.replace(/\/+$/, "")
-  const token = process.env.TOKEN
-  if (!registry || !token) throw new Error("REGISTRY_URL and TOKEN must be set")
+  const { SERVER_URL, REPOSITORY, SHA, TOKEN: token } = process.env
+  if (!SERVER_URL || !REPOSITORY || !SHA || !token) {
+    throw new Error("SERVER_URL, REPOSITORY, SHA and TOKEN must be set")
+  }
+  const [owner, repoName] = REPOSITORY.split("/")
+  const server = SERVER_URL.replace(/\/+$/, "")
+  const registry = `${server}/api/packages/${owner}/npm`
 
   const version = latestVersion(readFileSync("CHANGELOG.md", "utf8"))
   // The version is rewritten in the staged copy only; the repo keeps its dev version.
@@ -56,13 +106,24 @@ async function main() {
 
   const existing = await fetch(url, { headers })
   if (existing.ok && isPublished(await existing.json(), version)) {
-    console.log(`${pkg.name}@${version} is already published, skipping`)
-    return
-  }
-  if (!existing.ok && existing.status !== 404) {
+    console.log(`${pkg.name}@${version} is already published, skipping publish`)
+  } else if (!existing.ok && existing.status !== 404) {
     throw new Error(`registry lookup failed: ${existing.status} ${await existing.text()}`)
+  } else {
+    await publish(pkg, url, headers)
   }
 
+  const api = { base: `${server}/api/v1`, headers }
+  console.log(`tag v${version}: ${await ensureTag(api, REPOSITORY, version, SHA)}`)
+  console.log(`package link: ${await ensureLinked(api, owner, pkg.name, version, repoName)}`)
+}
+
+async function publish(
+  pkg: { name: string; version: string },
+  url: string,
+  headers: Record<string, string>,
+) {
+  const { version } = pkg
   rmSync(".release", { recursive: true, force: true })
   mkdirSync(".release/package", { recursive: true })
   writeFileSync(".release/package/package.json", JSON.stringify(pkg, null, 2))

test/release.test.ts

@@ -1,6 +1,13 @@
 import assert from "node:assert/strict"
 import { test } from "node:test"
-import { encodeName, isPublished, latestVersion, publishBody } from "../scripts/release.ts"
+import {
+  encodeName,
+  ensureLinked,
+  ensureTag,
+  isPublished,
+  latestVersion,
+  publishBody,
+} from "../scripts/release.ts"
 
 const changelog = (body: string) => `# Changelog\n\n${body}\n`
 
@@ -42,3 +49,83 @@ test("publishBody builds the npm publish payload with the tarball attached", ()
   assert.equal(body._attachments[file].data, tarball.toString("base64"))
   assert.equal(body._attachments[file].length, tarball.length)
 })
+
+// Fake Gitea API: each route answers with a status and optional JSON body; calls are recorded.
+function fakeApi(routes: Record<string, [number, unknown?]>) {
+  const calls: string[] = []
+  const fetchFn = (async (url: string, init?: RequestInit) => {
+    const key = `${init?.method ?? "GET"} ${url.replace("https://git.test/api/v1", "")}`
+    calls.push(key + (init?.body ? ` ${init.body}` : ""))
+    const [status, body] = routes[key] ?? [500, { message: `unexpected ${key}` }]
+    return new Response(JSON.stringify(body ?? {}), { status })
+  }) as typeof fetch
+  return {
+    calls,
+    api: { base: "https://git.test/api/v1", headers: { Authorization: "Bearer t" }, fetchFn },
+  }
+}
+
+test("ensureTag creates the tag when it does not exist", async () => {
+  const { calls, api } = fakeApi({
+    "GET /repos/haylan/r/tags/v1.0.0": [404],
+    "POST /repos/haylan/r/tags": [201],
+  })
+  assert.equal(await ensureTag(api, "haylan/r", "1.0.0", "abc123"), "created")
+  assert.deepEqual(JSON.parse(calls[1].replace("POST /repos/haylan/r/tags ", "")), {
+    tag_name: "v1.0.0",
+    target: "abc123",
+    message: "Release 1.0.0",
+  })
+})
+
+test("ensureTag leaves an existing tag alone", async () => {
+  const { calls, api } = fakeApi({ "GET /repos/haylan/r/tags/v1.0.0": [200, { name: "v1.0.0" }] })
+  assert.equal(await ensureTag(api, "haylan/r", "1.0.0", "abc123"), "exists")
+  assert.equal(calls.length, 1)
+})
+
+test("ensureTag throws on an unexpected API answer", async () => {
+  const { api } = fakeApi({ "GET /repos/haylan/r/tags/v1.0.0": [403, { message: "no" }] })
+  await assert.rejects(ensureTag(api, "haylan/r", "1.0.0", "abc"), /403/)
+})
+
+const pkgPath = "/packages/haylan/npm/%40haylan%2Fopencode-fastcrw"
+
+test("ensureLinked links an unlinked package to the repository", async () => {
+  const { calls, api } = fakeApi({
+    [`GET ${pkgPath}/1.0.0`]: [200, { repository: null }],
+    [`POST ${pkgPath}/-/link/r`]: [201],
+  })
+  assert.equal(
+    await ensureLinked(api, "haylan", "@haylan/opencode-fastcrw", "1.0.0", "r"),
+    "linked",
+  )
+  assert.equal(calls.length, 2)
+})
+
+test("ensureLinked skips a package that already has a repository", async () => {
+  const { calls, api } = fakeApi({
+    [`GET ${pkgPath}/1.0.0`]: [200, { repository: { full_name: "haylan/r" } }],
+  })
+  assert.equal(
+    await ensureLinked(api, "haylan", "@haylan/opencode-fastcrw", "1.0.0", "r"),
+    "already linked",
+  )
+  assert.equal(calls.length, 1)
+})
+
+test("ensureLinked throws when the package lookup or link fails", async () => {
+  const lookup = fakeApi({ [`GET ${pkgPath}/1.0.0`]: [404] })
+  await assert.rejects(
+    ensureLinked(lookup.api, "haylan", "@haylan/opencode-fastcrw", "1.0.0", "r"),
+    /404/,
+  )
+  const link = fakeApi({
+    [`GET ${pkgPath}/1.0.0`]: [200, {}],
+    [`POST ${pkgPath}/-/link/r`]: [403],
+  })
+  await assert.rejects(
+    ensureLinked(link.api, "haylan", "@haylan/opencode-fastcrw", "1.0.0", "r"),
+    /403/,
+  )
+})