model-compare-opencode-plugin 0.0.0-stage → 0.1.1

package/src/opencode/storage.ts

@@ -0,0 +1,97 @@
+// src/opencode/storage.ts
+// Versioned records in ctx.storage (design §7.2). OpenCode's plugin storage
+// is scoped to the plugin; records carry a version so corrupt or
+// unknown-version state is discarded instead of crashing the plugin.
+
+import { validateStoredCatalog } from "../core/catalog"
+import { fnv1aHex } from "../core/hash"
+import type { Sourced } from "../core/types"
+
+// The slice of OpenCode's ctx.storage the plugin relies on.
+export type Storage = {
+  get(key: string): Promise<unknown>
+  set(key: string, value: unknown): Promise<void>
+}
+
+// Reads a versioned record. Returns null — never throws — when the key is
+// missing, the value is not a JSON object, or `v` is missing or not 1 (§7.2:
+// corrupt or unknown-version entries are discarded and treated as absent).
+export async function readRecord<T extends { v: number }>(
+  storage: Storage,
+  key: string,
+): Promise<T | null> {
+  const raw: unknown = await storage.get(key)
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null
+  if ((raw as { v?: unknown }).v !== 1) return null
+  return raw as T
+}
+
+// Writes a versioned record. `value` already carries its `v`; the spread
+// simply guarantees the written shape is { ...value, v }.
+export async function writeRecord(
+  storage: Storage,
+  key: string,
+  value: { v: number } & Record<string, unknown>,
+): Promise<void> {
+  await storage.set(key, { ...value, v: value.v })
+}
+
+// ---- the document cache (§7.9) ------------------------------------------------
+// The last validated catalog and when the plugin acquired it:
+//   { v: 1, source: <identity>, doc: Catalog, acquiredAt: number }
+// stored per SOURCE IDENTITY, so a document is only ever served for the source
+// that produced it: changing `catalogURL`, `scriptPath` or `source` is a cache
+// miss, never a 6-hour stale answer from the previous source.
+
+export const remoteIdentity = (url: string): string => `remote:${url}`
+// The vendored copy has a fixed identity: its path changes with every install
+// location/version, and a plugin update must not look like a cold start.
+export const localIdentity = (scriptPath: string | null): string =>
+  `local:${scriptPath ?? "vendored"}`
+
+export const docCacheKey = (identity: string): string => `doc/cache/${fnv1aHex(identity)}`
+
+type DocCacheRecord = { v: number; source: unknown; doc: unknown; acquiredAt: unknown }
+
+// The cached document for one source identity, or null when there is none, it
+// belongs to another identity (a key collision), or it fails validation — a
+// corrupt record is a cache miss, never an exception mid-setup.
+export async function readCachedDoc(storage: Storage, identity: string): Promise<Sourced | null> {
+  const record = await readRecord<DocCacheRecord>(storage, docCacheKey(identity))
+  if (record === null) return null
+  if (record.source !== identity) return null
+  if (typeof record.acquiredAt !== "number") return null
+  const validated = validateStoredCatalog(record.doc)
+  if (!validated.ok) {
+    console.warn("[model-compare]", `discarding the cached catalog: ${validated.reason}`)
+    return null
+  }
+  return { doc: validated.catalog, acquiredAt: record.acquiredAt }
+}
+
+export async function writeCachedDoc(
+  storage: Storage,
+  identity: string,
+  sourced: Sourced,
+): Promise<void> {
+  await writeRecord(storage, docCacheKey(identity), {
+    v: 1,
+    source: identity,
+    doc: sourced.doc,
+    acquiredAt: sourced.acquiredAt,
+  })
+}
+
+// The most recently acquired valid document among the given identities (setup
+// seeds from it; under `auto` either source may have produced it).
+export async function readNewestCachedDoc(
+  storage: Storage,
+  identities: readonly string[],
+): Promise<Sourced | null> {
+  let newest: Sourced | null = null
+  for (const identity of identities) {
+    const cached = await readCachedDoc(storage, identity)
+    if (cached !== null && (newest === null || cached.acquiredAt > newest.acquiredAt)) newest = cached
+  }
+  return newest
+}

