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

package/node_modules/@switchboard/projections/node_modules/@switchboard/core/src/canonical-pack.ts

@@ -0,0 +1,400 @@
+/**
+ * Canonical Project Pack
+ *
+ * A traceable bundle/materialization of canonical project files used by
+ * external surfaces (ChatGPT compile, Claude Code execution, Codex audit).
+ *
+ * This is NOT a replacement for canonical state. It is a point-in-time
+ * snapshot that anchors compile -> build -> audit to the same governed
+ * file base.
+ *
+ * Key invariants:
+ * - Pack is derived from canonical state, never the reverse
+ * - Pack identity threads through dispatch, receipt, and audit provenance
+ * - Stale packs are honest: they block or warn, never silently serve old files
+ * - ChatGPT mirror/source-link is best-effort and never authority
+ */
+
+import { createHash, randomBytes } from "crypto";
+
+// ---------------------------------------------------------------------------
+// Pack types
+// ---------------------------------------------------------------------------
+
+export type PackStatus = "ready" | "stale" | "materialization_failed";
+
+export type PackMaterializationMode = "repo_worktree" | "file_pack_only";
+
+export type PackCreationSource =
+  | "project_create"
+  | "recompile"
+  | "manual_refresh"
+  | "slice_advance";
+
+export type MirrorLinkStatus =
+  | "not_attempted"
+  | "linked"
+  | "mirrored"
+  | "unavailable"
+  | "failed";
+
+export type PackFileRef = {
+  path: string;
+  /** Content hash (sha256 prefix) for integrity verification */
+  hash: string;
+};
+
+export type PackMirror = {
+  chatgpt_status: MirrorLinkStatus;
+  chatgpt_project_id: string | null;
+  last_mirror_at: string | null;
+  mirror_error: string | null;
+};
+
+export type CanonicalProjectPack = {
+  pack_id: string;
+  project_id: string;
+  version: number;
+  status: PackStatus;
+  materialization_mode: PackMaterializationMode;
+  creation_source: PackCreationSource;
+  created_at: string;
+
+  // Source refs — what canonical state this pack represents
+  contract_id: string;
+  spec_hash: string;
+  next_slice_id: string | null;
+
+  // Repo/worktree locator (when materialization_mode is repo_worktree)
+  repo_root: string | null;
+  worktree_path: string | null;
+
+  // File inventory
+  file_count: number;
+  files: PackFileRef[];
+
+  // Mirror/source-link — best-effort, never authority
+  mirror: PackMirror;
+
+  // Staleness tracking
+  stale_reason: string | null;
+  superseded_by: string | null;
+};
+
+// ---------------------------------------------------------------------------
+// Pack provenance — threaded through dispatch/receipt/audit
+// ---------------------------------------------------------------------------
+
+export type PackProvenance = {
+  pack_id: string;
+  pack_version: number;
+  pack_status_at_use: PackStatus;
+  /** True if the pack was already stale when this surface used it */
+  stale_at_use: boolean;
+};
+
+// ---------------------------------------------------------------------------
+// Pack readiness — structured preflight for surfaces
+// ---------------------------------------------------------------------------
+
+export type PackReadiness = {
+  has_pack: boolean;
+  pack_id: string | null;
+  pack_status: PackStatus | null;
+  is_stale: boolean;
+  stale_reason: string | null;
+  mirror_status: MirrorLinkStatus;
+  /** Whether the compile lane can proceed with this pack */
+  compile_ready: boolean;
+  /** Whether the execution lane can proceed with this pack */
+  execute_ready: boolean;
+  /** Blocking reason if not ready */
+  blocking_reason: string | null;
+};
+
+// ---------------------------------------------------------------------------
+// Stale-pack mismatch result
+// ---------------------------------------------------------------------------
+
+export type PackMismatchResult = {
+  is_mismatch: boolean;
+  kind: "none" | "spec_changed" | "contract_changed" | "slice_advanced" | "pack_missing";
+  detail: string;
+  /** Whether this mismatch should block dispatch */
+  should_block: boolean;
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function hashContent(content: string): string {
+  return createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+
+function generatePackId(): string {
+  return `pack-${randomBytes(8).toString("hex")}`;
+}
+
+// ---------------------------------------------------------------------------
+// Pack creation
+// ---------------------------------------------------------------------------
+
+export function createCanonicalProjectPack(input: {
+  project_id: string;
+  contract_id: string;
+  spec_markdown: string;
+  next_slice_id?: string | null;
+  creation_source: PackCreationSource;
+  materialization_mode: PackMaterializationMode;
+  repo_root?: string | null;
+  worktree_path?: string | null;
+  files: Array<{ path: string; content: string }>;
+  prior_version?: number;
+}): CanonicalProjectPack {
+  const fileRefs: PackFileRef[] = input.files.map(f => ({
+    path: f.path,
+    hash: hashContent(f.content),
+  }));
+
+  return {
+    pack_id: generatePackId(),
+    project_id: input.project_id,
+    version: (input.prior_version ?? 0) + 1,
+    status: "ready",
+    materialization_mode: input.materialization_mode,
+    creation_source: input.creation_source,
+    created_at: new Date().toISOString(),
+
+    contract_id: input.contract_id,
+    spec_hash: hashContent(input.spec_markdown),
+    next_slice_id: input.next_slice_id ?? null,
+
+    repo_root: input.repo_root ?? null,
+    worktree_path: input.worktree_path ?? null,
+
+    file_count: fileRefs.length,
+    files: fileRefs,
+
+    mirror: {
+      chatgpt_status: "not_attempted",
+      chatgpt_project_id: null,
+      last_mirror_at: null,
+      mirror_error: null,
+    },
+
+    stale_reason: null,
+    superseded_by: null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pack staleness
+// ---------------------------------------------------------------------------
+
+export function markPackStale(
+  pack: CanonicalProjectPack,
+  reason: string,
+  supersededBy?: string,
+): CanonicalProjectPack {
+  return {
+    ...pack,
+    status: "stale",
+    stale_reason: reason,
+    superseded_by: supersededBy ?? null,
+  };
+}
+
+export function markPackFailed(
+  pack: CanonicalProjectPack,
+  reason: string,
+): CanonicalProjectPack {
+  return {
+    ...pack,
+    status: "materialization_failed",
+    stale_reason: reason,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pack mismatch detection
+// ---------------------------------------------------------------------------
+
+export function detectPackMismatch(input: {
+  pack: CanonicalProjectPack | null;
+  current_spec_markdown: string;
+  current_contract_id: string;
+  current_next_slice_id: string | null;
+}): PackMismatchResult {
+  const { pack, current_spec_markdown, current_contract_id, current_next_slice_id } = input;
+
+  if (!pack) {
+    return {
+      is_mismatch: true,
+      kind: "pack_missing",
+      detail: "No canonical pack exists for this project.",
+      should_block: true,
+    };
+  }
+
+  if (pack.status === "stale" || pack.status === "materialization_failed") {
+    return {
+      is_mismatch: true,
+      kind: pack.stale_reason?.includes("contract") ? "contract_changed" : "spec_changed",
+      detail: `Pack ${pack.pack_id} is ${pack.status}: ${pack.stale_reason ?? "unknown reason"}.`,
+      should_block: pack.status === "materialization_failed",
+    };
+  }
+
+  const currentSpecHash = hashContent(current_spec_markdown);
+  if (currentSpecHash !== pack.spec_hash) {
+    return {
+      is_mismatch: true,
+      kind: "spec_changed",
+      detail: `Spec has changed since pack ${pack.pack_id} was created (pack hash: ${pack.spec_hash}, current: ${currentSpecHash}).`,
+      should_block: false,
+    };
+  }
+
+  if (current_contract_id !== pack.contract_id) {
+    return {
+      is_mismatch: true,
+      kind: "contract_changed",
+      detail: `Contract has changed since pack was created (pack: ${pack.contract_id}, current: ${current_contract_id}).`,
+      should_block: true,
+    };
+  }
+
+  if (current_next_slice_id && pack.next_slice_id && current_next_slice_id !== pack.next_slice_id) {
+    return {
+      is_mismatch: true,
+      kind: "slice_advanced",
+      detail: `Next slice has advanced since pack was created (pack: ${pack.next_slice_id}, current: ${current_next_slice_id}).`,
+      should_block: false,
+    };
+  }
+
+  return {
+    is_mismatch: false,
+    kind: "none",
+    detail: "Pack matches current canonical state.",
+    should_block: false,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pack readiness derivation
+// ---------------------------------------------------------------------------
+
+export function derivePackReadiness(input: {
+  pack: CanonicalProjectPack | null;
+  mismatch: PackMismatchResult;
+}): PackReadiness {
+  const { pack, mismatch } = input;
+
+  if (!pack) {
+    return {
+      has_pack: false,
+      pack_id: null,
+      pack_status: null,
+      is_stale: false,
+      stale_reason: null,
+      mirror_status: "not_attempted",
+      compile_ready: false,
+      execute_ready: false,
+      blocking_reason: "No canonical pack exists. Create or refresh the project pack first.",
+    };
+  }
+
+  if (pack.status === "materialization_failed") {
+    return {
+      has_pack: true,
+      pack_id: pack.pack_id,
+      pack_status: pack.status,
+      is_stale: true,
+      stale_reason: pack.stale_reason,
+      mirror_status: pack.mirror.chatgpt_status,
+      compile_ready: false,
+      execute_ready: false,
+      blocking_reason: `Pack materialization failed: ${pack.stale_reason ?? "unknown"}.`,
+    };
+  }
+
+  const isStale = pack.status === "stale" || mismatch.is_mismatch;
+  const staleReason = pack.stale_reason ?? (mismatch.is_mismatch ? mismatch.detail : null);
+
+  return {
+    has_pack: true,
+    pack_id: pack.pack_id,
+    pack_status: pack.status,
+    is_stale: isStale,
+    stale_reason: staleReason,
+    mirror_status: pack.mirror.chatgpt_status,
+    // Compile can proceed with a stale pack (it will produce updated output)
+    // but not with a failed pack
+    compile_ready: true,
+    // Execution should warn on stale but only block on mismatch.should_block
+    execute_ready: !mismatch.should_block,
+    blocking_reason: mismatch.should_block ? mismatch.detail : null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pack provenance resolution
+// ---------------------------------------------------------------------------
+
+export function resolvePackProvenance(
+  pack: CanonicalProjectPack | null,
+): PackProvenance | null {
+  if (!pack) return null;
+
+  return {
+    pack_id: pack.pack_id,
+    pack_version: pack.version,
+    pack_status_at_use: pack.status,
+    stale_at_use: pack.status === "stale",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Mirror/source-link — best-effort updates
+// ---------------------------------------------------------------------------
+
+export function updatePackMirror(
+  pack: CanonicalProjectPack,
+  update: Partial<PackMirror>,
+): CanonicalProjectPack {
+  return {
+    ...pack,
+    mirror: {
+      ...pack.mirror,
+      ...update,
+    },
+  };
+}
+
+/**
+ * Resolve mirror status honestly. If the mirror layer is unavailable
+ * or unsupported, that must not break the governed loop.
+ */
+export function resolveMirrorStatus(pack: CanonicalProjectPack): {
+  available: boolean;
+  status: MirrorLinkStatus;
+  honest_label: string;
+} {
+  const s = pack.mirror.chatgpt_status;
+
+  switch (s) {
+    case "linked":
+      return { available: true, status: s, honest_label: "ChatGPT project linked (best-effort mirror)" };
+    case "mirrored":
+      return { available: true, status: s, honest_label: "Files mirrored to ChatGPT project (best-effort)" };
+    case "failed":
+      return { available: false, status: s, honest_label: `Mirror failed: ${pack.mirror.mirror_error ?? "unknown"}` };
+    case "unavailable":
+      return { available: false, status: s, honest_label: "ChatGPT mirror not available for this project" };
+    case "not_attempted":
+    default:
+      return { available: false, status: s, honest_label: "Mirror not attempted" };
+  }
+}

package/node_modules/@switchboard/projections/node_modules/@switchboard/core/src/canonical.ts

@@ -0,0 +1,248 @@
+import type {
+  Condition,
+  ConditionType,
+  ProjectResource,
+  SynthesizedSeed,
+  ComplexityClassification,
+  CompilerSelection,
+} from "./types";
+import { projectResourceSchema } from "./types";
+
+// ---------------------------------------------------------------------------
+// Create a new canonical project resource from activation
+// ---------------------------------------------------------------------------
+
+export function createProjectResource(input: {
+  seed: SynthesizedSeed;
+  complexity: ComplexityClassification;
+  compiler: CompilerSelection;
+  constraints: string;
+}): ProjectResource {
+  const now = new Date().toISOString();
+  return projectResourceSchema.parse({
+    metadata: {
+      id: slugify(input.seed.title),
+      title: input.seed.title,
+      created_at: now,
+      generation: 1,
+    },
+    spec: {
+      problem: input.seed.problem,
+      target_user: input.seed.target_user,
+      v1_outcome: input.seed.v1_outcome,
+      non_goals: input.seed.non_goals,
+      constraints: input.constraints,
+      assumptions: [],
+      acceptance_criteria: [],
+      process_mode: input.complexity.mode,
+      compiler_intent: input.compiler.compiler_type,
+      task_type: input.seed.task_type,
+      first_build_slice: input.seed.first_build_slice,
+      approved_scope_changes: [],
+    },
+    status: {
+      phase: "activated",
+      observed_generation: 1,
+      activation: {
+        seed_confidence: input.seed.confidence,
+        complexity: input.complexity.verdict,
+        research_needed: false,
+      },
+    },
+    conditions: [
+      { type: "ProjectActivated", status: "True", reason: "Seed extracted and classified.", last_transition: now },
+    ],
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Spec mutations — only through controlled paths
+// ---------------------------------------------------------------------------
+
+export function updateSpec(
+  resource: ProjectResource,
+  changes: Partial<ProjectResource["spec"]>,
+): ProjectResource {
+  const now = new Date().toISOString();
+  return projectResourceSchema.parse({
+    ...resource,
+    metadata: {
+      ...resource.metadata,
+      generation: resource.metadata.generation + 1,
+    },
+    spec: { ...resource.spec, ...changes },
+    conditions: upsertCondition(resource.conditions, "ProjectActivated", "True", "Spec updated.", now),
+  });
+}
+
+export function approvesScopeChange(
+  resource: ProjectResource,
+  description: string,
+): ProjectResource {
+  return updateSpec(resource, {
+    approved_scope_changes: [...resource.spec.approved_scope_changes, description],
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Status mutations — only through controlled pathways
+// ---------------------------------------------------------------------------
+
+export function recordBriefAccepted(
+  resource: ProjectResource,
+  source: ProjectResource["status"]["brief"]["source"],
+  reconcileSummary: string,
+): ProjectResource {
+  const now = new Date().toISOString();
+  return projectResourceSchema.parse({
+    ...resource,
+    status: {
+      ...resource.status,
+      phase: "brief-accepted",
+      observed_generation: resource.metadata.generation,
+      brief: { source, accepted: true, reconcile_summary: reconcileSummary },
+    },
+    conditions: upsertCondition(
+      upsertCondition(resource.conditions, "BriefAccepted", "True", `Accepted via ${source ?? "unknown"}.`, now),
+      "BriefHeld", "False", "", now,
+    ),
+  });
+}
+
+export function recordBriefHeld(
+  resource: ProjectResource,
+  reason: string,
+): ProjectResource {
+  const now = new Date().toISOString();
+  return projectResourceSchema.parse({
+    ...resource,
+    status: {
+      ...resource.status,
+      phase: "brief-held",
+      observed_generation: resource.metadata.generation,
+      brief: { ...resource.status.brief, accepted: false, reconcile_summary: reason },
+    },
+    conditions: upsertCondition(
+      upsertCondition(resource.conditions, "BriefHeld", "True", reason, now),
+      "BriefAccepted", "False", "", now,
+    ),
+  });
+}
+
+export function recordExecutionStarted(
+  resource: ProjectResource,
+  surface: ProjectResource["status"]["execution"]["surface"],
+): ProjectResource {
+  const now = new Date().toISOString();
+  return projectResourceSchema.parse({
+    ...resource,
+    status: {
+      ...resource.status,
+      phase: "executing",
+      execution: { ...resource.status.execution, surface, started_at: now },
+    },
+    conditions: upsertCondition(resource.conditions, "Executing", "True", `Dispatched to ${surface ?? "unknown"}.`, now),
+  });
+}
+
+export function recordReturnReceived(
+  resource: ProjectResource,
+  returnStatus: string,
+  reconcileSummary: string,
+  promoted: boolean,
+): ProjectResource {
+  const now = new Date().toISOString();
+  const phase = promoted ? "updated" : "held-for-review";
+  const conditions = promoted
+    ? upsertCondition(
+        upsertCondition(resource.conditions, "ProjectUpdated", "True", `Return ${returnStatus}. ${reconcileSummary}`, now),
+        "Executing", "False", "", now,
+      )
+    : upsertCondition(
+        upsertCondition(resource.conditions, "HeldForReview", "True", reconcileSummary, now),
+        "Executing", "False", "", now,
+      );
+
+  return projectResourceSchema.parse({
+    ...resource,
+    status: {
+      ...resource.status,
+      phase,
+      observed_generation: resource.metadata.generation,
+      execution: { ...resource.status.execution, return_status: returnStatus, reconcile_summary: reconcileSummary },
+    },
+    conditions,
+  });
+}
+
+export function recordFeedbackPending(resource: ProjectResource): ProjectResource {
+  const now = new Date().toISOString();
+  return projectResourceSchema.parse({
+    ...resource,
+    status: { ...resource.status, phase: "feedback-pending" },
+    conditions: upsertCondition(resource.conditions, "FeedbackPending", "True", "Run completed. Feedback requested.", now),
+  });
+}
+
+export function recordClosed(resource: ProjectResource): ProjectResource {
+  const now = new Date().toISOString();
+  return projectResourceSchema.parse({
+    ...resource,
+    status: { ...resource.status, phase: "closed" },
+    conditions: upsertCondition(
+      upsertCondition(resource.conditions, "Closed", "True", "Run closed.", now),
+      "FeedbackPending", "False", "", now,
+    ),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Condition helpers
+// ---------------------------------------------------------------------------
+
+function upsertCondition(
+  conditions: Condition[],
+  type: ConditionType,
+  status: Condition["status"],
+  reason: string,
+  timestamp: string,
+): Condition[] {
+  const filtered = conditions.filter((c) => c.type !== type);
+  return [...filtered, { type, status, reason, last_transition: timestamp }];
+}
+
+export function getCondition(resource: ProjectResource, type: ConditionType): Condition | undefined {
+  return resource.conditions.find((c) => c.type === type);
+}
+
+export function isConditionTrue(resource: ProjectResource, type: ConditionType): boolean {
+  return getCondition(resource, type)?.status === "True";
+}
+
+export function activeConditions(resource: ProjectResource): Condition[] {
+  return resource.conditions.filter((c) => c.status === "True");
+}
+
+// ---------------------------------------------------------------------------
+// Generation checks
+// ---------------------------------------------------------------------------
+
+export function isStatusCurrent(resource: ProjectResource): boolean {
+  return resource.status.observed_generation >= resource.metadata.generation;
+}
+
+export function isStatusStale(resource: ProjectResource): boolean {
+  return resource.status.observed_generation < resource.metadata.generation;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 50);
+}