gswd 0.1.0

package/lib/bootstrap.ts

@@ -0,0 +1,617 @@
+/**
+ * GSWD Bootstrap Module — Pipeline orchestrator, policy engine, resume gate
+ *
+ * Contains:
+ * - runBootstrap(): async orchestrator that wires imagine -> specify -> audit -> compile
+ * - Types: BootstrapOptions, BootstrapResult, BootstrapStage, PolicyCheckInput, PolicyCheckResult
+ * - Policy engine: checkPolicy() with 4 detection functions
+ * - Resume gate: validateStageArtifacts(), shouldSkipStage()
+ * - Interrupt handler: handleInterrupt()
+ * - Auto decision display: renderAutoDecisionSummary()
+ * - Stage artifacts map: STAGE_ARTIFACTS
+ *
+ * Schema: GSWD_SPEC.md Section 8.1, 10.1-10.4
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { initState, readState, writeState, writeCheckpoint } from './state.js';
+import { getGswdConfig } from './config.js';
+import type { GswdConfig } from './config.js';
+import { renderBanner, renderCheckpoint, renderNextUp } from './render.js';
+import type { AutoDecision } from './imagine-synthesis.js';
+import { runImagine } from './imagine.js';
+import type { ImagineResult } from './imagine.js';
+import { runSpecify } from './specify.js';
+import type { SpecifyResult } from './specify.js';
+import { runAuditWorkflow } from './audit.js';
+import type { AuditWorkflowResult } from './audit.js';
+import { runCompileWorkflow } from './compile.js';
+import type { CompileWorkflowResult } from './compile.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface BootstrapOptions {
+  ideaFilePath?: string;
+  auto: boolean;
+  resume?: boolean;
+  skipResearch?: boolean;
+  policy?: 'strict' | 'balanced' | 'aggressive';
+  planningDir?: string;
+  configPath?: string;
+  spawnFn?: unknown; // Agent Task() wrapper (injectable for testing)
+}
+
+export type BootstrapStage = 'imagine' | 'specify' | 'audit' | 'compile';
+
+export interface BootstrapResult {
+  status: 'done' | 'failed' | 'interrupted';
+  stagesCompleted: BootstrapStage[];
+  artifactsWritten: string[];
+  autoDecisions: AutoDecision[];
+  interruptReasons: string[];
+  autoFixCycles: number;
+  error?: string;
+}
+
+export interface PolicyCheckInput {
+  config: GswdConfig;
+  integrationsContent?: string;
+  decisionsContent?: string;
+  nfrContent?: string;
+}
+
+export interface PolicyCheckResult {
+  shouldInterrupt: boolean;
+  reasons: string[];
+}
+
+// ─── Stage Artifacts ─────────────────────────────────────────────────────────
+
+/**
+ * Required artifact filenames per stage.
+ * Used by validateStageArtifacts() and shouldSkipStage().
+ */
+export const STAGE_ARTIFACTS: Record<BootstrapStage, string[]> = {
+  imagine: ['IMAGINE.md', 'ICP.md', 'GTM.md', 'COMPETITION.md', 'DECISIONS.md'],
+  specify: ['SPEC.md', 'JOURNEYS.md', 'NFR.md', 'ARCHITECTURE.md', 'INTEGRATIONS.md'],
+  audit: ['AUDIT.md'],
+  compile: ['PROJECT.md', 'REQUIREMENTS.md', 'ROADMAP.md', 'STATE.md'],
+};
+
+// ─── Policy Engine — Detection Functions ─────────────────────────────────────
+
+/**
+ * Detect integrations with a positive monthly cost.
+ * Parses dollar amounts from integration sections (### I-NNN headings).
+ * Returns array of integration IDs with cost > $0.
+ */
+function detectPaidIntegrations(integrationsContent: string): string[] {
+  const paidIds: string[] = [];
+  // Match integration section headings: ### I-001: Name or ## I-001: Name
+  const intRegex = /^#{2,3}\s+(I-\d{1,4})[:\s]/gm;
+  const positions: { id: string; start: number }[] = [];
+
+  let match: RegExpExecArray | null;
+  while ((match = intRegex.exec(integrationsContent)) !== null) {
+    positions.push({ id: match[1], start: match.index });
+  }
+
+  for (let i = 0; i < positions.length; i++) {
+    const end = i + 1 < positions.length ? positions[i + 1].start : integrationsContent.length;
+    const section = integrationsContent.slice(positions[i].start, end);
+    // Look for dollar amounts: $50, $25.99, 50 USD/month
+    const costMatch = section.match(/\$(\d+(?:\.\d+)?)|(\d+(?:\.\d+)?)\s*(?:USD|usd)\/month/);
+    if (costMatch) {
+      const amount = parseFloat(costMatch[1] ?? costMatch[2] ?? '0');
+      if (amount > 0) {
+        paidIds.push(positions[i].id);
+      }
+    }
+  }
+
+  return paidIds;
+}
+
+/**
+ * Detect integrations that require credentials (API keys, OAuth secrets, etc.).
+ * Returns array of { id, requirement } objects.
+ */
+function detectCredentialRequirements(integrationsContent: string): { id: string; requirement: string }[] {
+  const credentials: { id: string; requirement: string }[] = [];
+  const intRegex = /^#{2,3}\s+(I-\d{1,4})[:\s]/gm;
+  const positions: { id: string; start: number }[] = [];
+
+  let match: RegExpExecArray | null;
+  while ((match = intRegex.exec(integrationsContent)) !== null) {
+    positions.push({ id: match[1], start: match.index });
+  }
+
+  for (let i = 0; i < positions.length; i++) {
+    const end = i + 1 < positions.length ? positions[i + 1].start : integrationsContent.length;
+    const section = integrationsContent.slice(positions[i].start, end);
+    // Look for credential-related patterns
+    const credPatterns = [
+      /\b(?:API\s*key)\s*required\b/i,
+      /\bOAuth\s*(?:secret|token|key)\b/i,
+      /\bcredentials?\s*(?:required|needed)\b/i,
+      /\bsecret\s*(?:key|required)\b/i,
+    ];
+    for (const pattern of credPatterns) {
+      const credMatch = section.match(pattern);
+      if (credMatch) {
+        credentials.push({ id: positions[i].id, requirement: credMatch[0] });
+        break; // One match per integration is enough
+      }
+    }
+  }
+
+  return credentials;
+}
+
+/**
+ * Detect contradictions between decisions and integrations.
+ * E.g., "no accounts" decision + Stripe integration = conflict.
+ */
+function detectConflicts(decisionsContent: string, integrationsContent: string): string[] {
+  const conflicts: string[] = [];
+
+  const noAccountsDecision = /\bno\s+accounts?\b/i.test(decisionsContent) ||
+                              /\bno\s+auth\b/i.test(decisionsContent);
+  const hasStripe = /stripe/i.test(integrationsContent);
+  const hasPayments = /payment/i.test(integrationsContent);
+
+  if (noAccountsDecision && (hasStripe || hasPayments)) {
+    conflicts.push(
+      'Conflicting requirements: decision says "no accounts" but integrations include payment processing (requires accounts)'
+    );
+  }
+
+  return conflicts;
+}
+
+/**
+ * Detect security posture mismatches between NFR content and config.
+ * E.g., HIPAA/SOC2/PCI requirements without explicit config approval.
+ */
+function detectSecurityPosture(nfrContent: string, config: GswdConfig): string[] {
+  const flags: string[] = [];
+  const securityPatterns: { pattern: RegExp; label: string }[] = [
+    { pattern: /\bHIPAA\b/i, label: 'HIPAA' },
+    { pattern: /\bSOC\s*2\b/i, label: 'SOC2' },
+    { pattern: /\bPCI[\s-]*DSS\b/i, label: 'PCI-DSS' },
+    { pattern: /\bGDPR\b/i, label: 'GDPR' },
+  ];
+
+  for (const { pattern, label } of securityPatterns) {
+    if (pattern.test(nfrContent)) {
+      // Check if config has explicit security approval
+      // For now, config has no explicit security_approvals field,
+      // so any compliance requirement triggers an interrupt
+      flags.push(
+        `Security posture mismatch: ${label} compliance referenced in NFR but not explicitly approved in config — requires human review`
+      );
+    }
+  }
+
+  return flags;
+}
+
+// ─── Policy Engine — Main Function ───────────────────────────────────────────
+
+/**
+ * Check policy violations. Returns whether auto mode should be interrupted
+ * and the specific reasons.
+ *
+ * Checks:
+ * 1. Paid integrations not pre-approved
+ * 2. Credential requirements
+ * 3. Conflicting requirements (decisions vs integrations)
+ * 4. Security posture mismatches (NFR vs config)
+ */
+export function checkPolicy(input: PolicyCheckInput): PolicyCheckResult {
+  const reasons: string[] = [];
+  const { config } = input;
+
+  // 1. Paid integrations not pre-approved
+  if (input.integrationsContent) {
+    const paidIntegrations = detectPaidIntegrations(input.integrationsContent);
+    const preapproved = new Set(config.auto.preapproved_integrations);
+    for (const intId of paidIntegrations) {
+      if (!preapproved.has(intId) && !config.auto.allow_paid_integrations_under_budget) {
+        reasons.push(`Paid integration ${intId} requires pre-approval (not in preapproved_integrations)`);
+      }
+    }
+  }
+
+  // 2. Credentials that cannot be inferred
+  if (input.integrationsContent) {
+    const credentialRequired = detectCredentialRequirements(input.integrationsContent);
+    for (const cred of credentialRequired) {
+      reasons.push(`Integration ${cred.id} requires credentials: ${cred.requirement}`);
+    }
+  }
+
+  // 3. Conflicting requirements
+  if (input.decisionsContent && input.integrationsContent) {
+    const conflicts = detectConflicts(input.decisionsContent, input.integrationsContent);
+    reasons.push(...conflicts);
+  }
+
+  // 4. Security posture mismatches
+  if (input.nfrContent) {
+    const securityFlags = detectSecurityPosture(input.nfrContent, config);
+    reasons.push(...securityFlags);
+  }
+
+  return { shouldInterrupt: reasons.length > 0, reasons };
+}
+
+// ─── Resume Gate ─────────────────────────────────────────────────────────────
+
+/**
+ * Validate that all expected artifacts for a stage exist on disk and are non-empty.
+ * Returns { complete, missing } where missing lists filenames not found or empty.
+ */
+export function validateStageArtifacts(
+  planningDir: string,
+  stage: BootstrapStage
+): { complete: boolean; missing: string[] } {
+  const required = STAGE_ARTIFACTS[stage] ?? [];
+  const missing: string[] = [];
+
+  for (const filename of required) {
+    const filepath = path.join(planningDir, filename);
+    if (!fs.existsSync(filepath)) {
+      missing.push(filename);
+    } else {
+      // Check non-zero bytes (Pitfall 2: empty files)
+      try {
+        const stat = fs.statSync(filepath);
+        if (stat.size === 0) {
+          missing.push(filename);
+        }
+      } catch {
+        missing.push(filename);
+      }
+    }
+  }
+
+  return { complete: missing.length === 0, missing };
+}
+
+/**
+ * Determine if a stage can be skipped during resume.
+ * Only skips if: resume=true AND stage is done/pass AND all artifacts are present.
+ */
+export function shouldSkipStage(
+  stage: BootstrapStage,
+  state: { stage_status: Record<string, string> },
+  planningDir: string,
+  resume: boolean
+): boolean {
+  if (!resume) return false;
+
+  const stageStatus = state.stage_status[stage];
+  const isDone = stageStatus === 'done' || stageStatus === 'pass';
+  if (!isDone) return false;
+
+  // Validate artifacts before trusting checkpoint (RESM-03)
+  const { complete } = validateStageArtifacts(planningDir, stage);
+  return complete;
+}
+
+// ─── Interrupt Handler ───────────────────────────────────────────────────────
+
+/**
+ * Handle a policy interrupt: write reasons to STATE.json, render checkpoint, return result.
+ * MUST write to STATE.json BEFORE rendering (Pitfall 6).
+ */
+export function handleInterrupt(
+  reasons: string[],
+  statePath: string,
+  stagesCompleted: BootstrapStage[],
+  allArtifacts: string[],
+  allAutoDecisions: AutoDecision[],
+  autoFixCycles: number,
+): BootstrapResult {
+  // Step 1: Write to STATE.json FIRST
+  const state = readState(statePath);
+  if (state) {
+    if (!state.auto.interrupt_reasons) {
+      state.auto.interrupt_reasons = [];
+    }
+    state.auto.interrupt_reasons = [...state.auto.interrupt_reasons, ...reasons];
+    writeState(statePath, state);
+  }
+
+  // Step 2: Render checkpoint box
+  const box = renderCheckpoint(
+    'Auto Mode Interrupted',
+    'Bootstrap cannot continue automatically. Resolve:',
+    reasons.map(r => r.length > 50 ? r.slice(0, 47) + '...' : r),
+    'Resolve issues above, then re-run bootstrap'
+  );
+  console.log(box);
+
+  // Step 3: Return result
+  return {
+    status: 'interrupted',
+    stagesCompleted: [...stagesCompleted],
+    artifactsWritten: [...allArtifacts],
+    autoDecisions: [...allAutoDecisions],
+    interruptReasons: [...reasons],
+    autoFixCycles,
+  };
+}
+
+// ─── Auto Decision Summary ───────────────────────────────────────────────────
+
+/**
+ * Render a human-readable summary of auto-mode decisions.
+ * Returns empty string if no decisions.
+ */
+export function renderAutoDecisionSummary(decisions: AutoDecision[]): string {
+  if (decisions.length === 0) return '';
+
+  const lines = ['Auto-mode decisions:'];
+  for (const d of decisions) {
+    lines.push(`  \u26A1 ${d.type}: ${d.chosen}`);
+    lines.push(`     Why: ${d.rationale}`);
+    lines.push(`     Recorded in: DECISIONS.md + STATE.json auto.decisions[]`);
+  }
+  return lines.join('\n');
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Try to read a file, returning undefined if it doesn't exist.
+ */
+function tryReadFile(filePath: string): string | undefined {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Derive a project slug from an idea file path or a fallback.
+ */
+function deriveProjectSlug(input: string): string {
+  const base = path.basename(input, path.extname(input));
+  return base.replace(/[^a-z0-9-]/gi, '-').toLowerCase() || 'project';
+}
+
+// ─── Bootstrap Orchestrator ──────────────────────────────────────────────────
+
+/**
+ * Run the full bootstrap pipeline: init -> imagine -> specify -> audit -> compile.
+ *
+ * Implements GSWD_SPEC Section 8.1:
+ * - Auto mode threads autoMode/auto/autoFix to each stage
+ * - Resume mode skips completed stages with valid artifacts
+ * - Policy checks fire after imagine and after specify
+ * - Audit FAIL blocks compile (BOOT-03)
+ * - Auto-fix enabled with max 2 cycles when policy allows (BOOT-04)
+ * - state.stage = 'done' after successful compile (Pitfall 8)
+ *
+ * IMPORTANT: runImagine() and runSpecify() are ASYNC — use await.
+ *            runAuditWorkflow() and runCompileWorkflow() are SYNC — no await.
+ */
+export async function runBootstrap(options: BootstrapOptions): Promise<BootstrapResult> {
+  const planningDir = options.planningDir ?? path.join(process.cwd(), '.planning');
+  const gswdDir = path.join(planningDir, 'gswd');
+  const statePath = path.join(gswdDir, 'STATE.json');
+  const configPath = options.configPath ?? path.join(planningDir, 'config.json');
+
+  const stagesCompleted: BootstrapStage[] = [];
+  const allArtifacts: string[] = [];
+  let allAutoDecisions: AutoDecision[] = [];
+  let autoFixCycles = 0;
+
+  // Early validation: auto mode requires @idea.md
+  if (options.auto && !options.ideaFilePath) {
+    return {
+      status: 'failed',
+      stagesCompleted,
+      artifactsWritten: allArtifacts,
+      autoDecisions: allAutoDecisions,
+      interruptReasons: [],
+      autoFixCycles,
+      error: 'Auto mode requires @idea.md — provide a file describing your idea',
+    };
+  }
+
+  // Step 1: Ensure STATE.json exists
+  if (!fs.existsSync(statePath)) {
+    fs.mkdirSync(gswdDir, { recursive: true });
+    initState(gswdDir, deriveProjectSlug(options.ideaFilePath ?? planningDir));
+  }
+
+  // Step 2: Load config
+  const config = getGswdConfig(configPath);
+  if (options.policy) {
+    config.auto.policy = options.policy;
+  }
+
+  // Step 3: Configure auto mode in state
+  const initStateObj = readState(statePath);
+  if (initStateObj) {
+    initStateObj.auto.enabled = options.auto;
+    initStateObj.auto.policy = config.auto.policy;
+    writeState(statePath, initStateObj);
+  }
+
+  console.log(renderBanner('BOOTSTRAP'));
+
+  // ── IMAGINE ──────────────────────────────────────────────────────────
+  const imagineState = readState(statePath)!;
+  if (!shouldSkipStage('imagine', imagineState, planningDir, options.resume ?? false)) {
+    writeCheckpoint(statePath, 'gswd/bootstrap', 'imagine-start');
+    console.log(renderBanner('IMAGINE'));
+    // runImagine is ASYNC — MUST await
+    const imagineResult: ImagineResult = await runImagine({
+      ideaFilePath: options.ideaFilePath,
+      autoMode: options.auto,
+      skipResearch: options.skipResearch ?? false,
+      planningDir,
+      configPath,
+      spawnFn: options.spawnFn as any,
+    });
+    if (imagineResult.status !== 'complete') {
+      return {
+        status: 'failed',
+        stagesCompleted,
+        artifactsWritten: allArtifacts,
+        autoDecisions: allAutoDecisions,
+        interruptReasons: [],
+        autoFixCycles,
+        error: imagineResult.error ?? 'Imagine stage failed',
+      };
+    }
+    allArtifacts.push(...(imagineResult.artifacts_written ?? []));
+    if (imagineResult.auto_decisions) {
+      allAutoDecisions = [...allAutoDecisions, ...imagineResult.auto_decisions];
+    }
+
+    // Record auto decisions in STATE.json (AUTO-04)
+    if (options.auto && allAutoDecisions.length > 0) {
+      const stateAfterImagine = readState(statePath);
+      if (stateAfterImagine) {
+        (stateAfterImagine.auto as Record<string, unknown>).decisions = allAutoDecisions;
+        writeState(statePath, stateAfterImagine);
+      }
+    }
+  }
+  stagesCompleted.push('imagine');
+
+  // Policy check after imagine (conflicting requirements check)
+  if (options.auto) {
+    const decisionsContent = tryReadFile(path.join(planningDir, 'DECISIONS.md'));
+    const check = checkPolicy({ config, decisionsContent });
+    if (check.shouldInterrupt) {
+      return handleInterrupt(check.reasons, statePath, stagesCompleted, allArtifacts, allAutoDecisions, autoFixCycles);
+    }
+  }
+
+  // ── SPECIFY ──────────────────────────────────────────────────────────
+  const specifyState = readState(statePath)!;
+  if (!shouldSkipStage('specify', specifyState, planningDir, options.resume ?? false)) {
+    writeCheckpoint(statePath, 'gswd/bootstrap', 'specify-start');
+    console.log(renderBanner('SPECIFY'));
+    // runSpecify is ASYNC — MUST await
+    // When no spawnFn provided, set skipAgents: true (Pitfall 1)
+    const specifyResult: SpecifyResult = await runSpecify({
+      auto: options.auto,
+      skipAgents: !options.spawnFn,
+      planningDir,
+      configPath,
+      spawnFn: options.spawnFn as any,
+    });
+    if (specifyResult.status === 'failed') {
+      return {
+        status: 'failed',
+        stagesCompleted,
+        artifactsWritten: allArtifacts,
+        autoDecisions: allAutoDecisions,
+        interruptReasons: [],
+        autoFixCycles,
+        error: (specifyResult.errors ?? []).join('; ') || 'Specify stage failed',
+      };
+    }
+    allArtifacts.push(...specifyResult.artifacts);
+  }
+  stagesCompleted.push('specify');
+
+  // Policy check after specify (check integrations, NFRs, decisions)
+  if (options.auto) {
+    const intContent = tryReadFile(path.join(planningDir, 'INTEGRATIONS.md'));
+    const nfrContent = tryReadFile(path.join(planningDir, 'NFR.md'));
+    const decisionsContent = tryReadFile(path.join(planningDir, 'DECISIONS.md'));
+    const check = checkPolicy({ config, integrationsContent: intContent, nfrContent, decisionsContent });
+    if (check.shouldInterrupt) {
+      return handleInterrupt(check.reasons, statePath, stagesCompleted, allArtifacts, allAutoDecisions, autoFixCycles);
+    }
+  }
+
+  // ── AUDIT ────────────────────────────────────────────────────────────
+  const auditState = readState(statePath)!;
+  if (!shouldSkipStage('audit', auditState, planningDir, options.resume ?? false)) {
+    writeCheckpoint(statePath, 'gswd/bootstrap', 'audit-start');
+    console.log(renderBanner('AUDIT'));
+    // runAuditWorkflow is SYNC — no await (Pitfall 7)
+    const auditResult: AuditWorkflowResult = runAuditWorkflow({
+      planningDir,
+      statePath,
+      autoFix: options.auto && config.auto.policy !== 'strict',
+      maxCycles: 2,
+    });
+    autoFixCycles = auditResult.autoFixCycles;
+    if (!auditResult.passed) {
+      // BOOT-03: Cannot finish if audit is FAIL
+      return {
+        status: 'failed',
+        stagesCompleted,
+        artifactsWritten: allArtifacts,
+        autoDecisions: allAutoDecisions,
+        interruptReasons: [],
+        autoFixCycles,
+        error: 'Audit FAIL — cannot compile',
+      };
+    }
+  }
+  stagesCompleted.push('audit');
+
+  // ── COMPILE ──────────────────────────────────────────────────────────
+  const compileState = readState(statePath)!;
+  if (!shouldSkipStage('compile', compileState, planningDir, options.resume ?? false)) {
+    writeCheckpoint(statePath, 'gswd/bootstrap', 'compile-start');
+    console.log(renderBanner('COMPILE'));
+    // runCompileWorkflow is SYNC — no await (Pitfall 7)
+    const compileResult: CompileWorkflowResult = runCompileWorkflow({
+      planningDir,
+      statePath,
+    });
+    if (!compileResult.passed) {
+      return {
+        status: 'failed',
+        stagesCompleted,
+        artifactsWritten: allArtifacts,
+        autoDecisions: allAutoDecisions,
+        interruptReasons: [],
+        autoFixCycles,
+        error: compileResult.error ?? 'Compile validator failed',
+      };
+    }
+    allArtifacts.push(...compileResult.filesWritten);
+  }
+  stagesCompleted.push('compile');
+
+  // Step final: Set stage = 'done' (Pitfall 8 — ONLY place 'done' is written)
+  const doneState = readState(statePath)!;
+  doneState.stage = 'done';
+  writeState(statePath, doneState);
+  writeCheckpoint(statePath, 'gswd/bootstrap', 'bootstrap-done');
+
+  // Auto decision summary (AUTO-06)
+  if (options.auto && allAutoDecisions.length > 0) {
+    console.log(renderAutoDecisionSummary(allAutoDecisions));
+  }
+
+  console.log(renderNextUp(
+    ['PROJECT.md', 'REQUIREMENTS.md', 'ROADMAP.md', 'STATE.md'],
+    '/gsd:plan-phase 01'
+  ));
+
+  return {
+    status: 'done',
+    stagesCompleted,
+    artifactsWritten: allArtifacts,
+    autoDecisions: allAutoDecisions,
+    interruptReasons: [],
+    autoFixCycles,
+  };
+}