package/src/opencode/usebest.ts

@@ -0,0 +1,121 @@
+// src/opencode/usebest.ts
+// Shared /use-best decision + alias-view helpers (design §10). Pure module:
+// no OpenCode imports, no I/O. Both the server command (src/index.ts) and the
+// TUI entry (src/tui.tsx) consume it, so their decisions and messages can
+// never drift apart.
+
+import { parseUseBest, sanitizeCatalogText } from "./commands"
+import type { Priority } from "../core/types"
+
+export const PRIORITIES: readonly Priority[] = ["balanced", "price", "quality"]
+export const ALIAS_PROVIDER = "openrouter"
+export const aliasId = (p: Priority): string => `model-compare/${p}`
+export const aliasRef = (p: Priority): string => `${ALIAS_PROVIDER}/${aliasId(p)}`
+
+// The headless refusal text (§10; pinned by the integration suite's
+// REFUSAL_TEXT).
+export function useBestRefusal(p: Priority): string {
+  return `model-compare: ${aliasRef(p)} is currently disabled (no ranking data); not switching`
+}
+
+// The switch notice: the pick shown is the one the alias serves right now (a
+// pin can differ from rank 1 — minLead hysteresis), sanitized (F-20); "null"
+// means the caller could not observe a pick and says "unavailable".
+export function useBestNotice(p: Priority, currentPickId: string | null): string {
+  const pick = currentPickId === null ? "unavailable" : sanitizeCatalogText(currentPickId)
+  return `model-compare: switched to ${aliasRef(p)} (currently ${pick})`
+}
+
+// The full decision for a /use-best invocation: argument parsing plus the
+// enabled gate. `enabled` is the caller's registry view of each priority —
+// the server command reads state.enabled, the TUI entry reads the model
+// registry (which omits disabled aliases in some states and reports
+// `enabled: false` in others; absence is read as disabled by the caller).
+export function useBestDecision(input: {
+  argument: string
+  defaultPriority: Priority
+  enabled: (p: Priority) => boolean
+}): { ok: true; priority: Priority } | { ok: false; message: string } {
+  const parsed = parseUseBest(input.argument, input.defaultPriority)
+  if (!parsed.ok) return parsed
+  if (!input.enabled(parsed.priority)) {
+    return { ok: false, message: useBestRefusal(parsed.priority) }
+  }
+  return parsed
+}
+
+// ---- registry views (the TUI side's data source) ---------------------------
+
+// One model-compare alias as observed in the model registry.
+export type AliasView = {
+  priority: Priority
+  name: string
+  enabled: boolean
+  modelID: string | null
+}
+
+// Extract the plugin's alias entries from a model-list response. Only entries
+// present in the list are returned; a disabled alias is either omitted
+// entirely or reported with enabled: false — callers must treat a missing
+// view as disabled (probe-verified: list() omits disabled aliases).
+export function readAliasViews(
+  entries: ReadonlyArray<{ id?: unknown; name?: unknown; enabled?: unknown; modelID?: unknown }>,
+): AliasView[] {
+  const prefix = "model-compare/"
+  const views: AliasView[] = []
+  for (const entry of entries) {
+    if (typeof entry.id !== "string" || !entry.id.startsWith(prefix)) continue
+    const priority = entry.id.slice(prefix.length)
+    if (!PRIORITIES.includes(priority as Priority)) continue
+    views.push({
+      priority: priority as Priority,
+      name: typeof entry.name === "string" ? entry.name : "",
+      enabled: entry.enabled !== false,
+      modelID: typeof entry.modelID === "string" ? entry.modelID : null,
+    })
+  }
+  return views.sort(
+    (x, y) => PRIORITIES.indexOf(x.priority) - PRIORITIES.indexOf(y.priority),
+  )
+}
+
+// The pick shown in an alias's display name:
+// "Model Compare: <p> → <pick>[( fallback)]" → "<pick>[( fallback)]", or null
+// for the "(unavailable)" placeholder names.
+export function pickFromName(name: string): string | null {
+  const arrow = name.indexOf("→")
+  if (arrow === -1) return null
+  return name.slice(arrow + 1).trim()
+}
+
+// The pick an ENABLED alias view serves, or null when nothing observable is
+// served: the display name is the truth (it mirrors the picker, including
+// the "(fallback)" marker); modelID is the fallback when the name has no
+// arrow; an empty name is also "nothing observable". Exported for the TUI
+// half's picks dialog (statusLine's rules, one priority at a time). The
+// result is a DISPLAY string only (footer, dialog, toasts) and is flattened
+// here (F-20) as defense in depth: the name is normally built sanitized by
+// planAlias, but modelID is registry-sourced and can carry raw catalog text.
+export function pickOf(view: AliasView): string | null {
+  const pick = pickFromName(view.name) ?? view.modelID ?? (view.name === "" ? null : "unavailable")
+  return pick === null ? null : sanitizeCatalogText(pick)
+}
+
+// The priority column width for aligned pick rows: the longest priority
+// name ("balanced"), so every arrow — and the pick after it — starts at the
+// same column in the picks dialog: `price` gains three spaces before its
+// arrow, `quality` one.
+export function alignedPriority(priority: Priority): string {
+  return priority.padEnd(Math.max(...PRIORITIES.map((p) => p.length)))
+}
+
+// The compact footer line — the balanced pick only, e.g.
+// `MC: balanced → xiaomi/mimo-v2.6-flash`. The full three-priority view
+// lives behind the picks dialog (a select over the alias views);
+// registry-absent and disabled aliases read "disabled", a present-but-
+// unresolvable one reads "unavailable" — the line never vanishes.
+export function statusLine(views: AliasView[]): string {
+  const view = views.find((item) => item.priority === "balanced")
+  if (view === undefined || view.enabled === false) return "MC: balanced → disabled"
+  return `MC: balanced → ${pickOf(view) ?? "unavailable"}`
+}

