@blackbelt-technology/pi-agent-dashboard 0.2.9 → 0.4.0

package/packages/shared/src/platform/exec.ts

@@ -0,0 +1,220 @@
+/**
+ * Safe child-process wrappers that always set `windowsHide: true`.
+ *
+ * Rationale
+ * ─────────
+ * On Windows, spawning a `.cmd` shim (or anything node.exe wraps via cmd.exe)
+ * flashes a cmd-prompt window unless `windowsHide: true` is passed. This is
+ * a universal source of visible-UI bugs in this project: bridge process
+ * scanners, git polls, openspec polls, terminal subprocess checks, etc.
+ * Every spawn site needed to remember to set the flag, and we kept missing
+ * some (session-diff, git-operations, update-checker, doctor, tunnel, ...).
+ *
+ * Rather than fixing this per call site forever, this module wraps the
+ * Node `child_process` API with `windowsHide: true` as the default. Callers
+ * can still override by explicitly passing `windowsHide: false` if they
+ * genuinely want a visible console (none of our callers do).
+ *
+ * **Every spawn in packages/*\/src SHOULD import from here** instead of
+ * directly from `node:child_process`. A repo-level check can fail if
+ * direct imports sneak back in. See change: consolidate-platform-handlers.
+ */
+import {
+  execSync as nodeExecSync,
+  exec as nodeExec,
+  execFile as nodeExecFile,
+  spawnSync as nodeSpawnSync,
+  spawn as nodeSpawn,
+  type ExecSyncOptions,
+  type ExecOptions,
+  type ExecFileOptions,
+  type SpawnSyncOptions,
+  type SpawnOptions,
+  type ChildProcess,
+  type SpawnSyncReturns,
+} from "node:child_process";
+import { promisify } from "node:util";
+
+// ── Argv safety (Windows .cmd / .bat handling) ─────────────────────────────
+
+/**
+ * Build a spawn-safe argv for ANY command on ANY platform.
+ *
+ * The canonical way to invoke subprocesses without flashing cmd.exe
+ * console windows on Windows. Handles three cases:
+ *
+ *   1. Windows + `.cmd` / `.bat` shim → explicit `cmd.exe /c <cmd> <args>`.
+ *      This is the ONLY reliable way to invoke `.cmd` files without the
+ *      flashing-console bug (Node issue #21825, which happens when
+ *      `shell: true` is combined with `.cmd` + `detached` + `windowsHide`).
+ *      cmd.exe respects `windowsHide: true` on its own console directly.
+ *
+ *   2. Windows + native binary (`.exe`) → direct argv.
+ *
+ *   3. Unix (any binary or shell script) → direct argv.
+ *
+ * Always returns `{ shell: false, windowsHide: true }` — NEVER uses
+ * `shell: true`. Callers pass these spawn options along with the argv.
+ *
+ * Example:
+ *   const { argv, spawnOptions } = buildSafeArgv("npm.cmd", ["root", "-g"]);
+ *   spawnSync(argv[0], argv.slice(1), { cwd, env, ...spawnOptions });
+ *
+ * See change: consolidate-windows-spawn-and-platform-handlers.
+ */
+export interface SafeArgv {
+  argv: string[];
+  spawnOptions: { shell: false; windowsHide: true };
+}
+
+export function buildSafeArgv(
+  cmd: string,
+  args: readonly string[] = [],
+  platform: NodeJS.Platform = process.platform,
+): SafeArgv {
+  if (platform === "win32") {
+    // Route through cmd.exe for TWO cases:
+    //   1. Explicit .cmd/.bat shim — Node can't spawn these directly
+    //      with shell:false (CVE-2024-27980 fix in Node >= 20.12).
+    //   2. Extensionless name (e.g. "npm", "pi", "git") — Windows
+    //      resolves these via PATHEXT, but only shells do. Without
+    //      cmd.exe, spawn("npm") returns ENOENT because there's no
+    //      literal "npm" binary — just "npm.cmd".
+    // Native .exe / absolute paths bypass cmd.exe (no PATHEXT needed).
+    //
+    // /d = skip AutoRun, /s = treat quoted first token as command
+    // (preserves spaces), /c = run and exit. cmd.exe honors
+    // windowsHide on its console, so inner .cmd's node.exe inherits an
+    // invisible console — no flash.
+    const isShim = /\.(cmd|bat)$/i.test(cmd);
+    const hasExtension = /\.[A-Za-z0-9]+$/.test(cmd);
+    if (isShim || !hasExtension) {
+      return {
+        argv: ["cmd.exe", "/d", "/s", "/c", cmd, ...args],
+        spawnOptions: { shell: false, windowsHide: true },
+      };
+    }
+  }
+  return {
+    argv: [cmd, ...args],
+    spawnOptions: { shell: false, windowsHide: true },
+  };
+}
+
+// ── Option helpers ──────────────────────────────────────────────────────────
+
+type AnyOptions = { windowsHide?: boolean } | undefined;
+
+/**
+ * Merge caller options with `windowsHide: true` as the default.
+ * Explicit `windowsHide: false` from the caller is honored (for the rare
+ * case where a visible console is actually desired).
+ */
+function withHide<T extends AnyOptions>(opts: T): T & { windowsHide: boolean } {
+  const hide = opts?.windowsHide ?? true;
+  return { ...(opts ?? {}), windowsHide: hide } as T & { windowsHide: boolean };
+}
+
+// ── Synchronous wrappers ────────────────────────────────────────────────────
+
+/** Wrapped `execSync`. Always `windowsHide: true` unless overridden. */
+export function execSync(command: string, options: ExecSyncOptions & { encoding: BufferEncoding }): string;
+export function execSync(command: string, options?: ExecSyncOptions): Buffer | string;
+export function execSync(
+  command: string,
+  options?: ExecSyncOptions,
+): Buffer | string {
+  return nodeExecSync(command, withHide(options));
+}
+
+/** Wrapped `spawnSync`. Always `windowsHide: true` unless overridden. */
+export function spawnSync<T extends string | Buffer = Buffer>(
+  command: string,
+  args?: readonly string[],
+  options?: SpawnSyncOptions,
+): SpawnSyncReturns<T> {
+  return nodeSpawnSync(command, args ?? [], withHide(options)) as SpawnSyncReturns<T>;
+}
+
+// ── Asynchronous (callback) wrappers ────────────────────────────────────────
+
+/** Wrapped `exec` (callback form). */
+export function exec(
+  command: string,
+  callback?: (err: Error | null, stdout: string, stderr: string) => void,
+): ChildProcess;
+export function exec(
+  command: string,
+  options: ExecOptions,
+  callback?: (err: Error | null, stdout: string | Buffer, stderr: string | Buffer) => void,
+): ChildProcess;
+export function exec(
+  command: string,
+  optionsOrCallback?: ExecOptions | ((err: Error | null, stdout: any, stderr: any) => void),
+  maybeCallback?: (err: Error | null, stdout: any, stderr: any) => void,
+): ChildProcess {
+  if (typeof optionsOrCallback === "function") {
+    return nodeExec(command, withHide(undefined) as ExecOptions, optionsOrCallback);
+  }
+  return nodeExec(command, withHide(optionsOrCallback) as ExecOptions, maybeCallback);
+}
+
+/** Wrapped `execFile` (callback form). */
+export function execFile(
+  file: string,
+  args: readonly string[] | undefined,
+  options: ExecFileOptions,
+  callback?: (err: Error | null, stdout: string | Buffer, stderr: string | Buffer) => void,
+): ChildProcess;
+export function execFile(
+  file: string,
+  args?: readonly string[],
+  callback?: (err: Error | null, stdout: string, stderr: string) => void,
+): ChildProcess;
+export function execFile(
+  file: string,
+  args?: readonly string[],
+  optionsOrCallback?: ExecFileOptions | ((err: Error | null, stdout: any, stderr: any) => void),
+  maybeCallback?: (err: Error | null, stdout: any, stderr: any) => void,
+): ChildProcess {
+  if (typeof optionsOrCallback === "function") {
+    return nodeExecFile(file, args ?? [], withHide(undefined) as ExecFileOptions, optionsOrCallback);
+  }
+  return nodeExecFile(file, args ?? [], withHide(optionsOrCallback) as ExecFileOptions, maybeCallback);
+}
+
+/** Wrapped `spawn`. Always `windowsHide: true` unless overridden. */
+export function spawn(
+  command: string,
+  args?: readonly string[],
+  options?: SpawnOptions,
+): ChildProcess {
+  return nodeSpawn(command, args ?? [], withHide(options));
+}
+
+// ── Promise-returning variants ──────────────────────────────────────────────
+
+/** Promise-returning exec. */
+export const execAsync = promisify(exec) as unknown as (
+  command: string,
+  options?: ExecOptions,
+) => Promise<{ stdout: string | Buffer; stderr: string | Buffer }>;
+
+/** Promise-returning execFile. */
+export const execFileAsync = promisify(execFile) as unknown as (
+  file: string,
+  args?: readonly string[],
+  options?: ExecFileOptions,
+) => Promise<{ stdout: string | Buffer; stderr: string | Buffer }>;
+
+// ── Types pass-through for convenience ──────────────────────────────────────
+
+export type {
+  ExecSyncOptions,
+  ExecOptions,
+  ExecFileOptions,
+  SpawnSyncOptions,
+  SpawnOptions,
+  ChildProcess,
+  SpawnSyncReturns,
+};

