sofia-cli 0.1.1

package/src/cli/workshopCommand.ts

@@ -0,0 +1,496 @@
+/**
+ * Workshop command handler.
+ *
+ * Implements `sofia workshop` — the main interactive workshop command
+ * with New Session, Resume Session, Status, and Export menu options.
+ * Drives phase-by-phase conversation with decision gates.
+ */
+import { join } from 'node:path';
+
+import { ConversationLoop } from '../loop/conversationLoop.js';
+import { createCopilotClient } from '../shared/copilotClient.js';
+import type { CopilotClient } from '../shared/copilotClient.js';
+import { ActivitySpinner } from '../shared/activitySpinner.js';
+import { getLogger } from '../logging/logger.js';
+import type { WorkshopSession, PhaseValue } from '../shared/schemas/session.js';
+import { SessionStore, createDefaultStore } from '../sessions/sessionStore.js';
+import { createLoopIO } from './ioContext.js';
+import { createPhaseHandler, getPhaseOrder, getNextPhase } from '../phases/phaseHandlers.js';
+import type { PhaseHandlerConfig } from '../phases/phaseHandlers.js';
+import type { SofiaEvent } from '../shared/events.js';
+import { renderMarkdown } from '../shared/markdownRenderer.js';
+import { destroyWebSearchSession, isWebSearchConfigured, createWebSearchTool } from '../mcp/webSearch.js';
+import type { WebSearchConfig } from '../mcp/webSearch.js';
+import { loadEnvFile } from './envLoader.js';
+import { loadMcpConfig, McpManager } from '../mcp/mcpManager.js';
+import { RalphLoop } from '../develop/ralphLoop.js';
+import { deriveCheckpointState } from '../develop/checkpointState.js';
+import { createDefaultRegistry, selectTemplate } from '../develop/templateRegistry.js';
+
+export interface WorkshopCommandOptions {
+  session?: string;
+  json?: boolean;
+  debug?: boolean;
+  logFile?: string;
+  nonInteractive?: boolean;
+  newSession?: boolean;
+  phase?: string;
+  retry?: number;
+}
+
+/**
+ * Generate a timestamp-based session ID for human-friendly filenames.
+ * Format: YYYY-MM-DD_HHmmss  (e.g. "2026-02-27_143052")
+ */
+function generateSessionId(): string {
+  const d = new Date();
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return [
+    d.getFullYear(),
+    '-',
+    pad(d.getMonth() + 1),
+    '-',
+    pad(d.getDate()),
+    '_',
+    pad(d.getHours()),
+    pad(d.getMinutes()),
+    pad(d.getSeconds()),
+  ].join('');
+}
+
+/**
+ * Format a session identifier for display.
+ * Shows "name (id)" when a name exists, otherwise just the id.
+ */
+function sessionDisplayName(session: { sessionId: string; name?: string }): string {
+  return session.name ? `${session.name} (${session.sessionId})` : session.sessionId;
+}
+
+/**
+ * Create a new empty workshop session.
+ */
+function createNewSession(): WorkshopSession {
+  const now = new Date().toISOString();
+  return {
+    sessionId: generateSessionId(),
+    schemaVersion: '1.0.0',
+    createdAt: now,
+    updatedAt: now,
+    phase: 'Discover',
+    status: 'Active',
+    participants: [],
+    artifacts: { generatedFiles: [] },
+    turns: [],
+  };
+}
+
+/**
+ * Show the main workshop menu and return user choice.
+ */
+async function showMainMenu(
+  io: ReturnType<typeof createLoopIO>,
+  existingSessions: string[],
+): Promise<'new' | 'resume' | 'exit'> {
+  const hasExisting = existingSessions.length > 0;
+
+  const menuText = [
+    '\n# sofIA — AI Discovery Workshop\n',
+    'Choose an option:\n',
+    '  1. Start a new workshop session',
+    hasExisting ? '  2. Resume an existing session' : '',
+    '  3. Exit',
+    '',
+  ]
+    .filter(Boolean)
+    .join('\n');
+
+  io.write(renderMarkdown(menuText, { isTTY: io.isTTY }));
+
+  const answer = await io.readInput('Choose [1-3]: ');
+  if (answer === null || answer.trim() === '3') return 'exit';
+  if (answer.trim() === '2' && hasExisting) return 'resume';
+  return 'new';
+}
+
+/**
+ * Run the workshop flow for a session through its phases.
+ */
+async function runWorkshop(
+  session: WorkshopSession,
+  client: CopilotClient,
+  io: ReturnType<typeof createLoopIO>,
+  store: SessionStore,
+  options: WorkshopCommandOptions,
+  handlerConfig?: PhaseHandlerConfig,
+): Promise<void> {
+  const logger = getLogger();
+  const phaseOrder = getPhaseOrder();
+  let currentPhaseIdx = phaseOrder.indexOf(session.phase);
+  if (currentPhaseIdx === -1) currentPhaseIdx = 0;
+
+  // If a specific phase was requested, jump to it
+  if (options.phase) {
+    const requestedIdx = phaseOrder.indexOf(options.phase as PhaseValue);
+    if (requestedIdx !== -1) {
+      currentPhaseIdx = requestedIdx;
+      session.phase = phaseOrder[currentPhaseIdx];
+    }
+  }
+
+  while (currentPhaseIdx < phaseOrder.length) {
+    const phase = phaseOrder[currentPhaseIdx];
+    session.phase = phase;
+    session.updatedAt = new Date().toISOString();
+    await store.save(session);
+
+    io.write(renderMarkdown(`\n## Phase: ${phase}\n`, { isTTY: io.isTTY }));
+
+    // Create and preload the phase handler
+    const handler = createPhaseHandler(phase, handlerConfig);
+    await handler._preload();
+
+    // Generate initial message for auto-start
+    const initialMessage = handler.getInitialMessage?.(session);
+
+    const events: SofiaEvent[] = [];
+
+    // Create activity spinner for visual feedback
+    const spinner = new ActivitySpinner({
+      isTTY: io.isTTY,
+      isJsonMode: io.isJsonMode,
+      debugMode: options.debug,
+    });
+
+    const loop = new ConversationLoop({
+      client,
+      io,
+      session,
+      phaseHandler: handler,
+      initialMessage,
+      spinner,
+      onEvent: (e) => {
+        events.push(e);
+        if (options.debug && e.type === 'Activity') {
+          io.writeActivity(e.message);
+        }
+      },
+      onSessionUpdate: async (updatedSession) => {
+        session = updatedSession;
+        await store.save(session);
+      },
+    });
+
+    // Run the conversation loop for this phase
+    session = await loop.run();
+    session.updatedAt = new Date().toISOString();
+    await store.save(session);
+
+    // Decision gate
+    const gateResult = await io.showDecisionGate(phase);
+
+    switch (gateResult.choice) {
+      case 'continue': {
+        const next = getNextPhase(phase);
+        if (next) {
+          // FR-020: Show transition guidance when Plan → Develop
+          if (next === 'Develop') {
+            io.write(
+              renderMarkdown(
+                `\n### Starting PoC Generation\n\n` +
+                  `The Plan phase is complete. Now generating proof-of-concept code...\n`,
+                { isTTY: io.isTTY },
+              ),
+            );
+
+            // FR-021: Always run PoC generation after Plan phase
+            try {
+              const outputDir = join(process.cwd(), '..', 'poc', session.sessionId);
+              const checkpoint = deriveCheckpointState(session, outputDir);
+              const templateEntry = selectTemplate(
+                createDefaultRegistry(),
+                session.plan?.architectureNotes,
+                session.plan?.dependencies,
+              );
+              
+              const ralphLoop = new RalphLoop({
+                client,
+                io,
+                session,
+                spinner,
+                maxIterations: 20,
+                outputDir,
+                onSessionUpdate: async (updated) => {
+                  session = updated;
+                  await store.save(session);
+                },
+                onEvent: (event: SofiaEvent) => {
+                  // Log PoC generation events if debug is enabled
+                  if (options.debug) {
+                    logger.debug('RalphLoop event', { event });
+                  }
+                },
+                checkpoint,
+                templateEntry,
+              });
+              
+              const result = await ralphLoop.run();
+              session = result.session;
+              
+              if (result.finalStatus === 'success') {
+                io.write(
+                  renderMarkdown(
+                    `\n✅ PoC generated successfully in ${result.outputDir}\n\n` +
+                    `Next steps:\n` +
+                    `- Review the generated code\n` +
+                    `- Run tests: \`cd ${result.outputDir} && npm test\`\n` +
+                    `- Continue developing: \`sofia dev --session ${session.sessionId}\`\n`,
+                    { isTTY: io.isTTY },
+                  ),
+                );
+              } else {
+                io.write(
+                  renderMarkdown(
+                    `\n⚠️  PoC generation incomplete (${result.terminationReason})\n\n` +
+                    `The workshop can continue. To retry or resume PoC development:\n` +
+                    `\`\`\`\n` +
+                    `sofia dev --session ${session.sessionId}\n` +
+                    `\`\`\`\n`,
+                    { isTTY: io.isTTY },
+                  ),
+                );
+              }
+            } catch (err) {
+              const msg = err instanceof Error ? err.message : String(err);
+              io.write(
+                renderMarkdown(
+                  `\n⚠️  PoC generation failed: ${msg}\n\n` +
+                  `The workshop can continue. To retry:\n` +
+                  `\`\`\`\n` +
+                  `sofia dev --session ${session.sessionId}\n` +
+                  `\`\`\`\n`,
+                  { isTTY: io.isTTY },
+                ),
+              );
+            }
+            
+            // Continue to next phase regardless of PoC outcome
+          }
+          currentPhaseIdx = phaseOrder.indexOf(next);
+        } else {
+          // Mark session as completed
+          session.phase = 'Complete';
+          session.status = 'Completed';
+          session.updatedAt = new Date().toISOString();
+          await store.save(session);
+
+          io.write(
+            renderMarkdown(
+              '\n## Workshop Complete!\n\nUse `sofia export` to generate artifacts.\n',
+              {
+                isTTY: io.isTTY,
+              },
+            ),
+          );
+          return;
+        }
+        break;
+      }
+      case 'refine':
+        // Stay on the same phase
+        break;
+      case 'menu':
+        return; // Return to main menu
+      case 'exit':
+        session.status = 'Paused';
+        session.updatedAt = new Date().toISOString();
+        await store.save(session);
+        io.write(
+          renderMarkdown(
+            `\nSession **${sessionDisplayName(session)}** paused. Resume later with \`sofia workshop --session ${session.sessionId}\`.\n`,
+            { isTTY: io.isTTY },
+          ),
+        );
+        return;
+    }
+  }
+}
+
+export async function workshopCommand(opts: WorkshopCommandOptions): Promise<void> {
+  try {
+    await workshopCommandInner(opts);
+  } finally {
+    // Clean up ephemeral web search agent on workshop exit (FR-015)
+    await destroyWebSearchSession();
+  }
+}
+
+async function workshopCommandInner(opts: WorkshopCommandOptions): Promise<void> {
+  // FR-010: Load .env before any env var checks (e.g., isWebSearchConfigured)
+  loadEnvFile(join(process.cwd(), '.env'));
+
+  const store = createDefaultStore();
+  const io = createLoopIO({
+    json: opts.json,
+    nonInteractive: opts.nonInteractive,
+    debug: opts.debug,
+  });
+
+  // Get Copilot client
+  let client: CopilotClient;
+  try {
+    client = await createCopilotClient();
+  } catch (err: unknown) {
+    const logger = getLogger();
+    logger.error({ err }, 'Failed to create Copilot client — cannot start workshop');
+    const msg = err instanceof Error ? err.message : 'Unknown error creating Copilot client';
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({ error: msg }) + '\n');
+    } else {
+      console.error(`Error: ${msg}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  // FR-011: Create McpManager from .vscode/mcp.json
+  let mcpManager: McpManager | undefined;
+  try {
+    const mcpConfigPath = join(process.cwd(), '.vscode', 'mcp.json');
+    const mcpConfig = await loadMcpConfig(mcpConfigPath);
+    mcpManager = new McpManager(mcpConfig);
+  } catch {
+    // MCP not configured — proceed without it
+  }
+
+  // FR-012: Create WebSearchClient when configured
+  let webSearchClient: import('../phases/discoveryEnricher.js').WebSearchClient | undefined;
+  if (isWebSearchConfigured()) {
+    const config: WebSearchConfig = {
+      projectEndpoint: process.env.FOUNDRY_PROJECT_ENDPOINT!,
+      modelDeploymentName: process.env.FOUNDRY_MODEL_DEPLOYMENT_NAME!,
+    };
+    const searchFn = createWebSearchTool(config);
+    webSearchClient = { search: searchFn };
+  }
+
+  // Build handler config with MCP + web search
+  const handlerConfig: PhaseHandlerConfig = {
+    discover: {
+      io,
+      mcpManager,
+      webSearchClient,
+    },
+    mcpManager,
+    webSearchClient,
+  };
+
+  // Direct session resumption
+  if (opts.session) {
+    if (await store.exists(opts.session)) {
+      const session = await store.load(opts.session);
+      io.write(
+        renderMarkdown(`\nResuming session: **${sessionDisplayName(session)}**\n`, {
+          isTTY: io.isTTY,
+        }),
+      );
+      await runWorkshop(session, client, io, store, opts, handlerConfig);
+    } else {
+      const msg = `Session "${opts.session}" not found.`;
+      if (opts.json) {
+        process.stdout.write(JSON.stringify({ error: msg }) + '\n');
+      } else {
+        console.error(`Error: ${msg}`);
+      }
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  // New session flag
+  if (opts.newSession) {
+    const session = createNewSession();
+    await store.save(session);
+    if (opts.json) {
+      process.stdout.write(
+        JSON.stringify({ sessionId: session.sessionId, phase: session.phase }) + '\n',
+      );
+    } else {
+      io.write(
+        renderMarkdown(`\nNew session created: **${session.sessionId}**\n`, { isTTY: io.isTTY }),
+      );
+    }
+    await runWorkshop(session, client, io, store, opts, handlerConfig);
+    return;
+  }
+
+  // Interactive menu
+  if (opts.nonInteractive) {
+    if (opts.json) {
+      process.stdout.write(
+        JSON.stringify({ error: 'Non-interactive mode requires --session or --new-session.' }) +
+          '\n',
+      );
+    } else {
+      console.error('Error: Non-interactive mode requires --session or --new-session.');
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const existingSessions = await store.list();
+  const choice = await showMainMenu(io, existingSessions);
+
+  switch (choice) {
+    case 'new': {
+      const session = createNewSession();
+      await store.save(session);
+      io.write(renderMarkdown(`\nNew session: **${session.sessionId}**\n`, { isTTY: io.isTTY }));
+      await runWorkshop(session, client, io, store, opts, handlerConfig);
+      break;
+    }
+    case 'resume': {
+      const sessions = await store.list();
+      if (sessions.length === 0) {
+        io.write('No existing sessions found.\n');
+        break;
+      }
+      const sessionEntries = (
+        await Promise.all(
+          sessions.map(async (id) => {
+            try {
+              const session = await store.load(id);
+              return { id, display: sessionDisplayName(session), session };
+            } catch {
+              return { id, display: id, session: undefined };
+            }
+          }),
+        )
+      ).filter((entry) => entry.display !== entry.id);
+
+      // Show session list
+      io.write('\nAvailable sessions:\n');
+      sessionEntries.forEach((entry, idx) => {
+        io.write(`  ${idx + 1}. ${entry.display}\n`);
+      });
+      const answer = await io.readInput('Choose session number: ');
+      if (answer === null) break;
+      const idx = parseInt(answer.trim(), 10) - 1;
+      if (idx >= 0 && idx < sessionEntries.length) {
+        const entry = sessionEntries[idx];
+        const session = entry.session ?? (await store.load(entry.id));
+        io.write(
+          renderMarkdown(`\nResuming session: **${sessionDisplayName(session)}**\n`, {
+            isTTY: io.isTTY,
+          }),
+        );
+        await runWorkshop(session, client, io, store, opts, handlerConfig);
+      } else {
+        io.write('Invalid selection.\n');
+      }
+      break;
+    }
+    case 'exit':
+      io.write('Goodbye!\n');
+      break;
+  }
+}

package/src/develop/checkpointState.ts

@@ -0,0 +1,121 @@
+/**
+ * Checkpoint State Derivation.
+ *
+ * Derives resume behavior from existing session state. This is a runtime-only
+ * convenience type — it is NOT persisted to the session.
+ *
+ * Contract: specs/004-dev-resume-hardening/contracts/cli.md
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { PocIteration, WorkshopSession } from '../shared/schemas/session.js';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface CheckpointState {
+  /** Whether a prior PoC run exists */
+  hasPriorRun: boolean;
+  /** Number of fully completed iterations (with testResults) */
+  completedIterations: number;
+  /** Whether the last iteration was interrupted (no testResults) */
+  lastIterationIncomplete: boolean;
+  /** The iteration number to resume from */
+  resumeFromIteration: number;
+  /** Whether scaffolding can be skipped (output dir + metadata exist) */
+  canSkipScaffold: boolean;
+  /** Final status from prior run, if any */
+  priorFinalStatus: 'success' | 'failed' | 'partial' | undefined;
+  /** Prior iterations for LLM context seeding */
+  priorIterations: PocIteration[];
+}
+
+// ── Derivation ───────────────────────────────────────────────────────────────
+
+/**
+ * Derive the checkpoint state from an existing session and output directory.
+ *
+ * Used by `developCommand` and `RalphLoop` to decide resume behavior.
+ */
+export function deriveCheckpointState(
+  session: WorkshopSession,
+  outputDir: string,
+): CheckpointState {
+  const poc = session.poc;
+
+  // No prior run
+  if (!poc || !Array.isArray(poc.iterations) || poc.iterations.length === 0) {
+    return {
+      hasPriorRun: false,
+      completedIterations: 0,
+      lastIterationIncomplete: false,
+      resumeFromIteration: 1,
+      canSkipScaffold: false,
+      priorFinalStatus: undefined,
+      priorIterations: [],
+    };
+  }
+
+  // Validate iteration entries — if any are corrupt, fall back to fresh run
+  if (!validateIterations(poc.iterations)) {
+    return {
+      hasPriorRun: false,
+      completedIterations: 0,
+      lastIterationIncomplete: false,
+      resumeFromIteration: 1,
+      canSkipScaffold: false,
+      priorFinalStatus: undefined,
+      priorIterations: [],
+    };
+  }
+
+  const lastIter = poc.iterations[poc.iterations.length - 1];
+  const lastIncomplete = !lastIter.testResults && lastIter.outcome !== 'scaffold';
+  const completedIters = lastIncomplete ? poc.iterations.slice(0, -1) : poc.iterations;
+
+  const metadataPath = join(outputDir, '.sofia-metadata.json');
+  const metadataExists = existsSync(metadataPath);
+
+  // Validate metadata integrity: sessionId must match
+  let canSkipScaffold = metadataExists;
+  if (metadataExists) {
+    try {
+      const raw = readFileSync(metadataPath, 'utf-8');
+      const metadata = JSON.parse(raw) as { sessionId?: string };
+      if (metadata.sessionId !== session.sessionId) {
+        canSkipScaffold = false;
+      }
+    } catch {
+      canSkipScaffold = false;
+    }
+  }
+
+  return {
+    hasPriorRun: true,
+    completedIterations: completedIters.length,
+    lastIterationIncomplete: lastIncomplete,
+    resumeFromIteration: completedIters.length + 1,
+    canSkipScaffold,
+    priorFinalStatus: poc.finalStatus,
+    priorIterations: completedIters,
+  };
+}
+
+// ── Validation ───────────────────────────────────────────────────────────────
+
+/**
+ * Validate iteration entries have required fields and valid shapes.
+ * Returns false if any iteration is corrupt.
+ */
+function validateIterations(iterations: PocIteration[]): boolean {
+  for (const iter of iterations) {
+    if (
+      typeof iter.iteration !== 'number' ||
+      typeof iter.startedAt !== 'string' ||
+      !iter.startedAt
+    ) {
+      return false;
+    }
+  }
+  return true;
+}