sofia-cli 0.1.1

package/dist/src/cli/statusCommand.js

@@ -0,0 +1,110 @@
+/**
+ * Status command handler.
+ *
+ * Implements `sofia status` — displays session status and next expected action.
+ * Supports both TTY (human-readable) and JSON output modes.
+ */
+import { createDefaultStore } from '../sessions/sessionStore.js';
+import { renderTable } from '../shared/tableRenderer.js';
+import { getNextPhase } from '../phases/phaseHandlers.js';
+export async function statusCommand(opts) {
+    if (!opts.session) {
+        // Try to list all sessions
+        const store = createDefaultStore();
+        const sessions = await store.list();
+        if (sessions.length === 0) {
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ error: 'No sessions found. Start one with: sofia workshop --new-session' }) + '\n');
+            }
+            else {
+                console.error('No sessions found. Start one with: sofia workshop --new-session');
+            }
+            process.exitCode = 1;
+            return;
+        }
+        // Show all sessions
+        if (opts.json) {
+            const statuses = [];
+            for (const id of sessions) {
+                try {
+                    const s = await store.load(id);
+                    statuses.push({
+                        sessionId: s.sessionId,
+                        name: s.name,
+                        phase: s.phase,
+                        status: s.status,
+                        updatedAt: s.updatedAt,
+                    });
+                }
+                catch {
+                    statuses.push({ sessionId: id, error: 'Failed to load' });
+                }
+            }
+            process.stdout.write(JSON.stringify({ sessions: statuses }) + '\n');
+        }
+        else {
+            const rows = [];
+            for (const id of sessions) {
+                try {
+                    const s = await store.load(id);
+                    rows.push([s.sessionId.slice(0, 8), s.name ?? '', s.phase, s.status, s.updatedAt]);
+                }
+                catch {
+                    rows.push([id.slice(0, 8), '', '?', 'Error', '?']);
+                }
+            }
+            console.log(renderTable({
+                head: ['Session', 'Name', 'Phase', 'Status', 'Updated'],
+                rows,
+            }));
+        }
+        return;
+    }
+    const store = createDefaultStore();
+    if (!(await store.exists(opts.session))) {
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ error: `Session "${opts.session}" not found.` }) + '\n');
+        }
+        else {
+            console.error(`Error: Session "${opts.session}" not found.`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const session = await store.load(opts.session);
+    if (opts.json) {
+        const status = {
+            sessionId: session.sessionId,
+            phase: session.phase,
+            status: session.status,
+            nextPhase: getNextPhase(session.phase),
+            turns: session.turns?.length ?? 0,
+            participants: session.participants.length,
+            createdAt: session.createdAt,
+            updatedAt: session.updatedAt,
+            hasBusinessContext: !!session.businessContext,
+            hasWorkflow: !!session.workflow,
+            ideaCount: session.ideas?.length ?? 0,
+            hasSelection: !!session.selection,
+            hasPlan: !!session.plan,
+        };
+        if (session.name)
+            status.name = session.name;
+        process.stdout.write(JSON.stringify(status) + '\n');
+    }
+    else {
+        const next = getNextPhase(session.phase);
+        console.log(`\nSession: ${session.sessionId}`);
+        if (session.name) {
+            console.log(`Name:    ${session.name}`);
+        }
+        console.log(`Phase:   ${session.phase}`);
+        console.log(`Status:  ${session.status}`);
+        console.log(`Turns:   ${session.turns?.length ?? 0}`);
+        console.log(`Updated: ${session.updatedAt}`);
+        if (next) {
+            console.log(`Next:    ${next}`);
+        }
+        console.log('');
+    }
+}

package/dist/src/cli/workshopCommand.js

@@ -0,0 +1,400 @@
+/**
+ * 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 { ActivitySpinner } from '../shared/activitySpinner.js';
+import { getLogger } from '../logging/logger.js';
+import { createDefaultStore } from '../sessions/sessionStore.js';
+import { createLoopIO } from './ioContext.js';
+import { createPhaseHandler, getPhaseOrder, getNextPhase } from '../phases/phaseHandlers.js';
+import { renderMarkdown } from '../shared/markdownRenderer.js';
+import { destroyWebSearchSession, isWebSearchConfigured, createWebSearchTool } 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';
+/**
+ * Generate a timestamp-based session ID for human-friendly filenames.
+ * Format: YYYY-MM-DD_HHmmss  (e.g. "2026-02-27_143052")
+ */
+function generateSessionId() {
+    const d = new Date();
+    const pad = (n) => 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) {
+    return session.name ? `${session.name} (${session.sessionId})` : session.sessionId;
+}
+/**
+ * Create a new empty workshop session.
+ */
+function createNewSession() {
+    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, existingSessions) {
+    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, client, io, store, options, handlerConfig) {
+    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);
+        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 = [];
+        // 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) => {
+                                    // 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) {
+    try {
+        await workshopCommandInner(opts);
+    }
+    finally {
+        // Clean up ephemeral web search agent on workshop exit (FR-015)
+        await destroyWebSearchSession();
+    }
+}
+async function workshopCommandInner(opts) {
+    // 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;
+    try {
+        client = await createCopilotClient();
+    }
+    catch (err) {
+        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;
+    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;
+    if (isWebSearchConfigured()) {
+        const config = {
+            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 = {
+        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/dist/src/develop/checkpointState.js

@@ -0,0 +1,86 @@
+/**
+ * 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';
+// ── 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, outputDir) {
+    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);
+            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) {
+    for (const iter of iterations) {
+        if (typeof iter.iteration !== 'number' ||
+            typeof iter.startedAt !== 'string' ||
+            !iter.startedAt) {
+            return false;
+        }
+    }
+    return true;
+}