switchboard-cli 0.1.0-alpha.1

package/src/lib/proof.ts

@@ -0,0 +1,262 @@
+/**
+ * Portable proof capture — CLI-native proof persistence under .switchboard/proof/.
+ *
+ * Reuses @switchboard/core proof types (ProofArtifact, ProofManifest,
+ * buildProofManifest) but stores under .switchboard/proof/<dispatchId>/
+ * instead of .runs/ so the canonical root stays self-contained.
+ *
+ * The portable proof path captures what it can:
+ * - dispatch metadata (captured — from the governed harness)
+ * - structured return (derived — parsed from operator-provided YAML)
+ * - dispatch prompt (captured — the governed prompt)
+ *
+ * It does NOT fake an execution transcript — that requires real SDK
+ * transport. The evaluation lane is honest about this gap.
+ */
+
+import { createHash, randomBytes } from "crypto";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+import YAML from "yaml";
+import {
+  buildProofManifest,
+  type ProofArtifact,
+  type ProofManifest,
+  proofArtifactSchema,
+  proofManifestSchema,
+} from "@switchboard/core";
+import { proofDir, proofManifestPath } from "./paths";
+import { readYaml } from "./yaml-io";
+
+// ---------------------------------------------------------------------------
+// Content hashing
+// ---------------------------------------------------------------------------
+
+function hashContent(content: string): string {
+  return createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+
+// ---------------------------------------------------------------------------
+// Proof folder management
+// ---------------------------------------------------------------------------
+
+export function ensureProofDir(repoRoot: string, dispatchId: string): string {
+  const dir = proofDir(repoRoot, dispatchId);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+// ---------------------------------------------------------------------------
+// Capture individual proof artifacts
+// ---------------------------------------------------------------------------
+
+function captureArtifact(
+  dir: string,
+  kind: ProofArtifact["kind"],
+  provenance: ProofArtifact["provenance"],
+  filename: string,
+  content: string,
+  description: string,
+): ProofArtifact {
+  const filePath = join(dir, filename);
+  writeFileSync(filePath, content, "utf-8");
+
+  return proofArtifactSchema.parse({
+    artifact_id: `prf-${randomBytes(6).toString("hex")}`,
+    kind,
+    provenance,
+    filename,
+    captured_at: new Date().toISOString(),
+    size_bytes: Buffer.byteLength(content, "utf-8"),
+    content_hash: hashContent(content),
+    description,
+  });
+}
+
+/**
+ * Capture dispatch metadata as a proof artifact.
+ */
+export function captureDispatchProof(
+  repoRoot: string,
+  dispatchId: string,
+  meta: {
+    surface: string;
+    prompt: string;
+    packetHash: string;
+    promptHash: string;
+    specMarkdown: string;
+  },
+): ProofArtifact {
+  const dir = ensureProofDir(repoRoot, dispatchId);
+
+  const content = YAML.stringify({
+    dispatch_id: dispatchId,
+    surface: meta.surface,
+    packet_hash: meta.packetHash,
+    prompt_hash: meta.promptHash,
+    prompt_length: meta.prompt.length,
+    spec_length: meta.specMarkdown.length,
+    captured_at: new Date().toISOString(),
+  });
+
+  return captureArtifact(
+    dir,
+    "dispatch-metadata",
+    "captured",
+    "dispatch-metadata.yaml",
+    content,
+    `Dispatch ${dispatchId} to ${meta.surface}`,
+  );
+}
+
+/**
+ * Capture the governed prompt as a proof artifact.
+ */
+export function capturePromptProof(
+  repoRoot: string,
+  dispatchId: string,
+  prompt: string,
+): ProofArtifact {
+  const dir = ensureProofDir(repoRoot, dispatchId);
+
+  return captureArtifact(
+    dir,
+    "dispatch-metadata",
+    "captured",
+    "governed-prompt.md",
+    prompt,
+    `Governed dispatch prompt (${prompt.length} chars)`,
+  );
+}
+
+/**
+ * Capture the structured return as a proof artifact.
+ */
+export function captureReturnProof(
+  repoRoot: string,
+  dispatchId: string,
+  returnYaml: string,
+): ProofArtifact {
+  const dir = ensureProofDir(repoRoot, dispatchId);
+
+  return captureArtifact(
+    dir,
+    "return-structured",
+    "derived",
+    "structured-return.yaml",
+    returnYaml,
+    "Parsed structured return from execution output",
+  );
+}
+
+/**
+ * Capture an execution transcript as a proof artifact.
+ * This is a real "captured" artifact — it came from actual CLI transport,
+ * not from operator-provided YAML.
+ */
+export function captureTranscriptProof(
+  repoRoot: string,
+  dispatchId: string,
+  transcript: string,
+  surface: string,
+  durationMs: number,
+): ProofArtifact {
+  const dir = ensureProofDir(repoRoot, dispatchId);
+
+  const header = [
+    `# Execution Transcript`,
+    `# Surface: ${surface}`,
+    `# Dispatch: ${dispatchId}`,
+    `# Duration: ${durationMs}ms`,
+    `# Captured: ${new Date().toISOString()}`,
+    `---\n`,
+  ].join("\n");
+
+  return captureArtifact(
+    dir,
+    "execution-transcript",
+    "captured",
+    "execution-transcript.md",
+    header + transcript,
+    `Captured execution transcript from ${surface} (${durationMs}ms)`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Manifest persistence
+// ---------------------------------------------------------------------------
+
+/**
+ * Build and write a proof manifest for a dispatch.
+ * Collects any artifacts already in the proof folder + newly provided ones.
+ */
+export function buildAndWriteProofManifest(
+  repoRoot: string,
+  dispatchId: string,
+  additionalArtifacts: ProofArtifact[] = [],
+): ProofManifest {
+  const dir = proofDir(repoRoot, dispatchId);
+  const existingArtifacts: ProofArtifact[] = [];
+
+  // Scan for already-captured artifacts
+  if (existsSync(dir)) {
+    const files = readdirSync(dir).filter(f => f !== "manifest.yaml");
+    for (const file of files) {
+      const filePath = join(dir, file);
+      const s = statSync(filePath);
+      if (s.isFile()) {
+        const content = readFileSync(filePath, "utf-8");
+
+        // Classify kind from filename
+        let kind: ProofArtifact["kind"] = "custom";
+        if (file.includes("dispatch-metadata")) kind = "dispatch-metadata";
+        else if (file.includes("return")) kind = "return-structured";
+        else if (file.includes("prompt")) kind = "dispatch-metadata";
+        else if (file.includes("transcript")) kind = "execution-transcript";
+        else if (file.includes("trace")) kind = "execution-trace";
+
+        existingArtifacts.push(proofArtifactSchema.parse({
+          artifact_id: `prf-${randomBytes(6).toString("hex")}`,
+          kind,
+          provenance: file.includes("return") ? "derived" : "captured",
+          filename: file,
+          captured_at: new Date(s.mtimeMs).toISOString(),
+          size_bytes: s.size,
+          content_hash: hashContent(content),
+          description: `Proof artifact: ${file}`,
+        }));
+      }
+    }
+  }
+
+  // Deduplicate by filename (prefer provided over scanned)
+  const seenFilenames = new Set(additionalArtifacts.map(a => a.filename));
+  const allArtifacts = [
+    ...additionalArtifacts,
+    ...existingArtifacts.filter(a => !seenFilenames.has(a.filename)),
+  ];
+
+  const manifest = buildProofManifest({
+    dispatchId,
+    runFolder: dir,
+    artifacts: allArtifacts,
+  });
+
+  // Write manifest
+  ensureProofDir(repoRoot, dispatchId);
+  const manifestFile = proofManifestPath(repoRoot, dispatchId);
+  writeFileSync(manifestFile, YAML.stringify(manifest), "utf-8");
+
+  return manifest;
+}
+
+/**
+ * Load a proof manifest for a dispatch, if one exists.
+ */
+export function loadPortableProofManifest(
+  repoRoot: string,
+  dispatchId: string,
+): ProofManifest | null {
+  const manifestFile = proofManifestPath(repoRoot, dispatchId);
+  return readYaml<ProofManifest>(manifestFile);
+}

package/src/lib/transport.ts

@@ -0,0 +1,276 @@
+/**
+ * Transport detection — discovers whether Claude Code or Codex CLI
+ * is available locally, with honest status reporting.
+ *
+ * Returns actionable readiness signals so commands can:
+ * 1. Attempt automatic transport when ready
+ * 2. Fall back to manual with clear guidance when not
+ * 3. Never fake or approximate transport availability
+ */
+
+import { execFileSync, type SpawnSyncReturns } from "child_process";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type TransportStatus =
+  | "ready"            // CLI found + invocable (auth validated at execution time)
+  | "no-cli"           // CLI binary not found on PATH
+  | "no-auth"          // CLI found but auth provably missing
+  | "cli-error"        // CLI found but probe command failed unexpectedly
+  | "manual-requested"; // Operator explicitly chose manual dispatch
+
+export type TransportCapability =
+  | "review-only"      // Transcript capture only — CLI cannot modify files (claude -p default)
+  | "write-capable"    // CLI can modify repo files (requires --allowedTools or equivalent)
+  | "unknown";         // Cannot determine capability
+
+export interface TransportReadiness {
+  status: TransportStatus;
+  cli_path: string | null;
+  detail: string;
+  capability: TransportCapability;
+  capability_detail: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function whichSync(cmd: string): string | null {
+  try {
+    return execFileSync("which", [cmd], {
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Claude Code detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect whether the `claude` CLI is available and authenticated.
+ *
+ * Checks:
+ * 1. `claude` binary on PATH (via `which`)
+ * 2. Basic invocability (`claude --version`)
+ *
+ * Does NOT run a real prompt — that happens in the transport itself.
+ */
+export function detectClaudeTransport(): TransportReadiness {
+  const cliPath = whichSync("claude");
+
+  if (!cliPath) {
+    return {
+      status: "no-cli",
+      cli_path: null,
+      detail: "Claude Code CLI not found on PATH. Install: npm install -g @anthropic-ai/claude-code",
+      capability: "unknown",
+      capability_detail: "CLI not found.",
+    };
+  }
+
+  // Probe: can we invoke it?
+  try {
+    execFileSync(cliPath, ["--version"], {
+      encoding: "utf-8",
+      timeout: 10000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (e: any) {
+    return {
+      status: "cli-error",
+      cli_path: cliPath,
+      detail: `Claude CLI found at ${cliPath} but --version failed: ${e.message?.slice(0, 120) ?? "unknown error"}`,
+      capability: "unknown",
+      capability_detail: "CLI probe failed.",
+    };
+  }
+
+  // Capability: claude -p (print mode) is review-only by default.
+  // Write capability requires --allowedTools or similar flags.
+  return {
+    status: "ready",
+    cli_path: cliPath,
+    detail: `Claude Code CLI ready at ${cliPath} (auth validated at execution time)`,
+    capability: "review-only",
+    capability_detail: "Print mode (-p) captures transcript only. Claude cannot modify files without --allowedTools flag. To enable writes: claude -p --allowedTools Edit,Write",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Codex CLI detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect whether the `codex` CLI is available and authenticated.
+ *
+ * Checks:
+ * 1. `codex` binary on PATH
+ * 2. Basic invocability (`codex --version`)
+ *
+ * Auth is validated at execution time, not detection time.
+ * Codex supports both OPENAI_API_KEY and local login — we do not
+ * hard-require either, since a `--version` probe cannot distinguish them.
+ */
+export function detectCodexTransport(): TransportReadiness {
+  const cliPath = whichSync("codex");
+
+  if (!cliPath) {
+    return {
+      status: "no-cli",
+      cli_path: null,
+      detail: "Codex CLI not found on PATH. Install: npm install -g @openai/codex",
+      capability: "unknown",
+      capability_detail: "CLI not found.",
+    };
+  }
+
+  // Probe: can we invoke it?
+  try {
+    execFileSync(cliPath, ["--version"], {
+      encoding: "utf-8",
+      timeout: 10000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (e: any) {
+    return {
+      status: "cli-error",
+      cli_path: cliPath,
+      detail: `Codex CLI found at ${cliPath} but --version failed: ${e.message?.slice(0, 120) ?? "unknown error"}`,
+      capability: "unknown",
+      capability_detail: "CLI probe failed.",
+    };
+  }
+
+  // Codex review is always read-only — that's the correct audit posture
+  return {
+    status: "ready",
+    cli_path: cliPath,
+    detail: `Codex CLI ready at ${cliPath} (auth validated at execution time)`,
+    capability: "review-only",
+    capability_detail: "Codex review mode is read-only by design (audit lane).",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Transport execution — Claude Code
+// ---------------------------------------------------------------------------
+
+export interface TransportResult {
+  success: boolean;
+  transcript: string;
+  exit_code: number;
+  error?: string;
+  duration_ms: number;
+}
+
+/**
+ * Execute a governed prompt via Claude Code CLI in print mode.
+ *
+ * Uses `claude -p` (print mode) which reads the prompt, produces output,
+ * and exits. The full stdout is captured as the execution transcript.
+ */
+export function executeClaudeTransport(
+  cliPath: string,
+  prompt: string,
+  workingDirectory: string,
+  timeoutMs: number = 600000, // 10 minutes default
+): TransportResult {
+  const start = Date.now();
+
+  try {
+    const result = execFileSync(cliPath, ["-p", "--output-format", "text"], {
+      input: prompt,
+      cwd: workingDirectory,
+      encoding: "utf-8",
+      timeout: timeoutMs,
+      maxBuffer: 10 * 1024 * 1024, // 10MB
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    return {
+      success: true,
+      transcript: result,
+      exit_code: 0,
+      duration_ms: Date.now() - start,
+    };
+  } catch (e: any) {
+    const exitCode = e.status ?? 1;
+    const stdout = e.stdout ?? "";
+    const stderr = e.stderr ?? "";
+
+    return {
+      success: false,
+      transcript: stdout || stderr || e.message || "Unknown transport error",
+      exit_code: exitCode,
+      error: stderr || e.message,
+      duration_ms: Date.now() - start,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Transport execution — Codex CLI
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute an audit review via Codex CLI `review` subcommand.
+ *
+ * `codex review` is Codex's built-in read-only code review surface.
+ * It inspects the working tree and produces review output without
+ * making changes — exactly what an audit lane needs.
+ *
+ * Constraint: `--uncommitted` and `[PROMPT]` are mutually exclusive
+ * in the Codex CLI. We use `--uncommitted` for the working tree scope
+ * and `--title` to pass dispatch context.
+ */
+export function executeCodexTransport(
+  cliPath: string,
+  auditTitle: string,
+  workingDirectory: string,
+  timeoutMs: number = 600000,
+): TransportResult {
+  const start = Date.now();
+
+  // --title passes dispatch context; --uncommitted scopes to working tree
+  const titleSnippet = auditTitle.slice(0, 200);
+  try {
+    const result = execFileSync(
+      cliPath,
+      ["review", "--uncommitted", "--title", titleSnippet],
+      {
+        cwd: workingDirectory,
+        encoding: "utf-8",
+        timeout: timeoutMs,
+        maxBuffer: 10 * 1024 * 1024,
+        stdio: ["pipe", "pipe", "pipe"],
+      },
+    );
+
+    return {
+      success: true,
+      transcript: result,
+      exit_code: 0,
+      duration_ms: Date.now() - start,
+    };
+  } catch (e: any) {
+    const exitCode = e.status ?? 1;
+    const stdout = e.stdout ?? "";
+    const stderr = e.stderr ?? "";
+
+    return {
+      success: false,
+      transcript: stdout || stderr || e.message || "Unknown transport error",
+      exit_code: exitCode,
+      error: stderr || e.message,
+      duration_ms: Date.now() - start,
+    };
+  }
+}

package/src/lib/yaml-io.ts

@@ -0,0 +1,62 @@
+/**
+ * YAML read/write helpers for Switchboard CLI.
+ *
+ * Thin wrappers around the `yaml` package that handle
+ * missing files, directory creation, and consistent formatting.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname } from "path";
+import YAML from "yaml";
+
+/**
+ * Read and parse a YAML file. Returns null if the file doesn't exist.
+ * Throws on parse errors (malformed YAML is a real problem, not a missing-file case).
+ */
+export function readYaml<T = unknown>(filePath: string): T | null {
+  if (!existsSync(filePath)) return null;
+  const raw = readFileSync(filePath, "utf-8");
+  return YAML.parse(raw) as T;
+}
+
+/**
+ * Read a YAML file or throw if it doesn't exist.
+ */
+export function requireYaml<T = unknown>(filePath: string, label: string): T {
+  const result = readYaml<T>(filePath);
+  if (result === null || result === undefined) {
+    throw new Error(`Required file not found: ${filePath} (${label})`);
+  }
+  return result;
+}
+
+/**
+ * Write a value as YAML. Creates parent directories if needed.
+ */
+export function writeYaml(filePath: string, data: unknown): void {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const content = YAML.stringify(data, { lineWidth: 120 });
+  writeFileSync(filePath, content, "utf-8");
+}
+
+/**
+ * Read a markdown file. Returns null if missing.
+ */
+export function readMarkdown(filePath: string): string | null {
+  if (!existsSync(filePath)) return null;
+  return readFileSync(filePath, "utf-8");
+}
+
+/**
+ * Write a markdown file. Creates parent directories if needed.
+ */
+export function writeMarkdown(filePath: string, content: string): void {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(filePath, content, "utf-8");
+}