sofia-cli 0.1.1

package/src/logging/logger.ts

@@ -0,0 +1,73 @@
+/**
+ * Logger setup with pino.
+ *
+ * Features:
+ * - File logging when --log-file is provided
+ * - Stderr logging by default
+ * - Automatic redaction of secrets/PII (password, token, secret, key, auth)
+ */
+import pino from 'pino';
+import type { Logger } from 'pino';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export interface LoggerOptions {
+  logFile?: string;
+  level?: string;
+  name?: string;
+}
+
+const REDACT_PATHS = [
+  'password',
+  'token',
+  'secret',
+  'apiKey',
+  'api_key',
+  'authorization',
+  'auth',
+  'credential',
+  'credentials',
+];
+
+/**
+ * Create a configured pino logger.
+ *
+ * If logFile is specified, logs go to the file.
+ * Otherwise, logs go to stderr (to keep stdout clean for CLI output).
+ */
+export function createLogger(options: LoggerOptions = {}): Logger {
+  const { logFile, level = 'info', name = 'sofia' } = options;
+
+  const pinoOpts: pino.LoggerOptions = {
+    name,
+    level,
+    redact: {
+      paths: REDACT_PATHS,
+      censor: '[REDACTED]',
+    },
+  };
+
+  if (logFile) {
+    mkdirSync(dirname(logFile), { recursive: true });
+    const dest = pino.destination({ dest: logFile, sync: false });
+    return pino(pinoOpts, dest);
+  }
+
+  // Default: write to stderr to keep stdout clean
+  return pino(pinoOpts, pino.destination({ dest: 2, sync: false }));
+}
+
+/** Global logger instance; call initGlobalLogger() to configure it. */
+let globalLogger: Logger | undefined;
+
+export function initGlobalLogger(options: LoggerOptions = {}): Logger {
+  globalLogger = createLogger(options);
+  return globalLogger;
+}
+
+export function getLogger(): Logger {
+  if (!globalLogger) {
+    globalLogger = createLogger();
+  }
+  return globalLogger;
+}

package/src/loop/conversationLoop.ts

