switchboard-cli 0.1.0-alpha.3 → 0.1.0-alpha.5

package/src/lib/proof.ts

@@ -1,262 +0,0 @@
-/**
- * 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

@@ -1,276 +0,0 @@
-/**
- * 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

@@ -1,62 +0,0 @@
-/**
- * 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");
-}