sofia-cli 0.1.1

package/dist/src/cli/directCommands.js

@@ -0,0 +1,143 @@
+/**
+ * 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 { createPhaseHandler, getPhaseOrder } from '../phases/phaseHandlers.js';
+import { classifyError, toUserMessage } from '../shared/errorClassifier.js';
+// ── Validation ───────────────────────────────────────────────────────────────
+const VALID_PHASES = getPhaseOrder();
+function validateInputs(opts) {
+    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, message) {
+    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) {
+    // 1. Validate inputs
+    const validationError = validateInputs(opts);
+    if (validationError)
+        return validationError;
+    // 2. Load session
+    let session;
+    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) {
+        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;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            session = await runPhase(session, opts);
+            return { exitCode: 0 };
+        }
+        catch (err) {
+            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, opts) {
+    const phase = session.phase;
+    const handler = createPhaseHandler(phase);
+    await handler._preload();
+    const events = [];
+    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/dist/src/cli/envLoader.js

@@ -0,0 +1,16 @@
+/**
+ * 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) {
+    config({ path: envPath, override: false, quiet: true });
+}

package/dist/src/cli/exportCommand.js

@@ -0,0 +1,53 @@
+/**
+ * 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 async function exportCommand(opts) {
+    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})`);
+        }
+    }
+}

package/dist/src/cli/index.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * sofIA CLI entrypoint.
+ *
+ * Provides the main `sofia` command. Running `sofia` with no subcommand
+ * starts the workshop flow (default). Explicit subcommands:
+ * - workshop: alias for the default workshop flow
+ * - status: display session status
+ * - export: export session artifacts
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+import { loadEnvFile } from './envLoader.js';
+// ── Load .env from workspace root ──────────────────────────────────────────
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+loadEnvFile(path.resolve(__dirname, '../../.env'));
+// ── Build CLI ──────────────────────────────────────────────────────────────
+/**
+ * Build the Commander program. Accepts optional handler overrides for testing.
+ * When handlers are not provided, they dynamically import the real modules.
+ */
+export function buildCli(handlers) {
+    const program = new Command();
+    program.name('sofia').description('sofIA — AI Discovery Workshop CLI').version('0.1.0');
+    // ── Global options ──────────────────────────────────────────────────────
+    program
+        .option('--session <id>', 'Target an existing session')
+        .option('--json', 'Emit machine-readable JSON only on stdout')
+        .option('--debug', 'Enable debug telemetry')
+        .option('--log-file <path>', 'Write structured logs to file')
+        .option('--non-interactive', 'Disallow prompts; fail with actionable error if input is missing');
+    // ── Workshop options promoted to top level (FR-004) ──────────────────────
+    program
+        .option('--new-session', 'Start a new session')
+        .option('--phase <phase>', 'Jump to a specific phase')
+        .option('--retry <count>', 'Retry transient failures N times', parseInt);
+    // ── Workshop handler logic ──────────────────────────────────────────────
+    async function invokeWorkshopHandler(programOpts, cmdOpts) {
+        const merged = { ...programOpts, ...cmdOpts };
+        if (handlers?.workshopHandler) {
+            await handlers.workshopHandler(merged);
+            return;
+        }
+        // Direct command mode: if --session and --phase are both specified
+        if (merged.session && merged.phase) {
+            const { runDirectCommand } = await import('./directCommands.js');
+            const { createLoopIO } = await import('./ioContext.js');
+            const { createDefaultStore } = await import('../sessions/sessionStore.js');
+            const { createCopilotClient } = await import('../shared/copilotClient.js');
+            const { getLogger } = await import('../logging/logger.js');
+            const store = createDefaultStore();
+            const io = createLoopIO({
+                json: merged.json,
+                nonInteractive: merged.nonInteractive,
+            });
+            let client;
+            try {
+                client = await createCopilotClient();
+            }
+            catch (err) {
+                const logger = getLogger();
+                logger.error({ err }, 'Failed to create Copilot client — cannot run direct command');
+                const msg = err instanceof Error ? err.message : 'Unknown error creating Copilot client';
+                if (merged.json) {
+                    process.stdout.write(JSON.stringify({ error: msg }) + '\n');
+                }
+                else {
+                    console.error(`Error: ${msg}`);
+                }
+                process.exitCode = 1;
+                return;
+            }
+            const result = await runDirectCommand({
+                sessionId: merged.session,
+                phase: merged.phase,
+                store,
+                client,
+                io,
+                nonInteractive: merged.nonInteractive,
+                json: merged.json,
+                debug: merged.debug,
+                retry: merged.retry,
+            });
+            process.exitCode = result.exitCode;
+            return;
+        }
+        const { workshopCommand } = await import('./workshopCommand.js');
+        await workshopCommand(merged);
+    }
+    // ── Workshop command (default + alias) ─────────────────────────────────
+    program
+        .command('workshop', { isDefault: true })
+        .description('Start or resume a governed AI Discovery Workshop session')
+        .action(async () => {
+        const opts = program.opts();
+        await invokeWorkshopHandler(opts);
+    });
+    // ── Status command ────────────────────────────────────────────────────
+    program
+        .command('status')
+        .description('Display session status and next expected action')
+        .action(async () => {
+        if (handlers?.statusHandler) {
+            await handlers.statusHandler(program.opts());
+            return;
+        }
+        const { statusCommand } = await import('./statusCommand.js');
+        const globalOpts = program.opts();
+        await statusCommand(globalOpts);
+    });
+    // ── Export command ────────────────────────────────────────────────────
+    program
+        .command('export')
+        .description('Export workshop artifacts for a session')
+        .option('--output <dir>', 'Output directory (default: ./exports/<sessionId>/)')
+        .action(async (opts) => {
+        if (handlers?.exportHandler) {
+            await handlers.exportHandler({ ...program.opts(), ...opts });
+            return;
+        }
+        const { exportCommand } = await import('./exportCommand.js');
+        const globalOpts = program.opts();
+        await exportCommand({ ...globalOpts, ...opts });
+    });
+    // ── Dev command ───────────────────────────────────────────────────────
+    program
+        .command('dev')
+        .description('Generate a proof-of-concept repository for a completed workshop session')
+        .option('--max-iterations <n>', 'Maximum Ralph loop iterations (default: 20)', parseInt)
+        .option('--output <dir>', 'Output directory for the PoC (default: ./poc/<sessionId>/)')
+        .option('--force', 'Overwrite existing output directory and start fresh')
+        .action(async (opts) => {
+        const { developCommand } = await import('./developCommand.js');
+        const { createDefaultStore } = await import('../sessions/sessionStore.js');
+        const { createLoopIO } = await import('./ioContext.js');
+        const { createCopilotClient } = await import('../shared/copilotClient.js');
+        const { getLogger } = await import('../logging/logger.js');
+        const { loadMcpConfig, McpManager } = await import('../mcp/mcpManager.js');
+        const { join: pathJoin } = await import('node:path');
+        const globalOpts = program.opts();
+        const merged = { ...globalOpts, ...opts };
+        const store = createDefaultStore();
+        const io = createLoopIO({
+            json: merged.json,
+            nonInteractive: merged.nonInteractive,
+        });
+        let client;
+        try {
+            client = await createCopilotClient();
+        }
+        catch (err) {
+            const logger = getLogger();
+            logger.error({ err }, 'Failed to create Copilot client');
+            const msg = err instanceof Error ? err.message : 'Unknown error creating Copilot client';
+            if (merged.json) {
+                process.stdout.write(JSON.stringify({ error: msg }) + '\n');
+            }
+            else {
+                process.stderr.write(`Error: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        // Load MCP config and wire adapters when MCP servers are configured
+        const mcpConfigPath = pathJoin(process.cwd(), '.vscode', 'mcp.json');
+        let mcpManager;
+        try {
+            const mcpConfig = await loadMcpConfig(mcpConfigPath);
+            if (Object.keys(mcpConfig.servers).length > 0) {
+                mcpManager = new McpManager(mcpConfig);
+                // Mark all configured servers as connected (optimistic: actual MCP failures
+                // degrade gracefully inside GitHubMcpAdapter / McpContextEnricher)
+                for (const name of mcpManager.listServers()) {
+                    mcpManager.markConnected(name);
+                }
+            }
+        }
+        catch {
+            // MCP config is optional — proceed without it
+        }
+        await developCommand(merged, {
+            store,
+            io,
+            client,
+            mcpManager,
+        });
+    });
+    return program;
+}
+// ── Auto-parse when run as CLI entrypoint ─────────────────────────────────
+// Only auto-parse when running as the main CLI entrypoint, not when imported for testing
+const isMainModule = process.argv[1] &&
+    (process.argv[1].endsWith('/cli/index.js') ||
+        process.argv[1].endsWith('/cli/index.ts') ||
+        process.argv[1].endsWith('sofia'));
+if (isMainModule) {
+    const program = buildCli();
+    program.parseAsync(process.argv).catch((err) => {
+        console.error(err instanceof Error ? err.message : 'Unknown error');
+        process.exit(1);
+    });
+}

package/dist/src/cli/ioContext.js

@@ -0,0 +1,109 @@
+/**
+ * IO Context.
+ *
+ * Detects TTY vs non-TTY, JSON mode, and provides the LoopIO
+ * implementation for the ConversationLoop based on CLI options.
+ */
+import * as readline from 'node:readline';
+import { renderMarkdown } from '../shared/markdownRenderer.js';
+/**
+ * Create a LoopIO implementation based on CLI context.
+ */
+export function createLoopIO(options = {}) {
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    const errorOutput = options.errorOutput ?? process.stderr;
+    const isTTY = !options.nonInteractive && Boolean(input.isTTY);
+    const isJsonMode = options.json ?? false;
+    const isDebug = options.debug ?? false;
+    let rl = null;
+    let rlClosed = false;
+    function getReadline() {
+        if (!rl || rlClosed) {
+            rlClosed = false;
+            rl = readline.createInterface({
+                input: input,
+                output: isTTY ? output : undefined,
+                terminal: isTTY,
+            });
+            rl.on('close', () => { rlClosed = true; });
+        }
+        return rl;
+    }
+    return {
+        write(text) {
+            output.write(text);
+        },
+        writeActivity(text) {
+            if (!isJsonMode) {
+                errorOutput.write(`[activity] ${text}\n`);
+            }
+        },
+        writeToolSummary(toolName, summary, details) {
+            if (isJsonMode || options.nonInteractive)
+                return;
+            errorOutput.write(`✓ ${toolName}: ${summary}\n`);
+            if (isDebug && details) {
+                if (details.args) {
+                    errorOutput.write(`  args: ${JSON.stringify(details.args, null, 2)}\n`);
+                }
+                if (details.result !== undefined) {
+                    errorOutput.write(`  result: ${JSON.stringify(details.result, null, 2)}\n`);
+                }
+            }
+        },
+        async readInput(prompt) {
+            if (options.nonInteractive) {
+                return null; // Non-interactive mode: no input
+            }
+            return new Promise((resolve) => {
+                const r = getReadline();
+                r.question(prompt ?? '> ', (answer) => {
+                    resolve(answer);
+                });
+                r.once('close', () => resolve(null));
+            });
+        },
+        async showDecisionGate(phase) {
+            if (isJsonMode || options.nonInteractive) {
+                return { choice: 'continue' };
+            }
+            const phaseOrder = [
+                'Discover', 'Ideate', 'Design', 'Select', 'Plan', 'Develop', 'Complete',
+            ];
+            const currentIdx = phaseOrder.indexOf(phase);
+            const nextPhase = currentIdx < phaseOrder.length - 1 ? phaseOrder[currentIdx + 1] : null;
+            const rendered = renderMarkdown(`\n---\n\n**Phase "${phase}" complete.**\n\n` +
+                `Options:\n` +
+                `  1. Continue to ${nextPhase ?? 'Complete'}\n` +
+                `  2. Refine current phase\n` +
+                `  3. Return to main menu\n` +
+                `  4. Exit\n`, { isTTY });
+            output.write(rendered);
+            return new Promise((resolve) => {
+                const r = getReadline();
+                r.question('Choose [1-4]: ', (answer) => {
+                    const choiceMap = {
+                        '1': 'continue',
+                        '2': 'refine',
+                        '3': 'menu',
+                        '4': 'exit',
+                    };
+                    const choice = choiceMap[answer.trim()] ?? 'continue';
+                    resolve({
+                        choice,
+                        targetPhase: choice === 'continue' ? (nextPhase ?? undefined) : undefined,
+                    });
+                });
+            });
+        },
+        isJsonMode,
+        isTTY,
+    };
+}
+/**
+ * Close any open readline interfaces.
+ */
+export function closeIO(_io) {
+    // The IO might hold a readline interface — no-op if not applicable
+}

package/dist/src/cli/preflight.js

@@ -0,0 +1,57 @@
+/**
+ * Preflight checks — validates environment readiness before starting a workshop.
+ *
+ * Each check returns a PreflightCheck result. runPreflightChecks() collects all
+ * results, never short-circuits, and returns an aggregate PreflightResult.
+ */
+/**
+ * Run all preflight checks in parallel and aggregate results.
+ *
+ * - Checks that throw are caught and reported as fail with `required: true`.
+ * - Overall pass requires that no check with `required !== false` has status 'fail'.
+ */
+export async function runPreflightChecks(checks) {
+    const entries = Object.entries(checks);
+    const results = await Promise.all(entries.map(async ([key, fn]) => {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                name: key.replace(/^check/, '').replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, ''),
+                status: 'fail',
+                message,
+                required: true,
+            };
+        }
+    }));
+    const passed = results.every((c) => c.status !== 'fail' || c.required === false);
+    return { passed, checks: results };
+}
+/**
+ * Check for legacy web search env vars (FR-016).
+ *
+ * If `SOFIA_FOUNDRY_AGENT_ENDPOINT` or `SOFIA_FOUNDRY_AGENT_KEY` are set,
+ * returns a fail result with migration instructions.
+ */
+export async function checkLegacyWebSearchEnvVars() {
+    const legacyEndpoint = process.env.SOFIA_FOUNDRY_AGENT_ENDPOINT;
+    const legacyKey = process.env.SOFIA_FOUNDRY_AGENT_KEY;
+    if (legacyEndpoint || legacyKey) {
+        return {
+            name: 'legacy-web-search-env',
+            status: 'fail',
+            message: 'Legacy web search env vars detected. ' +
+                'Migrate: replace SOFIA_FOUNDRY_AGENT_ENDPOINT with FOUNDRY_PROJECT_ENDPOINT ' +
+                'and remove SOFIA_FOUNDRY_AGENT_KEY (API key auth is no longer used). ' +
+                'See docs/environment.md',
+            required: true,
+        };
+    }
+    return {
+        name: 'legacy-web-search-env',
+        status: 'pass',
+        message: 'No legacy web search env vars detected',
+    };
+}