@@ -0,0 +1,355 @@
+/**
+ * ConversationLoop abstraction.
+ *
+ * Orchestrates multi-turn conversations with the LLM in a phase-based workflow.
+ * Handles:
+ * - Streaming renderer (incremental text output)
+ * - Event dispatching (TextDelta, Activity, ToolCall, etc.)
+ * - Ctrl+C handling (graceful shutdown)
+ * - Decision gates between phases
+ *
+ * Single entry point for all phase-based conversations to avoid
+ * duplicate inline multi-turn loops (FR-015).
+ */
+import type {
+  ConversationSession,
+  CopilotClient,
+  CopilotMessage,
+  SessionOptions,
+} from '../shared/copilotClient.js';
+import type { SofiaEvent } from '../shared/events.js';
+import { createActivityEvent } from '../shared/events.js';
+import { renderMarkdown } from '../shared/markdownRenderer.js';
+import type { ActivitySpinner } from '../shared/activitySpinner.js';
+import { createNoOpSpinner } from '../shared/activitySpinner.js';
+import type { PhaseValue } from '../shared/schemas/session.js';
+import type { WorkshopSession } from '../shared/schemas/session.js';
+import { phaseSummarize } from './phaseSummarizer.js';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type DecisionGateChoice = 'continue' | 'refine' | 'choose-phase' | 'menu' | 'exit';
+
+export interface DecisionGateResult {
+  choice: DecisionGateChoice;
+  targetPhase?: PhaseValue;
+}
+
+export interface LoopIO {
+  /** Write text to the user (stdout or equivalent). */
+  write(text: string): void;
+  /** Write activity/telemetry to stderr. */
+  writeActivity(text: string): void;
+  /** Write a tool completion summary to stderr. */
+  writeToolSummary(
+    toolName: string,
+    summary: string,
+    details?: { args?: Record<string, unknown>; result?: unknown },
+  ): void;
+  /** Read user input. Returns the input string or null on EOF/Ctrl+D. */
+  readInput(prompt?: string): Promise<string | null>;
+  /** Show the decision gate and get user choice. */
+  showDecisionGate(phase: PhaseValue): Promise<DecisionGateResult>;
+  /** Check if running in JSON mode. */
+  isJsonMode: boolean;
+  /** Check if TTY. */
+  isTTY: boolean;
+}
+
+export interface PhaseHandler {
+  /** The phase this handler manages. */
+  phase: PhaseValue;
+  /** Build the system prompt for this phase. */
+  buildSystemPrompt(session: WorkshopSession): string;
+  /** Get reference documents to include. */
+  getReferences?(session: WorkshopSession): string[];
+  /** Post-process the phase result (extract structured data, update session). */
+  extractResult(session: WorkshopSession, response: string): Partial<WorkshopSession>;
+  /** Optional async hook called after extractResult to perform async enrichment. */
+  postExtract?(session: WorkshopSession): Promise<Partial<WorkshopSession>>;
+  /** Optional: determine if the phase is complete based on conversation. */
+  isComplete?(session: WorkshopSession, response: string): boolean;
+  /** Generate the initial message to send to the LLM at phase start. */
+  getInitialMessage?(session: WorkshopSession): string;
+}
+
+export interface ConversationLoopOptions {
+  client: CopilotClient;
+  io: LoopIO;
+  session: WorkshopSession;
+  phaseHandler: PhaseHandler;
+  onEvent?: (event: SofiaEvent) => void;
+  onSessionUpdate?: (session: WorkshopSession) => Promise<void>;
+  /** If provided, send this message to the LLM before waiting for user input (auto-start). */
+  initialMessage?: string;
+  /** Activity spinner for visual feedback (no-op spinner used if omitted). */
+  spinner?: ActivitySpinner;
+}
+
+// ── ConversationLoop ─────────────────────────────────────────────────────────
+
+export class ConversationLoop {
+  private aborted = false;
+  private session: WorkshopSession;
+  private readonly client: CopilotClient;
+  private readonly io: LoopIO;
+  private readonly handler: PhaseHandler;
+  private readonly onEvent: (event: SofiaEvent) => void;
+  private readonly onSessionUpdate: (session: WorkshopSession) => Promise<void>;
+  private readonly initialMessage?: string;
+  private readonly spinner: ActivitySpinner;
+
+  constructor(options: ConversationLoopOptions) {
+    this.client = options.client;
+    this.io = options.io;
+    this.session = { ...options.session };
+    this.handler = options.phaseHandler;
+    this.onEvent = options.onEvent ?? (() => {});
+    this.onSessionUpdate = options.onSessionUpdate ?? (async () => {});
+    this.initialMessage = options.initialMessage;
+    this.spinner = options.spinner ?? createNoOpSpinner();
+  }
+
+  /** Run the conversation loop for the current phase. */
+  async run(): Promise<WorkshopSession> {
+    this.setupSignalHandler();
+
+    let systemPrompt = this.handler.buildSystemPrompt(this.session);
+
+    // FR-007b, FR-007c: Inject phase boundary instruction to prevent LLM drift
+    systemPrompt += `\n\nYou are in the ${this.handler.phase} phase. Do NOT introduce or begin the next phase. The user will be offered a decision gate when this phase is complete.`;
+
+    // Inject prior conversation history into the system prompt when resuming
+    // so the LLM has context from previous turns in this phase.
+    const priorTurns = (this.session.turns ?? []).filter((t) => t.phase === this.handler.phase);
+    if (priorTurns.length > 0) {
+      const historyBlock = priorTurns.map((t) => `[${t.role}]: ${t.content}`).join('\n\n');
+      systemPrompt += `\n\n## Previous conversation history\n\n${historyBlock}`;
+    }
+
+    const references = this.handler.getReferences?.(this.session) ?? [];
+    const sessionOpts: SessionOptions = { systemPrompt, references };
+
+    const conversationSession = await this.client.createSession(sessionOpts);
+
+    this.emitEvent(createActivityEvent(`Starting ${this.handler.phase} phase`));
+
+    // Auto-start: send initial message to LLM before waiting for user input
+    if (this.initialMessage) {
+      const response = await this.streamResponse(conversationSession, {
+        role: 'user',
+        content: this.initialMessage,
+      });
+
+      const now = new Date().toISOString();
+      const turns = this.session.turns ?? [];
+      turns.push(
+        {
+          phase: this.handler.phase,
+          sequence: turns.length + 1,
+          role: 'user',
+          content: this.initialMessage,
+          timestamp: now,
+        },
+        {
+          phase: this.handler.phase,
+          sequence: turns.length + 2,
+          role: 'assistant',
+          content: response,
+          timestamp: now,
+        },
+      );
+
+      const updates = this.handler.extractResult(this.session, response);
+      this.session = {
+        ...this.session,
+        ...updates,
+        turns,
+        updatedAt: now,
+      };
+
+      // Run async post-extraction hook if present (e.g., discovery enrichment)
+      if (this.handler.postExtract) {
+        const postUpdates = await this.handler.postExtract(this.session);
+        this.session = { ...this.session, ...postUpdates, updatedAt: new Date().toISOString() };
+      }
+
+      await this.onSessionUpdate(this.session);
+    }
+
+    // Main conversation loop
+    while (!this.aborted) {
+      const userInput = await this.io.readInput(`[${this.handler.phase}] > `);
+
+      if (userInput === null) {
+        // EOF / Ctrl+D — treat as "done" signal
+        break;
+      }
+
+      const trimmed = userInput.trim();
+      if (trimmed.toLowerCase() === 'done' || trimmed === '') {
+        // Check if handler considers the phase complete
+        if (this.handler.isComplete?.(this.session, '') !== false) {
+          break;
+        }
+        // Otherwise continue the conversation
+      }
+
+      // Send user message and stream response
+      const response = await this.streamResponse(conversationSession, {
+        role: 'user',
+        content: trimmed,
+      });
+
+      // Accumulate turn history
+      const now = new Date().toISOString();
+      const turns = this.session.turns ?? [];
+      turns.push(
+        {
+          phase: this.handler.phase,
+          sequence: turns.length + 1,
+          role: 'user',
+          content: trimmed,
+          timestamp: now,
+        },
+        {
+          phase: this.handler.phase,
+          sequence: turns.length + 2,
+          role: 'assistant',
+          content: response,
+          timestamp: now,
+        },
+      );
+
+      // Extract structured data from the response
+      const updates = this.handler.extractResult(this.session, response);
+
+      this.session = {
+        ...this.session,
+        ...updates,
+        turns,
+        updatedAt: now,
+      };
+
+      // Run async post-extraction hook if present (e.g., discovery enrichment)
+      if (this.handler.postExtract) {
+        const postUpdates = await this.handler.postExtract(this.session);
+        this.session = { ...this.session, ...postUpdates, updatedAt: new Date().toISOString() };
+      }
+
+      // Persist after every turn (FR-039a)
+      await this.onSessionUpdate(this.session);
+    }
+
+    // FR-006: Post-phase summarization fallback
+    // If structured data wasn't extracted during conversation, try a dedicated summarization call
+    try {
+      const summarizationUpdates = await phaseSummarize(
+        this.client,
+        this.handler.phase,
+        this.session,
+        this.handler,
+      );
+      if (Object.keys(summarizationUpdates).length > 0) {
+        this.session = {
+          ...this.session,
+          ...summarizationUpdates,
+          updatedAt: new Date().toISOString(),
+        };
+        await this.onSessionUpdate(this.session);
+      }
+    } catch {
+      // Summarization failure is non-fatal
+    }
+
+    return this.session;
+  }
+
+  /** Stream response from the LLM and render incrementally. */
+  private async streamResponse(
+    session: ConversationSession,
+    message: CopilotMessage,
+  ): Promise<string> {
+    const chunks: string[] = [];
+    let firstTextDelta = true;
+
+    // Start "Thinking..." spinner before sending
+    this.spinner.startThinking();
+
+    try {
+      for await (const event of session.send(message)) {
+        // Check if user pressed Ctrl+C during streaming
+        if (this.aborted) break;
+
+        this.emitEvent(event);
+
+        if (event.type === 'TextDelta') {
+          // Stop spinner on first text output
+          if (firstTextDelta) {
+            this.spinner.stop();
+            firstTextDelta = false;
+          }
+
+          chunks.push(event.text);
+          if (!this.io.isJsonMode) {
+            // Render markdown for TTY, raw for non-TTY
+            if (this.io.isTTY) {
+              this.io.write(renderMarkdown(event.text, { isTTY: true }));
+            } else {
+              this.io.write(event.text);
+            }
+          }
+        } else if (event.type === 'Activity') {
+          this.io.writeActivity(event.message);
+        } else if (event.type === 'ToolCall') {
+          this.spinner.startToolCall(event.toolName);
+        } else if (event.type === 'ToolResult') {
+          const summary =
+            typeof event.result === 'string'
+              ? event.result
+              : JSON.stringify(event.result).slice(0, 120);
+          this.spinner.completeToolCall(event.toolName, summary);
+          this.io.writeToolSummary(event.toolName, summary);
+          // Resume thinking spinner in case more processing follows
+          this.spinner.startThinking();
+        }
+      }
+    } finally {
+      // Always stop spinner — prevents cursor-hidden state on errors
+      this.spinner.stop();
+    }
+
+    const fullResponse = chunks.join('');
+
+    // In JSON mode, output the full rendered response
+    if (this.io.isJsonMode) {
+      this.io.write(JSON.stringify({ phase: this.handler.phase, content: fullResponse }));
+    } else {
+      this.io.write('\n');
+    }
+
+    return fullResponse;
+  }
+
+  private emitEvent(event: SofiaEvent): void {
+    this.onEvent(event);
+  }
+
+  private setupSignalHandler(): void {
+    const handler = () => {
+      this.aborted = true;
+      this.emitEvent(createActivityEvent('Ctrl+C received — finishing current turn'));
+    };
+    // Avoid MaxListenersExceededWarning when many loops are created in tests
+    const current = process.listenerCount('SIGINT');
+    if (current >= 10) {
+      process.setMaxListeners(current + 1);
+    }
+    process.once('SIGINT', handler);
+  }
+
+  /** Get the current session state. */
+  getSession(): WorkshopSession {
+    return { ...this.session };
+  }
+}

