Merge pull request 'chore: scaffold package, TypeScript, Prettier and changelog' (#10) from feat/scaffold into main

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

.claude/skills/fastcrw-search-api/SKILL.md

@@ -36,7 +36,7 @@ Result: `url`, `title`, `description`, `snippet` (always-populated alias of `des
 Body `{ "success": false, "error": string, "error_code": string }`.
 
 | HTTP | error_code                            |
-|---|---|
+| ---- | ------------------------------------- |
 | 400  | `invalid_request`                     |
 | 401  | auth middleware message               |
 | 422  | `target_unreachable`                  |

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

@@ -43,8 +43,13 @@ await ctx.websearch.transform((editor) => {
 
 ```jsonc
 {
-  "plugins": [{ "package": "~/.config/opencode/plugins/fastcrw", "options": { "baseURL": "http://crw.home:3000", "limit": 8 } }],
+  "plugins": [
-  "websearch": { "provider": "fastcrw" }
+    {
+      "package": "~/.config/opencode/plugins/fastcrw",
+      "options": { "baseURL": "http://crw.home:3000", "limit": 8 },
+    },
+  ],
+  "websearch": { "provider": "fastcrw" },
 }
 ```
 

.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

.prettierignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+package-lock.json

.prettierrc.json

@@ -0,0 +1,4 @@
+{
+  "semi": false,
+  "printWidth": 100
+}

CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+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]

docs/research/fastcrw-search-api.md

@@ -19,7 +19,7 @@ Resolves issue #3. Researched 2026-10-03 against `main` of github.com/us/crw (`f
 ## Env var names
 
 | Var                  | Used by          | Meaning                                                                                             |
-|---|---|---|
+| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------- |
 | `CRW_API_URL`        | crw-mcp, crw CLI | Remote server base URL. Default `https://api.fastcrw.com`; `http://localhost:3000` for self-hosted. |
 | `CRW_API_KEY`        | crw-mcp, crw CLI | Bearer token for the remote server.                                                                 |
 | `CRW_LOCAL`          | crw-mcp          | Truthy forces embedded mode, ignoring `CRW_API_URL`.                                                |
@@ -35,7 +35,7 @@ Plugin should use `CRW_API_URL` / `CRW_API_KEY` to match upstream naming.
 Source: `SearchRequest` in crates/crw-core/src/types.rs (camelCase serde); blog/crw-search-api-release.md.
 
 | Field                                                                                                   | Type             | Notes                                                                                  |
-|---|---|---|
+| ------------------------------------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------- |
 | `query`                                                                                                 | string, required | Max 2000 chars (handler validation).                                                   |
 | `limit`                                                                                                 | int, optional    | Default 5 (`default_limit`); clamped server-side to `1..=max_limit` (max 20).          |
 | `lang`                                                                                                  | string           | SearXNG language, e.g. `en`, `de`, `auto`; validated as a language tag.                |
@@ -56,9 +56,19 @@ Envelope `ApiResponse` (camelCase, absent fields omitted): `success`, `data`, `e
 Hosted example (flat, per docs):
 
 ```json
-{"success": true, "data": [
+{
-  {"url": "https://...", "title": "...", "description": "...", "snippet": "...", "position": 1, "score": 9.5}
+  "success": true,
-]}
+  "data": [
+    {
+      "url": "https://...",
+      "title": "...",
+      "description": "...",
+      "snippet": "...",
+      "position": 1,
+      "score": 9.5
+    }
+  ]
+}
 ```
 
 Self-hosted (CLI parser handles `{"success": true, "data": {"results": [ ... ]}}`).
@@ -72,7 +82,7 @@ Conflict note: the docs example and CLI show flat `data[]` for hosted; the struc
 JSON body `{"success": false, "error": "<message>", "error_code": "<code>"}` (crates/crw-server/src/error.rs).
 
 | HTTP | error_code                            | Cause                            |
-|---|---|---|
+| ---- | ------------------------------------- | -------------------------------- |
 | 400  | `invalid_request`                     | bad query/limit/lang             |
 | 401  | (auth middleware message)             | missing/invalid key              |
 | 429  | `rate_limited`                        | rate limit                       |

docs/research/opencode-v2-plugin-api.md

@@ -14,7 +14,7 @@ Caveat: pages were read through a fetch-and-summarise tool, so quotes are as ret
 ## Verdict on the user's sketch
 
 | Sketch element                                   | Verdict            | Evidence                                                                                                                                                                 |
-|---|---|---|
+| ------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `Plugin.define` from `"@opencode/plugin"`        | RIGHT              | [S1] `import { Plugin } from "@opencode/plugin"` / `export default Plugin.define({ id: "example", async setup(ctx) {...} })`. V1 package was `@opencode-ai/plugin` [S5]. |
 | `ctx.websearch.transform`                        | RIGHT              | [S1] `await ctx.websearch.transform((editor) => { ... })`                                                                                                                |
 | `editor.add`                                     | RIGHT              | [S1] `editor.add({ id: "internal", name: "Internal search", execute: async ({ query }, { signal }) => {...} })`                                                          |
@@ -22,6 +22,7 @@ Caveat: pages were read through a fetch-and-summarise tool, so quotes are as ret
 | `websearch.provider`                             | RIGHT (config key) | [S3][S4] `{ "websearch": { "provider": "tavily" } }`; also `"random"`. Built-in ids: exa, firecrawl, parallel, tavily, tinyfish [S4].                                    |
 
 Things the sketch likely missed / must add:
+
 - `id` is required on `Plugin.define` (stable, used for storage scoping/diagnostics) [S5].
 - A plugin-added provider is made active with `editor.default.set("<id>")` [S1]; `websearch.provider` in config selects by provider id, so `"provider": "<your-id>"` is the expected pairing (inference from [S1]+[S4]; docs do not state it explicitly -> verify at runtime).
 - Options are read as `ctx.options` (not passed as a setup arg) [S1].
@@ -29,47 +30,64 @@ Things the sketch likely missed / must add:
 ## Sub-questions
 
 ### 1. Plugin entry / definition shape
+
 Each module has one default export with a unique id and `setup`:
+
 ```ts
 import { Plugin } from "@opencode/plugin"
 export default Plugin.define({
   id: "example",
-  async setup(ctx) { /* may return a cleanup function */ },
+  async setup(ctx) {
+    /* may return a cleanup function */
+  },
 })
 ```
+
 [S1][S5]. Context: `ctx.app.version`, `ctx.location` (`directory`, optional `workspaceID`, project), `ctx.options`, `ctx.storage` (durable JSON, plugin-scoped), plus domains `ctx.session/permission/shell/tool/websearch/...` [S1][S5]. Return cleanup from `setup` for timers/sockets [S5]. V1 plugins do not run in V2; dual-support is possible via spreading `Plugin.define(...)` and adding a V1 `server()` [S1][S5].
 
 ### 2. Registration/loading (local path vs npm)
+
 `"plugins"` array in `opencode.json(c)`; entries are strings or objects [S2]:
 npm `"opencode-acme-plugin"`, `"opencode-acme-plugin@1.2.0"`, `"@acme/opencode-plugin"`; local `"./plugins/local"`, `"../shared/plugin.ts"`, `"/abs/plugin.ts"`, `"file:///..."`. Also auto-discovery of `.ts/.js` files and packages in `.opencode/plugins/` or `~/.config/opencode/plugins/` [S2]. CLI: `opencode plugin add|list|check|update|remove` [S2]. Disable via ids: `["*", "-opencode.provider.*", ...]` [S2]. Published package needs `"type":"module"`, `exports["."]` -> entry, dependency `@opencode/plugin` [S1].
 
 ### 3. Passing options
+
 ```jsonc
-{ "plugins": [ { "package": "./plugins/company", "options": { "strict": true } } ] }
+{ "plugins": [{ "package": "./plugins/company", "options": { "strict": true } }] }
 ```
+
 read via `ctx.options.strict` in `setup` [S1][S3]. Options type is untyped key/value (validate yourself).
 
 ### 4. Can a plugin provide/replace the websearch provider?
+
 Yes. [S1]:
+
 ```ts
 await ctx.websearch.transform((editor) => {
-  editor.add({ id: "internal", name: "Internal search",
+  editor.add({
+    id: "internal",
+    name: "Internal search",
     execute: async ({ query }, { signal }) => {
       const response = await fetch(`https://search.example.com?q=${query}`, { signal })
       return [{ url: "", title: "", content: "", time: {} }]
-    } })
+    },
+  })
   editor.default.set("internal")
 })
 ```
+
 Disable: `editor.default.set(false)`; re-evaluate: `await ctx.websearch.reload()` [S1]. The API reference lists add/default/remove operations [S6] (remove not shown in S1 example; exact editor type unverified).
 
 ### 5. How `websearch.provider` is selected
+
 Config `{ "websearch": { "provider": "<id>" | "random" } }`; `"random"` picks an available provider; `"websearch": false` disables search entirely [S3][S4]. Provider on HTTP 429 enters cooldown and search retries another provider [S4]. Provider API keys via `/connect` or env (e.g. `TAVILY_API_KEY`) [S4]. For a plugin provider, `editor.default.set(id)` is the plugin-side selection [S1]; interplay/precedence with the config `provider` key is not documented -> verify.
 
 ### 6. Required search result shape
+
 From [S1] the `execute` return is an array of `{ url, title, content, time }`; the example uses `time: {}` (object, inner shape undocumented). [S6] lists the same four fields. Unverified: whether `time` fields are optional, exact `time` keys (e.g. published/updated), and whether extra fields are allowed. `execute` receives `({ query }, { signal })`; `signal` is an AbortSignal and must be passed to fetch [S1].
 
 ## Open items (need source or runtime check)
+
 - Exact TS types for editor, `time`, and execute args (read anomalyco/opencode source or `@opencode/plugin` typings after install).
 - Precedence of config `websearch.provider` vs plugin `editor.default.set`.
 - [S6] suggested `POST /api/websearch/query` with `{query, provider?}` -> `{results, provider}`; this came from the summariser and is lower confidence.

docs/spec.md

@@ -9,7 +9,7 @@ An opencode v2 plugin that makes a self-hosted fastCRW server opencode's only we
 ## Identifiers
 
 | What                        | Value                                                  |
-|---|---|
+| --------------------------- | ------------------------------------------------------ |
 | npm package                 | `@haylan/opencode-fastcrw`                             |
 | Plugin id (`Plugin.define`) | `fastcrw.websearch`                                    |
 | Provider id / display name  | `fastcrw` / "fastCRW"                                  |
@@ -25,7 +25,11 @@ export default Plugin.define({
   async setup(ctx) {
     const config = resolveConfig(ctx.options, process.env) // throws on bad values
     await ctx.websearch.transform((editor) => {
-      editor.add({ id: "fastcrw", name: "fastCRW", execute: ({ query }, { signal }) => search(config, query, signal, fetch) })
+      editor.add({
+        id: "fastcrw",
+        name: "fastCRW",
+        execute: ({ query }, { signal }) => search(config, query, signal, fetch),
+      })
       editor.default.set("fastcrw")
     })
   },
@@ -39,7 +43,7 @@ fastCRW is the default and only provider; there is no fallback to built-ins.
 Precedence: plugin option > env var > default.
 
 | Option    | Env var       | Default                 | Rules                                                                  |
-|---|---|---|---|
+| --------- | ------------- | ----------------------- | ---------------------------------------------------------------------- |
 | `baseURL` | `CRW_API_URL` | `http://localhost:3000` | trim, strip trailing `/`, must be `http(s)` URL                        |
 | `apiKey`  | `CRW_API_KEY` | none                    | optional; Bearer header only when set; never logged or echoed          |
 | `limit`   | none          | `8`                     | clamp to 1..20; invalid falls back to 8, never throws                  |
@@ -50,8 +54,13 @@ Validation runs in `setup`. A malformed `baseURL`, bad `tbs` or non-string `lang
 
 ```jsonc
 {
-  "plugins": [{ "package": "@haylan/opencode-fastcrw", "options": { "baseURL": "http://crw.home:3000", "limit": 8 } }],
+  "plugins": [
-  "websearch": { "provider": "fastcrw" }
+    {
+      "package": "@haylan/opencode-fastcrw",
+      "options": { "baseURL": "http://crw.home:3000", "limit": 8 },
+    },
+  ],
+  "websearch": { "provider": "fastcrw" },
 }
 ```
 

package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@haylan/opencode-fastcrw",
+  "version": "0.0.0-dev",
+  "description": "opencode v2 plugin that makes a self-hosted fastCRW server the websearch provider",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "format": "prettier --write .",
+    "check": "prettier --check . && tsc --noEmit",
+    "test": "node --test",
+    "smoke": "node scripts/smoke.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://git.arthurerlich.de/haylan/fastcrw-opencode-websarch.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@opencode/plugin": "^2.0.22"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "prettier": "^3.9.9",
+    "typescript": "^7.0.2"
+  }
+}

src/index.ts

@@ -0,0 +1,2 @@
+// ponytail: placeholder so `tsc` has an input; replaced by the plugin entry.
+export {}

tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"],
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}