package/src/rpc.ts

@@ -0,0 +1,78 @@
+// src/rpc.ts
+// The plugin's RPC surface (V2 plugins RPC): methods the TUI half and other
+// clients can call on the server plugin, plus the event the /model-compare
+// command emits. The report method returns the SAME text the command
+// synthesizes — one builder in src/index.ts serves both, so the two can
+// never drift. The report EVENT carries the structured entries (the TUI's
+// selectable report dialog), because the transcript notice itself only
+// surfaces at the session's next turn.
+import { Rpc } from "@opencode/plugin/rpc"
+
+export const ModelCompare = Rpc.define({
+  id: "model-compare",
+  methods: {
+    report: {
+      input: { type: "object", properties: {}, additionalProperties: false },
+      output: {
+        type: "object",
+        properties: {
+          text: { type: "string" },
+          age: { type: ["string", "null"] },
+          entries: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                priority: { type: "string" },
+                rank: { type: ["integer", "null"] },
+                id: { type: "string" },
+                value: { type: "string" },
+                score: { type: "string" },
+                quality: { type: "string" },
+                price: { type: "string" },
+                current: { type: "boolean" },
+                fromFallback: { type: "boolean" },
+              },
+              required: ["priority", "rank", "id", "value", "score", "quality", "price", "current", "fromFallback"],
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ["text", "age", "entries"],
+        additionalProperties: false,
+      },
+    },
+  },
+  events: {
+    report: {
+      schema: {
+        type: "object",
+        properties: {
+          sessionID: { type: "string" },
+          age: { type: ["string", "null"] },
+          entries: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                priority: { type: "string" },
+                rank: { type: ["integer", "null"] },
+                id: { type: "string" },
+                value: { type: "string" },
+                score: { type: "string" },
+                quality: { type: "string" },
+                price: { type: "string" },
+                current: { type: "boolean" },
+                fromFallback: { type: "boolean" },
+              },
+              required: ["priority", "rank", "id", "value", "score", "quality", "price", "current", "fromFallback"],
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ["sessionID", "age", "entries"],
+        additionalProperties: false,
+      },
+    },
+  },
+})

