sofia-cli 0.1.1

package/src/phases/discoveryEnricher.ts

@@ -0,0 +1,223 @@
+/**
+ * Discovery Phase Enrichment.
+ *
+ * After the user provides company information in Step 1, this module
+ * optionally enriches the session with web search results and WorkIQ insights.
+ *
+ * Contract: specs/003-mcp-transport-integration/contracts/discovery-enricher.md
+ */
+import type { McpManager } from '../mcp/mcpManager.js';
+import type { LoopIO } from '../loop/conversationLoop.js';
+import type { ActivitySpinner } from '../shared/activitySpinner.js';
+import type { DiscoveryEnrichment } from '../shared/schemas/session.js';
+import type { WebSearchResult } from '../mcp/webSearch.js';
+
+// ── WebSearchClient interface ────────────────────────────────────────────────
+
+export interface WebSearchClient {
+  search(query: string): Promise<WebSearchResult>;
+}
+
+// ── Options ──────────────────────────────────────────────────────────────────
+
+export interface DiscoveryEnricherOptions {
+  /** Company and team summary from Step 1 */
+  companySummary: string;
+  /** MCP manager for WorkIQ tool calls */
+  mcpManager: McpManager;
+  /** IO for permission prompts and progress messages */
+  io: LoopIO;
+  /** Activity spinner for visual feedback */
+  spinner?: ActivitySpinner;
+  /** Web search client (defaults to production webSearch module) */
+  webSearchClient?: WebSearchClient;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+const MAX_ITEMS = 10;
+
+/**
+ * Extract a likely company name from the summary.
+ * Uses the first capitalized multi-word sequence or first noun phrase.
+ */
+function extractCompanyName(summary: string): string {
+  // Try quoted string first
+  const quoted = summary.match(/"([^"]+)"/);
+  if (quoted) return quoted[1];
+  // Try first capitalized multi-word sequence
+  const capitalized = summary.match(/\b([A-Z][a-zA-Z]*(?:\s+[A-Z][a-zA-Z]*)*)\b/);
+  if (capitalized) return capitalized[1];
+  // Fallback: first 3 words
+  return summary.split(/\s+/).slice(0, 3).join(' ');
+}
+
+/**
+ * Map search results to "Title: Snippet" strings, capped at MAX_ITEMS.
+ */
+function mapResults(results: Array<{ title: string; snippet: string }>): string[] {
+  return results.slice(0, MAX_ITEMS).map((r) => `${r.title}: ${r.snippet}`);
+}
+
+// ── DiscoveryEnricher ────────────────────────────────────────────────────────
+
+export class DiscoveryEnricher {
+  /**
+   * Run the full enrichment flow: web search + optional WorkIQ.
+   */
+  async enrich(options: DiscoveryEnricherOptions): Promise<DiscoveryEnrichment> {
+    const { companySummary, mcpManager, io, webSearchClient } = options;
+
+    let webResult: Partial<DiscoveryEnrichment> = {};
+    let workiqResult: Partial<DiscoveryEnrichment> = {};
+
+    // Run web search if client provided
+    if (webSearchClient) {
+      io.writeActivity('Searching for recent company and industry context...');
+      webResult = await this.enrichFromWebSearch(companySummary, webSearchClient);
+    }
+
+    // Run WorkIQ if available
+    if (mcpManager.isAvailable('workiq')) {
+      workiqResult = await this.enrichFromWorkIQ(companySummary, mcpManager, io);
+    }
+
+    // Merge results
+    const sourcesUsed = [...(webResult.sourcesUsed ?? []), ...(workiqResult.sourcesUsed ?? [])];
+
+    const enrichment: DiscoveryEnrichment = {
+      ...webResult,
+      ...workiqResult,
+      sourcesUsed: sourcesUsed.length > 0 ? sourcesUsed : undefined,
+      enrichedAt: new Date().toISOString(),
+    };
+
+    return enrichment;
+  }
+
+  /**
+   * Run only the web search enrichment step.
+   */
+  async enrichFromWebSearch(
+    companySummary: string,
+    webSearchClient: WebSearchClient,
+  ): Promise<Partial<DiscoveryEnrichment>> {
+    const companyName = extractCompanyName(companySummary);
+
+    // GET CURRENT YEAR for dynamic query generation
+    const currentYear = new Date().getFullYear();
+
+    // Construct multiple queries to cover different angles
+
+    const queries = [
+      `${companyName} recent news ${currentYear - 1} ${currentYear}`,
+      `${companyName} competitors market ${currentYear - 1}`,
+      `${companyName} industry AI trends ${currentYear}`,
+    ];
+
+    const allSnippets: string[] = [];
+    let companyNews: string[] = [];
+    let competitorInfo: string[] = [];
+    let industryTrends: string[] = [];
+
+    for (let i = 0; i < queries.length; i++) {
+      try {
+        const result: WebSearchResult = await webSearchClient.search(queries[i]);
+        if (result.degraded) continue;
+
+        const mapped = mapResults(result.results);
+        if (mapped.length === 0) {
+          continue;
+        }
+
+        allSnippets.push(...result.results.map((r) => r.snippet));
+
+        if (i === 0) companyNews = mapped;
+        else if (i === 1) competitorInfo = mapped;
+        else if (i === 2) industryTrends = mapped;
+
+        // Stop after first successful query to avoid exhausting provider quotas
+        // across repeated enrichment calls in a single workshop run.
+        break;
+      } catch {
+        // Individual query failure — continue with remaining queries
+        continue;
+      }
+    }
+
+    // If no results at all, return minimal object
+    if (allSnippets.length === 0) {
+      return {};
+    }
+
+    return {
+      companyNews,
+      competitorInfo,
+      industryTrends,
+      webSearchResults: allSnippets.join('\n'),
+      sourcesUsed: ['websearch'],
+      enrichedAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Run only the WorkIQ enrichment step.
+   * Prompts the user for consent before making any WorkIQ calls.
+   */
+  async enrichFromWorkIQ(
+    companySummary: string,
+    mcpManager: McpManager,
+    io: LoopIO,
+  ): Promise<Partial<DiscoveryEnrichment>> {
+    // Prompt for consent (default No)
+    const answer = await io.readInput('May sofIA access WorkIQ for team insights? (y/N) ');
+    if (!answer || answer.trim().toLowerCase() !== 'y') {
+      return {};
+    }
+
+    try {
+      const response = (await mcpManager.callTool(
+        'workiq',
+        'analyze_team',
+        {
+          summary: companySummary,
+          focus: ['expertise', 'collaboration', 'documentation'],
+        },
+        { timeoutMs: 30_000 },
+      )) as Record<string, unknown>;
+
+      // Extract structured fields or fallback to insights string
+      let teamExpertise: string[] | undefined;
+      let collaborationPatterns: string[] | undefined;
+      let documentationGaps: string[] | undefined;
+
+      if (Array.isArray(response.teamExpertise)) {
+        teamExpertise = response.teamExpertise as string[];
+        collaborationPatterns = (response.collaborationPatterns ?? []) as string[];
+        documentationGaps = (response.documentationGaps ?? []) as string[];
+      } else if (typeof response.insights === 'string') {
+        // Fallback: split by newline
+        const lines = (response.insights as string).split('\n').filter(Boolean);
+        teamExpertise = lines.length > 0 ? [lines[0]] : [];
+        collaborationPatterns = lines.length > 1 ? [lines[1]] : [];
+        documentationGaps = lines.length > 2 ? [lines[2]] : [];
+      }
+
+      if (!teamExpertise) {
+        return {};
+      }
+
+      return {
+        workiqInsights: {
+          teamExpertise,
+          collaborationPatterns,
+          documentationGaps,
+        },
+        sourcesUsed: ['workiq'],
+      };
+    } catch {
+      // Graceful degradation — return empty on any error
+      return {};
+    }
+  }
+}

package/src/phases/phaseExtractors.ts

@@ -0,0 +1,247 @@
+/**
+ * Phase extraction utilities.
+ *
+ * Parsers that extract structured data from LLM responses.
+ * Each extractor tries to find a JSON block in the response
+ * and validates it against the expected schema.
+ */
+import { z } from '../vendor/zod.js';
+import {
+  businessContextSchema,
+  workflowMapSchema,
+  ideaCardSchema,
+  ideaEvaluationSchema,
+  selectedIdeaSchema,
+  implementationPlanSchema,
+  pocDevelopmentStateSchema,
+  type BusinessContext,
+  type WorkflowMap,
+  type IdeaCard,
+  type IdeaEvaluation,
+  type SelectedIdea,
+  type ImplementationPlan,
+  type PocDevelopmentState,
+} from '../shared/schemas/session.js';
+
+// ---------------------------------------------------------------------------
+// JSON block extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the first JSON object or array from a response string.
+ * Tries:
+ *   1. Markdown fenced code block (```json ... ```)
+ *   2. First `{...}` or `[...]` in plain text
+ *
+ * Returns the parsed value, or null if nothing valid is found.
+ */
+export function extractJsonBlock(response: string): unknown {
+  // 1. Try fenced code block
+  const fenceMatch = response.match(/```(?:json)?\s*\n([\s\S]*?)\n```/);
+  if (fenceMatch) {
+    try {
+      return JSON.parse(fenceMatch[1].trim());
+    } catch {
+      // fall through
+    }
+  }
+
+  // 2. Try raw JSON — find first { or [
+  const objectMatch = response.match(/(\{[\s\S]*\})/);
+  if (objectMatch) {
+    try {
+      return JSON.parse(objectMatch[1]);
+    } catch {
+      // fall through
+    }
+  }
+
+  const arrayMatch = response.match(/(\[[\s\S]*\])/);
+  if (arrayMatch) {
+    try {
+      return JSON.parse(arrayMatch[1]);
+    } catch {
+      // fall through
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Multi-block JSON extraction (FR-007)
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract ALL JSON objects/arrays from a response string.
+ * Uses /g flag for fenced blocks and bracket-depth counting for raw JSON.
+ * Returns an array of parsed values.
+ */
+export function extractAllJsonBlocks(response: string): unknown[] {
+  const results: unknown[] = [];
+  const seen = new Set<string>();
+
+  // 1. Try all fenced code blocks
+  const fenceRegex = /```(?:json)?\s*\n([\s\S]*?)\n```/g;
+  let fenceMatch;
+  while ((fenceMatch = fenceRegex.exec(response)) !== null) {
+    const raw = fenceMatch[1].trim();
+    if (seen.has(raw)) continue;
+    try {
+      const parsed = JSON.parse(raw);
+      results.push(parsed);
+      seen.add(raw);
+    } catch {
+      // skip invalid JSON
+    }
+  }
+
+  // 2. Try bracket-depth counter for raw JSON (only if no fenced blocks found)
+  if (results.length === 0) {
+    for (const opener of ['{', '['] as const) {
+      const closer = opener === '{' ? '}' : ']';
+      let depth = 0;
+      let start = -1;
+
+      for (let i = 0; i < response.length; i++) {
+        const ch = response[i];
+        if (ch === opener) {
+          if (depth === 0) start = i;
+          depth++;
+        } else if (ch === closer) {
+          depth--;
+          if (depth === 0 && start >= 0) {
+            const raw = response.slice(start, i + 1);
+            if (!seen.has(raw)) {
+              try {
+                const parsed = JSON.parse(raw);
+                results.push(parsed);
+                seen.add(raw);
+              } catch {
+                // skip invalid
+              }
+            }
+            start = -1;
+          }
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Extract the first JSON block from a response that validates against a Zod schema.
+ * Tries each extracted block with safeParse, returns the first valid match.
+ */
+export function extractJsonBlockForSchema<T>(
+  response: string,
+  schema: z.ZodType<T>,
+): T | null {
+  const blocks = extractAllJsonBlocks(response);
+  for (const block of blocks) {
+    const result = schema.safeParse(block);
+    if (result.success) return result.data;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Typed extractors
+// ---------------------------------------------------------------------------
+
+function safeParse<T>(schema: z.ZodType<T>, data: unknown): T | null {
+  const result = schema.safeParse(data);
+  return result.success ? result.data : null;
+}
+
+/**
+ * Extract BusinessContext from an LLM response containing a JSON block.
+ */
+export function extractBusinessContext(response: string): BusinessContext | null {
+  const json = extractJsonBlock(response);
+  if (!json || typeof json !== 'object' || Array.isArray(json)) return null;
+  return safeParse(businessContextSchema, json);
+}
+
+/**
+ * Extract WorkflowMap from an LLM response containing a JSON block.
+ */
+export function extractWorkflow(response: string): WorkflowMap | null {
+  const json = extractJsonBlock(response);
+  if (!json || typeof json !== 'object' || Array.isArray(json)) return null;
+  return safeParse(workflowMapSchema, json);
+}
+
+/**
+ * Extract IdeaCard[] from an LLM response.
+ * Supports both a raw array and an `{ ideas: [...] }` wrapper.
+ */
+export function extractIdeas(response: string): IdeaCard[] | null {
+  const json = extractJsonBlock(response);
+  if (!json) return null;
+
+  // Raw array
+  if (Array.isArray(json)) {
+    const parsed = z.array(ideaCardSchema).safeParse(json);
+    return parsed.success ? parsed.data : null;
+  }
+
+  // Wrapper object with `ideas` key
+  if (typeof json === 'object' && 'ideas' in (json as Record<string, unknown>)) {
+    const parsed = z.array(ideaCardSchema).safeParse((json as Record<string, unknown>).ideas);
+    return parsed.success ? parsed.data : null;
+  }
+
+  return null;
+}
+
+/**
+ * Extract IdeaEvaluation from an LLM response.
+ */
+export function extractEvaluation(response: string): IdeaEvaluation | null {
+  const json = extractJsonBlock(response);
+  if (!json || typeof json !== 'object' || Array.isArray(json)) return null;
+  return safeParse(ideaEvaluationSchema, json);
+}
+
+/**
+ * Extract SelectedIdea from an LLM response.
+ */
+export function extractSelection(response: string): SelectedIdea | null {
+  const json = extractJsonBlock(response);
+  if (!json || typeof json !== 'object' || Array.isArray(json)) return null;
+  return safeParse(selectedIdeaSchema, json);
+}
+
+/**
+ * Extract ImplementationPlan from an LLM response.
+ */
+export function extractPlan(response: string): ImplementationPlan | null {
+  const json = extractJsonBlock(response);
+  if (!json || typeof json !== 'object' || Array.isArray(json)) return null;
+  return safeParse(implementationPlanSchema, json);
+}
+
+/**
+ * Extract a sessionName string from an LLM response JSON block.
+ * Returns the trimmed name, or null if not present/empty.
+ */
+export function extractSessionName(response: string): string | null {
+  const json = extractJsonBlock(response);
+  if (!json || typeof json !== 'object' || Array.isArray(json)) return null;
+  const obj = json as Record<string, unknown>;
+  if (typeof obj.sessionName !== 'string') return null;
+  const trimmed = obj.sessionName.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+/**
+ * Extract PocDevelopmentState from an LLM response.
+ */
+export function extractPocState(response: string): PocDevelopmentState | null {
+  const json = extractJsonBlock(response);
+  if (!json || typeof json !== 'object' || Array.isArray(json)) return null;
+  return safeParse(pocDevelopmentStateSchema, json);
+}