sofia-cli 0.1.1

package/src/cli/index.ts

@@ -0,0 +1,249 @@
+#!/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';
+import type { PhaseValue } from '../shared/schemas/session.js';
+
+// ── Load .env from workspace root ──────────────────────────────────────────
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+loadEnvFile(path.resolve(__dirname, '../../.env'));
+
+// ── Handler types ──────────────────────────────────────────────────────────
+
+export interface CliHandlers {
+  workshopHandler: (opts: Record<string, unknown>) => Promise<void>;
+  statusHandler: (opts: Record<string, unknown>) => Promise<void>;
+  exportHandler: (opts: Record<string, unknown>) => Promise<void>;
+}
+
+// ── 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?: Partial<CliHandlers>): Command {
+  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: Record<string, unknown>,
+    cmdOpts?: Record<string, unknown>,
+  ): Promise<void> {
+    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 as boolean,
+        nonInteractive: merged.nonInteractive as boolean,
+      });
+
+      let client;
+      try {
+        client = await createCopilotClient();
+      } catch (err: unknown) {
+        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 as string,
+        phase: merged.phase as PhaseValue,
+        store,
+        client,
+        io,
+        nonInteractive: merged.nonInteractive as boolean,
+        json: merged.json as boolean,
+        debug: merged.debug as boolean,
+        retry: merged.retry as number,
+      });
+
+      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 as boolean,
+        nonInteractive: merged.nonInteractive as boolean,
+      });
+
+      let client;
+      try {
+        client = await createCopilotClient();
+      } catch (err: unknown) {
+        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: import('../mcp/mcpManager.js').McpManager | undefined;
+      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 as Parameters<typeof developCommand>[0], {
+        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/src/cli/ioContext.ts

@@ -0,0 +1,139 @@
+/**
+ * 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 type { LoopIO, DecisionGateResult, DecisionGateChoice } from '../loop/conversationLoop.js';
+import type { PhaseValue } from '../shared/schemas/session.js';
+import { renderMarkdown } from '../shared/markdownRenderer.js';
+
+export interface IoContextOptions {
+  json?: boolean;
+  nonInteractive?: boolean;
+  debug?: boolean;
+  input?: NodeJS.ReadableStream;
+  output?: NodeJS.WritableStream;
+  errorOutput?: NodeJS.WritableStream;
+}
+
+/**
+ * Create a LoopIO implementation based on CLI context.
+ */
+export function createLoopIO(options: IoContextOptions = {}): LoopIO {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const errorOutput = options.errorOutput ?? process.stderr;
+  const isTTY = !options.nonInteractive && Boolean((input as NodeJS.ReadStream).isTTY);
+  const isJsonMode = options.json ?? false;
+  const isDebug = options.debug ?? false;
+
+  let rl: readline.Interface | null = null;
+  let rlClosed = false;
+
+  function getReadline(): readline.Interface {
+    if (!rl || rlClosed) {
+      rlClosed = false;
+      rl = readline.createInterface({
+        input: input as NodeJS.ReadableStream,
+        output: isTTY ? (output as NodeJS.WritableStream) : undefined,
+        terminal: isTTY,
+      });
+      rl.on('close', () => { rlClosed = true; });
+    }
+    return rl;
+  }
+
+  return {
+    write(text: string): void {
+      (output as NodeJS.WritableStream).write(text);
+    },
+
+    writeActivity(text: string): void {
+      if (!isJsonMode) {
+        (errorOutput as NodeJS.WritableStream).write(`[activity] ${text}\n`);
+      }
+    },
+
+    writeToolSummary(toolName: string, summary: string, details?: { args?: Record<string, unknown>; result?: unknown }): void {
+      if (isJsonMode || options.nonInteractive) return;
+
+      (errorOutput as NodeJS.WritableStream).write(`✓ ${toolName}: ${summary}\n`);
+
+      if (isDebug && details) {
+        if (details.args) {
+          (errorOutput as NodeJS.WritableStream).write(`  args: ${JSON.stringify(details.args, null, 2)}\n`);
+        }
+        if (details.result !== undefined) {
+          (errorOutput as NodeJS.WritableStream).write(`  result: ${JSON.stringify(details.result, null, 2)}\n`);
+        }
+      }
+    },
+
+    async readInput(prompt?: string): Promise<string | null> {
+      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: PhaseValue): Promise<DecisionGateResult> {
+      if (isJsonMode || options.nonInteractive) {
+        return { choice: 'continue' };
+      }
+
+      const phaseOrder: PhaseValue[] = [
+        '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 as NodeJS.WritableStream).write(rendered);
+
+      return new Promise((resolve) => {
+        const r = getReadline();
+        r.question('Choose [1-4]: ', (answer) => {
+          const choiceMap: Record<string, DecisionGateChoice> = {
+            '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: LoopIO): void {
+  // The IO might hold a readline interface — no-op if not applicable
+}

package/src/cli/preflight.ts

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+
+/** Result of a single check. */
+export interface PreflightCheck {
+  name: string;
+  status: 'pass' | 'warn' | 'fail';
+  message: string;
+  /** If true (default), a 'fail' status causes overall failure. */
+  required?: boolean;
+}
+
+/** Aggregate result of all checks. */
+export interface PreflightResult {
+  passed: boolean;
+  checks: PreflightCheck[];
+}
+
+/** A map of named async check functions. */
+export type CheckMap = Record<string, () => Promise<PreflightCheck>>;
+
+/**
+ * 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: CheckMap): Promise<PreflightResult> {
+  const entries = Object.entries(checks);
+
+  const results = await Promise.all(
+    entries.map(async ([key, fn]) => {
+      try {
+        return await fn();
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          name: key.replace(/^check/, '').replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, ''),
+          status: 'fail' as const,
+          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(): Promise<PreflightCheck> {
+  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',
+  };
+}

package/src/cli/statusCommand.ts

@@ -0,0 +1,118 @@
+/**
+ * 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 interface StatusCommandOptions {
+  session?: string;
+  json?: boolean;
+  debug?: boolean;
+  logFile?: string;
+  nonInteractive?: boolean;
+}
+
+export async function statusCommand(opts: StatusCommandOptions): Promise<void> {
+  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: string[][] = [];
+      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: Record<string, unknown> = {
+      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('');
+  }
+}