@deeeed/metamask-harness 0.5.0 → 0.6.0

package/src/commands/shared.ts

@@ -1,235 +0,0 @@
-// Shared helpers for the mm-harness command modules: flag parsing, adapter
-// resolution, script composition, and the teaching-error emitter. Each command
-// module composes adapters/ scripts directly via spawnScript.
-//
-// Composition seam (overridable for contract tests):
-//   MM_HARNESS_SCRIPT_BIN_<STEM>  — override a specific script by its basename.
-//   For node invocations (bin === process.execPath) the stem is derived from the
-//   script path in args[0], e.g. MM_HARNESS_SCRIPT_BIN_OPEN_DEBUG_MJS.
-
-import { spawn, spawnSync } from 'node:child_process';
-import path from 'node:path';
-
-import { detectAdapter } from '../harness.ts';
-import { resolveLeafInvoke, shellLeafMissing } from '../leaf-invoke.ts';
-import { runnerDir } from '../paths.ts';
-import type { MetaMaskRecipeAdapter } from '../types.ts';
-
-// Exit-code taxonomy (docs/CLI-SPEC.md §5.6).
-export const EXIT = { ok: 0, runtime: 1, usage: 2, infra: 3, bounded: 4, validation: 5 } as const;
-
-// Adapters that launch a live app surface (core is headless).
-export type DeviceAdapter = 'mobile' | 'extension';
-
-export interface ParsedFlags {
-  positional: string[];
-  options: Record<string, string | boolean>;
-}
-
-// Positionals + boolean/valued flags; camelCases --foo-bar to fooBar.
-export function parseFlags(argv: string[], booleans: Set<string>): ParsedFlags {
-  const positional: string[] = [];
-  const options: Record<string, string | boolean> = {};
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (!arg.startsWith('--')) {
-      positional.push(arg);
-      continue;
-    }
-    const body = arg.slice(2);
-    const eq = body.indexOf('=');
-    const rawKey = eq === -1 ? body : body.slice(0, eq);
-    const inline = eq === -1 ? undefined : body.slice(eq + 1);
-    const key = rawKey.replace(/-([a-z])/gu, (_, c: string) => c.toUpperCase());
-    if (booleans.has(key)) {
-      options[key] = inline === undefined ? true : inline !== 'false';
-      continue;
-    }
-    if (inline !== undefined) {
-      options[key] = inline;
-      continue;
-    }
-    // Valued flag with a following token, unless the next token is itself a flag.
-    const next = argv[i + 1];
-    if (next === undefined || next.startsWith('--')) {
-      options[key] = true;
-      continue;
-    }
-    options[key] = next;
-    i += 1;
-  }
-  return { positional, options };
-}
-
-export function str(options: Record<string, string | boolean>, key: string): string | undefined {
-  const value = options[key];
-  return typeof value === 'string' ? value : undefined;
-}
-
-export function flag(options: Record<string, string | boolean>, key: string): boolean {
-  return options[key] === true;
-}
-
-export function targetOf(options: Record<string, string | boolean>): string {
-  return path.resolve(str(options, 'target') ?? str(options, 'projectRoot') ?? process.cwd());
-}
-
-const ADAPTER_TOKENS: readonly string[] = ['mobile', 'extension', 'core'];
-
-// Explicit --adapter/--platform, else an optional hint, else auto-detect from the
-// target. Reimplemented here (rather than shared with cli.ts) to avoid a cycle.
-export function resolveAdapter(
-  options: Record<string, string | boolean>,
-  target: string,
-  hint?: MetaMaskRecipeAdapter,
-): MetaMaskRecipeAdapter | undefined {
-  const explicit = str(options, 'adapter') ?? str(options, 'platform');
-  if (explicit && ADAPTER_TOKENS.includes(explicit)) return explicit as MetaMaskRecipeAdapter;
-  if (hint) return hint;
-  return detectAdapter(target);
-}
-
-export interface ScriptResult {
-  status: number;
-  output: string;
-}
-
-// Compose an adapters/ script directly. Output is always captured (needed for
-// heal classification) and, in human mode, forwarded to stderr. --json keeps
-// stdout clean for the machine summary. `env` overlays extra vars onto the
-// inherited environment for spawns that need a scoped variable (e.g. color mode).
-export function spawnScript(
-  script: string,
-  args: string[],
-  cwd: string,
-  json: boolean,
-  env?: Record<string, string>,
-): ScriptResult {
-  // For node invocations (script === process.execPath) the seam stem is derived
-  // from args[0] so each spawned script has its own override key.
-  const isNodeScript = script === process.execPath && args.length > 0;
-  // Seam stem: for node invocations derive from args[0] so each script has its
-  // own override key; for shell and other leaves derive from the script basename.
-  const stem = isNodeScript
-    ? path.basename(args[0]).replace(/[^A-Za-z0-9]/gu, '_').toUpperCase()
-    : path.basename(script).replace(/[^A-Za-z0-9]/gu, '_').toUpperCase();
-  const override = process.env[`MM_HARNESS_SCRIPT_BIN_${stem}`];
-  const bin = override ?? script;
-  const directArgs = override !== undefined && isNodeScript ? args.slice(1) : args;
-
-  // Shell leaves (.sh) run through bash so file mode need not be executable.
-  // Bash exits 127 (not a Node spawn error) for a missing file, so pre-check.
-  if (shellLeafMissing(bin)) {
-    const message =
-      `leaf could not start: ${path.basename(bin)} (ENOENT)\n` +
-      `  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) — the shell leaf is missing or not executable`;
-    process.stderr.write(`${message}\n`);
-    return { status: 1, output: message };
-  }
-
-  const { bin: invokeBin, args: spawnArgs } = resolveLeafInvoke(bin, directArgs);
-  const result = spawnSync(invokeBin, spawnArgs, {
-    cwd,
-    encoding: 'utf8',
-    env: env ? { ...process.env, ...env } : process.env,
-    maxBuffer: 64 * 1024 * 1024,
-  });
-  if (result.error) {
-    // Spawn failure for non-shell leaves (ENOENT/EACCES) or when bash itself
-    // cannot start. Always emit so a leaf that cannot start is never silent.
-    // For node invocations the leaf name comes from args[0], not process.execPath.
-    const leaf = isNodeScript ? path.basename(args[0]) : path.basename(script);
-    const code = (result.error as NodeJS.ErrnoException).code ?? 'ESPAWN';
-    const message =
-      `leaf could not start: ${leaf} (${code})\n` +
-      `  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) — the shell leaf is missing or not executable`;
-    process.stderr.write(`${message}\n`);
-    return { status: 1, output: message };
-  }
-  const output = `${result.stdout ?? ''}${result.stderr ?? ''}`;
-  if (!json && output) process.stderr.write(output);
-  return { status: result.status ?? 1, output };
-}
-
-// Streaming variant of spawnScript for long-running leaves (mobile prepare:
-// native build + Metro + health-bridge poll, minutes long). spawnScript buffers
-// via spawnSync and, in --json mode, suppresses output entirely — so those leaves
-// run with zero feedback until exit. This tees the child's stdout+stderr to the
-// parent's STDERR live (so the --json envelope on stdout stays clean) while still
-// capturing the combined output for heal classification. Same seam, leaf-invoke
-// resolution, missing-leaf pre-check, and spawn-error contract as spawnScript.
-export function spawnScriptStreaming(
-  script: string,
-  args: string[],
-  cwd: string,
-  env?: Record<string, string>,
-): Promise<ScriptResult> {
-  const isNodeScript = script === process.execPath && args.length > 0;
-  const stem = isNodeScript
-    ? path.basename(args[0]).replace(/[^A-Za-z0-9]/gu, '_').toUpperCase()
-    : path.basename(script).replace(/[^A-Za-z0-9]/gu, '_').toUpperCase();
-  const override = process.env[`MM_HARNESS_SCRIPT_BIN_${stem}`];
-  const bin = override ?? script;
-  const directArgs = override !== undefined && isNodeScript ? args.slice(1) : args;
-
-  if (shellLeafMissing(bin)) {
-    const message =
-      `leaf could not start: ${path.basename(bin)} (ENOENT)\n` +
-      `  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) — the shell leaf is missing or not executable`;
-    process.stderr.write(`${message}\n`);
-    return Promise.resolve({ status: 1, output: message });
-  }
-
-  const { bin: invokeBin, args: spawnArgs } = resolveLeafInvoke(bin, directArgs);
-  return new Promise<ScriptResult>((resolve) => {
-    const child = spawn(invokeBin, spawnArgs, {
-      cwd,
-      env: env ? { ...process.env, ...env } : process.env,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    let output = '';
-    // Route BOTH child streams to the parent's stderr, live: stdout is reserved
-    // for the harness --json envelope, so all human/leaf progress goes to stderr.
-    const tee = (chunk: Buffer): void => {
-      const text = chunk.toString('utf8');
-      output += text;
-      process.stderr.write(text);
-    };
-    child.stdout?.on('data', tee);
-    child.stderr?.on('data', tee);
-    child.on('error', (error: NodeJS.ErrnoException) => {
-      const leaf = isNodeScript ? path.basename(args[0]) : path.basename(script);
-      const code = error.code ?? 'ESPAWN';
-      const message =
-        `leaf could not start: ${leaf} (${code})\n` +
-        `  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) — the shell leaf is missing or not executable`;
-      process.stderr.write(`${message}\n`);
-      resolve({ status: 1, output: message });
-    });
-    child.on('close', (status) => {
-      resolve({ status: status ?? 1, output });
-    });
-  });
-}
-
-// Both escapes from a failed repo-type detection (defined at the detection source
-// in harness.ts): where to run it (checkout/target) and how to force it (adapter).
-export { ADAPTER_DETECT_NEXT } from '../harness.ts';
-
-// Teaching-error emitter (exit 2, machine-readable in --json). `userAction` is
-// REQUIRED: a teaching error without a reachable escape must not compile, so the
-// escape is a typed parameter rather than free-form prose spliced into `message`.
-export function usageOut(json: boolean, command: string, message: string, userAction: string): number {
-  if (json) {
-    console.log(
-      JSON.stringify(
-        { schemaVersion: 1, command, status: 'fail', exitCode: EXIT.usage, error: { code: 'USAGE', message, userAction } },
-        null,
-        2,
-      ),
-    );
-  } else {
-    console.error(`✗ mm-harness ${command}: ${message}\n  Next: ${userAction}`);
-  }
-  return EXIT.usage;
-}

package/src/commands/update.ts

@@ -1,316 +0,0 @@
-// update — keep the globally-installed mm-harness current against the npm registry.
-// `mm-harness update` upgrades to the published latest; `--check` reports without
-// touching anything; `--json` carries { current, latest, updateAvailable }. A
-// passive once-a-day nudge (maybeNudge) prints a single stderr line when a newer
-// version exists — it never blocks, never auto-updates, and stays off stdout so
-// the --json contract of every other command is untouched. Every failure path
-// (no npm, registry unreachable, permission-denied global dir) names its escape.
-//
-// Two fetch strategies:
-//   fetchLatest    — spawnSync(`npm view`) used by the explicit `update` command;
-//                    respects the user's npm registry config; bounded by timeoutMs.
-//   fetchLatestAsync — native fetch() used by the passive nudge; never spawns a
-//                    subprocess; hard-aborts at timeoutMs so it cannot block the
-//                    event loop beyond that bound.
-
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-
-import { runnerDir } from '../paths.ts';
-import { EXIT, flag, parseFlags } from './shared.ts';
-
-export const PACKAGE_NAME = '@deeeed/metamask-harness';
-const NUDGE_INTERVAL_MS = 24 * 60 * 60 * 1000;
-const NUDGE_FETCH_TIMEOUT_MS = 300;
-
-export function currentVersion(): string {
-  try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(runnerDir, 'package.json'), 'utf8')) as { version?: string };
-    return pkg.version ?? '0.0.0';
-  } catch {
-    return '0.0.0';
-  }
-}
-
-function parseVersion(value: string): { nums: number[]; pre: string } {
-  const cleaned = value.replace(/^v/u, '');
-  const dash = cleaned.indexOf('-');
-  const core = dash === -1 ? cleaned : cleaned.slice(0, dash);
-  const pre = dash === -1 ? '' : cleaned.slice(dash + 1);
-  const nums = core.split('.').map((part) => Number.parseInt(part, 10) || 0);
-  while (nums.length < 3) nums.push(0);
-  return { nums, pre };
-}
-
-// True when `candidate` is a strictly higher version than `base`. A release outranks
-// a prerelease of the same core (1.0.0 > 1.0.0-rc.1); prereleases compare lexically.
-export function isNewer(candidate: string, base: string): boolean {
-  const a = parseVersion(candidate);
-  const b = parseVersion(base);
-  for (let i = 0; i < 3; i += 1) {
-    if (a.nums[i] !== b.nums[i]) return a.nums[i] > b.nums[i];
-  }
-  if (a.pre === b.pre) return false;
-  if (a.pre === '') return true;
-  if (b.pre === '') return false;
-  return a.pre > b.pre;
-}
-
-export interface FetchResult {
-  latest?: string;
-  error?: { kind: 'no-npm' | 'unreachable'; message: string };
-}
-
-// Query the registry dist-tag `latest` via `npm view`. `timeoutMs` bounds the
-// wait; callers MUST pass a finite value — an unbounded registry call can hang
-// indefinitely. When the timeout fires, spawnSync sets result.signal to SIGTERM.
-export function fetchLatest(timeoutMs: number): FetchResult {
-  const result = spawnSync('npm', ['view', PACKAGE_NAME, 'dist-tags.latest'], {
-    encoding: 'utf8',
-    timeout: timeoutMs,
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-  if (result.error) {
-    const code = (result.error as NodeJS.ErrnoException).code;
-    if (code === 'ENOENT') return { error: { kind: 'no-npm', message: 'npm was not found on PATH' } };
-    return { error: { kind: 'unreachable', message: result.error.message } };
-  }
-  if (result.signal) {
-    return { error: { kind: 'unreachable', message: `registry fetch timed out after ${timeoutMs}ms` } };
-  }
-  if (result.status !== 0) {
-    return { error: { kind: 'unreachable', message: (result.stderr ?? '').trim() || `npm view exited ${result.status}` } };
-  }
-  const latest = (result.stdout ?? '').trim();
-  if (!latest) return { error: { kind: 'unreachable', message: 'npm returned no dist-tag for latest' } };
-  return { latest };
-}
-
-// Async variant for the passive nudge: uses the native fetch() API so it never
-// spawns a subprocess and never blocks the event loop. Hard-aborts at timeoutMs.
-// Skips silently on any error (nudge is best-effort).
-async function fetchLatestAsync(timeoutMs: number): Promise<FetchResult> {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const url = `https://registry.npmjs.org/-/package/${encodeURIComponent(PACKAGE_NAME)}/dist-tags`;
-    const res = await fetch(url, { signal: controller.signal });
-    if (!res.ok) return { error: { kind: 'unreachable', message: `registry returned HTTP ${res.status}` } };
-    const data = (await res.json()) as Record<string, string>;
-    const latest = data['latest'];
-    if (!latest) return { error: { kind: 'unreachable', message: 'npm registry returned no latest dist-tag' } };
-    return { latest };
-  } catch (err) {
-    const msg = (err as Error).name === 'AbortError'
-      ? `registry fetch timed out after ${timeoutMs}ms`
-      : (err as Error).message;
-    return { error: { kind: 'unreachable', message: msg } };
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-// Non-zero on every failure (EXIT.infra = 3) so it never collides with `--check`'s
-// exit 1 = "update available"; each carries the exact reachable escape.
-function teachFailure(
-  json: boolean,
-  current: string,
-  code: string,
-  message: string,
-  userAction: string,
-): number {
-  if (json) {
-    console.log(
-      JSON.stringify(
-        { schemaVersion: 1, command: 'update', status: 'fail', current, error: { code, message, userAction } },
-        null,
-        2,
-      ),
-    );
-  } else {
-    console.error(`✗ mm-harness update: ${message}\n  Next: ${userAction}`);
-  }
-  return EXIT.infra;
-}
-
-function emitFetchError(json: boolean, error: NonNullable<FetchResult['error']>, current: string): number {
-  if (error.kind === 'no-npm') {
-    return teachFailure(
-      json,
-      current,
-      'NO_NPM',
-      'npm was not found on PATH — cannot check for updates',
-      'install Node.js (which bundles npm) from https://nodejs.org, then re-run: mm-harness update',
-    );
-  }
-  return teachFailure(
-    json,
-    current,
-    'REGISTRY_UNREACHABLE',
-    `could not reach the npm registry (${error.message})`,
-    'check your network, then re-run: mm-harness update — or inspect the registry with: npm config get registry',
-  );
-}
-
-export async function handleUpdate(argv: string[]): Promise<number> {
-  const { options } = parseFlags(argv, new Set(['check', 'json']));
-  const json = flag(options, 'json');
-  const checkOnly = flag(options, 'check');
-  const current = currentVersion();
-
-  const fetched = fetchLatest(30_000);
-  if (fetched.error) return emitFetchError(json, fetched.error, current);
-  const latest = fetched.latest as string;
-  const updateAvailable = isNewer(latest, current);
-
-  if (checkOnly) {
-    if (json) {
-      console.log(JSON.stringify({ schemaVersion: 1, command: 'update', current, latest, updateAvailable }, null, 2));
-    } else if (updateAvailable) {
-      console.error(`mm-harness ${current} → ${latest} available · run: mm-harness update`);
-    } else {
-      console.log(`mm-harness is up to date (${current}).`);
-    }
-    // exit 1 signals "update available"; exit 0 signals up-to-date.
-    return updateAvailable ? EXIT.runtime : EXIT.ok;
-  }
-
-  if (!updateAvailable) {
-    if (json) {
-      console.log(JSON.stringify({ schemaVersion: 1, command: 'update', current, latest, updateAvailable: false, updated: false }, null, 2));
-    } else {
-      console.log(`mm-harness is up to date (${current}).`);
-    }
-    return EXIT.ok;
-  }
-
-  const INSTALL_TIMEOUT_MS = 5 * 60 * 1000;
-  const install = spawnSync('npm', ['i', '-g', `${PACKAGE_NAME}@latest`], {
-    encoding: 'utf8',
-    timeout: INSTALL_TIMEOUT_MS,
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-  if (install.error) {
-    const code = (install.error as NodeJS.ErrnoException).code;
-    if (code === 'ENOENT') return emitFetchError(json, { kind: 'no-npm', message: 'npm was not found on PATH' }, current);
-    return teachFailure(json, current, 'INSTALL_FAILED', `global install failed (${install.error.message})`, `run it directly to see the error: npm i -g ${PACKAGE_NAME}@latest`);
-  }
-  if (install.signal) {
-    return teachFailure(
-      json,
-      current,
-      'INSTALL_FAILED',
-      `global install timed out after ${INSTALL_TIMEOUT_MS / 1000}s — slow network or registry unavailable`,
-      `check your network, then retry: mm-harness update — or install manually: npm i -g ${PACKAGE_NAME}@latest`,
-    );
-  }
-  const combined = `${install.stdout ?? ''}${install.stderr ?? ''}`;
-  if (install.status !== 0) {
-    if (/EACCES|permission denied|EPERM/iu.test(combined)) {
-      return teachFailure(
-        json,
-        current,
-        'GLOBAL_DIR_PERMISSION',
-        'global install denied — the npm global directory is not writable',
-        'either re-run with sudo, or point npm at a user-writable prefix: npm config set prefix ~/.npm-global (then add ~/.npm-global/bin to PATH) and re-run: mm-harness update',
-      );
-    }
-    return teachFailure(
-      json,
-      current,
-      'INSTALL_FAILED',
-      `global install failed (${combined.trim() || `npm exited ${install.status}`})`,
-      `run it directly to see the error: npm i -g ${PACKAGE_NAME}@latest`,
-    );
-  }
-
-  // Re-check the registry so the reported new version is the one that resolved,
-  // not merely the tag we asked for. Best-effort — fall back to the tag if slow.
-  const rechecked = fetchLatest(30_000);
-  const installed = rechecked.latest ?? latest;
-  if (json) {
-    console.log(JSON.stringify({ schemaVersion: 1, command: 'update', current, latest: installed, updateAvailable: true, updated: true, from: current, to: installed }, null, 2));
-  } else {
-    console.log(`mm-harness updated ${current} → ${installed}.`);
-  }
-  return EXIT.ok;
-}
-
-// --- Passive update nudge ----------------------------------------------------
-
-interface NudgeCache {
-  lastCheck: number;
-  latest: string;
-}
-
-function cacheFile(): string {
-  const override = process.env.MM_HARNESS_UPDATE_CACHE;
-  if (override) return override;
-  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
-  return path.join(base, 'mm-harness', 'update-check.json');
-}
-
-function readCache(file: string): NudgeCache | null {
-  try {
-    const data = JSON.parse(fs.readFileSync(file, 'utf8')) as Partial<NudgeCache>;
-    if (typeof data.lastCheck === 'number' && typeof data.latest === 'string') {
-      return { lastCheck: data.lastCheck, latest: data.latest };
-    }
-  } catch {
-    // Missing or corrupt cache = no prior state; a fresh probe will rebuild it.
-  }
-  return null;
-}
-
-function writeCache(file: string, cache: NudgeCache): void {
-  try {
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify(cache));
-  } catch {
-    // Best-effort; a cache we cannot persist just means the next run re-probes.
-  }
-}
-
-// Suppressed in CI and when the user opts out — the nudge is for interactive use.
-export function nudgeDisabled(): boolean {
-  return process.env.MM_HARNESS_NO_UPDATE_CHECK === '1' || Boolean(process.env.CI);
-}
-
-// Pure decision, testable without a clock or network.
-export function nudgeLine(current: string, latest: string): string | null {
-  return isNewer(latest, current) ? `mm-harness ${current} → ${latest} available · run: mm-harness update` : null;
-}
-
-// One throttled, bounded, stderr-only line when a newer version is published.
-// Called via setImmediate in mm-harness-cli.ts so no nudge code runs before
-// parse/dispatch starts. Prints AFTER command output via process.once('exit'),
-// giving cleaner UX than mid-output interleaving. The `latest` closure variable
-// is captured by the exit handler; an async probe that resolves before
-// process.exit() fires updates it automatically. Offline / timeout / no network
-// skip silently. Cache timestamp is stamped before the fetch so an abandoned
-// probe (process exits within 300ms) does not re-probe on the next invocation.
-export async function maybeNudge(now: number = Date.now()): Promise<void> {
-  if (nudgeDisabled()) return;
-  const file = cacheFile();
-  const cache = readCache(file);
-  const current = currentVersion();
-  // Mutable: exit handler closes over this so a probe result that arrives before
-  // process.exit() automatically updates what gets printed.
-  let latest = cache?.latest ?? '';
-  // Register once — checks nudgeLine at exit time, picking up the freshest value.
-  process.once('exit', () => {
-    const line = nudgeLine(current, latest);
-    if (line) process.stderr.write(`${line}\n`);
-  });
-  if (!cache || now - cache.lastCheck >= NUDGE_INTERVAL_MS) {
-    // Stamp before the fetch so a killed probe does not re-probe next run.
-    writeCache(file, { lastCheck: now, latest });
-    const fetched = await fetchLatestAsync(NUDGE_FETCH_TIMEOUT_MS);
-    if (fetched.latest) {
-      latest = fetched.latest;
-      writeCache(file, { lastCheck: now, latest });
-    }
-  }
-}

package/src/completions-cache.ts

@@ -1,86 +0,0 @@
-// Dynamic completions cache (module + file format).
-//
-// The DISCOVER layer (actions/flows) is the single source that feeds the agent
-// (compose), the shell (complete), and docs (cheatsheet). Shell completion
-// scripts call the hidden `mm-harness completion-candidates <actions|flows>`
-// command; that command reads/writes this per-checkout cache so tab-completion
-// never blocks the shell on a manifest/library read.
-//
-// Format (per-checkout, git-ignored — lives under the runtime dir):
-//   { version, updatedAt (epoch ms), candidates: { actions?: string[], flows?: string[] } }
-// TTL: short; a stale/missing cache falls back to a live read (never an error).
-// Invalidated on overlay install (`mm-harness install`) — the overlay is what
-// changes the available action/flow vocabulary.
-
-import fs from 'node:fs';
-import path from 'node:path';
-
-import { recipeRuntimePath } from './paths.ts';
-
-export const COMPLETION_CACHE_VERSION = 1;
-// Short TTL: completions must reflect a freshly-installed overlay quickly; a miss
-// is cheap (one manifest read) and never blocks the shell.
-export const COMPLETION_CACHE_TTL_MS = 60_000;
-
-export type CompletionKind = 'actions' | 'flows';
-
-export interface CompletionCache {
-  version: number;
-  updatedAt: number;
-  candidates: Partial<Record<CompletionKind, string[]>>;
-}
-
-export function completionCachePath(projectRoot: string): string {
-  return recipeRuntimePath(projectRoot, '.completion-cache.json');
-}
-
-export function readCompletionCache(projectRoot: string): CompletionCache | undefined {
-  try {
-    const raw = JSON.parse(fs.readFileSync(completionCachePath(projectRoot), 'utf8')) as CompletionCache;
-    if (!raw || raw.version !== COMPLETION_CACHE_VERSION || typeof raw.updatedAt !== 'number') return undefined;
-    return raw;
-  } catch {
-    return undefined;
-  }
-}
-
-export function isCacheFresh(cache: CompletionCache, now: number = Date.now()): boolean {
-  return now - cache.updatedAt < COMPLETION_CACHE_TTL_MS;
-}
-
-// Return cached candidates for a kind when the cache is present + fresh; else
-// undefined (caller does a live read and then writeCompletionCandidates).
-export function readFreshCandidates(
-  projectRoot: string,
-  kind: CompletionKind,
-  now: number = Date.now(),
-): string[] | undefined {
-  const cache = readCompletionCache(projectRoot);
-  if (!cache || !isCacheFresh(cache, now)) return undefined;
-  return cache.candidates[kind];
-}
-
-export function writeCompletionCandidates(
-  projectRoot: string,
-  kind: CompletionKind,
-  candidates: string[],
-): void {
-  const existing = readCompletionCache(projectRoot);
-  const next: CompletionCache = {
-    version: COMPLETION_CACHE_VERSION,
-    updatedAt: Date.now(),
-    candidates: { ...(existing?.candidates ?? {}), [kind]: candidates },
-  };
-  const file = completionCachePath(projectRoot);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, `${JSON.stringify(next, null, 2)}\n`);
-}
-
-// Invalidated on overlay install (the overlay defines the action/flow vocabulary).
-export function invalidateCompletionCache(projectRoot: string): void {
-  try {
-    fs.rmSync(completionCachePath(projectRoot));
-  } catch {
-    // Absent cache is the desired post-state; nothing to do.
-  }
-}