create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/opencode-cli.js

@@ -0,0 +1,480 @@
+'use strict';
+
+// WP-0 of docs/opencode-lead-and-delegate-model-selection-2026-10-28.html (§6.1):
+// the OpenCode CLI adapter. Dependency-free. It asks the installed `opencode`
+// binary exactly two questions — its version, and its model catalog
+// (`models --verbose`) — through an injectable `execFile`, so tests never spawn a
+// real process and no caller has to know the output shapes.
+//
+// Everything here is deliberately total: `opencodeVersion` never rejects
+// (a missing/timed-out binary is `null`); `opencodeCatalog` rejects only with
+// `.code === 'opencode_catalog_unavailable'`.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFile: nodeExecFile } = require('node:child_process');
+
+const VERSION_TIMEOUT_MS = 5000;
+const CATALOG_TIMEOUT_MS = 15000;
+const CATALOG_CACHE_MS = 60000;
+const MAX_BUFFER = 8 * 1024 * 1024;
+// How far up from the binary's own directory `opencodeLine` looks for a
+// package.json: the binary sits at `<pkg>/bin/opencode(.exe)` (1) or, for the
+// scoped npm layout, `<pkg>/node_modules/@opencode/cli/bin/opencode.exe` — one
+// level is enough, three leaves room for a wrapping shim.
+const PACKAGE_LOOKUP_LEVELS = 3;
+
+/** @typedef {{ major:number, minor:number, patch:number, raw:string, line:'v1'|'v2' }} OpencodeVersion */
+/** @typedef {{ value:string, label:string, sublabel:string, kind:'model', provider:string,
+ *              status:string, variants:string[], efforts:{ values:[], model_default:null } }} OpencodeLeadRow */
+
+// Cache state, keyed by the resolved-bin key from _binCacheKey(). Version entries
+// never expire (a binary's version only changes when its mtime changes); catalog
+// entries carry the `now()` at which they were stored.
+const versionCache = new Map();
+const catalogCache = new Map();
+// Last non-null async line detection (opencodeLine), keyed by the `bin` STRING as
+// given (e.g. 'opencode') so the sync peekOpencodeLine() can answer the launch
+// path without any fs. Only positive ('v1'/'v2') findings are stored: a `null` is
+// never recorded, so a later opencodeVersion() can still supply the fallback.
+const lineByBin = new Map();
+// One in-flight child per (kind, bin key): concurrent callers await the same promise.
+const inflight = new Map();
+
+async function _isFile(candidate, fsImpl) {
+  try {
+    return (await fsImpl.stat(candidate)).isFile();
+  } catch {
+    /* expected: a missing or unreadable PATH candidate is simply not a match */
+    return false;
+  }
+}
+
+// A bare name is resolved by walking env.PATH; a resolved file is keyed by
+// realpath + mtimeMs so an upgrade (or a differently-installed copy) misses the
+// cache. Anything unresolvable falls back to the raw bin string, which is what
+// tests pass (a non-existent name) so their cache keys stay plain.
+async function _binCacheKey(bin, env) {
+  const raw = String(bin == null ? '' : bin);
+  try {
+    let resolved = null;
+    if (raw.includes('/')) {
+      resolved = raw;
+    } else {
+      const pathEnv = (env && env.PATH) || '';
+      for (const dir of String(pathEnv).split(path.delimiter)) {
+        if (!dir) continue;
+        const candidate = path.join(dir, raw);
+        if (await _isFile(candidate, fs.promises)) { resolved = candidate; break; }
+      }
+    }
+    if (resolved && await _isFile(resolved, fs.promises)) {
+      const real = await fs.promises.realpath(resolved);
+      const stat = await fs.promises.stat(real);
+      return `${real}:${stat.mtimeMs}`;
+    }
+  } catch {
+    /* expected: an unresolvable bin falls back to the raw name as its cache key */
+  }
+  return raw;
+}
+
+// The callback contract, deliberately not `promisify(execFile)`: an AbortSignal
+// deadline is enforced here, around the callback, so an injected fake that never
+// calls back still settles. The signal is also handed to execFile, which kills a
+// real child on abort; the listener settles the injected-fake case the same way.
+function _run(execFileImpl, bin, argv, env, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const signal = AbortSignal.timeout(timeoutMs);
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener('abort', onAbort);
+      fn(value);
+    };
+    const onAbort = () => {
+      const err = new Error(`opencode "${argv[0]}" timed out after ${timeoutMs} ms`);
+      err.code = 'opencode_timeout';
+      finish(reject, err);
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    try {
+      execFileImpl(bin, argv, {
+        env,
+        timeout: timeoutMs,
+        maxBuffer: MAX_BUFFER,
+        windowsHide: true,
+        signal,
+      }, (err, stdout) => {
+        if (err) finish(reject, err);
+        else finish(resolve, String(stdout == null ? '' : stdout));
+      });
+    } catch (err) {
+      finish(reject, err);
+    }
+  });
+}
+
+function _parseVersion(stdout) {
+  const match = String(stdout == null ? '' : stdout).match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  const major = Number(match[1]);
+  return {
+    major,
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    raw: match[0],
+    line: major >= 2 ? 'v2' : 'v1',
+  };
+}
+
+function _catalogUnavailable(cause) {
+  const detail = cause && cause.message ? `: ${cause.message}` : '';
+  const err = new Error(`opencode_catalog_unavailable${detail}`);
+  err.code = 'opencode_catalog_unavailable';
+  if (cause !== undefined) err.cause = cause;
+  return err;
+}
+
+// Index just past the JSON object starting at `start` (which must be '{'), or -1
+// when it never closes. Brace depth is tracked with string/escape awareness so a
+// `{` or `}` inside a model description cannot truncate the slice.
+function _matchJsonObject(text, start) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < text.length; i += 1) {
+    const ch = text[i];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === '\\') escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') { inString = true; continue; }
+    if (ch === '{') depth += 1;
+    else if (ch === '}') {
+      depth -= 1;
+      if (depth === 0) return i + 1;
+      if (depth < 0) return -1;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Parses `<bin> models --verbose` stdout: repeated blocks of one `provider/model`
+ * line (it may carry extra slashes and `@`, e.g.
+ * `doordash/@fireworks/accounts/fireworks/models/glm-5p2`) followed by exactly one
+ * pretty-printed JSON object. Garbage between blocks is skipped.
+ * @param {string} stdout
+ * @returns {Array<{ value: string, row: object }>}
+ */
+function parseModelsVerbose(stdout) {
+  const text = String(stdout == null ? '' : stdout);
+  const out = [];
+  let i = 0;
+  while (i < text.length) {
+    let lineEnd = text.indexOf('\n', i);
+    if (lineEnd < 0) lineEnd = text.length;
+    const value = text.slice(i, lineEnd).trim();
+    i = lineEnd + 1;
+    if (!value || value.includes('{') || !value.includes('/')) continue;
+    let j = i;
+    while (j < text.length && /\s/.test(text[j])) j += 1;
+    if (text[j] !== '{') continue;
+    const end = _matchJsonObject(text, j);
+    if (end < 0) continue;
+    let row = null;
+    try {
+      row = JSON.parse(text.slice(j, end));
+    } catch {
+      /* expected: a truncated or non-JSON block is skipped, not fatal */
+      continue;
+    }
+    if (!row || typeof row !== 'object' || Array.isArray(row)) continue;
+    out.push({ value, row });
+    i = end;
+  }
+  return out;
+}
+
+/**
+ * Pure. One catalog entry → one picker row.
+ * @param {string} value the `provider/model` id printed by the CLI
+ * @param {object} row the decoded JSON object
+ * @returns {OpencodeLeadRow}
+ */
+function opencodeRow(value, row) {
+  const r = row && typeof row === 'object' && !Array.isArray(row) ? row : {};
+  return {
+    value,
+    label: r.name || value,
+    sublabel: value,
+    kind: 'model',
+    provider: r.providerID || String(value).split('/')[0],
+    status: r.status || 'active',
+    variants: Object.keys(r.variants || {}),
+    efforts: { values: [], model_default: null },
+  };
+}
+
+/**
+ * `<bin> --version` (timeout VERSION_TIMEOUT_MS), cached per bin key forever.
+ * Resolves `null` — never rejects — when the binary is missing, times out, or
+ * prints no `x.y.z`. A failed call is not cached.
+ * @param {{ bin?:string, env?:object, execFile?:Function, now?:Function, timeoutMs?:number }} [opts]
+ * @returns {Promise<OpencodeVersion|null>}
+ */
+async function opencodeVersion(opts = {}) {
+  const {
+    bin = 'opencode',
+    env = process.env,
+    execFile = nodeExecFile,
+    now = Date.now, // eslint-disable-line no-unused-vars -- accepted for API symmetry
+    timeoutMs = VERSION_TIMEOUT_MS,
+  } = opts;
+  const key = await _binCacheKey(bin, env);
+  if (versionCache.has(key)) return versionCache.get(key);
+
+  const flightKey = `version:${key}`;
+  if (inflight.has(flightKey)) return inflight.get(flightKey);
+
+  const promise = (async () => {
+    try {
+      const stdout = await _run(execFile, bin, ['--version'], env, timeoutMs);
+      return { ok: true, value: _parseVersion(stdout) };
+    } catch {
+      /* expected: missing/timed-out/denied binary -> null, and not cached */
+      return { ok: false, value: null };
+    }
+  })();
+  inflight.set(flightKey, promise);
+  try {
+    const result = await promise;
+    if (result.ok) versionCache.set(key, result.value);
+    return result.value;
+  } finally {
+    inflight.delete(flightKey);
+  }
+}
+
+/**
+ * Pure. OpenCode 2.x `models` output → entries: one trimmed `provider/model` id per line (the id
+ * may hold more `/` and `@` after the provider); lines with spaces or no `/` are skipped, and a
+ * repeated id keeps its first entry. 2.x prints no metadata, so every `row` is `{}`.
+ * @param {string} stdout
+ * @returns {Array<{ value: string, row: object }>}
+ */
+function parseModelsList(stdout) {
+  const seen = new Set();
+  const out = [];
+  for (const raw of String(stdout == null ? '' : stdout).split('\n')) {
+    const value = raw.trim();
+    if (!/^[^\s/]+\/\S+$/.test(value) || seen.has(value)) continue;
+    seen.add(value);
+    out.push({ value, row: {} });
+  }
+  return out;
+}
+
+/**
+ * The catalog of the INSTALLED line (timeout CATALOG_TIMEOUT_MS): 1.x runs `<bin> models --verbose`;
+ * 2.x has no `--verbose` (it exits "Unrecognized flag") and runs `<bin> models --standalone`, a
+ * private server, so the providers of this process's own inline config are listed too (the shared
+ * background service ignores that config, docs/opencode-v2-model-switch-standalone-plugin-2026-10-30.html
+ * P-S4). `opts.line` is a test seam; by default the line comes from opencodeLine(). Deprecated rows are
+ * dropped and the rest sorted by label; the result is cached for
+ * CATALOG_CACHE_MS. Rejects with `.code === 'opencode_catalog_unavailable'`
+ * (cause preserved on `.cause`) on error, timeout, or zero parsed rows.
+ * @param {{ bin?:string, env?:object, execFile?:Function, now?:Function, timeoutMs?:number, line?:'v1'|'v2'|null }} [opts]
+ * @returns {Promise<OpencodeLeadRow[]>}
+ */
+async function opencodeCatalog(opts = {}) {
+  const {
+    bin = 'opencode',
+    env = process.env,
+    execFile = nodeExecFile,
+    now = Date.now,
+    timeoutMs = CATALOG_TIMEOUT_MS,
+  } = opts;
+  // One bin key (realpath + mtime) is one install, so it is one line: the cache needs no line in its key.
+  const key = await _binCacheKey(bin, env);
+  const cached = catalogCache.get(key);
+  if (cached && now() - cached.at < CATALOG_CACHE_MS) return cached.rows;
+
+  const flightKey = `catalog:${key}`;
+  if (inflight.has(flightKey)) return inflight.get(flightKey);
+
+  const promise = (async () => {
+    const line = opts.line !== undefined ? opts.line : await opencodeLine({ bin, env });
+    const argv = line === 'v2' ? ['models', '--standalone'] : ['models', '--verbose'];
+    let stdout;
+    try {
+      stdout = await _run(execFile, bin, argv, env, timeoutMs);
+    } catch (err) {
+      throw _catalogUnavailable(err);
+    }
+    const parsed = line === 'v2' ? parseModelsList(stdout) : parseModelsVerbose(stdout);
+    if (!parsed.length) {
+      throw _catalogUnavailable(new Error(`no model rows parsed from \`${argv.join(' ')}\``));
+    }
+    const rows = parsed
+      .map(({ value, row }) => opencodeRow(value, row))
+      .filter((row) => row.status !== 'deprecated')
+      .sort((a, b) => a.label.localeCompare(b.label));
+    catalogCache.set(key, { at: now(), rows });
+    return rows;
+  })();
+  inflight.set(flightKey, promise);
+  try {
+    return await promise;
+  } finally {
+    inflight.delete(flightKey);
+  }
+}
+
+// A bare name is resolved by walking env.PATH; a path is used as-is. Either way
+// the realpath is returned so the package.json walk starts at the real install
+// location (a `bin/opencode` symlink is the common shape). Unresolvable → null.
+async function _resolveBinFile(bin, env, fsImpl) {
+  const raw = String(bin == null ? '' : bin);
+  try {
+    if (raw.includes('/')) {
+      return (await _isFile(raw, fsImpl)) ? await fsImpl.realpath(raw) : null;
+    }
+    const pathEnv = (env && env.PATH) || '';
+    for (const dir of String(pathEnv).split(path.delimiter)) {
+      if (!dir) continue;
+      const candidate = path.join(dir, raw);
+      if (await _isFile(candidate, fsImpl)) return await fsImpl.realpath(candidate);
+    }
+  } catch {
+    /* expected: an unresolvable or broken bin has no line to report */
+    return null;
+  }
+  return null;
+}
+
+async function _readPackageJson(dir, fsImpl) {
+  try {
+    const parsed = JSON.parse(await fsImpl.readFile(path.join(dir, 'package.json'), 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    /* expected: a missing/invalid package.json is simply not a match */
+    return null;
+  }
+}
+
+// Only the two package names CTM has measured mean anything here; a version
+// without a parseable major is treated as v1 (`opencode-ai` has always been 1.x
+// where it accepted `--model`).
+function _lineFromPackageJson(pkg) {
+  const name = String(pkg && pkg.name ? pkg.name : '').trim();
+  if (name === '@opencode/cli') return 'v2';
+  if (name === 'opencode-ai') {
+    const major = Number.parseInt(String(pkg.version || '').split('.')[0], 10);
+    return Number.isFinite(major) && major >= 2 ? 'v2' : 'v1';
+  }
+  return null;
+}
+
+/**
+ * Async, no spawn. Resolves `bin` (bare name → walk env.PATH; a path → as is),
+ * realpath, then walks up at most PACKAGE_LOOKUP_LEVELS directories from the
+ * binary's directory for a package.json. name '@opencode/cli' → 'v2'; name
+ * 'opencode-ai' → 'v2' if version major >= 2 else 'v1'. Otherwise falls back to
+ * the cached result of a previous opencodeVersion() for the same cache key, else
+ * null. A non-null result is recorded in `lineByBin` under the `bin` string as
+ * given, so the sync peekOpencodeLine() can answer later without any fs. Never
+ * rejects.
+ * @param {{ bin?:string, env?:object, fsImpl?:object }} [opts]
+ * @returns {Promise<'v1'|'v2'|null>}
+ */
+async function opencodeLine({ bin = 'opencode', env = process.env, fsImpl = fs.promises } = {}) {
+  const binKey = String(bin == null ? '' : bin);
+  const key = await _binCacheKey(bin, env);
+  let line = null;
+  try {
+    const resolved = await _resolveBinFile(bin, env, fsImpl);
+    if (resolved) {
+      let dir = path.dirname(resolved);
+      for (let i = 0; i <= PACKAGE_LOOKUP_LEVELS && dir; i += 1) {
+        const pkg = await _readPackageJson(dir, fsImpl);
+        if (pkg) {
+          line = _lineFromPackageJson(pkg);
+          break;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+      }
+    }
+  } catch {
+    /* expected: any fs surprise degrades to the cached-version fallback */
+    line = null;
+  }
+
+  if (!line) {
+    const cachedVersion = versionCache.get(key);
+    line = (cachedVersion && cachedVersion.line) || null;
+  }
+  if (line) lineByBin.set(binKey, line);
+  return line;
+}
+
+/**
+ * R-6 (docs/opencode-v2-model-switch-standalone-plugin-2026-10-30.html §5.1/§6.1): prime the line
+ * for `bin` ASYNCHRONOUSLY, before any OpenCode launch argv is built. server.js's handleCreate
+ * awaits this once, at the top of an OpenCode create/restore, so the sync argv path can then read
+ * the answer with no fs at all (peekOpencodeLine). Returns the peeked line when one is already
+ * known, else the result of opencodeLine() — which memoises into `lineByBin` and, by its own
+ * contract, never rejects (a missing/unreadable bin is `null`). Never rejects here either.
+ * @param {{ bin?:string, env?:object }} [opts]
+ * @returns {Promise<'v1'|'v2'|null>}
+ */
+async function primeOpencodeLine({ bin = 'opencode', env = process.env } = {}) {
+  const known = peekOpencodeLine({ bin });
+  if (known) return known;
+  try {
+    return await opencodeLine({ bin, env });
+  } catch {
+    /* expected: opencodeLine never rejects, but a prime must not be able to fail a launch */
+    return null;
+  }
+}
+
+/**
+ * Sync, NO fs, NO spawn: the last non-null opencodeLine() result for this `bin`
+ * string, else null. The launch path calls this so it never blocks on the fs.
+ * @param {{ bin?:string }} [opts]
+ * @returns {'v1'|'v2'|null}
+ */
+function peekOpencodeLine({ bin = 'opencode' } = {}) {
+  const binKey = String(bin == null ? '' : bin);
+  return lineByBin.get(binKey) || null;
+}
+
+/** Tests only: drop every cached version, catalog, line, and in-flight entry. */
+function _resetOpencodeCliCache() {
+  versionCache.clear();
+  catalogCache.clear();
+  lineByBin.clear();
+  inflight.clear();
+}
+
+module.exports = {
+  opencodeVersion,
+  opencodeCatalog,
+  opencodeLine,
+  primeOpencodeLine,
+  peekOpencodeLine,
+  opencodeRow,
+  parseModelsVerbose,
+  parseModelsList,
+  _resetOpencodeCliCache,
+  VERSION_TIMEOUT_MS,
+  CATALOG_TIMEOUT_MS,
+  CATALOG_CACHE_MS,
+};