package/src/sources/index.ts

@@ -0,0 +1,115 @@
+// src/sources/index.ts
+// Source selection and acquisition (design §3, §9): pick the catalog source
+// and run it. "local" runs the configured-or-vendored script and rejects on
+// failure — the caller keeps its last-known-good document. "auto" probes
+// python first, runs local when it passes, and degrades to the remote catalog
+// with an actionable warning when python is unusable or the local run fails
+// (§3: warn and degrade, never throw from setup). "remote" fetches the
+// published catalog without ever touching python. Only a failed remote
+// fallback rejects.
+
+import { fileURLToPath } from "node:url"
+import type { Config } from "../config"
+import type { Sourced } from "../core/types"
+import { localIdentity, remoteIdentity, type Storage } from "../opencode/storage"
+import { probePython, runLocalScript } from "./local"
+import { fetchRemote } from "./remote"
+
+// The vendored script, resolved from this module (src/sources/) back to the
+// package root so it is found regardless of the process's working directory.
+const VENDORED_SCRIPT = fileURLToPath(new URL("../../vendor/model_compare.py", import.meta.url))
+
+// Injectable seams for tests; each defaults to the real implementation.
+// storage is required because the remote path cannot proceed without it.
+export type AcquireDeps = {
+  storage: Storage
+  probePython?: typeof probePython
+  runLocal?: typeof runLocalScript
+  fetchRemote?: typeof fetchRemote
+}
+
+export type Acquired = {
+  sourced: Sourced
+  source: "local" | "remote"
+  // The cache identity of the source that produced the document (storage.ts):
+  // the tick persists the document under it.
+  identity: string
+  fromCache: boolean
+  warnings: string[]
+}
+
+// runLocalScript prefixes every failure with this; the fallback warning
+// re-wraps the cause instead of repeating the prefix.
+const LOCAL_PREFIX = "local source failed: "
+
+function asReason(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export async function acquire(cfg: Config, deps: AcquireDeps): Promise<Acquired> {
+  const probe = deps.probePython ?? probePython
+  const runLocal = deps.runLocal ?? runLocalScript
+  const doFetch = deps.fetchRemote ?? fetchRemote
+
+  const scriptPath = cfg.scriptPath ?? VENDORED_SCRIPT
+
+  // Remote mode never probes python or runs the script (§9). fetchRemote's
+  // fromCache flag is lifted to the result; sourced itself stays a plain
+  // Sourced (§5).
+  if (cfg.source === "remote") {
+    const { doc, acquiredAt, fromCache } = await doFetch(cfg.catalogURL, deps.storage)
+    return {
+      sourced: { doc, acquiredAt },
+      source: "remote",
+      identity: remoteIdentity(cfg.catalogURL),
+      fromCache,
+      warnings: [],
+    }
+  }
+
+  if (cfg.source === "local") {
+    const sourced = await runLocal(scriptPath)
+    return { sourced, source: "local", identity: localIdentity(cfg.scriptPath), fromCache: false, warnings: [] }
+  }
+
+  // Auto: probe first; a usable python gets one local attempt. Either
+  // failure — the probe or the run — degrades to remote with the cause named.
+  const warnings: string[] = []
+  const probed = await probe()
+  if (probed.ok) {
+    try {
+      const sourced = await runLocal(scriptPath)
+      return {
+        sourced,
+        source: "local",
+        identity: localIdentity(cfg.scriptPath),
+        fromCache: false,
+        warnings: [],
+      }
+    } catch (error) {
+      const cause = asReason(error).replace(LOCAL_PREFIX, "")
+      warnings.push(`local source failed (${cause}); using remote catalog`)
+    }
+  } else {
+    warnings.push(`${probed.reason}; using remote catalog`)
+  }
+
+  const { doc, acquiredAt, fromCache } = await doFetch(cfg.catalogURL, deps.storage)
+  return {
+    sourced: { doc, acquiredAt },
+    source: "remote",
+    identity: remoteIdentity(cfg.catalogURL),
+    fromCache,
+    warnings,
+  }
+}
+
+// The cache identities a configuration can have produced a document under:
+// setup seeds from the newest of them (under `auto` either source may have won).
+export function cacheIdentities(cfg: Config): string[] {
+  const local = localIdentity(cfg.scriptPath)
+  const remote = remoteIdentity(cfg.catalogURL)
+  if (cfg.source === "local") return [local]
+  if (cfg.source === "remote") return [remote]
+  return [local, remote]
+}

package/src/sources/local.ts

@@ -0,0 +1,175 @@
+// src/sources/local.ts
+// The local catalog source (design §9, §11): run the vendored script with
+// execFile — no shell, a timeout, and a minimal environment — then parse and
+// validate whatever it printed. Any failure (missing interpreter, non-zero
+// exit, timeout, invalid JSON, rejected document) rejects as
+// "local source failed: <reason>"; the exit code only refines the message,
+// with stderr informing it (§9).
+
+import { execFile as execFileCallback } from "node:child_process"
+import { promisify } from "node:util"
+import { validateCatalog } from "../core/catalog"
+import type { Sourced } from "../core/types"
+
+const execFile = promisify(execFileCallback)
+
+const STDERR_TAIL_CHARS = 500
+
+// execFile's default maxBuffer is 1 MiB — easily exceeded by a catalog
+// stdout, and the default kill would report it as a generic failure. An
+// explicit, generous cap keeps normal runs safe while bounding memory.
+export const MAX_BUFFER_BYTES = 64 * 1024 * 1024 // 64 MiB
+
+// The version probe prints one line; ten seconds is generous. A hung
+// interpreter (a stuck version-manager shim) must not stall the refresh tick.
+const PROBE_TIMEOUT_MS = 10_000
+
+// Environment variables the script may need beyond HOME and PATH (design
+// §11): its cache location, the AA key, proxy settings in both casings, and
+// custom CA paths. Passed through only when set and non-empty.
+const PASSTHROUGH_ENV = [
+  "XDG_CACHE_HOME",
+  "AA_API_KEY",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "NO_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "no_proxy",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+] as const
+
+// The shape execFile rejects with on failure: `code` is the exit status for a
+// non-zero exit, "ENOENT" when the interpreter is missing, and null when the
+// child was killed by a signal; `stdout`/`stderr` carry what was collected.
+type ExecFileError = Error & {
+  code?: string | number
+  killed?: boolean
+  signal?: NodeJS.Signals | null
+  stdout?: string
+  stderr?: string
+}
+
+// The script's environment (design §11): HOME and PATH from process.env
+// (omitted when absent) plus the passthrough list when set and non-empty.
+// Built fresh — process.env itself is never touched.
+export function scriptEnv(): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {}
+  for (const key of ["HOME", "PATH"] as const) {
+    const value = process.env[key]
+    if (value !== undefined) env[key] = value
+  }
+  for (const key of PASSTHROUGH_ENV) {
+    const value = process.env[key]
+    if (value !== undefined && value !== "") env[key] = value
+  }
+  return env
+}
+
+// The trimmed last chunk of stderr for failure messages; empty stderr
+// contributes nothing to the message.
+function stderrTail(stderr: string | undefined): string {
+  const text = (stderr ?? "").trim()
+  if (text === "") return ""
+  const tail = text.length > STDERR_TAIL_CHARS ? text.slice(-STDERR_TAIL_CHARS) : text
+  return `; stderr: ${tail}`
+}
+
+// Whether the plugin can run the vendored script at all: python3 present and
+// at least 3.10 (design §9). The reason names what failed.
+export async function probePython(
+  timeoutMs = PROBE_TIMEOUT_MS,
+): Promise<{ ok: true } | { ok: false; reason: string }> {
+  let version: string
+  try {
+    const { stdout } = await execFile(
+      "python3",
+      ["-c", "import sys; print('.'.join(map(str, sys.version_info[:2])))"],
+      { timeout: timeoutMs, maxBuffer: MAX_BUFFER_BYTES },
+    )
+    version = stdout.trim()
+  } catch (error) {
+    const err = error as ExecFileError
+    if (err.code === "ENOENT") {
+      return { ok: false, reason: "python3 not found (spawn ENOENT)" }
+    }
+    if (err.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+      return { ok: false, reason: `python3 probe output exceeded the ${MAX_BUFFER_BYTES / (1024 * 1024)} MiB cap` }
+    }
+    if (err.killed && err.signal) {
+      return { ok: false, reason: `python3 probe timed out after ${timeoutMs}ms` }
+    }
+    return { ok: false, reason: `python3 could not be probed: ${err.message}` }
+  }
+
+  const match = /^(\d+)\.(\d+)$/.exec(version)
+  if (match === null) {
+    return {
+      ok: false,
+      reason: `python3 reported unparseable version info: ${JSON.stringify(version)}`,
+    }
+  }
+  const major = Number(match[1])
+  const minor = Number(match[2])
+  if (major < 3 || (major === 3 && minor < 10)) {
+    return { ok: false, reason: `python3 is ${major}.${minor}, need >= 3.10` }
+  }
+  return { ok: true }
+}
+
+// Run the script (an explicit path — resolving the vendored default is the
+// caller's job), validate its stdout, and stamp the plugin's own acquisition
+// time on the document (design §5, §9).
+export async function runLocalScript(
+  scriptPath: string,
+  timeoutMs = 60_000,
+): Promise<Sourced> {
+  let stdout: string
+  try {
+    const result = await execFile("python3", [scriptPath, "--catalog"], {
+      env: scriptEnv(),
+      timeout: timeoutMs,
+      maxBuffer: MAX_BUFFER_BYTES,
+    })
+    stdout = result.stdout
+  } catch (error) {
+    const err = error as ExecFileError
+    const stderr = stderrTail(err.stderr)
+    if (err.code === "ENOENT") {
+      throw new Error(`local source failed: python3 not found (spawn ENOENT)${stderr}`)
+    }
+    // Checked before the signal branch: the maxBuffer kill also sets
+    // killed/signal, but its reason is distinct — the output cap, not the
+    // timeout.
+    if (err.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+      throw new Error(
+        `local source failed: script output exceeded the ${MAX_BUFFER_BYTES / (1024 * 1024)} MiB cap${stderr}`,
+      )
+    }
+    if (err.signal) {
+      const cause = err.killed
+        ? `timed out after ${timeoutMs}ms`
+        : `terminated by ${err.signal}`
+      throw new Error(`local source failed: ${cause} (killed with ${err.signal})${stderr}`)
+    }
+    if (typeof err.code === "number") {
+      throw new Error(`local source failed: exit code ${err.code}${stderr}`)
+    }
+    throw new Error(`local source failed: ${err.message}${stderr}`)
+  }
+
+  let raw: unknown
+  try {
+    raw = JSON.parse(stdout)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`local source failed: invalid JSON on stdout (${message})`)
+  }
+
+  const validated = validateCatalog(raw)
+  if (!validated.ok) {
+    throw new Error(`local source failed: invalid catalog document: ${validated.reason}`)
+  }
+  return { doc: validated.catalog, acquiredAt: Date.now() }
+}