package/packages/shared/src/platform/git.ts

@@ -0,0 +1,155 @@
+/**
+ * Git tool module — Recipe-based API for git operations the dashboard runs
+ * from multiple call sites (session-diff, git-info extension, doctor).
+ *
+ * Every function in this file is a thin wrapper over `run(recipe, input)`:
+ * no `child_process` imports, no `process.platform` branches, no inline
+ * shell-escape logic. The Recipe objects describe *what* git invocation
+ * to run; the runner handles *how* to spawn it safely.
+ *
+ * Exit codes:
+ *   `git diff`   exits 0 when there's a diff, 1 when there's nothing to
+ *                show (we tolerate 1).
+ *   Other commands exit 0 on success and non-zero on real errors.
+ *
+ * See change: platform-command-executor.
+ */
+import { run, unwrap, type Recipe, type Result } from "./runner.js";
+
+// ── Recipes (pure data) ─────────────────────────────────────────────────────
+
+const GIT_TIMEOUT = 15_000;
+
+interface WithCwd {
+  cwd: string;
+}
+
+export const GIT_IS_REPO: Recipe<WithCwd, boolean> = {
+  argv: () => ["git", "rev-parse", "--is-inside-work-tree"],
+  parse: (out) => out.trim() === "true",
+  timeout: GIT_TIMEOUT,
+};
+
+export const GIT_CURRENT_BRANCH: Recipe<WithCwd, string | undefined> = {
+  argv: () => ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+  parse: (out) => out.trim() || undefined,
+  timeout: GIT_TIMEOUT,
+};
+
+export const GIT_HEAD_SHA: Recipe<WithCwd & { short?: boolean }, string | undefined> = {
+  argv: ({ short }) => short ? ["git", "rev-parse", "--short", "HEAD"] : ["git", "rev-parse", "HEAD"],
+  parse: (out) => out.trim() || undefined,
+  timeout: GIT_TIMEOUT,
+};
+
+export const GIT_REMOTE_URL: Recipe<WithCwd & { remote?: string }, string | undefined> = {
+  argv: ({ remote }) => ["git", "remote", "get-url", remote ?? "origin"],
+  parse: (out) => out.trim() || undefined,
+  timeout: GIT_TIMEOUT,
+};
+
+export const GIT_DIFF: Recipe<WithCwd & { path: string; ref?: string }, string> = {
+  argv: ({ path, ref }) => ["git", "diff", ref ?? "HEAD", "--", path],
+  parse: (out) => out,
+  timeout: GIT_TIMEOUT,
+  // git diff exits 1 when --exit-code is set or in some configurations;
+  // no diff is not an error for our callers.
+  tolerate: [1],
+};
+
+export const GIT_STATUS_PORCELAIN: Recipe<WithCwd & { path?: string }, string> = {
+  argv: ({ path }) =>
+    path === undefined
+      ? ["git", "status", "--porcelain"]
+      : ["git", "status", "--porcelain", "--", path],
+  parse: (out) => out,
+  timeout: GIT_TIMEOUT,
+};
+
+/**
+ * `gh pr view --json number -q .number` — requires the `gh` CLI.
+ * Returns undefined when there is no PR for the current branch (gh exits 1).
+ */
+export const GH_PR_NUMBER: Recipe<WithCwd, number | undefined> = {
+  argv: () => ["gh", "pr", "view", "--json", "number", "-q", ".number"],
+  parse: (out) => {
+    const n = parseInt(out.trim(), 10);
+    return Number.isFinite(n) ? n : undefined;
+  },
+  timeout: GIT_TIMEOUT,
+  tolerate: [1], // gh exits 1 when no PR exists — not an error
+};
+
+// ── Registry (for lint / docs / enumeration) ────────────────────────────────
+
+export const GIT_RECIPES = {
+  GIT_IS_REPO,
+  GIT_CURRENT_BRANCH,
+  GIT_HEAD_SHA,
+  GIT_REMOTE_URL,
+  GIT_DIFF,
+  GIT_STATUS_PORCELAIN,
+  GH_PR_NUMBER,
+} as const;
+
+// ── Public API — typed functions (use Result for explicit control) ──────────
+
+export function isGitRepo(input: WithCwd): Result<boolean> {
+  return run(GIT_IS_REPO, input, { cwd: input.cwd });
+}
+
+export function currentBranch(input: WithCwd): Result<string | undefined> {
+  return run(GIT_CURRENT_BRANCH, input, { cwd: input.cwd });
+}
+
+export function headSha(input: WithCwd & { short?: boolean }): Result<string | undefined> {
+  return run(GIT_HEAD_SHA, input, { cwd: input.cwd });
+}
+
+export function remoteUrl(input: WithCwd & { remote?: string }): Result<string | undefined> {
+  return run(GIT_REMOTE_URL, input, { cwd: input.cwd });
+}
+
+export function diff(input: WithCwd & { path: string; ref?: string }): Result<string> {
+  return run(GIT_DIFF, input, { cwd: input.cwd });
+}
+
+export function statusPorcelain(input: WithCwd & { path?: string }): Result<string> {
+  return run(GIT_STATUS_PORCELAIN, input, { cwd: input.cwd });
+}
+
+export function prNumber(input: WithCwd): Result<number | undefined> {
+  return run(GH_PR_NUMBER, input, { cwd: input.cwd });
+}
+
+// ── Best-effort convenience wrappers (swallow errors → default) ─────────────
+// Callers that only want "the value or a default" without dealing with Result
+// discriminants can use these instead.
+
+export function isGitRepoOr(input: WithCwd, fallback = false): boolean {
+  return unwrap(isGitRepo(input), fallback);
+}
+
+export function currentBranchOr(input: WithCwd, fallback?: string): string | undefined {
+  return unwrap(currentBranch(input), fallback);
+}
+
+export function headShaOr(input: WithCwd & { short?: boolean }, fallback?: string): string | undefined {
+  return unwrap(headSha(input), fallback);
+}
+
+export function remoteUrlOr(input: WithCwd & { remote?: string }, fallback?: string): string | undefined {
+  return unwrap(remoteUrl(input), fallback);
+}
+
+export function diffOr(input: WithCwd & { path: string; ref?: string }, fallback = ""): string {
+  return unwrap(diff(input), fallback);
+}
+
+export function statusPorcelainOr(input: WithCwd & { path?: string }, fallback = ""): string {
+  return unwrap(statusPorcelain(input), fallback);
+}
+
+export function prNumberOr(input: WithCwd, fallback?: number): number | undefined {
+  return unwrap(prNumber(input), fallback);
+}

