@s-berdia/opencode-router 1.0.1 → 1.1.1

package/README.md

@@ -1,6 +1,12 @@
 # opencode-router
 
-Automatic model routing for [OpenCode](https://opencode.ai) on the **Go**, **Go Plus**, and **Free** plans.
+[![npm version](https://img.shields.io/npm/v/@s-berdia/opencode-router)](https://www.npmjs.com/package/@s-berdia/opencode-router)
+[![npm downloads](https://img.shields.io/npm/dm/@s-berdia/opencode-router)](https://www.npmjs.com/package/@s-berdia/opencode-router)
+[![CI](https://github.com/s-berdia/Opencode_router/actions/workflows/ci.yml/badge.svg)](https://github.com/s-berdia/Opencode_router/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+**Switch models before you hit your [OpenCode](https://opencode.ai) limit.** Automatic
+model routing and quota failover for the **Go**, **Go Plus**, and **Free** plans.
 
 ![opencode-router demo: the scorecard gives each agent a model, and the build agent changes to the next model at 85% of its 5-hour limit](docs/router-demo.gif)
 
@@ -41,6 +47,15 @@ the router, read its [known limits](./USAGE.md#11-known-limits).
 
 ## Quick start
 
+If you have the OpenCode command-line tool, run this command. Then close OpenCode, start
+it again, and go to step 4.
+
+```bash
+opencode plugin @s-berdia/opencode-router --global
+```
+
+If you do not have the command-line tool, edit the config file:
+
 1. Open your global OpenCode config file in a text editor:
    - Windows: `C:\Users\<your-user-name>\.config\opencode\opencode.json`
    - macOS and Linux: `~/.config/opencode/opencode.json`
@@ -66,6 +81,10 @@ the router, read its [known limits](./USAGE.md#11-known-limits).
 
 The router now selects models automatically. You do not have to do more.
 
+OpenCode does not update plugins automatically. When a new version of the router is
+available, the router shows a note. Then type `/routing-update` and restart OpenCode.
+See [Update the router](./USAGE.md#12-update-the-router).
+
 ## Commands
 
 ### In OpenCode
@@ -76,6 +95,7 @@ The router now selects models automatically. You do not have to do more.
 | `/routing-status` | Show the model in use for each agent (after failover) and its 5-hour quota use |
 | `/routing-plan go-plus` | Save a plan profile (`go`, `go-plus`, or `free`) and apply it immediately |
 | `/routing-eval` | Send one test prompt to the `build` models and write a report |
+| `/routing-update` | Look for a newer version and remove the old copy that OpenCode keeps. Then restart OpenCode |
 
 ### In a terminal
 
@@ -88,6 +108,7 @@ npx @s-berdia/opencode-router status                 # models in use and quota u
 npx @s-berdia/opencode-router plan go-plus           # save the plan profile and rebuild
 npx @s-berdia/opencode-router cat                    # catalog file, date, model count
 npx @s-berdia/opencode-router install --scope global # write slash-command files
+npx @s-berdia/opencode-router@latest update          # remove OpenCode's old copy
 npx @s-berdia/opencode-router --help                 # all commands and options
 ```
 
@@ -140,6 +161,7 @@ or a value that is not valid, the router ignores it and shows a note in the scor
 | `blend` | `{ "input": 0.75, "output": 0.25, "cacheRead": 0.1 }` | Token mix used to calculate the cost of one million tokens |
 | `enduranceScale` | `{ "minTokensPer5h": 0.25, "maxTokensPer5h": 40 }` | Millions of tokens per 5 hours that give an endurance score of 0 and 100 |
 | `feeds` | `{ "enabled": false }` | Optional benchmark feed: `{ "enabled": true, "url": "https://...", "timeoutMs": 5000 }` |
+| `updateCheck` | `true` | Once each 24 hours, ask npm for the newest router version. `false` stops the check |
 
 The [usage guide](./USAGE.md#6-change-the-router-settings) has examples for each key.
 
@@ -172,6 +194,7 @@ score = w_intelligence * intelligence
 | `~/.config/opencode/router/routing-table.json` | The last routing table |
 | `~/.config/opencode/router/last-apply.json` | The result of the last live apply |
 | `~/.config/opencode/router/eval-report.md` | The report of the last `/routing-eval` |
+| `~/.config/opencode/router/update-check.json` | The time of the last update check and the newest version on npm |
 | `opencode.json` or `opencode.jsonc` (global, or the project file with `--scope project`) | `model`, `small_model`, and `agent.<role>.model` and `variant`. Comments and all other keys stay. A file with a JSON error is not changed |
 
 If `XDG_CONFIG_HOME` is set, the router uses `$XDG_CONFIG_HOME/opencode` in place of
@@ -183,6 +206,10 @@ Models with `-free` in their name can collect your prompts for training. The sco
 marks them `free*`. To keep your main work off these models, set
 `"privacy": { "freeModelsOk": false }`. To never use them, set `"denyModels": ["*-free"]`.
 
+Once each 24 hours, the router sends one request to `registry.npmjs.org` to get the
+newest version number of the router. It sends no other data. To stop this, set
+`"updateCheck": false`.
+
 ## Development
 
 ```bash
@@ -198,6 +225,12 @@ To use your local build in OpenCode, put the absolute path of the folder in the
 list. Example for Windows: `"plugin": ["file:///C:/code/Opencode_router"]`. Run
 `npm run build` after each change, then restart OpenCode.
 
+## Contributing
+
+Bug reports, model scores, and code changes are welcome. Read
+[CONTRIBUTING.md](./CONTRIBUTING.md). For questions and ideas, use
+[Discussions](https://github.com/s-berdia/Opencode_router/discussions).
+
 ## License
 
 [MIT](./LICENSE)

package/USAGE.md

@@ -16,7 +16,8 @@ Do the steps in sequence. Each command has a label that tells you which shell to
 9. [Files and folders](#9-files-and-folders)
 10. [Troubleshooting](#10-troubleshooting)
 11. [Known limits](#11-known-limits)
-12. [Remove the router](#12-remove-the-router)
+12. [Update the router](#12-update-the-router)
+13. [Remove the router](#13-remove-the-router)
 
 ## 1. Before you start
 
@@ -41,7 +42,22 @@ Make sure that you have these items:
 
 ## 2. Install the plugin
 
-### Option A: from npm (recommended)
+### Option A: with the OpenCode command-line tool (fastest)
+
+1. Run this command. It works in PowerShell, CMD, Git Bash, macOS, and Linux:
+
+   ```bash
+   opencode plugin @s-berdia/opencode-router --global
+   ```
+
+   The command downloads the plugin and adds `"@s-berdia/opencode-router"` to the
+   `plugin` list of your global config file.
+2. Close OpenCode. Start OpenCode again.
+
+If the `opencode` command is not found, use Option B. Or install the command-line tool
+with `npm install -g opencode-ai`, and then do step 1 again.
+
+### Option B: from npm, by hand
 
 1. Open the global OpenCode config file.
 
@@ -81,7 +97,7 @@ Make sure that you have these items:
 To use the router in one project only, put the `plugin` entry in `opencode.json` in the
 root folder of that project, not in the global file.
 
-### Option B: from source
+### Option C: from source
 
 Use this option to test changes to the code.
 
@@ -119,8 +135,8 @@ Use this option to test changes to the code.
 
 1. In the OpenCode prompt, type `/` and look at the list of commands. Make sure that
    these commands are in the list: `/refresh-routing`, `/routing-status`,
-   `/routing-plan`, and `/routing-eval`. If they are not in the list, go to
-   [Troubleshooting](#10-troubleshooting).
+   `/routing-plan`, `/routing-eval`, and `/routing-update`. If they are not in the list,
+   go to [Troubleshooting](#10-troubleshooting).
 2. Type this command and push Enter:
 
    ```text
@@ -311,6 +327,19 @@ models of that family.
 }
 ```
 
+### Stop the update check
+
+Once each 24 hours, the router asks npm for the newest version number of the router. It
+sends one request to `registry.npmjs.org` and no other data. When a newer version is
+available, the router shows a toast in OpenCode and a line under the status and the
+scorecard. To stop the check:
+
+```json
+{
+  "updateCheck": false
+}
+```
+
 ### Advanced cost settings
 
 | Key | Default | Meaning |
@@ -356,6 +385,7 @@ These commands work in PowerShell, CMD, Git Bash, macOS, and Linux.
 | `opencode-router plan go-plus --scope global` | Save the plan in the global settings, then calculate and write the routing table |
 | `opencode-router cat` | Show the catalog path, its date, and the number of models |
 | `opencode-router install --scope global` | Write the slash commands as files in `~/.config/opencode/command/`. If `router.config.json` does not exist, it also writes an empty one |
+| `opencode-router update` | Ask npm for the newest version. If the copy that OpenCode keeps is older, remove it. See [Update the router](#12-update-the-router) |
 
 The terminal tool reads the global `router.config.json` and the project file of the
 current folder, in the same way as the plugin.
@@ -436,6 +466,7 @@ The router writes these files:
 | `~/.config/opencode/router/routing-table.json` | Plugin | The last routing table |
 | `~/.config/opencode/router/last-apply.json` | Plugin | The result of the last live apply |
 | `~/.config/opencode/router/eval-report.md` | `/routing-eval` | The test report |
+| `~/.config/opencode/router/update-check.json` | Plugin, `status`, `refresh` | The time of the last update check and the newest version on npm |
 | `~/.config/opencode/opencode.json` | `/refresh-routing`, `/routing-plan` | `model`, `small_model`, and `agent.<role>.model` and `variant` |
 | `~/.config/opencode/router.config.json` | `/routing-plan`, `install` (only if missing) | Your router settings |
 
@@ -466,7 +497,7 @@ Do not commit the `router/` folder. It contains your usage data.
 
 ## 11. Known limits
 
-These are the limits of version 1.0.1.
+These are the limits of version 1.1.1.
 
 1. The router sets the model of the `plan`, `build`, `general`, and `explore` agents at
    each message. If you select a different model by hand, the router replaces it. To
@@ -483,7 +514,59 @@ These are the limits of version 1.0.1.
    rate-limit error for a full session puts only the model of that session into a
    cooldown.
 
-## 12. Remove the router
+## 12. Update the router
+
+OpenCode downloads the plugin one time and then uses its own copy. It does not download
+a newer version automatically. The router looks for a newer version once each 24 hours
+and tells you when one is available.
+
+### With the slash command
+
+1. In the OpenCode prompt, type this command and push Enter:
+
+   ```text
+   /routing-update
+   ```
+
+2. Read the result:
+   - `OpenCode has opencode-router <version>, the newest version.`: you do not have to
+     do more.
+   - `Removed the cached copy: ...`: go to step 3.
+   - `opencode.json pins an older version ...`: do the steps in
+     [With a fixed version](#with-a-fixed-version).
+3. Close OpenCode. Start OpenCode again. OpenCode downloads the newest version when it
+   starts.
+4. Type `/routing-status`. If the line `opencode-router <version> is available` does not
+   show, the update is complete.
+
+Between steps 2 and 3, the router slash commands do not work, because the files that they
+use are removed. Restart OpenCode immediately.
+
+### From a terminal
+
+If the slash commands do not work, close OpenCode and run this command. Then start
+OpenCode again.
+
+```bash
+npx @s-berdia/opencode-router@latest update
+```
+
+This command works in PowerShell, CMD, Git Bash, macOS, and Linux.
+
+### With a fixed version
+
+To select the version yourself, write it in the `plugin` list:
+
+```json
+{
+  "plugin": ["@s-berdia/opencode-router@1.1.1"]
+}
+```
+
+To update, change the number to the new version and restart OpenCode. The newest version
+is on <https://www.npmjs.com/package/@s-berdia/opencode-router>.
+
+## 13. Remove the router
 
 1. Open `opencode.json` (see [step 2](#2-install-the-plugin)).
 2. Remove `"@s-berdia/opencode-router"` from the `plugin` list.
@@ -509,5 +592,6 @@ These are the limits of version 1.0.1.
    ```
 
 6. If you ran `install`, delete these files from `~/.config/opencode/command/`:
-   `refresh-routing.md`, `routing-status.md`, `routing-plan.md`, and `routing-eval.md`.
+   `refresh-routing.md`, `routing-status.md`, `routing-plan.md`, `routing-eval.md`, and
+   `routing-update.md`.
 7. Restart OpenCode.

package/dist/bin.js

@@ -822,12 +822,12 @@ function parseTree(text, errors = [], options = ParseOptions.DEFAULT) {
   }
   return result;
 }
-function findNodeAtLocation(root, path5) {
+function findNodeAtLocation(root, path6) {
   if (!root) {
     return void 0;
   }
   let node = root;
-  for (let segment of path5) {
+  for (let segment of path6) {
     if (typeof segment === "string") {
       if (node.type !== "object" || !Array.isArray(node.children)) {
         return void 0;
@@ -1181,14 +1181,14 @@ function getNodeType(value) {
 
 // node_modules/jsonc-parser/lib/esm/impl/edit.js
 function setProperty(text, originalPath, value, options) {
-  const path5 = originalPath.slice();
+  const path6 = originalPath.slice();
   const errors = [];
   const root = parseTree(text, errors);
   let parent = void 0;
   let lastSegment = void 0;
-  while (path5.length > 0) {
-    lastSegment = path5.pop();
-    parent = findNodeAtLocation(root, path5);
+  while (path6.length > 0) {
+    lastSegment = path6.pop();
+    parent = findNodeAtLocation(root, path6);
     if (parent === void 0 && value !== void 0) {
       if (typeof lastSegment === "string") {
         value = { [lastSegment]: value };
@@ -1413,8 +1413,8 @@ function printParseErrorCode(code) {
   }
   return "<unknown ParseErrorCode>";
 }
-function modify(text, path5, value, options) {
-  return setProperty(text, path5, value, options);
+function modify(text, path6, value, options) {
+  return setProperty(text, path6, value, options);
 }
 function applyEdits(text, edits) {
   let sortedEdits = edits.slice(0).sort((a, b) => {
@@ -1443,10 +1443,13 @@ function globalConfigDir() {
   const base = xdg && xdg.length > 0 ? xdg : path.join(os.homedir(), ".config");
   return path.join(base, "opencode");
 }
-function catalogCacheFile() {
+function opencodeCacheDir() {
   const xdg = process.env.XDG_CACHE_HOME;
   const base = xdg && xdg.length > 0 ? xdg : path.join(os.homedir(), ".cache");
-  return path.join(base, "opencode", "models.json");
+  return path.join(base, "opencode");
+}
+function catalogCacheFile() {
+  return path.join(opencodeCacheDir(), "models.json");
 }
 function globalRouterConfigFile() {
   return path.join(globalConfigDir(), "router.config.json");
@@ -1814,6 +1817,7 @@ function sanitizeUserConfig(raw, file, notes) {
   if (threshold !== void 0 && !(typeof threshold === "number" && threshold > 0 && threshold <= 1)) {
     drop("softThreshold", "must be a number above 0 and at most 1");
   }
+  if (config.updateCheck !== void 0 && typeof config.updateCheck !== "boolean") drop("updateCheck", "must be true or false");
   for (const key of ["denyModels", "allowModels"]) {
     const list = config[key];
     if (list !== void 0 && !(Array.isArray(list) && list.every((item) => typeof item === "string"))) {
@@ -2542,7 +2546,8 @@ var SLASH_COMMANDS = [
   { name: "refresh-routing", description: "Recompute and apply OpenCode model routing", args: "refresh" },
   { name: "routing-status", description: "Show the model in use per role and its 5-hour quota use", args: "status" },
   { name: "routing-plan", description: "Switch the routing plan (go | go-plus | free) and rebuild", args: "plan $1" },
-  { name: "routing-eval", description: "Run the router scoring stress test", args: "eval" }
+  { name: "routing-eval", description: "Run the router scoring stress test", args: "eval" },
+  { name: "routing-update", description: "Update opencode-router to the newest version", args: "update" }
 ];
 var OUTPUT_BEGIN = "---BEGIN ROUTER OUTPUT---";
 function cliScriptPath() {
@@ -2594,6 +2599,9 @@ function ledgerFile() {
 function evalReportFile() {
   return path4.join(stateDir(), "eval-report.md");
 }
+function updateCheckFile() {
+  return path4.join(stateDir(), "update-check.json");
+}
 function applyMarkerFile() {
   return path4.join(stateDir(), "last-apply.json");
 }
@@ -2740,6 +2748,97 @@ async function runEval(opts = {}) {
   return 0;
 }
 
+// src/update.ts
+import fs6 from "fs";
+import path5 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var PACKAGE_NAME = "@s-berdia/opencode-router";
+var LATEST_URL = `https://registry.npmjs.org/${PACKAGE_NAME.replace("/", "%2f")}/latest`;
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var TIMEOUT_MS = 3e3;
+function parseVersion(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+  return match ? match.slice(1).map(Number) : null;
+}
+function isNewerVersion(a, b) {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (!left || !right) return false;
+  for (let i = 0; i < 3; i++) {
+    if (left[i] !== right[i]) return left[i] > right[i];
+  }
+  return false;
+}
+function installedVersion() {
+  const file = fileURLToPath2(new URL("../package.json", import.meta.url));
+  return readJson(file)?.version ?? "0.0.0";
+}
+async function fetchLatestVersion() {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(LATEST_URL, { signal: controller.signal, headers: { accept: "application/json" } });
+    if (!res.ok) return void 0;
+    const body = await res.json();
+    return typeof body.version === "string" ? body.version : void 0;
+  } catch {
+    return void 0;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function checkForUpdate(opts = {}) {
+  try {
+    if (loadUserConfig(opts.projectDir).config.updateCheck === false) return null;
+    const current = opts.current ?? installedVersion();
+    const now = opts.now ?? Date.now();
+    const state = readJson(updateCheckFile());
+    let latest = state?.latest;
+    const fresh = state !== void 0 && now >= state.checkedAt && now - state.checkedAt < CHECK_INTERVAL_MS;
+    if (!fresh) {
+      latest = await fetchLatestVersion() ?? latest;
+      writeJson(updateCheckFile(), { checkedAt: now, latest });
+    }
+    return latest && isNewerVersion(latest, current) ? { current, latest } : null;
+  } catch {
+    return null;
+  }
+}
+function updateNotice(update) {
+  return `opencode-router ${update.latest} is available (installed: ${update.current}). To update, type /routing-update in OpenCode.`;
+}
+function clearOutdatedCopies(latest) {
+  const [scope, name] = PACKAGE_NAME.split("/");
+  const scopeDir = path5.join(opencodeCacheDir(), "packages", scope);
+  const result = { removed: [], pinned: [], current: [], failed: [] };
+  let entries = [];
+  try {
+    entries = fs6.readdirSync(scopeDir);
+  } catch {
+    return result;
+  }
+  for (const entry of entries) {
+    const dir = path5.join(scopeDir, entry);
+    if (entry === name || entry === `${name}@latest`) {
+      const manifest = path5.join(dir, "node_modules", scope, name, "package.json");
+      const version = readJson(manifest)?.version ?? "0.0.0";
+      if (!isNewerVersion(latest, version)) {
+        result.current.push(dir);
+        continue;
+      }
+      try {
+        fs6.rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+        result.removed.push(dir);
+      } catch (error) {
+        result.failed.push({ dir, error: error instanceof Error ? error.message : String(error) });
+      }
+    } else if (entry.startsWith(`${name}@`) && isNewerVersion(latest, entry.slice(name.length + 1))) {
+      result.pinned.push(entry);
+    }
+  }
+  return result;
+}
+
 // src/cli.ts
 var HELP = `opencode-router - dynamic model routing for OpenCode Go / Go Plus / Free
 
@@ -2750,6 +2849,7 @@ Usage:
   opencode-router install [--scope]     Write slash-command files and a starter config
   opencode-router cat                   Show catalog metadata (path, date, model count)
   opencode-router eval                  Run the scoring stress test
+  opencode-router update                Look for a newer version and clear OpenCode's cached copy
 
 Options:
   --plan <go|go-plus|free>   Plan profile for this run
@@ -2814,6 +2914,12 @@ function parseCommandLine(argv, cwd) {
 function build(opts) {
   return buildRoutingTable({ plan: opts.plan, catalogFile: opts.catalog, projectDir: opts.cwd });
 }
+async function writeUpdateNotice(opts) {
+  const update = await checkForUpdate({ projectDir: opts.cwd });
+  if (update) process.stdout.write(`
+${updateNotice(update)}
+`);
+}
 async function cmdRefresh(opts) {
   const { table } = await build(opts);
   if (opts.json) {
@@ -2845,6 +2951,7 @@ Applied: ${detail}
         "A running OpenCode session recomputes routing on its next message (within 15 s). Restart to reload the UI display now.\n"
       );
     }
+    await writeUpdateNotice(opts);
   }
   return 0;
 }
@@ -2858,6 +2965,7 @@ async function cmdStatus(opts) {
     process.stdout.write(JSON.stringify({ table: result.table, rows, usage }, null, 2) + "\n");
   } else {
     process.stdout.write(formatStatus(result.table, rows) + "\n");
+    await writeUpdateNotice(opts);
   }
   return 0;
 }
@@ -2901,6 +3009,44 @@ function cmdInstall(opts) {
   );
   return 0;
 }
+async function cmdUpdate() {
+  const latest = await fetchLatestVersion();
+  if (!latest) {
+    process.stderr.write("error: could not reach the npm registry. Try again later.\n");
+    return 1;
+  }
+  const { removed, pinned, current, failed } = clearOutdatedCopies(latest);
+  if (failed.length > 0) {
+    for (const { dir, error } of failed) process.stderr.write(`error: could not remove ${dir} (${error})
+`);
+    process.stderr.write(`Close OpenCode, then run this command in a terminal: npx ${PACKAGE_NAME}@latest update
+`);
+    return 1;
+  }
+  for (const dir of removed) process.stdout.write(`Removed the cached copy: ${dir}
+`);
+  if (removed.length > 0) {
+    process.stdout.write(`Restart OpenCode. It then installs opencode-router ${latest}.
+`);
+  }
+  if (pinned.length > 0) {
+    process.stdout.write(
+      `opencode.json pins an older version (${pinned.join(", ")}). Change the plugin entry to "${PACKAGE_NAME}@${latest}", then restart OpenCode.
+`
+    );
+  }
+  if (removed.length > 0 || pinned.length > 0) return 0;
+  if (current.length > 0) {
+    process.stdout.write(`OpenCode has opencode-router ${latest}, the newest version.
+`);
+  } else {
+    process.stdout.write(
+      `OpenCode has no cached copy of opencode-router. The newest version is ${latest}. If you use a local build, run git pull and npm run build. If your OpenCode has the command "opencode plugin update", run it.
+`
+    );
+  }
+  return 0;
+}
 function usageError(error) {
   process.stderr.write(`error: ${error.message}
 
@@ -2928,6 +3074,8 @@ async function main(argv, cwd = process.cwd()) {
         return cmdInstall(opts);
       case "eval":
         return await runEval({ plan: opts.plan, catalog: opts.catalog, json: opts.json, projectDir: opts.cwd });
+      case "update":
+        return await cmdUpdate();
       default:
         throw new UsageError(`unknown command "${command}"`);
     }