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

package/src/index.ts

@@ -1,43 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Switchboard CLI — repo-native governance substrate.
- *
- * Portable-first: reads .switchboard/ canonical state, compiles governed
- * dispatch packets, and writes them to disk. No hosted app required.
- */
-
-import { Command } from "commander";
-import { registerInitCommand } from "./commands/init";
-import { registerCompileCommand } from "./commands/compile";
-import { registerPacketCommand } from "./commands/packet";
-import { registerRunClaudeCommand } from "./commands/run-claude";
-import { registerIngestCommand } from "./commands/ingest";
-import { registerReceiptCommand } from "./commands/receipt";
-import { registerEvaluateCommand } from "./commands/evaluate";
-import { registerAuditCodexCommand } from "./commands/audit-codex";
-import { registerCalibrateCommand } from "./commands/calibrate";
-
-const program = new Command();
-
-program
-  .name("sb")
-  .description("Switchboard CLI — portable governance substrate for AI workflows")
-  .version("0.1.0-alpha.1");
-
-// Wave 1: compile + packet
-registerInitCommand(program);
-registerCompileCommand(program);
-registerPacketCommand(program);
-
-// Wave 2: run + ingest + receipt + evaluate + audit
-registerRunClaudeCommand(program);
-registerIngestCommand(program);
-registerReceiptCommand(program);
-registerEvaluateCommand(program);
-registerAuditCodexCommand(program);
-
-// Wave 3: calibration
-registerCalibrateCommand(program);
-
-program.parse();

package/src/lib/draft-return.ts