package/packages/shared/src/platform/index.ts

@@ -0,0 +1,15 @@
+export * from "./binary-lookup.js";
+export * from "./process.js";
+export * from "./process-scan.js";
+export * from "./shell.js";
+export * from "./commands.js";
+export * from "./exec.js";
+export * from "./runner.js";
+export * from "./detached-spawn.js";
+export * from "./spawn-mechanism.js";
+export * from "./process-identify.js";
+export * from "./subprocess-adapter.js";
+export * as git from "./git.js";
+export * as openspec from "./openspec.js";
+export * as npm from "./npm.js";
+export * as paths from "./paths.js";

package/packages/shared/src/platform/npm.ts

@@ -0,0 +1,162 @@
+/**
+ * npm tool module — Recipe-based API for the npm CLI.
+ *
+ * Covers the subset of npm operations the dashboard actually invokes:
+ *   - `npm root -g`          (resolve the global node_modules path)
+ *   - `npm outdated`         (check for updates, local or global)
+ *   - `npm install`          (install a package, local or global)
+ *   - `npm view <pkg> version` (read upstream version)
+ *
+ * See change: platform-command-executor.
+ */
+import { run, unwrap, type Recipe, type Result } from "./runner.js";
+
+const NPM_TIMEOUT_FAST = 10_000;
+const NPM_TIMEOUT_INSTALL = 120_000;
+
+interface WithCwd {
+  cwd?: string;
+}
+
+// ── Recipes ─────────────────────────────────────────────────────────────────
+
+/**
+ * `npm root -g` — returns the absolute path to the global node_modules.
+ * Cached by callers (it's stable per Node install).
+ */
+export const NPM_ROOT_GLOBAL: Recipe<Record<string, never>, string> = {
+  argv: () => ["npm", "root", "-g"],
+  parse: (out) => out.trim(),
+  timeout: NPM_TIMEOUT_FAST,
+};
+
+/**
+ * `npm outdated <pkg> --json` (or without `<pkg>` for project-wide).
+ * npm exits 1 when updates are available and 0 when up-to-date — we tolerate
+ * exit 1 so callers see the JSON body either way.
+ */
+export const NPM_OUTDATED: Recipe<WithCwd & { pkg?: string }, unknown | null> = {
+  argv: ({ pkg }) => pkg === undefined
+    ? ["npm", "outdated", "--json"]
+    : ["npm", "outdated", pkg, "--json"],
+  parse: (out) => {
+    const trimmed = out.trim();
+    if (!trimmed) return null;
+    try { return JSON.parse(trimmed); } catch { return null; }
+  },
+  timeout: NPM_TIMEOUT_FAST,
+  tolerate: [1],
+};
+
+/**
+ * `npm outdated -g <pkg> --json`. Same exit-1 tolerance.
+ */
+export const NPM_OUTDATED_GLOBAL: Recipe<{ pkg?: string }, unknown | null> = {
+  argv: ({ pkg }) => pkg === undefined
+    ? ["npm", "outdated", "-g", "--json"]
+    : ["npm", "outdated", "-g", pkg, "--json"],
+  parse: (out) => {
+    const trimmed = out.trim();
+    if (!trimmed) return null;
+    try { return JSON.parse(trimmed); } catch { return null; }
+  },
+  timeout: NPM_TIMEOUT_FAST,
+  tolerate: [1],
+};
+
+/**
+ * `npm install <pkg>@<version>` — local install. Long timeout.
+ */
+export const NPM_INSTALL: Recipe<WithCwd & { pkg: string; version?: string }, string> = {
+  argv: ({ pkg, version }) => ["npm", "install", version ? `${pkg}@${version}` : pkg],
+  parse: (out) => out,
+  timeout: NPM_TIMEOUT_INSTALL,
+};
+
+/**
+ * `npm install -g <pkg>@<version>` — global install.
+ */
+export const NPM_INSTALL_GLOBAL: Recipe<{ pkg: string; version?: string }, string> = {
+  argv: ({ pkg, version }) => ["npm", "install", "-g", version ? `${pkg}@${version}` : pkg],
+  parse: (out) => out,
+  timeout: NPM_TIMEOUT_INSTALL,
+};
+
+/**
+ * `npm view <pkg> version` — the single-value shorthand for "latest version".
+ */
+export const NPM_VIEW_VERSION: Recipe<{ pkg: string }, string> = {
+  argv: ({ pkg }) => ["npm", "view", pkg, "version"],
+  parse: (out) => out.trim(),
+  timeout: NPM_TIMEOUT_FAST,
+};
+
+export const NPM_RECIPES = {
+  NPM_ROOT_GLOBAL,
+  NPM_OUTDATED,
+  NPM_OUTDATED_GLOBAL,
+  NPM_INSTALL,
+  NPM_INSTALL_GLOBAL,
+  NPM_VIEW_VERSION,
+} as const;
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * `npm root -g`. Returns a `Result` for explicit error handling; use
+ * `rootGlobalOr` for best-effort semantics.
+ *
+ * Previous versions cached the result in a module-level variable. That
+ * cache is now owned by `ToolRegistry` (the runner consults the
+ * registry for every resolved binary including `npm` itself). Cache
+ * invalidation flows through `registry.rescan()`.
+ *
+ * See change: consolidate-tool-resolution.
+ */
+export function rootGlobal(): Result<string> {
+  return run(NPM_ROOT_GLOBAL, {}, {});
+}
+
+/**
+ * Test-only no-op kept for backward compatibility with existing test
+ * suites. The `cachedGlobalRoot` variable no longer exists.
+ */
+export function _resetNpmRootCache(): void { /* no-op */ }
+
+export function outdated(input: WithCwd & { pkg?: string }): Result<unknown | null> {
+  return run(NPM_OUTDATED, input, { cwd: input.cwd });
+}
+
+export function outdatedGlobal(input: { pkg?: string } = {}): Result<unknown | null> {
+  return run(NPM_OUTDATED_GLOBAL, input, {});
+}
+
+export function install(input: WithCwd & { pkg: string; version?: string }): Result<string> {
+  return run(NPM_INSTALL, input, { cwd: input.cwd });
+}
+
+export function installGlobal(input: { pkg: string; version?: string }): Result<string> {
+  return run(NPM_INSTALL_GLOBAL, input, {});
+}
+
+export function viewVersion(input: { pkg: string }): Result<string> {
+  return run(NPM_VIEW_VERSION, input, {});
+}
+
+// ── Best-effort variants ────────────────────────────────────────────────────
+
+export function rootGlobalOr(fallback = ""): string {
+  return unwrap(rootGlobal(), fallback);
+}
+
+export function outdatedOr(input: WithCwd & { pkg?: string }, fallback: unknown | null = null): unknown | null {
+  return unwrap(outdated(input), fallback);
+}
+
+export function outdatedGlobalOr(input: { pkg?: string } = {}, fallback: unknown | null = null): unknown | null {
+  return unwrap(outdatedGlobal(input), fallback);
+}
+
+export function viewVersionOr(input: { pkg: string }, fallback = ""): string {
+  return unwrap(viewVersion(input), fallback);
+}

