sofia-cli 0.1.1

package/src/cli/developCommand.ts

@@ -0,0 +1,308 @@
+/**
+ * `sofia dev` command handler.
+ *
+ * Runs the Develop phase for a completed workshop session:
+ * - Validates the session has selection + plan
+ * - Derives checkpoint state for resume decisions
+ * - Creates a RalphLoop and runs it
+ * - Displays results (repo URL/path, final status)
+ *
+ * Contract: specs/002-poc-generation/tasks.md (T019, T029, T038)
+ * Contract: specs/004-dev-resume-hardening/contracts/cli.md
+ */
+import { join } from 'node:path';
+import { existsSync, rmSync } from 'node:fs';
+
+import type { WorkshopSession } from '../shared/schemas/session.js';
+import type { McpManager } from '../mcp/mcpManager.js';
+import { createNoOpSpinner } from '../shared/activitySpinner.js';
+import { RalphLoop } from '../develop/ralphLoop.js';
+import { McpContextEnricher } from '../develop/mcpContextEnricher.js';
+import { deriveCheckpointState } from '../develop/checkpointState.js';
+import { createDefaultRegistry, selectTemplate } from '../develop/templateRegistry.js';
+import { PocScaffolder } from '../develop/pocScaffolder.js';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface DevelopCommandOptions {
+  /** Session ID to develop */
+  session?: string;
+  /** Maximum Ralph loop iterations */
+  maxIterations?: number;
+  /** Output directory for the PoC */
+  output?: string;
+  /** Force overwrite of existing output directory */
+  force?: boolean;
+  /** Emit machine-readable JSON only */
+  json?: boolean;
+  /** Enable debug output */
+  debug?: boolean;
+}
+
+export interface DevelopCommandDeps {
+  store: {
+    load(sessionId: string): Promise<WorkshopSession | null>;
+    save(session: WorkshopSession): Promise<void>;
+    list(): Promise<string[]>;
+  };
+  io: import('../loop/conversationLoop.js').LoopIO;
+  client: import('../shared/copilotClient.js').CopilotClient;
+  /** Optional MCP manager — when provided, wires GitHub MCP and context enrichment */
+  mcpManager?: McpManager;
+}
+
+// ── Validation ────────────────────────────────────────────────────────────────
+
+/**
+ * Validate that a session is ready for the Develop phase.
+ *
+ * Returns null if valid, or an error message if not.
+ */
+export function validateSessionForDevelop(session: WorkshopSession): string | null {
+  if (!session.selection) {
+    return [
+      'Session is missing an idea selection.',
+      'Run the Select phase first: sofia workshop --session ' + session.sessionId,
+    ].join('\n');
+  }
+
+  if (!session.plan) {
+    return [
+      'Session is missing an implementation plan.',
+      'Run the Plan phase first: sofia workshop --session ' + session.sessionId,
+    ].join('\n');
+  }
+
+  return null;
+}
+
+// ── Command handler ───────────────────────────────────────────────────────────
+
+/**
+ * Main handler for the `sofia dev` command.
+ */
+export async function developCommand(
+  opts: DevelopCommandOptions,
+  deps: DevelopCommandDeps,
+): Promise<void> {
+  const { store, io, client } = deps;
+  const { mcpManager } = deps;
+  const json = opts.json ?? false;
+  // ── Resolve session ──────────────────────────────────────────────────────
+  let sessionId = opts.session;
+
+  if (!sessionId) {
+    // Try to find the most recent session
+    const sessions = await store.list();
+    if (sessions.length === 0) {
+      const msg = 'No sessions found. Start a workshop first: sofia workshop';
+      if (json) {
+        process.stdout.write(JSON.stringify({ error: msg }) + '\n');
+      } else {
+        io.writeActivity(msg);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    sessionId = sessions[sessions.length - 1];
+    io.writeActivity(`Using most recent session: ${sessionId}`);
+  }
+
+  // ── Load session ─────────────────────────────────────────────────────────
+  const session = await store.load(sessionId);
+
+  if (!session) {
+    const msg = `Session not found: ${sessionId}`;
+    if (json) {
+      process.stdout.write(JSON.stringify({ error: msg }) + '\n');
+    } else {
+      io.writeActivity(msg);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  // ── Validate session ─────────────────────────────────────────────────────
+  const validationError = validateSessionForDevelop(session);
+  if (validationError) {
+    if (json) {
+      process.stdout.write(JSON.stringify({ error: validationError }) + '\n');
+    } else {
+      process.stderr.write(`Error: ${validationError}\n`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  // ── Determine output directory ───────────────────────────────────────────
+  const outputDir = opts.output
+    ? join(process.cwd(), opts.output)
+    : join(process.cwd(), '..', 'poc', sessionId);
+
+  // ── Handle --force: reset session.poc AND output directory ───────────────
+  if (opts.force) {
+    // FR-008/009/010: Clear session state before doing anything else
+    session.poc = undefined;
+    await store.save(session);
+
+    const dirExists = existsSync(outputDir);
+    if (dirExists) {
+      try {
+        rmSync(outputDir, { recursive: true, force: true });
+      } catch (err: unknown) {
+        const msg = `Failed to clear output directory: ${err instanceof Error ? err.message : String(err)}`;
+        if (json) {
+          process.stdout.write(JSON.stringify({ error: msg }) + '\n');
+        } else {
+          process.stderr.write(`Error: ${msg}\n`);
+        }
+        process.exitCode = 1;
+        return;
+      }
+    }
+    if (!json) {
+      io.writeActivity('Cleared existing output directory and session state (--force)');
+    }
+  }
+
+  // ── Derive checkpoint state (resume detection) ───────────────────────────
+  const checkpoint = deriveCheckpointState(session, outputDir);
+
+  // FR-005: If PoC already succeeded, exit with completion message
+  if (!opts.force && checkpoint.priorFinalStatus === 'success') {
+    const msg = `PoC already complete for session ${sessionId}. Use --force to start fresh.`;
+    if (json) {
+      process.stdout.write(JSON.stringify({ status: 'already-complete', sessionId }) + '\n');
+    } else {
+      io.writeActivity(msg);
+    }
+    return;
+  }
+
+  // FR-006: Default to resume for failed/partial
+  if (!opts.force && checkpoint.hasPriorRun) {
+    if (!json) {
+      io.writeActivity(
+        `Resuming session ${sessionId} from iteration ${checkpoint.resumeFromIteration} (${checkpoint.completedIterations} completed iterations found)`,
+      );
+    }
+  }
+
+  // ── Template selection ────────────────────────────────────────────────────
+  const registry = createDefaultRegistry();
+  const template = selectTemplate(
+    registry,
+    session.plan?.architectureNotes,
+    session.plan?.dependencies,
+  );
+  if (!json) {
+    const matchedPattern = template.matchPatterns.find((p) =>
+      [session.plan?.architectureNotes ?? '', ...(session.plan?.dependencies ?? [])]
+        .join(' ')
+        .toLowerCase()
+        .includes(p.toLowerCase()),
+    );
+    io.writeActivity(
+      `Selected template: ${template.id}${matchedPattern ? ` (matched '${matchedPattern}' in architecture notes)` : ' (default)'}`,
+    );
+  }
+
+  // ── Create RalphLoop ─────────────────────────────────────────────────────
+  const spinner = createNoOpSpinner();
+
+  const enricher = mcpManager ? new McpContextEnricher(mcpManager) : undefined;
+
+  const ralph = new RalphLoop({
+    client,
+    io,
+    session,
+    spinner,
+    maxIterations: opts.maxIterations ?? 10,
+    outputDir,
+    enricher,
+    checkpoint,
+    scaffolder: new PocScaffolder(template),
+    templateEntry: template,
+    onSessionUpdate: async (updated) => {
+      await store.save(updated);
+    },
+    onEvent: (event) => {
+      if (opts.debug) {
+        io.writeActivity(`[event] ${event.type}: ${JSON.stringify(event)}`);
+      }
+    },
+  });
+
+  // ── Run the loop ─────────────────────────────────────────────────────────
+  if (!json) {
+    io.writeActivity(
+      `Starting PoC generation for session: ${sessionId}\n` +
+        `Output: ${outputDir}\n` +
+        `Max iterations: ${opts.maxIterations ?? 10}`,
+    );
+  }
+
+  let result;
+  try {
+    result = await ralph.run();
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (json) {
+      process.stdout.write(JSON.stringify({ error: msg }) + '\n');
+    } else {
+      process.stderr.write(`Error: ${msg}\n`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  // ── Display results ──────────────────────────────────────────────────────
+  if (json) {
+    const output = {
+      sessionId,
+      finalStatus: result.finalStatus,
+      terminationReason: result.terminationReason,
+      iterationsCompleted: result.iterationsCompleted,
+      repoSource: result.session.poc?.repoSource ?? 'local',
+      repoUrl: result.session.poc?.repoUrl,
+      repoPath: result.session.poc?.repoPath ?? outputDir,
+      outputDir: result.outputDir,
+    };
+    process.stdout.write(JSON.stringify(output) + '\n');
+  } else {
+    const repoInfo = result.session.poc?.repoUrl
+      ? `Repository URL: ${result.session.poc.repoUrl}`
+      : `Repository Path: ${result.session.poc?.repoPath ?? outputDir}`;
+
+    io.write(
+      [
+        '',
+        `PoC Generation Complete`,
+        `──────────────────────`,
+        `Status: ${result.finalStatus}`,
+        `Reason: ${result.terminationReason}`,
+        `Iterations: ${result.iterationsCompleted}`,
+        repoInfo,
+        '',
+      ].join('\n'),
+    );
+
+    if (result.finalStatus !== 'success') {
+      io.write(
+        [
+          'Recovery options:',
+          `  • Resume: sofia dev --session ${sessionId}`,
+          `  • More iterations: sofia dev --session ${sessionId} --max-iterations 20`,
+                    `  • More iterations: sofia dev --session ${sessionId} --max-iterations 30`,
+          `  • Start fresh: sofia dev --session ${sessionId} --force`,
+          '',
+        ].join('\n'),
+      );
+    }
+  }
+
+  // Exit code based on final status
+  if (result.finalStatus === 'failed') {
+    process.exitCode = 1;
+  }
+}

package/src/cli/directCommands.ts

@@ -0,0 +1,195 @@
+/**
+ * Direct command mode (US3).
+ *
+ * Provides non-interactive and automation-friendly entry points:
+ * - `sofia workshop --session <id> --phase <phase>` jumps to a specific phase
+ * - Enforces required inputs in non-interactive mode
+ * - JSON-only stdout when --json
+ * - Retry transient failures when --retry specified
+ */
+import { ConversationLoop } from '../loop/conversationLoop.js';
+import type { LoopIO } from '../loop/conversationLoop.js';
+import type { CopilotClient } from '../shared/copilotClient.js';
+import type { WorkshopSession, PhaseValue } from '../shared/schemas/session.js';
+import { SessionStore } from '../sessions/sessionStore.js';
+import { createPhaseHandler, getPhaseOrder } from '../phases/phaseHandlers.js';
+import type { SofiaEvent } from '../shared/events.js';
+import { classifyError, toUserMessage } from '../shared/errorClassifier.js';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface DirectCommandOptions {
+  sessionId: string;
+  phase: PhaseValue;
+  store: SessionStore;
+  client: CopilotClient;
+  io: LoopIO;
+  nonInteractive?: boolean;
+  json?: boolean;
+  debug?: boolean;
+  retry?: number;
+}
+
+export interface DirectCommandResult {
+  exitCode: number;
+  error?: string;
+}
+
+// ── Validation ───────────────────────────────────────────────────────────────
+
+const VALID_PHASES = getPhaseOrder();
+
+function validateInputs(opts: DirectCommandOptions): DirectCommandResult | null {
+  if (!opts.sessionId) {
+    const error = 'Required: --session <id>. Provide a session ID to target.';
+    emitError(opts, error);
+    return { exitCode: 1, error };
+  }
+
+  if (opts.nonInteractive && !opts.phase) {
+    const error = 'Required: --phase <phase>. In non-interactive mode, a phase must be specified.';
+    emitError(opts, error);
+    return { exitCode: 1, error };
+  }
+
+  if (opts.phase && !VALID_PHASES.includes(opts.phase)) {
+    const error = `Invalid phase "${opts.phase}". Valid phases: ${VALID_PHASES.join(', ')}`;
+    emitError(opts, error);
+    return { exitCode: 1, error };
+  }
+
+  return null; // validation passed
+}
+
+function emitError(opts: DirectCommandOptions, message: string): void {
+  if (opts.json || opts.io.isJsonMode) {
+    // JSON mode: follow the standard `{ error: "..." }` shape used by other commands
+    opts.io.write(JSON.stringify({ error: message }) + '\n');
+  } else {
+    // Non-JSON mode: emit a human-readable error message so failures are visible
+    opts.io.write(`Error: ${message}\n`);
+  }
+}
+
+// ── Core execution ──────────────────────────────────────────────────────────
+
+/**
+ * Run a direct command: load session, execute phase, persist results.
+ *
+ * Supports retry for transient failures (connection, timeout, etc.).
+ */
+export async function runDirectCommand(opts: DirectCommandOptions): Promise<DirectCommandResult> {
+  // 1. Validate inputs
+  const validationError = validateInputs(opts);
+  if (validationError) return validationError;
+
+  // 2. Load session
+  let session: WorkshopSession;
+  try {
+    if (!(await opts.store.exists(opts.sessionId))) {
+      const error = `Session "${opts.sessionId}" not found.`;
+      emitError(opts, error);
+      return { exitCode: 1, error };
+    }
+    session = await opts.store.load(opts.sessionId);
+  } catch (err: unknown) {
+    const error = err instanceof Error ? err.message : 'Failed to load session';
+    emitError(opts, error);
+    return { exitCode: 1, error };
+  }
+
+  // 3. Set phase
+  if (opts.phase) {
+    session.phase = opts.phase;
+    session.updatedAt = new Date().toISOString();
+    await opts.store.save(session);
+  }
+
+  // 4. Run phase with retry
+  const maxAttempts = (opts.retry ?? 0) + 1;
+  let lastError: Error | undefined;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      session = await runPhase(session, opts);
+      return { exitCode: 0 };
+    } catch (err: unknown) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      const classification = classifyError(lastError);
+
+      if (!classification.recoverable || attempt >= maxAttempts) {
+        const error = lastError.message;
+        emitError(opts, error);
+        return { exitCode: 1, error };
+      }
+
+      // Log retry attempt
+      opts.io.writeActivity(
+        `Attempt ${attempt}/${maxAttempts} failed (${classification.category}): ${toUserMessage(classification)}. Retrying...`,
+      );
+
+      // Brief backoff before retry
+      await new Promise((resolve) => setTimeout(resolve, 100 * attempt));
+    }
+  }
+
+  // Should not reach here, but safety net
+  const error = lastError?.message ?? 'Unknown error';
+  return { exitCode: 1, error };
+}
+
+// ── Phase runner ────────────────────────────────────────────────────────────
+
+async function runPhase(
+  session: WorkshopSession,
+  opts: DirectCommandOptions,
+): Promise<WorkshopSession> {
+  const phase = session.phase;
+  const handler = createPhaseHandler(phase);
+  await handler._preload();
+
+  const events: SofiaEvent[] = [];
+
+  const loop = new ConversationLoop({
+    client: opts.client,
+    io: opts.io,
+    session,
+    phaseHandler: handler,
+    onEvent: (e) => {
+      events.push(e);
+      if (opts.debug && e.type === 'Activity') {
+        opts.io.writeActivity(e.message);
+      }
+    },
+    onSessionUpdate: async (updatedSession) => {
+      session = updatedSession;
+      await opts.store.save(session);
+    },
+  });
+
+  session = await loop.run();
+  session.updatedAt = new Date().toISOString();
+  await opts.store.save(session);
+
+  // In JSON mode, emit result summary
+  if (opts.json || opts.io.isJsonMode) {
+    opts.io.write(
+      JSON.stringify({
+        sessionId: session.sessionId,
+        phase: session.phase,
+        status: session.status,
+        updatedAt: session.updatedAt,
+      }) + '\n',
+    );
+  }
+
+  // Decision gate
+  const gateResult = await opts.io.showDecisionGate(phase);
+  if (gateResult.choice === 'exit') {
+    session.status = 'Paused';
+    session.updatedAt = new Date().toISOString();
+    await opts.store.save(session);
+  }
+
+  return session;
+}

package/src/cli/envLoader.ts

@@ -0,0 +1,17 @@
+/**
+ * Loads a `.env` file into `process.env` without overwriting existing values.
+ *
+ * Called at CLI startup so that variables written by `infra/deploy.sh`
+ * (e.g. `FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL_DEPLOYMENT_NAME`) are
+ * available to the application automatically.
+ */
+import { config } from 'dotenv';
+
+/**
+ * Load environment variables from the given `.env` file path.
+ * Variables already present in `process.env` are **not** overwritten.
+ * If the file does not exist the call is a silent no-op.
+ */
+export function loadEnvFile(envPath: string): void {
+  config({ path: envPath, override: false, quiet: true });
+}

package/src/cli/exportCommand.ts

@@ -0,0 +1,65 @@
+/**
+ * Export command handler.
+ *
+ * Implements `sofia export` — exports workshop artifacts for a session.
+ * Generates Markdown files per phase and a summary.json.
+ */
+import { createDefaultStore } from '../sessions/sessionStore.js';
+import { exportSession } from '../sessions/exportWriter.js';
+import { ensureExportDir } from '../sessions/exportPaths.js';
+
+export interface ExportCommandOptions {
+  session?: string;
+  json?: boolean;
+  debug?: boolean;
+  logFile?: string;
+  nonInteractive?: boolean;
+  output?: string;
+}
+
+export async function exportCommand(opts: ExportCommandOptions): Promise<void> {
+  if (!opts.session) {
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({ error: 'No session specified. Use --session <id>.' }) + '\n');
+    } else {
+      console.error('Error: No session specified. Use --session <id>.');
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const store = createDefaultStore();
+
+  if (!(await store.exists(opts.session))) {
+    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;
+  }
+
+  const session = await store.load(opts.session);
+  const exportDir = opts.output
+    ? opts.output
+    : await ensureExportDir(opts.session);
+
+  const result = await exportSession(session, exportDir);
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({
+      sessionId: session.sessionId,
+      exported: true,
+      exportDir: result.exportDir,
+      files: result.files,
+    }) + '\n');
+  } else {
+    console.log(`Exported session "${session.sessionId}" to ${result.exportDir}`);
+    console.log(`Generated ${result.files.length} file(s):`);
+    for (const file of result.files) {
+      console.log(`  - ${file.path} (${file.type})`);
+    }
+  }
+}