@@ -1,278 +0,0 @@
-/**
- * Draft Return Generator — produces a structured SB_RETURN.yaml draft
- * from execution evidence, proof artifacts, and dispatch context.
- *
- * This is NOT auto-ingest. The draft is:
- * - Explicitly marked as operator-review-required
- * - Conservative: never claims objective_met=yes without explicit evidence
- * - Provenance-labeled: every populated field cites its source
- * - Honest about gaps: where evidence is missing, says so plainly
- *
- * The operator opens the draft, reviews it, edits as needed, then submits
- * through the existing ingest path.
- */
-
-import { existsSync, readFileSync, readdirSync } from "fs";
-import { join, relative } from "path";
-import { execSync } from "child_process";
-import type { HandoffRecord, ReturnReport } from "@switchboard/core";
-import type { ProofManifest } from "@switchboard/core";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface DraftReturnInput {
-  handoff: HandoffRecord;
-  transcript: string | null;
-  proofManifest: ProofManifest | null;
-  repoRoot: string;
-}
-
-export interface DraftReturnResult {
-  draft: ReturnReport;
-  warnings: string[];
-  evidence_sources: string[];
-}
-
-// ---------------------------------------------------------------------------
-// Transcript signal extraction (deterministic, no LLM)
-// ---------------------------------------------------------------------------
-
-interface TranscriptSignals {
-  mentions_success: boolean;
-  mentions_failure: boolean;
-  mentions_error: boolean;
-  mentions_test: boolean;
-  mentions_blocked: boolean;
-  file_mentions: string[];
-  verification_mentions: string[];
-  summary_hint: string;
-}
-
-function extractTranscriptSignals(transcript: string): TranscriptSignals {
-  const lower = transcript.toLowerCase();
-
-  const mentions_success = /\b(completed?|succeed(ed)?|success(ful(ly)?)?|done|finished|implemented|created|built)\b/.test(lower);
-  const mentions_failure = /\b(fail(ed|ure)?|could not|unable to|cannot|error(ed)?)\b/.test(lower);
-  const mentions_error = /\b(error|exception|traceback|panic|crash)\b/.test(lower);
-  const mentions_test = /\b(test(s|ing)?|spec|vitest|jest|mocha|pass(ed|ing)?|assert)\b/.test(lower);
-  const mentions_blocked = /\b(block(ed)?|permission denied|not allowed|unauthorized|timeout)\b/.test(lower);
-
-  // Extract file-like mentions (paths with extensions)
-  const fileRegex = /[\w./-]+\.(ts|js|tsx|jsx|json|yaml|yml|md|css|html|py|go|rs|sh)\b/g;
-  const file_mentions = [...new Set(transcript.match(fileRegex) ?? [])].slice(0, 20);
-
-  // Extract verification-like mentions
-  const verification_mentions: string[] = [];
-  if (mentions_test) {
-    const testLines = transcript.split("\n").filter(l =>
-      /(pass|fail|test|spec|✓|✗|PASS|FAIL)/.test(l)
-    ).slice(0, 5);
-    verification_mentions.push(...testLines.map(l => l.trim().slice(0, 120)));
-  }
-
-  // Build summary hint
-  let summary_hint: string;
-  if (mentions_blocked) {
-    summary_hint = "Execution was blocked or encountered permission issues.";
-  } else if (mentions_failure && !mentions_success) {
-    summary_hint = "Execution encountered failures.";
-  } else if (mentions_success && !mentions_failure) {
-    summary_hint = "Transcript suggests successful completion (needs operator verification).";
-  } else if (mentions_success && mentions_failure) {
-    summary_hint = "Transcript shows mixed results — some success, some failures.";
-  } else {
-    summary_hint = "Transcript did not contain clear success or failure signals.";
-  }
-
-  return {
-    mentions_success,
-    mentions_failure,
-    mentions_error,
-    mentions_test,
-    mentions_blocked,
-    file_mentions,
-    verification_mentions,
-    summary_hint,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Git-based changed files detection
-// ---------------------------------------------------------------------------
-
-function detectChangedFiles(repoRoot: string): string[] {
-  try {
-    // git status --porcelain captures staged, unstaged, AND untracked files
-    const output = execSync("git status --porcelain 2>/dev/null || true", {
-      cwd: repoRoot,
-      encoding: "utf-8",
-      timeout: 5000,
-    });
-    // Porcelain format: "XY filename" — extract filenames, skip .switchboard/ internals
-    return output
-      .split("\n")
-      .map(l => l.slice(3).trim())
-      .filter(f => f && !f.startsWith(".switchboard/"))
-      .slice(0, 50);
-  } catch {
-    return [];
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Main generator
-// ---------------------------------------------------------------------------
-
-export function generateDraftReturn(input: DraftReturnInput): DraftReturnResult {
-  const { handoff, transcript, proofManifest, repoRoot } = input;
-  const warnings: string[] = [];
-  const evidence_sources: string[] = [];
-
-  // Start from the template defaults
-  const draft: ReturnReport = {
-    handoff_id: handoff.handoff_id,
-    surface_used: handoff.surface,
-    objective_attempted: handoff.loop.objective,
-    // Conservative defaults — NEVER auto-promote to "yes"
-    status: "partial",
-    objective_met: "partial",
-    done_when_met: "partial",
-    summary: "",
-    changed_files: [],
-    decisions_made: [],
-    blockers: [],
-    escalations: [],
-    evidence: [],
-    success_criteria_met: [],
-    verification_run: [],
-    artifacts_created: [],
-    recommended_next_step: "Review this draft, verify claims, then run switchboard ingest.",
-    packet_id: "",
-    packet_hash: "",
-  };
-
-  // --- Populate from transcript signals ---
-  let signals: TranscriptSignals | null = null;
-
-  if (transcript && transcript.trim().length > 0) {
-    signals = extractTranscriptSignals(transcript);
-    evidence_sources.push("execution-transcript");
-
-    // Status from transcript signals
-    if (signals.mentions_blocked) {
-      draft.status = "blocked";
-      draft.blockers.push("Execution was blocked (transcript indicates permission or access issues).");
-      warnings.push("Transcript suggests execution was blocked. Check for permission issues.");
-    } else if (signals.mentions_failure && !signals.mentions_success) {
-      draft.status = "partial";
-      warnings.push("Transcript suggests failures occurred. Review before claiming completion.");
-    }
-    // Never auto-set status to "done" — that's for the operator
-
-    // Evidence from transcript
-    if (signals.mentions_success) {
-      draft.evidence.push(`[transcript] Execution transcript suggests completion (needs operator verification).`);
-    }
-    if (signals.mentions_error) {
-      draft.evidence.push(`[transcript] Errors detected in execution transcript — review required.`);
-    }
-
-    // Verification from transcript
-    for (const v of signals.verification_mentions) {
-      draft.verification_run.push(`[transcript] ${v}`);
-    }
-
-    // File mentions from transcript
-    for (const f of signals.file_mentions) {
-      if (!draft.changed_files.includes(f)) {
-        draft.evidence.push(`[transcript] File referenced in transcript: ${f}`);
-      }
-    }
-
-    // Summary from transcript signals
-    draft.summary = `DRAFT — ${signals.summary_hint} Operator review required before ingest.`;
-  } else {
-    draft.summary = "DRAFT — no execution transcript available. Fill in manually from execution results.";
-    warnings.push("No execution transcript found. Draft is a skeleton only.");
-  }
-
-  // --- Populate changed files from git ---
-  const gitChangedFiles = detectChangedFiles(repoRoot);
-  if (gitChangedFiles.length > 0) {
-    draft.changed_files = gitChangedFiles;
-    evidence_sources.push("git-diff");
-    draft.evidence.push(`[git-status] ${gitChangedFiles.length} file(s) detected (staged + unstaged + untracked, excluding .switchboard/).`);
-  } else {
-    warnings.push("No changed files detected via git. Fill in changed_files manually if execution modified files.");
-  }
-
-  // --- Populate from proof manifest ---
-  if (proofManifest) {
-    evidence_sources.push("proof-manifest");
-    draft.evidence.push(`[proof] ${proofManifest.artifacts.length} proof artifact(s) captured (${proofManifest.provenance_summary.captured_count} captured, ${proofManifest.provenance_summary.derived_count} derived).`);
-    for (const artifact of proofManifest.artifacts) {
-      draft.artifacts_created.push(`[proof:${artifact.kind}] ${artifact.filename} (${artifact.size_bytes} bytes)`);
-    }
-  }
-
-  // --- Do NOT pre-fill success_criteria_met ---
-  // Downstream accounting (gate, delta, normalizer) treats any row in
-  // success_criteria_met as real criteria met. Pre-filling with
-  // "[needs confirmation]" placeholders would silently inflate confidence
-  // if the operator ingests without editing. Leave empty; add a warning
-  // so the operator knows to fill them in.
-  if (handoff.loop.done_when.length > 0) {
-    warnings.push(`${handoff.loop.done_when.length} done-when criteria must be confirmed manually: ${handoff.loop.done_when.map(c => c.slice(0, 50)).join("; ")}`);
-  }
-
-  // --- Ensure schema validity ---
-  // objective_met stays "partial" — we never auto-promote
-  // done_when_met stays "partial" — we never auto-promote
-  // If draft has evidence + verification, note it's still partial pending review
-  if (draft.evidence.length > 0 && draft.verification_run.length > 0) {
-    warnings.push("Draft has evidence and verification data from transcript. Promote objective_met/done_when_met to 'yes' only after manual review.");
-  }
-
-  // Final safety: ensure summary is non-empty
-  if (!draft.summary) {
-    draft.summary = "DRAFT — generated from execution evidence. Operator review required.";
-  }
-
-  return { draft, warnings, evidence_sources };
-}
-
-// ---------------------------------------------------------------------------
-// YAML serialization with draft header
-// ---------------------------------------------------------------------------
-
-export function serializeDraftReturn(result: DraftReturnResult): string {
-  const YAML = require("yaml") as typeof import("yaml");
-
-  const header = [
-    "# ============================================================",
-    "# DRAFT RETURN — REVIEW REQUIRED BEFORE INGEST",
-    "# ============================================================",
-    "#",
-    "# This return was auto-generated from execution evidence.",
-    "# Fields marked [transcript], [git], [proof] cite their source.",
-    "# Fields marked [needs confirmation] require operator verification.",
-    "#",
-    `# Evidence sources: ${result.evidence_sources.join(", ") || "none"}`,
-    `# Warnings: ${result.warnings.length}`,
-  ];
-
-  for (const w of result.warnings) {
-    header.push(`#   - ${w}`);
-  }
-
-  header.push(
-    "#",
-    "# Review this file, then run: switchboard ingest",
-    "# ============================================================",
-    "",
-  );
-
-  return header.join("\n") + YAML.stringify(result.draft);
-}

package/src/lib/drift-guard.ts

@@ -1,105 +0,0 @@
-/**
- * Drift guard — detects meaningful disagreement between the compiled
- * loop objective and current.next_objective.
- *
- * Fails or warns honestly before packet/run proceeds with a mismatched
- * objective. This prevents the operator from unknowingly dispatching
- * against a stale or overridden objective.
- */
-
-import { existsSync } from "fs";
-import type { LoopContract, WorkingState } from "@switchboard/core";
-import { loopPath } from "./paths";
-import { readYaml } from "./yaml-io";
-import * as out from "./output";
-
-function compact(text: string): string {
-  return text.replace(/\s+/g, " ").trim().toLowerCase();
-}
-
-export interface DriftCheckResult {
-  drifted: boolean;
-  loopObjective: string | null;
-  currentObjective: string;
-  reason: string;
-}
-
-/**
- * Check if the compiled loop objective meaningfully disagrees with
- * current.next_objective.
- *
- * Returns { drifted: false } when:
- * - No loop.yaml exists (packet/run will compile one fresh)
- * - The objectives match after whitespace normalization
- *
- * Returns { drifted: true } when:
- * - loop.yaml exists AND its objective differs from current.next_objective
- */
-export function checkObjectiveDrift(repoRoot: string, current: WorkingState): DriftCheckResult {
-  const loopFile = loopPath(repoRoot);
-
-  if (!existsSync(loopFile)) {
-    return {
-      drifted: false,
-      loopObjective: null,
-      currentObjective: current.next_objective,
-      reason: "No compiled loop.yaml — will compile fresh.",
-    };
-  }
-
-  const loop = readYaml<LoopContract>(loopFile);
-  if (!loop || !loop.objective) {
-    return {
-      drifted: false,
-      loopObjective: null,
-      currentObjective: current.next_objective,
-      reason: "loop.yaml exists but has no objective.",
-    };
-  }
-
-  const loopNorm = compact(loop.objective);
-  const currentNorm = compact(current.next_objective);
-
-  if (loopNorm === currentNorm) {
-    return {
-      drifted: false,
-      loopObjective: loop.objective,
-      currentObjective: current.next_objective,
-      reason: "Objectives match.",
-    };
-  }
-
-  return {
-    drifted: true,
-    loopObjective: loop.objective,
-    currentObjective: current.next_objective,
-    reason: "Compiled loop objective differs from current.next_objective.",
-  };
-}
-
-/**
- * Enforce the drift guard. Returns true if safe to proceed, false if blocked.
- * When --force is set, warns but proceeds.
- */
-export function enforceDriftGuard(
-  repoRoot: string,
-  current: WorkingState,
-  force: boolean,
-): boolean {
-  const check = checkObjectiveDrift(repoRoot, current);
-
-  if (!check.drifted) return true;
-
-  out.warn("Objective drift detected between loop.yaml and current.yaml");
-  out.section("Loop objective", check.loopObjective ?? "(none)");
-  out.section("Current objective", check.currentObjective);
-
-  if (force) {
-    out.warn("Proceeding with current.next_objective (--force).");
-    out.info("The compiled loop.yaml will be ignored; a fresh loop will be compiled.");
-    return true;
-  }
-
-  out.fail("Run `switchboard compile` to re-sync, or use --force to override.");
-  return false;
-}

package/src/lib/errors.ts

@@ -1,61 +0,0 @@
-/**
- * CLI error handling — converts thrown errors into operator-facing messages.
- *
- * Wraps command action handlers so stack traces never leak to the user
- * unless NODE_DEBUG=switchboard is set.
- */
-
-import * as out from "./output";
-
-/**
- * Wrap an async command action so errors produce clean CLI output
- * instead of raw stack traces.
- */
-export function withCliErrors<T extends unknown[]>(
-  fn: (...args: T) => Promise<void>,
-): (...args: T) => Promise<void> {
-  return async (...args: T) => {
-    try {
-      await fn(...args);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-
-      // Known error patterns → helpful operator messages
-      if (message.includes("Required file not found")) {
-        out.fail(message);
-        out.info("Run `switchboard init` to create the .switchboard/ directory first.");
-      } else if (message.includes("Could not find a Switchboard project root")) {
-        out.fail(message);
-      } else if (err && (err as any).issues && Array.isArray((err as any).issues)) {
-        // ZodError — extract human-readable validation messages
-        const issues = (err as any).issues as Array<{ path: string[]; message: string }>;
-        const summary = issues
-          .slice(0, 5)
-          .map(i => `  ${i.path.join(".")}: ${i.message}`)
-          .join("\n");
-        out.fail("Invalid YAML data — validation failed:");
-        console.error(summary);
-        if (issues.length > 5) {
-          out.info(`  ... and ${issues.length - 5} more issue(s)`);
-        }
-        out.info("Check that the return file matches the expected SB_RETURN.yaml schema.");
-      } else if (message.includes("Return objective does not match")) {
-        out.fail(message);
-        out.info("The return's objective_attempted must exactly match the handoff objective.");
-        out.info("Check .switchboard/handoffs/ for the expected objective.");
-      } else if (message.includes("no active handoff")) {
-        out.fail(message);
-        out.info("Run `switchboard run claude` first to create a dispatch.");
-      } else {
-        out.fail(message);
-      }
-
-      // Show stack trace only in debug mode
-      if (process.env["NODE_DEBUG"]?.includes("switchboard") && err instanceof Error) {
-        console.error(err.stack);
-      }
-
-      process.exitCode = 1;
-    }
-  };
-}

package/src/lib/output.ts

@@ -1,43 +0,0 @@
-/**
- * CLI output helpers — structured console output with consistent formatting.
- */
-
-const RESET = "\x1b[0m";
-const BOLD = "\x1b[1m";
-const DIM = "\x1b[2m";
-const GREEN = "\x1b[32m";
-const YELLOW = "\x1b[33m";
-const RED = "\x1b[31m";
-const CYAN = "\x1b[36m";
-
-export function heading(text: string): void {
-  console.log(`\n${BOLD}${CYAN}${text}${RESET}\n`);
-}
-
-export function success(text: string): void {
-  console.log(`${GREEN}✓${RESET} ${text}`);
-}
-
-export function warn(text: string): void {
-  console.log(`${YELLOW}⚠${RESET} ${text}`);
-}
-
-export function fail(text: string): void {
-  console.log(`${RED}✗${RESET} ${text}`);
-}
-
-export function info(text: string): void {
-  console.log(`${DIM}  ${text}${RESET}`);
-}
-
-export function bullet(text: string): void {
-  console.log(`  • ${text}`);
-}
-
-export function fileWritten(label: string, path: string): void {
-  console.log(`${GREEN}✓${RESET} ${label}: ${DIM}${path}${RESET}`);
-}
-
-export function section(label: string, value: string): void {
-  console.log(`  ${BOLD}${label}:${RESET} ${value}`);
-}

package/src/lib/paths.ts

@@ -1,125 +0,0 @@
-/**
- * Path resolution helpers for Switchboard CLI.
- *
- * Discovers the repo root (by walking up to find .git or .switchboard/)
- * and resolves all canonical .switchboard/ paths from there.
- */
-
-import { existsSync, readdirSync, statSync } from "fs";
-import { dirname, join, resolve } from "path";
-
-const SWITCHBOARD_DIR = ".switchboard";
-
-/**
- * Walk up from `startDir` looking for a directory that contains
- * `.switchboard/` or `.git/`. Returns the first match, or null.
- */
-export function findRepoRoot(startDir: string = process.cwd()): string | null {
-  let dir = resolve(startDir);
-  const root = dirname(dir) === dir ? dir : undefined; // filesystem root guard
-
-  while (true) {
-    if (existsSync(join(dir, SWITCHBOARD_DIR)) || existsSync(join(dir, ".git"))) {
-      return dir;
-    }
-    const parent = dirname(dir);
-    if (parent === dir) return null; // hit filesystem root
-    dir = parent;
-  }
-}
-
-/**
- * Resolve repo root or throw with a helpful message.
- */
-export function requireRepoRoot(startDir?: string): string {
-  const root = findRepoRoot(startDir);
-  if (!root) {
-    throw new Error(
-      "Could not find a Switchboard project root.\n" +
-      "Run `switchboard init` to create a .switchboard/ directory, or run from inside a git repo.",
-    );
-  }
-  return root;
-}
-
-// ---------------------------------------------------------------------------
-// Canonical path helpers
-// ---------------------------------------------------------------------------
-
-export function sbDir(repoRoot: string): string {
-  return join(repoRoot, SWITCHBOARD_DIR);
-}
-
-export function contractPath(repoRoot: string): string {
-  return join(sbDir(repoRoot), "project", "contract.yaml");
-}
-
-export function currentStatePath(repoRoot: string): string {
-  return join(sbDir(repoRoot), "working", "current.yaml");
-}
-
-export function loopPath(repoRoot: string): string {
-  return join(sbDir(repoRoot), "working", "loop.yaml");
-}
-
-export function specPath(repoRoot: string): string {
-  return join(sbDir(repoRoot), "artifacts", "SB_SPEC.md");
-}
-
-export function packetsDir(repoRoot: string): string {
-  return join(sbDir(repoRoot), "packets");
-}
-
-export function handoffsDir(repoRoot: string): string {
-  return join(sbDir(repoRoot), "handoffs");
-}
-
-export function receiptsDir(repoRoot: string): string {
-  return join(sbDir(repoRoot), "receipts");
-}
-
-export function evaluationsDir(repoRoot: string): string {
-  return join(sbDir(repoRoot), "evaluations");
-}
-
-export function returnsDir(repoRoot: string): string {
-  return join(sbDir(repoRoot), "returns");
-}
-
-export function dispatchMetaPath(repoRoot: string, dispatchId: string): string {
-  return join(sbDir(repoRoot), "working", `dispatch-${dispatchId}.yaml`);
-}
-
-export function returnTemplatePath(repoRoot: string, dispatchId: string): string {
-  return join(returnsDir(repoRoot), `${dispatchId}-template.yaml`);
-}
-
-export function proofDir(repoRoot: string, dispatchId: string): string {
-  return join(sbDir(repoRoot), "proof", dispatchId);
-}
-
-export function proofManifestPath(repoRoot: string, dispatchId: string): string {
-  return join(proofDir(repoRoot, dispatchId), "manifest.yaml");
-}
-
-// ---------------------------------------------------------------------------
-// Latest-file lookup
-// ---------------------------------------------------------------------------
-
-/**
- * Find the most recently modified YAML file in a directory.
- * Returns the full path, or null if the dir is empty / doesn't exist.
- */
-export function latestYamlIn(dirPath: string): string | null {
-  if (!existsSync(dirPath)) return null;
-
-  const files = readdirSync(dirPath)
-    .filter(f => f.endsWith(".yaml") || f.endsWith(".yml"))
-    .map(f => {
-      const full = join(dirPath, f);
-      return { path: full, mtime: statSync(full).mtimeMs };
-    })
-    .sort((a, b) => b.mtime - a.mtime);
-
-  return files[0]?.path ?? null;
-}