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

package/node_modules/@switchboard/projections/node_modules/@switchboard/core/src/handoff-visibility.ts

@@ -0,0 +1,204 @@
+import type {
+  DispatchRecord,
+  HandoffRecord,
+  HandoffVisibility,
+  LineageStatus,
+  ProjectContract,
+  ReturnReport,
+  RoutingResult,
+} from "./types";
+import { SURFACE_LABELS, dispatchRecordSchema, handoffVisibilitySchema } from "./types";
+import { randomBytes } from "crypto";
+
+// ---------------------------------------------------------------------------
+// System detection from scope text
+// ---------------------------------------------------------------------------
+
+const SYSTEM_HINTS: [RegExp, string][] = [
+  [/\bsupabase\b/i, "Supabase"],
+  [/\bpostgres\b|\bsql\b|\bdatabase\b|\btable\b/i, "Database"],
+  [/\bauth\b/i, "Auth"],
+  [/\bapi\b|\bendpoint\b/i, "API"],
+  [/\bmiddleware\b/i, "Middleware"],
+  [/\bui\b|\bcomponent\b|\bpage\b|\blayout\b/i, "UI"],
+  [/\bcli\b/i, "CLI"],
+  [/\bstorage\b|\bupload\b/i, "Storage"],
+  [/\btest\b|\bspec\b/i, "Tests"],
+  [/\bredis\b/i, "Redis"],
+  [/\bai\b|\bllm\b|\bclaude\b/i, "AI / LLM"],
+];
+
+function detectSystems(text: string): string[] {
+  const systems = new Set<string>();
+  for (const [pattern, label] of SYSTEM_HINTS) {
+    if (pattern.test(text)) systems.add(label);
+  }
+  return [...systems];
+}
+
+// ---------------------------------------------------------------------------
+// User-facing routing reason
+// ---------------------------------------------------------------------------
+
+function humanizeRoutingReason(
+  surface: string,
+  route: RoutingResult | null,
+): string {
+  const label = SURFACE_LABELS[surface as keyof typeof SURFACE_LABELS] ?? surface;
+
+  if (route?.rationale) {
+    // Clean up raw rationale into user-facing language
+    const raw = route.rationale;
+    if (/governance/i.test(raw)) {
+      return `Routed to ${label} for scope narrowing — project classified as needing governance.`;
+    }
+    if (/implementation/i.test(raw) || /build|scaffold|wire/i.test(raw)) {
+      return `Routed to ${label} for implementation — task is code-bound with repo context.`;
+    }
+    if (/research|clarif/i.test(raw)) {
+      return `Routed to ${label} for research and clarification before implementation.`;
+    }
+    if (/ui|visual|taste|polish/i.test(raw)) {
+      return `Routed to ${label} for UI/visual work requiring interactive feedback.`;
+    }
+    return `Routed to ${label}: ${raw.length > 80 ? raw.slice(0, 77) + "…" : raw}`;
+  }
+
+  // Fallback based on surface
+  if (surface === "claude-code") {
+    return `Routed to ${label} for bounded code execution in the repository.`;
+  }
+  if (surface === "chatgpt") {
+    return `Routed to ${label} for research, shaping, or scope narrowing.`;
+  }
+  if (surface === "cursor") {
+    return `Routed to ${label} for interactive UI/visual development.`;
+  }
+  return `Routed to ${label}.`;
+}
+
+// ---------------------------------------------------------------------------
+// Derive handoff visibility from existing objects
+// ---------------------------------------------------------------------------
+
+export function deriveHandoffVisibility(input: {
+  handoff: HandoffRecord;
+  contract: ProjectContract;
+  route: RoutingResult | null;
+}): HandoffVisibility {
+  const { handoff, contract, route } = input;
+  const surface = handoff.surface;
+  const surfaceLabel = SURFACE_LABELS[surface as keyof typeof SURFACE_LABELS] ?? surface;
+
+  // Combine scope text for system detection
+  const scopeText = [
+    handoff.objective,
+    ...handoff.included_scope,
+    ...handoff.excluded_scope,
+    ...handoff.loop.scope_in,
+  ].join(" ");
+
+  const systems_in_scope = detectSystems(scopeText);
+
+  const repo_binding = contract.repo_status === "repo-present"
+    ? "Bound to existing repository."
+    : "No repository — will be created on first execution.";
+
+  const dispatch = {
+    goal: handoff.objective,
+    protected_boundaries: contract.non_goals,
+    expected_outputs: handoff.loop.expected_artifacts,
+    acceptance_basis: handoff.loop.success_criteria,
+  };
+
+  return handoffVisibilitySchema.parse({
+    surface,
+    surface_label: surfaceLabel,
+    routing_reason: humanizeRoutingReason(surface, route),
+    handoff_id: handoff.handoff_id,
+    contract_title: contract.title,
+    repo_binding,
+    systems_in_scope,
+    dispatched_at: handoff.launched_at ?? new Date().toISOString(),
+    dispatch,
+    return_summary: "",
+    return_status: "",
+    return_linked: false,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Link a return to the visibility object
+// ---------------------------------------------------------------------------
+
+export function linkReturnToVisibility(
+  visibility: HandoffVisibility,
+  ret: ReturnReport,
+): HandoffVisibility {
+  return handoffVisibilitySchema.parse({
+    ...visibility,
+    return_summary: ret.summary,
+    return_status: ret.status,
+    return_linked: true,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch record — full lineage from contract → dispatch → return → delta
+// ---------------------------------------------------------------------------
+
+export function buildDispatchRecord(input: {
+  handoff: HandoffRecord;
+  contract: ProjectContract;
+  route: RoutingResult | null;
+}): DispatchRecord {
+  const { handoff, contract, route } = input;
+  const surface = handoff.surface;
+  const surfaceLabel = SURFACE_LABELS[surface as keyof typeof SURFACE_LABELS] ?? surface;
+  const scopeText = [handoff.objective, ...handoff.included_scope, ...handoff.loop.scope_in].join(" ");
+
+  return dispatchRecordSchema.parse({
+    dispatch_id: `dsp-${randomBytes(8).toString("hex")}`,
+    project_id: contract.project_id,
+    contract_id: contract.project_id,
+    provider_target: surface,
+    provider_label: surfaceLabel,
+    dispatch_reason: humanizeRoutingReason(surface, route),
+    route_surface: surface,
+    route_fallback: route?.fallback_surface,
+    route_rationale: route?.rationale ?? "",
+    packet_summary: `${handoff.objective} — bounded by ${contract.non_goals.length} protected boundaries, targeting ${surfaceLabel}.`,
+    bounded_by: contract.non_goals,
+    systems_in_play: detectSystems(scopeText),
+    dispatched_at: handoff.launched_at ?? new Date().toISOString(),
+  });
+}
+
+export function linkReturnToDispatch(
+  record: DispatchRecord,
+  ret: ReturnReport,
+  lineage: LineageStatus = "return-received",
+): DispatchRecord {
+  return dispatchRecordSchema.parse({
+    ...record,
+    return_id: ret.handoff_id,
+    return_received_at: new Date().toISOString(),
+    return_status: ret.status,
+    return_summary: ret.summary,
+    lineage_status: lineage,
+  });
+}
+
+export function linkDeltaToDispatch(
+  record: DispatchRecord,
+  deltaId: string,
+  nextSliceId: string,
+  lineage: LineageStatus = "absorbed",
+): DispatchRecord {
+  return dispatchRecordSchema.parse({
+    ...record,
+    delta_id: deltaId,
+    next_slice_id: nextSliceId,
+    lineage_status: lineage,
+  });
+}

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

@@ -0,0 +1,87 @@
+import { compileLoopContract } from "./loop-compiler";
+import { validateLoopReadiness } from "./loop-validator";
+import { chooseRecommendedSurface } from "./router";
+import type { HandoffRecord, LaunchReadiness, LoopContract, ProjectContract, ReturnReport, RoutingResult, WorkingState } from "./types";
+import { handoffRecordSchema, returnReportSchema } from "./types";
+
+type HandoffDraftInput = {
+  contract: ProjectContract;
+  current: WorkingState;
+  route?: RoutingResult;
+  objective?: string;
+  scope_in?: string[];
+  scope_out?: string[];
+  done_when?: string[];
+  success_criteria?: string[];
+  verify_with?: string[];
+  loop?: LoopContract;
+  readiness?: LaunchReadiness;
+  handoff_id?: string;
+  launched_at?: string;
+};
+
+function timestamp(now = new Date()) {
+  const iso = now.toISOString().replace(/[-:]/g, "");
+  return `${iso.slice(0, 8)}-${iso.slice(9, 15)}`;
+}
+
+export function createHandoffDraft(input: HandoffDraftInput): HandoffRecord {
+  const route =
+    input.route ??
+    chooseRecommendedSurface({
+      repo_present: input.contract.repo_status === "repo-present",
+      task: input.current.next_objective,
+      last_return_status: input.current.last_return_status === "not-started" ? undefined : input.current.last_return_status,
+      last_return_reason: input.current.latest_blockers.join(" "),
+    });
+
+  const loop =
+    input.loop ??
+    compileLoopContract({
+      contract: input.contract,
+      current: input.current,
+      route,
+      ...(input.objective ? { objective: input.objective } : {}),
+      ...(input.scope_in ? { scope_in: input.scope_in } : {}),
+      ...(input.scope_out ? { scope_out: input.scope_out } : {}),
+      ...(input.done_when ? { done_when: input.done_when } : {}),
+      ...(input.success_criteria ? { success_criteria: input.success_criteria } : {}),
+      ...(input.verify_with ? { verify_with: input.verify_with } : {}),
+    });
+  const readiness = input.readiness ?? validateLoopReadiness(loop);
+
+  return handoffRecordSchema.parse({
+    handoff_id: input.handoff_id ?? `handoff-${timestamp()}`,
+    surface: route.primary_recommendation,
+    objective: loop.objective,
+    included_scope: loop.scope_in,
+    excluded_scope: loop.scope_out,
+    done_when: loop.done_when,
+    return_condition: loop.return_when,
+    loop,
+    readiness,
+    bundle_version: "SBX-v1",
+    launched_at: input.launched_at,
+  });
+}
+
+export function createReturnTemplate(handoff: HandoffRecord): ReturnReport {
+  return returnReportSchema.parse({
+    handoff_id: handoff.handoff_id,
+    surface_used: handoff.surface,
+    objective_attempted: handoff.loop.objective,
+    status: "partial",
+    objective_met: "partial",
+    done_when_met: "partial",
+    summary: "Replace this summary before ingesting.",
+    changed_files: [],
+    decisions_made: [],
+    blockers: [],
+    escalations: [],
+    evidence: [],
+    success_criteria_met: [],
+    verification_run: [],
+    artifacts_created: [],
+    recommended_next_step: "Describe the next narrow step after this handoff.",
+  });
+}

package/node_modules/@switchboard/projections/node_modules/@switchboard/core/src/harness-compiler.ts

@@ -0,0 +1,246 @@
+/**
+ * Route-Native Harness Compiler
+ *
+ * Compiles an ExecutionHarness from model-neutral canonical state.
+ *
+ * This is the compilation boundary between Switchboard's surface-agnostic
+ * governance (contract, working state, loop contract) and the route-native
+ * execution shape each surface receives.
+ *
+ * Before this module existed, route-native decisions were scattered across:
+ *   - loop-compiler.ts    (surface-specific done_when / verify_with defaults)
+ *   - dispatch-formatter.ts  (packet shape switching)
+ *   - surface-profiles.ts    (capability lookup)
+ *   - surface-playbooks.ts   (tactical notes lookup)
+ *   - execute/route.ts       (surface-specific dispatch branches)
+ *
+ * The harness compiler consolidates those into a single compiled object
+ * so downstream code (dispatch, execution, receipt) can consume one
+ * route-native bundle instead of re-deriving surface awareness at each step.
+ *
+ * Canonical contract stays model-neutral. The harness is the first place
+ * where route-native decisions are committed.
+ */
+
+import type {
+  BudgetConstraint,
+  ContextBindings,
+  DispatchMode,
+  ExecutionHarness,
+  HarnessGovernance,
+  LoopContract,
+  ProjectContract,
+  ReturnExpectation,
+  RoutingResult,
+  Surface,
+  SurfaceProfile,
+} from "./types";
+import { executionHarnessSchema } from "./types";
+import { getSurfaceProfile } from "./surface-profiles";
+import { getSurfacePlaybook } from "./surface-playbooks";
+
+// ---------------------------------------------------------------------------
+// Compiler input
+// ---------------------------------------------------------------------------
+
+export interface HarnessCompilerInput {
+  /** Unique dispatch identifier for this harness. */
+  dispatch_id: string;
+  /** Model-neutral project contract. */
+  contract: ProjectContract;
+  /** Already-compiled loop contract (scope, done_when, etc.). */
+  loop: LoopContract;
+  /** Routing decision (surface + rationale). */
+  route: RoutingResult;
+  /** Optional working directory for repo-bound surfaces. */
+  working_directory?: string;
+  /** Optional model hint for API surfaces. */
+  model_hint?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Deterministic harness ID
+// ---------------------------------------------------------------------------
+
+function harnessId(dispatchId: string, surface: Surface): string {
+  return `harness-${surface}-${dispatchId.replace(/^dsp-/, "")}`;
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch mode derivation
+// ---------------------------------------------------------------------------
+
+function deriveDispatchMode(profile: SurfaceProfile): DispatchMode {
+  if (!profile.capabilities.can_dispatch_programmatically) return "manual";
+  if (profile.receipt_model === "async_callback") return "async";
+  return "auto";
+}
+
+// ---------------------------------------------------------------------------
+// Return expectation compilation
+// ---------------------------------------------------------------------------
+
+const STRUCTURED_RETURN_FIELDS = [
+  "status",
+  "objective_met",
+  "done_when_met",
+  "summary",
+  "changed_files",
+  "evidence",
+  "recommended_next_step",
+] as const;
+
+const HUMAN_RETURN_FIELDS = [
+  "status",
+  "summary",
+  "recommended_next_step",
+] as const;
+
+function compileReturnExpectation(profile: SurfaceProfile): ReturnExpectation {
+  const structured = profile.capabilities.can_return_structured;
+  return {
+    structured,
+    required_fields: structured
+      ? [...STRUCTURED_RETURN_FIELDS]
+      : [...HUMAN_RETURN_FIELDS],
+    human_mediated: profile.receipt_model === "human_return",
+    async_callback: profile.receipt_model === "async_callback",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Budget constraint compilation
+// ---------------------------------------------------------------------------
+
+function compileBudgetConstraint(
+  profile: SurfaceProfile,
+  loop: LoopContract,
+): BudgetConstraint {
+  // Verification is expected for structured-return surfaces.
+  // Manual/human-return surfaces cannot reliably produce verification evidence.
+  const verificationExpected = profile.capabilities.can_return_structured;
+
+  return {
+    correction_caution_threshold: 0.2,
+    correction_over_budget_threshold: 0.5,
+    verification_expected: verificationExpected,
+    verification_notes: loop.verify_with,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Context bindings compilation
+// ---------------------------------------------------------------------------
+
+function compileContextBindings(
+  input: HarnessCompilerInput,
+  profile: SurfaceProfile,
+): ContextBindings {
+  return {
+    working_directory: profile.capabilities.supports_working_directory
+      ? (input.working_directory ?? null)
+      : null,
+    model_hint: input.model_hint ?? "",
+    async_return: profile.receipt_model === "async_callback",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Governance envelope extraction
+// ---------------------------------------------------------------------------
+
+function extractGovernanceBinding(
+  contract: ProjectContract,
+  loop: LoopContract,
+): HarnessGovernance {
+  return {
+    contract_id: contract.project_id,
+    contract_title: contract.title,
+    non_goals: contract.non_goals,
+    must_not_widen: contract.task_clauses.must_not_widen,
+    protected_scope_out: loop.scope_out,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Core compiler
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a route-native ExecutionHarness from model-neutral canonical inputs.
+ *
+ * This is the single compilation boundary. After this call, the harness
+ * contains everything the dispatch layer and receiving surface need.
+ *
+ * @throws if the surface has no registered profile
+ */
+export function compileExecutionHarness(
+  input: HarnessCompilerInput,
+): ExecutionHarness {
+  const surface = input.route.primary_recommendation;
+  const profile = getSurfaceProfile(surface);
+
+  if (!profile) {
+    throw new Error(
+      `Cannot compile harness: no surface profile for "${surface}".`,
+    );
+  }
+
+  const playbook = getSurfacePlaybook(surface);
+
+  const raw = {
+    harness_id: harnessId(input.dispatch_id, surface),
+    dispatch_id: input.dispatch_id,
+    compiled_at: new Date().toISOString(),
+
+    // Route identity
+    surface,
+    surface_class: profile.surface_class,
+    dispatch_mode: deriveDispatchMode(profile),
+    receipt_model: profile.receipt_model,
+    packet_format: profile.packet_format,
+    execution_shape: input.loop.execution_shape,
+
+    // Compiled execution scope (straight from the loop contract)
+    objective: input.loop.objective,
+    scope_in: input.loop.scope_in,
+    scope_out: input.loop.scope_out,
+    done_when: input.loop.done_when,
+    success_criteria: input.loop.success_criteria,
+    verify_with: input.loop.verify_with,
+    return_when: input.loop.return_when,
+    blocker_escalation: input.loop.blocker_escalation,
+    fallback_surface: input.loop.fallback_surface,
+
+    // Route-native sections
+    playbook_notes: playbook.notes,
+    return_expectation: compileReturnExpectation(profile),
+    budget_constraint: compileBudgetConstraint(profile, input.loop),
+    context_bindings: compileContextBindings(input, profile),
+    governance_envelope: extractGovernanceBinding(
+      input.contract,
+      input.loop,
+    ),
+  };
+
+  return executionHarnessSchema.parse(raw);
+}
+
+// ---------------------------------------------------------------------------
+// Convenience queries on compiled harnesses
+// ---------------------------------------------------------------------------
+
+/** Whether the harness can be dispatched without human intervention. */
+export function isAutoDispatchable(harness: ExecutionHarness): boolean {
+  return harness.dispatch_mode === "auto";
+}
+
+/** Whether the harness expects a structured return. */
+export function expectsStructuredReturn(harness: ExecutionHarness): boolean {
+  return harness.return_expectation.structured;
+}
+
+/** Whether the harness expects verification evidence. */
+export function expectsVerification(harness: ExecutionHarness): boolean {
+  return harness.budget_constraint.verification_expected;
+}

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

@@ -0,0 +1,57 @@
+export * from "./types";
+export * from "./router";
+export * from "./compiler";
+export * from "./classifier";
+export * from "./compiler-adapter";
+export * from "./loop-compiler";
+export * from "./loop-validator";
+export * from "./surface-playbooks";
+export * from "./handoff";
+export * from "./ingest";
+export * from "./synthesis-provider";
+export * from "./reconcile";
+export * from "./dossier";
+export * from "./provider-registry";
+export * from "./canonical";
+export * from "./ledger";
+export * from "./activation";
+export * from "./handoff-v2";
+export * from "./routing-v2";
+export * from "./reconcile-v2";
+export * from "./gates";
+export * from "./gate-state";
+export * from "./canonical-delta";
+export * from "./project-charter";
+export * from "./handoff-visibility";
+export * from "./reconcile-matrix";
+export * from "./governance-envelope";
+export * from "./packet-integrity";
+export * from "./pressure-assessment";
+export * from "./run-snapshot";
+export * from "./lock-readiness";
+export * from "./dispatch-receipt";
+export * from "./codex-audit";
+export * from "./product-objects";
+export * from "./surface-profiles";
+export * from "./build-map";
+export * from "./claude-executor";
+export * from "./codex-executor";
+export * from "./preflight";
+export * from "./launch-block-payload";
+export * from "./parallel-conflict";
+export * from "./proof-capture";
+export * from "./live-event";
+export * from "./live-event-bus";
+export * from "./return-normalizer";
+export * from "./audited-receipt";
+export * from "./dispatch-formatter";
+export * from "./evaluation-lane";
+export * from "./eval-scope";
+export * from "./execution-trace";
+export * from "./budget-ledger";
+export * from "./overflow-manifest";
+export * from "./claim-spread";
+export * from "./harness-compiler";
+export * from "./meta-harness";
+export * from "./receipt-v2";
+export * from "./canonical-pack";