package/src/loop/phaseSummarizer.ts

@@ -0,0 +1,114 @@
+/**
+ * Post-phase summarization utility.
+ *
+ * When the conversation loop finishes a phase and the expected structured
+ * session field is still null, this module makes a one-shot LLM call to
+ * extract structured data from the full conversation transcript.
+ *
+ * Contract: specs/006-workshop-extraction-fixes/contracts/summarization-and-export.md
+ * FRs: FR-001 through FR-007
+ */
+import type { CopilotClient } from '../shared/copilotClient.js';
+import type { PhaseValue, WorkshopSession } from '../shared/schemas/session.js';
+import type { PhaseHandler } from './conversationLoop.js';
+import { loadSummarizationPrompt } from '../prompts/promptLoader.js';
+
+// ── Phase → session field mapping ────────────────────────────────────────────
+
+const PHASE_SESSION_FIELD: Record<string, keyof WorkshopSession> = {
+  Discover: 'businessContext',
+  Ideate: 'ideas',
+  Design: 'evaluation',
+  Select: 'selection',
+  Plan: 'plan',
+  Develop: 'poc',
+};
+
+/**
+ * Check whether a phase needs post-phase summarization.
+ * Returns true if the session field for this phase is null/undefined.
+ */
+export function needsSummarization(phase: PhaseValue, session: WorkshopSession): boolean {
+  const fieldName = PHASE_SESSION_FIELD[phase];
+  if (!fieldName) return false;
+  const value = session[fieldName];
+  return value === undefined || value === null;
+}
+
+/**
+ * Build a concatenated transcript from conversation turns for a specific phase.
+ */
+export function buildPhaseTranscript(phase: PhaseValue, session: WorkshopSession): string {
+  const turns = (session.turns ?? []).filter((t) => t.phase === phase);
+  if (turns.length === 0) return '';
+  return turns.map((t) => `[${t.role}]: ${t.content}`).join('\n\n');
+}
+
+/**
+ * Post-phase summarization call.
+ *
+ * If the expected structured field for `phase` is still null after the
+ * conversation loop, makes a one-shot LLM call to extract it from the
+ * full transcript.
+ *
+ * Returns partial session updates (may be empty if extraction still fails).
+ * Never throws — summarization is a best-effort fallback.
+ */
+export async function phaseSummarize(
+  client: CopilotClient,
+  phase: PhaseValue,
+  session: WorkshopSession,
+  handler: PhaseHandler,
+): Promise<Partial<WorkshopSession>> {
+  // Skip if field is already populated
+  if (!needsSummarization(phase, session)) {
+    return {};
+  }
+
+  // Build the transcript
+  const transcript = buildPhaseTranscript(phase, session);
+  if (!transcript) {
+    return {};
+  }
+
+  try {
+    // Load the phase-specific summarization prompt
+    const systemPrompt = await loadSummarizationPrompt(phase);
+
+    // Create a new session for the summarization call (avoids polluting context)
+    const summarizationSession = await client.createSession({ systemPrompt });
+
+    // Send the transcript as a single user message and collect the full response
+    const chunks: string[] = [];
+    for await (const event of summarizationSession.send({
+      role: 'user',
+      content: transcript,
+    })) {
+      if (event.type === 'TextDelta') {
+        chunks.push(event.text);
+      }
+    }
+    const response = chunks.join('');
+
+    // Extract structured data using the phase handler's extractResult
+    const updates = handler.extractResult(session, response);
+
+    // For Design phase, also extract Mermaid diagram (FR-007a)
+    // Store in plan.architectureNotes if available (session schema doesn't have
+    // a dedicated architectureDiagram field)
+    if (phase === 'Design') {
+      const mermaidMatch = response.match(/```mermaid\s*\n([\s\S]*?)\n```/);
+      if (mermaidMatch) {
+        const diagram = mermaidMatch[1].trim();
+        if (!updates.plan) {
+          updates.plan = { milestones: [], architectureNotes: diagram };
+        }
+      }
+    }
+
+    return updates;
+  } catch {
+    // Summarization failure is non-fatal — log and return empty
+    return {};
+  }
+}