switchboard-cli 0.1.0-alpha.1

package/src/store/filesystem-store.ts

@@ -0,0 +1,326 @@
+/**
+ * Filesystem Store — local YAML-backed adapter for .switchboard/ state.
+ *
+ * Implements only the subset needed for Wave 1 (compile + packet).
+ * Does NOT replicate the full Supabase store. Each function reads/writes
+ * a single canonical file under .switchboard/.
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import YAML from "yaml";
+import {
+  projectContractSchema,
+  workingStateSchema,
+  loopContractSchema,
+  handoffRecordSchema,
+  dispatchReceiptSchema,
+  type ProjectContract,
+  type WorkingState,
+  type LoopContract,
+  type HandoffRecord,
+  type DispatchReceipt,
+  type ReceiptIssuedV2,
+  type AuditedReceipt,
+  type EvaluationResult,
+  type CanonicalDelta,
+  type NormalizedReturnEnvelope,
+  type GateState,
+} from "@switchboard/core";
+import {
+  contractPath,
+  currentStatePath,
+  loopPath,
+  specPath,
+  packetsDir,
+  sbDir,
+  handoffsDir,
+  receiptsDir,
+  evaluationsDir,
+  returnsDir,
+  dispatchMetaPath,
+  latestYamlIn,
+} from "../lib/paths";
+import { readYaml, requireYaml, writeYaml, readMarkdown, writeMarkdown } from "../lib/yaml-io";
+
+// ---------------------------------------------------------------------------
+// Read operations
+// ---------------------------------------------------------------------------
+
+export function loadContract(repoRoot: string): ProjectContract {
+  const raw = requireYaml(contractPath(repoRoot), "project contract");
+  return projectContractSchema.parse(raw);
+}
+
+export function loadCurrentState(repoRoot: string): WorkingState {
+  const raw = requireYaml(currentStatePath(repoRoot), "working state");
+  return workingStateSchema.parse(raw);
+}
+
+export function loadLoop(repoRoot: string): LoopContract | null {
+  const raw = readYaml(loopPath(repoRoot));
+  if (!raw) return null;
+  return loopContractSchema.parse(raw);
+}
+
+export function loadSpec(repoRoot: string): string | null {
+  return readMarkdown(specPath(repoRoot));
+}
+
+export function specExists(repoRoot: string): boolean {
+  return existsSync(specPath(repoRoot));
+}
+
+export function switchboardExists(repoRoot: string): boolean {
+  return existsSync(sbDir(repoRoot));
+}
+
+// ---------------------------------------------------------------------------
+// Write operations
+// ---------------------------------------------------------------------------
+
+export function writeContract(repoRoot: string, contract: ProjectContract): void {
+  writeYaml(contractPath(repoRoot), contract);
+}
+
+export function writeCurrentState(repoRoot: string, state: WorkingState): void {
+  writeYaml(currentStatePath(repoRoot), state);
+}
+
+export function writeLoop(repoRoot: string, loop: LoopContract): void {
+  writeYaml(loopPath(repoRoot), loop);
+}
+
+export function writeSpec(repoRoot: string, content: string): void {
+  writeMarkdown(specPath(repoRoot), content);
+}
+
+/**
+ * Write a dispatch packet file to .switchboard/packets/.
+ * Returns the full path of the written file.
+ */
+export function writePacket(repoRoot: string, filename: string, content: string): string {
+  const dir = packetsDir(repoRoot);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const filePath = join(dir, filename);
+  writeFileSync(filePath, content, "utf-8");
+  return filePath;
+}
+
+// ---------------------------------------------------------------------------
+// Wave 2: Handoff persistence
+// ---------------------------------------------------------------------------
+
+function ensureDir(dir: string): void {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+export function saveHandoff(repoRoot: string, handoff: HandoffRecord): string {
+  ensureDir(handoffsDir(repoRoot));
+  const filePath = join(handoffsDir(repoRoot), `${handoff.handoff_id}.yaml`);
+  writeYaml(filePath, handoff);
+  return filePath;
+}
+
+export function loadHandoff(repoRoot: string, handoffId: string): HandoffRecord | null {
+  const filePath = join(handoffsDir(repoRoot), `${handoffId}.yaml`);
+  const raw = readYaml(filePath);
+  if (!raw) return null;
+  return handoffRecordSchema.parse(raw);
+}
+
+export function loadLatestHandoff(repoRoot: string): HandoffRecord | null {
+  const latest = latestYamlIn(handoffsDir(repoRoot));
+  if (!latest) return null;
+  const raw = readYaml(latest);
+  if (!raw) return null;
+  return handoffRecordSchema.parse(raw);
+}
+
+// ---------------------------------------------------------------------------
+// Wave 2: Dispatch metadata persistence
+// ---------------------------------------------------------------------------
+
+export interface DispatchMeta {
+  dispatch_id: string;
+  handoff_id: string;
+  surface: string;
+  prompt: string;
+  spec_markdown: string;
+  dispatched_at: string;
+  dispatch_receipt?: DispatchReceipt;
+}
+
+export function saveDispatchMeta(repoRoot: string, meta: DispatchMeta): string {
+  const filePath = dispatchMetaPath(repoRoot, meta.dispatch_id);
+  writeYaml(filePath, meta);
+  return filePath;
+}
+
+export function loadDispatchMeta(repoRoot: string, dispatchId: string): DispatchMeta | null {
+  const raw = readYaml<DispatchMeta>(dispatchMetaPath(repoRoot, dispatchId));
+  return raw ?? null;
+}
+
+export function loadLatestDispatchMeta(repoRoot: string): DispatchMeta | null {
+  // Dispatch meta files are in working/ with dispatch-<id>.yaml naming
+  const workingDir = join(sbDir(repoRoot), "working");
+  if (!existsSync(workingDir)) return null;
+  const { readdirSync, statSync } = require("fs") as typeof import("fs");
+  const files = readdirSync(workingDir)
+    .filter((f: string) => f.startsWith("dispatch-") && f.endsWith(".yaml"))
+    .map((f: string) => ({ path: join(workingDir, f), mtime: statSync(join(workingDir, f)).mtimeMs }))
+    .sort((a: { mtime: number }, b: { mtime: number }) => b.mtime - a.mtime);
+  if (files.length === 0) return null;
+  return readYaml<DispatchMeta>(files[0]!.path) ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Wave 2: Return persistence
+// ---------------------------------------------------------------------------
+
+export function saveReturn(repoRoot: string, dispatchId: string, returnData: unknown): string {
+  ensureDir(returnsDir(repoRoot));
+  const filePath = join(returnsDir(repoRoot), `${dispatchId}-return.yaml`);
+  writeYaml(filePath, returnData);
+  return filePath;
+}
+
+export function loadReturnYaml(repoRoot: string, path: string): string | null {
+  if (!existsSync(path)) return null;
+  return readFileSync(path, "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Wave 2: Receipt persistence
+// ---------------------------------------------------------------------------
+
+export function saveReceiptV2(repoRoot: string, receipt: ReceiptIssuedV2): string {
+  ensureDir(receiptsDir(repoRoot));
+  const filePath = join(receiptsDir(repoRoot), `${receipt.receipt_id}.yaml`);
+  writeYaml(filePath, receipt);
+  return filePath;
+}
+
+export function saveReceiptJson(repoRoot: string, receipt: ReceiptIssuedV2): string {
+  ensureDir(receiptsDir(repoRoot));
+  const filePath = join(receiptsDir(repoRoot), `${receipt.receipt_id}.json`);
+  writeFileSync(filePath, JSON.stringify(receipt, null, 2), "utf-8");
+  return filePath;
+}
+
+export function loadLatestReceipt(repoRoot: string): ReceiptIssuedV2 | null {
+  const latest = latestYamlIn(receiptsDir(repoRoot));
+  if (!latest) return null;
+  return readYaml<ReceiptIssuedV2>(latest) ?? null;
+}
+
+/**
+ * Find a receipt by its source dispatch_id.
+ * Scans receipt files and matches on the dispatch_id field inside the YAML,
+ * since receipts are stored by receipt_id, not dispatch_id.
+ */
+export function loadReceiptByDispatch(repoRoot: string, dispatchId: string): ReceiptIssuedV2 | null {
+  const dir = receiptsDir(repoRoot);
+  if (!existsSync(dir)) return null;
+  const files = readdirSync(dir)
+    .filter(f => f.endsWith(".yaml") && !f.endsWith("-audited.yaml"))
+    .map(f => join(dir, f));
+
+  for (const filePath of files) {
+    const receipt = readYaml<ReceiptIssuedV2>(filePath);
+    if (receipt && (receipt as any).dispatch_id === dispatchId) {
+      return receipt;
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Wave 2: Audited receipt persistence (V1 format for evaluation lane)
+// ---------------------------------------------------------------------------
+
+export function saveAuditedReceipt(repoRoot: string, receipt: AuditedReceipt): string {
+  ensureDir(receiptsDir(repoRoot));
+  const filePath = join(receiptsDir(repoRoot), `${receipt.receipt_id}-audited.yaml`);
+  writeYaml(filePath, receipt);
+  return filePath;
+}
+
+export function loadLatestAuditedReceipt(repoRoot: string): AuditedReceipt | null {
+  const dir = receiptsDir(repoRoot);
+  if (!existsSync(dir)) return null;
+  const { readdirSync, statSync } = require("fs") as typeof import("fs");
+  const files = readdirSync(dir)
+    .filter((f: string) => f.endsWith("-audited.yaml"))
+    .map((f: string) => ({ path: join(dir, f), mtime: statSync(join(dir, f)).mtimeMs }))
+    .sort((a: { mtime: number }, b: { mtime: number }) => b.mtime - a.mtime);
+  if (files.length === 0) return null;
+  return readYaml<AuditedReceipt>(files[0]!.path) ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Wave 2: Evaluation result persistence
+// ---------------------------------------------------------------------------
+
+export function saveEvaluationResult(repoRoot: string, result: EvaluationResult): string {
+  ensureDir(evaluationsDir(repoRoot));
+  const filePath = join(evaluationsDir(repoRoot), `${result.evaluation_id}.yaml`);
+  writeYaml(filePath, result);
+  return filePath;
+}
+
+export function saveEvaluationJson(repoRoot: string, result: EvaluationResult): string {
+  ensureDir(evaluationsDir(repoRoot));
+  const filePath = join(evaluationsDir(repoRoot), `${result.evaluation_id}.json`);
+  writeFileSync(filePath, JSON.stringify(result, null, 2), "utf-8");
+  return filePath;
+}
+
+// ---------------------------------------------------------------------------
+// Wave 2: Governed pipeline intermediate persistence
+// ---------------------------------------------------------------------------
+
+export function saveCanonicalDelta(repoRoot: string, delta: CanonicalDelta): string {
+  ensureDir(returnsDir(repoRoot));
+  const filePath = join(returnsDir(repoRoot), `${delta.delta_id}.yaml`);
+  writeYaml(filePath, delta);
+  return filePath;
+}
+
+export function saveNormalizedEnvelope(repoRoot: string, envelope: NormalizedReturnEnvelope): string {
+  ensureDir(returnsDir(repoRoot));
+  const filePath = join(returnsDir(repoRoot), `${envelope.envelope_id}.yaml`);
+  writeYaml(filePath, envelope);
+  return filePath;
+}
+
+export function saveGateState(repoRoot: string, dispatchId: string, gate: GateState): string {
+  ensureDir(returnsDir(repoRoot));
+  const filePath = join(returnsDir(repoRoot), `gate-${dispatchId}.yaml`);
+  writeYaml(filePath, gate);
+  return filePath;
+}
+
+// ---------------------------------------------------------------------------
+// Scaffold — create the canonical .switchboard/ directory tree
+// ---------------------------------------------------------------------------
+
+export function scaffoldDirectories(repoRoot: string): void {
+  // Wave 1 directories only. handoffs/, receipts/, and evaluations/
+  // are created on demand in Wave 2 when those commands land.
+  const dirs = [
+    join(sbDir(repoRoot), "project"),
+    join(sbDir(repoRoot), "working"),
+    join(sbDir(repoRoot), "artifacts"),
+    packetsDir(repoRoot),
+  ];
+
+  for (const dir of dirs) {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+}