package/packages/shared/src/platform/openspec.ts

@@ -0,0 +1,91 @@
+/**
+ * OpenSpec tool module — Recipe-based API for the openspec CLI.
+ *
+ * Replaces the ad-hoc spawnSync/execFile calls in `openspec-poller.ts`
+ * with typed Recipes executed through the runner. The higher-level
+ * `pollOpenSpec` / `pollOpenSpecAsync` functions remain in
+ * `openspec-poller.ts` (they aggregate list + per-change status into
+ * the dashboard's OpenSpecData shape) and now use these primitives.
+ *
+ * See change: platform-command-executor.
+ */
+import { run, unwrap, type Recipe, type Result } from "./runner.js";
+
+const OPENSPEC_TIMEOUT = 10_000;
+
+interface WithCwd {
+  cwd: string;
+}
+
+/** Parse JSON from stdout; returns null on parse failure. */
+function parseJsonOrNull(out: string): unknown | null {
+  const trimmed = out.trim();
+  if (!trimmed) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+// ── Recipes ─────────────────────────────────────────────────────────────────
+
+export const OPENSPEC_LIST: Recipe<WithCwd, unknown | null> = {
+  argv: () => ["openspec", "list", "--json"],
+  parse: parseJsonOrNull,
+  timeout: OPENSPEC_TIMEOUT,
+};
+
+export const OPENSPEC_STATUS: Recipe<WithCwd & { change: string }, unknown | null> = {
+  argv: ({ change }) => ["openspec", "status", "--change", change, "--json"],
+  parse: parseJsonOrNull,
+  timeout: OPENSPEC_TIMEOUT,
+};
+
+/**
+ * `openspec archive --completed` — bulk-archives all completed changes.
+ * Stdout is human-readable (not JSON); callers typically don't parse it,
+ * they just await success/failure.
+ */
+export const OPENSPEC_ARCHIVE_COMPLETED: Recipe<WithCwd, string> = {
+  argv: () => ["openspec", "archive", "--completed"],
+  parse: (out) => out,
+  // Archive operations can be slow when many changes are processed.
+  timeout: 30_000,
+};
+
+export const OPENSPEC_RECIPES = {
+  OPENSPEC_LIST,
+  OPENSPEC_STATUS,
+  OPENSPEC_ARCHIVE_COMPLETED,
+} as const;
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/** Run `openspec list --json` and return the parsed JSON, or null on failure. */
+export function list(input: WithCwd): Result<unknown | null> {
+  return run(OPENSPEC_LIST, input, { cwd: input.cwd });
+}
+
+/** Run `openspec status --change <name> --json` and return parsed JSON or null. */
+export function status(input: WithCwd & { change: string }): Result<unknown | null> {
+  return run(OPENSPEC_STATUS, input, { cwd: input.cwd });
+}
+
+/** Run `openspec archive --completed`. Returns raw stdout on success. */
+export function archiveCompleted(input: WithCwd): Result<string> {
+  return run(OPENSPEC_ARCHIVE_COMPLETED, input, { cwd: input.cwd });
+}
+
+// ── Best-effort variants (mirror the pattern established in git.ts) ─────────
+
+export function listOr(input: WithCwd, fallback: unknown | null = null): unknown | null {
+  return unwrap(list(input), fallback);
+}
+
+export function statusOr(
+  input: WithCwd & { change: string },
+  fallback: unknown | null = null,
+): unknown | null {
+  return unwrap(status(input), fallback);
+}