sofia-cli 0.1.1

package/dist/src/shared/data/cardsLoader.js

@@ -0,0 +1,51 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from '../../vendor/zod';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// ── Schemas ──────────────────────────────────────────────────────────────────
+const discoveryCardSchema = z.object({
+    cardId: z.string(),
+    category: z.string(),
+    title: z.string(),
+    description: z.string(),
+    typicalScenarios: z.array(z.string()),
+    azureServices: z.array(z.string()),
+    optionalCategory: z.string().optional(),
+});
+const cardsDatasetSchema = z.object({
+    categories: z.array(z.string()),
+    cards: z.array(discoveryCardSchema),
+});
+// ── Loader ───────────────────────────────────────────────────────────────────
+let cachedDataset = null;
+/**
+ * Load and validate the AI Discovery Cards dataset.
+ * The result is cached after the first load.
+ */
+export async function loadCardsDataset() {
+    if (cachedDataset)
+        return cachedDataset;
+    const filePath = join(__dirname, "cards.json");
+    const raw = await readFile(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    cachedDataset = cardsDatasetSchema.parse(parsed);
+    return cachedDataset;
+}
+/**
+ * Get all cards in a specific category.
+ */
+export async function getCardsByCategory(category) {
+    const dataset = await loadCardsDataset();
+    return dataset.cards.filter((c) => c.category === category);
+}
+/**
+ * Search cards by keyword in title, description, or typicalScenarios.
+ */
+export async function searchCards(query) {
+    const dataset = await loadCardsDataset();
+    const lowerQuery = query.toLowerCase();
+    return dataset.cards.filter((c) => c.title.toLowerCase().includes(lowerQuery) ||
+        c.description.toLowerCase().includes(lowerQuery) ||
+        c.typicalScenarios.some((s) => s.toLowerCase().includes(lowerQuery)));
+}

package/dist/src/shared/errorClassifier.js

@@ -0,0 +1,120 @@
+/**
+ * Centralized error classifier for sofIA CLI.
+ *
+ * Maps raw errors to well-defined categories with:
+ * - Recovery guidance (is it retryable?)
+ * - User-facing messages (no stack traces)
+ * - Category-based handling (MCP, auth, network, validation, etc.)
+ */
+// ---------------------------------------------------------------------------
+// Classification
+// ---------------------------------------------------------------------------
+/**
+ * Classify any thrown value into a well-defined `ErrorClassification`.
+ */
+export function classifyError(err) {
+    // Normalise to an Error-like shape
+    const error = err instanceof Error
+        ? err
+        : typeof err === 'string'
+            ? new Error(err)
+            : new Error(String(err));
+    const code = err.code;
+    const statusCode = err.statusCode;
+    // --- Network / system codes ---
+    if (code === 'ECONNREFUSED') {
+        return {
+            category: 'connection',
+            recoverable: true,
+            message: error.message,
+            originalError: err,
+        };
+    }
+    if (code === 'ENOTFOUND') {
+        return {
+            category: 'dns',
+            recoverable: true,
+            message: error.message,
+            originalError: err,
+        };
+    }
+    if (code === 'ETIMEDOUT' || code === 'ESOCKETTIMEDOUT') {
+        return {
+            category: 'timeout',
+            recoverable: true,
+            message: error.message,
+            originalError: err,
+        };
+    }
+    if (code === 'ENOENT') {
+        return {
+            category: 'not-found',
+            recoverable: false,
+            message: error.message,
+            originalError: err,
+        };
+    }
+    // --- HTTP status codes ---
+    if (statusCode === 401 || statusCode === 403) {
+        return {
+            category: 'auth',
+            recoverable: false,
+            message: error.message,
+            originalError: err,
+        };
+    }
+    if (statusCode === 429) {
+        return {
+            category: 'rate-limit',
+            recoverable: true,
+            message: error.message,
+            originalError: err,
+        };
+    }
+    // --- Zod / validation errors ---
+    if (error.name === 'ZodError' || error.name === 'ZodValidationError') {
+        return {
+            category: 'validation',
+            recoverable: false,
+            message: error.message,
+            originalError: err,
+        };
+    }
+    // --- MCP server errors (heuristic: message mentions "MCP") ---
+    if (/\bmcp\b/i.test(error.message)) {
+        return {
+            category: 'mcp',
+            recoverable: true,
+            message: error.message,
+            originalError: err,
+        };
+    }
+    // --- Fallback ---
+    return {
+        category: 'internal',
+        recoverable: false,
+        message: error.message,
+        originalError: err,
+    };
+}
+// ---------------------------------------------------------------------------
+// User-facing messages
+// ---------------------------------------------------------------------------
+const USER_MESSAGES = {
+    connection: 'Unable to establish a connection. Please check that the service is running and try again.',
+    dns: 'DNS lookup failed — verify your network connection and that the hostname is correct.',
+    timeout: 'The request timed out. The service may be under heavy load; please try again shortly.',
+    auth: 'Authentication failed — please check your credentials or auth token and try again.',
+    'rate-limit': 'Rate limit exceeded. Please wait a moment before retrying.',
+    'not-found': 'The requested resource was not found. Verify the path or identifier and try again.',
+    validation: 'Data validation failed. The input or stored data does not match the expected schema.',
+    mcp: 'An MCP service encountered an error. It may be temporarily unavailable — retrying might help.',
+    internal: 'An unexpected error occurred. If the problem persists, please report it.',
+};
+/**
+ * Convert a classification into a safe, user-facing message
+ * (never includes stack traces or internal details).
+ */
+export function toUserMessage(classification) {
+    return USER_MESSAGES[classification.category];
+}

package/dist/src/shared/events.js

@@ -0,0 +1,28 @@
+/**
+ * Internal event model for sofia CLI.
+ *
+ * Adapts Copilot SDK events into a stable internal model for the
+ * ConversationLoop, streaming renderer, and telemetry.
+ */
+// ── Factory functions ────────────────────────────────────────────────────────
+function now() {
+    return new Date().toISOString();
+}
+export function createTextDeltaEvent(text) {
+    return { type: 'TextDelta', timestamp: now(), text };
+}
+export function createActivityEvent(message, data) {
+    return { type: 'Activity', timestamp: now(), message, data };
+}
+export function createToolCallEvent(toolName, args) {
+    return { type: 'ToolCall', timestamp: now(), toolName, args };
+}
+export function createToolResultEvent(toolName, result) {
+    return { type: 'ToolResult', timestamp: now(), toolName, result };
+}
+export function createPhaseChangedEvent(fromPhase, toPhase) {
+    return { type: 'PhaseChanged', timestamp: now(), fromPhase, toPhase };
+}
+export function createErrorEvent(code, message, details) {
+    return { type: 'Error', timestamp: now(), code, message, details };
+}

package/dist/src/shared/markdownRenderer.js

@@ -0,0 +1,34 @@
+/**
+ * Markdown rendering helper.
+ *
+ * Uses marked + marked-terminal for rich TTY output.
+ * Falls back to plain text for non-TTY / JSON mode.
+ */
+import { Marked } from 'marked';
+import { markedTerminal } from 'marked-terminal';
+// Pre-configured marked instance for TTY rendering.
+// Using a dedicated instance avoids stacking renderers
+// on the global `marked` when renderMarkdown is called repeatedly.
+const ttyMarked = new Marked(markedTerminal());
+const plainMarked = new Marked();
+/**
+ * Render markdown to terminal-friendly output.
+ *
+ * - TTY mode: renders to ANSI-colored output
+ * - Non-TTY mode: strips ANSI, returns readable text
+ * - JSON mode: returns raw markdown unchanged
+ */
+export function renderMarkdown(markdown, options = {}) {
+    if (!markdown)
+        return '';
+    const { isTTY = process.stdout.isTTY ?? false, jsonMode = false } = options;
+    // In JSON mode, return raw markdown for machine consumption
+    if (jsonMode) {
+        return markdown;
+    }
+    if (isTTY) {
+        return ttyMarked.parse(markdown, { async: false });
+    }
+    // Non-TTY: return plain text (strip markdown syntax minimally)
+    return plainMarked.parse(markdown, { async: false });
+}

package/dist/src/shared/schemas/session.js

@@ -0,0 +1,265 @@
+/**
+ * Shared Zod schemas for WorkshopSession and related entities.
+ *
+ * Source of truth: specs/001-cli-workshop-rebuild/data-model.md
+ * Contract: specs/001-cli-workshop-rebuild/contracts/session-json.md
+ */
+import { z } from '../../vendor/zod.js';
+// ── Enums ────────────────────────────────────────────────────────────────────
+export const Phase = [
+    'Discover',
+    'Ideate',
+    'Design',
+    'Select',
+    'Plan',
+    'Develop',
+    'Complete',
+];
+export const phaseSchema = z.enum(Phase);
+export const SessionStatus = ['Active', 'Paused', 'Completed', 'Errored'];
+export const sessionStatusSchema = z.enum(SessionStatus);
+// ── Leaf entities ────────────────────────────────────────────────────────────
+export const metricSchema = z.object({
+    name: z.string(),
+    value: z.string().optional(),
+    unit: z.string().optional(),
+});
+export const participantSchema = z.object({
+    id: z.string(),
+    displayName: z.string(),
+    role: z.enum(['Facilitator', 'Attendee', 'Observer']),
+});
+export const businessContextSchema = z.object({
+    businessDescription: z.string(),
+    challenges: z.array(z.string()),
+    constraints: z.array(z.string()).optional(),
+    successMetrics: z.array(metricSchema).optional(),
+});
+export const topicSelectionSchema = z.object({
+    topicArea: z.string(),
+    scopeNotes: z.string().optional(),
+});
+// ── Workflow ─────────────────────────────────────────────────────────────────
+export const workflowStepSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().optional(),
+    metrics: z.array(metricSchema).optional(),
+});
+export const workflowEdgeSchema = z.object({
+    fromStepId: z.string(),
+    toStepId: z.string(),
+});
+export const workflowMapSchema = z.object({
+    activities: z.array(workflowStepSchema),
+    edges: z.array(workflowEdgeSchema),
+});
+// ── Cards ────────────────────────────────────────────────────────────────────
+export const envisioningCardSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    category: z.string().optional(),
+    notes: z.string().optional(),
+});
+export const cardScoreSchema = z.object({
+    cardId: z.string(),
+    dimensions: z.record(z.string(), z.number()),
+});
+export const cardSelectionSchema = z.object({
+    selectedCards: z.array(envisioningCardSchema),
+    scores: z.array(cardScoreSchema).optional(),
+});
+// ── Ideas ────────────────────────────────────────────────────────────────────
+export const ideaCardSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    description: z.string(),
+    workflowStepIds: z.array(z.string()),
+    aspirationalScope: z.string().optional(),
+    assumptions: z.array(z.string()).optional(),
+});
+// ── Evaluation ───────────────────────────────────────────────────────────────
+export const ideaEvaluationItemSchema = z.object({
+    ideaId: z.string(),
+    feasibility: z.number(),
+    value: z.number(),
+    risks: z.array(z.string()).optional(),
+    dataNeeded: z.array(z.string()).optional(),
+    humanValue: z.array(z.string()).optional(),
+    kpisInfluenced: z.array(z.string()).optional(),
+});
+export const ideaEvaluationSchema = z.object({
+    ideas: z.array(ideaEvaluationItemSchema),
+    method: z.enum(['feasibility-value-matrix', 'custom']),
+});
+// ── Selection ────────────────────────────────────────────────────────────────
+export const selectedIdeaSchema = z.object({
+    ideaId: z.string(),
+    selectionRationale: z.string(),
+    confirmedByUser: z.boolean(),
+    confirmedAt: z.string().optional(),
+});
+// ── Plan ─────────────────────────────────────────────────────────────────────
+export const milestoneSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    items: z.array(z.string()),
+});
+export const implementationPlanSchema = z.object({
+    milestones: z.array(milestoneSchema),
+    architectureNotes: z.string().optional(),
+    dependencies: z.array(z.string()).optional(),
+});
+// ── PoC ──────────────────────────────────────────────────────────────────────
+// T007: New schemas for TechStack, TestFailure, TestResults
+export const techStackSchema = z.object({
+    language: z.string(),
+    framework: z.string().optional(),
+    testRunner: z.string(),
+    buildCommand: z.string().optional(),
+    runtime: z.string(),
+});
+export const testFailureSchema = z.object({
+    testName: z.string(),
+    message: z.string(),
+    expected: z.string().optional(),
+    actual: z.string().optional(),
+    file: z.string().optional(),
+    line: z.number().optional(),
+});
+export const testResultsSchema = z
+    .object({
+    passed: z.number(),
+    failed: z.number(),
+    skipped: z.number(),
+    total: z.number(),
+    durationMs: z.number(),
+    failures: z.array(testFailureSchema),
+    rawOutput: z.string().optional(),
+})
+    .refine((d) => d.total === d.passed + d.failed + d.skipped, {
+    message: 'total must equal passed + failed + skipped',
+});
+// T005: Extended pocIterationSchema
+export const pocIterationSchema = z.object({
+    iteration: z.number(),
+    startedAt: z.string(),
+    endedAt: z.string().optional(),
+    changesSummary: z.string().optional(),
+    /** @deprecated kept for backward compatibility with pre-002 session files */
+    testsRun: z.array(z.string()).optional(),
+    // New fields for Feature 002
+    outcome: z
+        .enum(['tests-passing', 'tests-failing', 'error', 'scaffold'])
+        .optional()
+        .default('scaffold'),
+    filesChanged: z.array(z.string()).default([]),
+    testResults: testResultsSchema.optional(),
+    errorMessage: z.string().optional(),
+    llmPromptContext: z.string().optional(),
+});
+// T006: Extended pocDevelopmentStateSchema
+export const pocDevelopmentStateSchema = z.object({
+    repoPath: z.string().optional(),
+    repoUrl: z.string().optional(),
+    repoSource: z.enum(['local']), // Always local - users push manually to GitHub when ready
+    techStack: techStackSchema.optional(),
+    iterations: z.array(pocIterationSchema),
+    finalStatus: z.enum(['success', 'failed', 'partial']).optional(),
+    terminationReason: z
+        .enum(['tests-passing', 'max-iterations', 'user-stopped', 'error'])
+        .optional(),
+    totalDurationMs: z.number().optional(),
+    finalTestResults: testResultsSchema.optional(),
+});
+// ── Artifacts ────────────────────────────────────────────────────────────────
+// ── Discovery Enrichment (Feature 003) ───────────────────────────────────────
+export const DiscoveryEnrichmentSchema = z.object({
+    /** Raw web search summary text (combined from all queries) */
+    webSearchResults: z.string().optional(),
+    /** Recent news headlines/snippets about the company */
+    companyNews: z.array(z.string()).max(10).optional(),
+    /** Competitor activity summaries */
+    competitorInfo: z.array(z.string()).max(10).optional(),
+    /** Industry trend descriptions */
+    industryTrends: z.array(z.string()).max(10).optional(),
+    /** WorkIQ-derived team insights (only present if user consented) */
+    workiqInsights: z
+        .object({
+        /** Identified team skill areas */
+        teamExpertise: z.array(z.string()).max(10).optional(),
+        /** Meeting/communication patterns identified */
+        collaborationPatterns: z.array(z.string()).max(10).optional(),
+        /** Areas lacking internal documentation */
+        documentationGaps: z.array(z.string()).max(10).optional(),
+    })
+        .optional(),
+    /** ISO 8601 timestamp when enrichment was collected */
+    enrichedAt: z.string().datetime().optional(),
+    /** Which sources were queried ('websearch', 'workiq') */
+    sourcesUsed: z.array(z.string()).optional(),
+});
+export const DiscoveryStateSchema = z.object({
+    enrichment: DiscoveryEnrichmentSchema.optional(),
+});
+// ── Artifacts ────────────────────────────────────────────────────────────────
+export const generatedFileSchema = z.object({
+    relativePath: z.string(),
+    type: z.enum(['markdown', 'json', 'text']),
+    createdAt: z.string(),
+});
+export const artifactIndexSchema = z.object({
+    exportDir: z.string().optional(),
+    generatedFiles: z.array(generatedFileSchema),
+});
+// ── Conversation Turn ────────────────────────────────────────────────────────
+export const conversationTurnSchema = z.object({
+    phase: phaseSchema,
+    sequence: z.number(),
+    role: z.enum(['user', 'assistant', 'system']),
+    content: z.string(),
+    timestamp: z.string(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+// ── Error Record ─────────────────────────────────────────────────────────────
+export const errorRecordSchema = z.object({
+    timestamp: z.string(),
+    code: z.string(),
+    message: z.string(),
+    details: z.record(z.string(), z.unknown()).optional(),
+});
+// ── Activity (telemetry event) ───────────────────────────────────────────────
+export const activitySchema = z.object({
+    id: z.string(),
+    timestamp: z.string(),
+    kind: z.enum(['phase', 'tool', 'io', 'warning', 'error', 'progress']),
+    message: z.string(),
+    data: z.record(z.string(), z.unknown()).optional(),
+});
+// ── Workshop Session (root) ──────────────────────────────────────────────────
+export const workshopSessionSchema = z
+    .object({
+    sessionId: z.string(),
+    schemaVersion: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    name: z.string().optional(),
+    phase: phaseSchema,
+    status: sessionStatusSchema,
+    participants: z.array(participantSchema),
+    businessContext: businessContextSchema.optional(),
+    topic: topicSelectionSchema.optional(),
+    activities: z.array(activitySchema).optional(),
+    workflow: workflowMapSchema.optional(),
+    cards: cardSelectionSchema.optional(),
+    ideas: z.array(ideaCardSchema).optional(),
+    evaluation: ideaEvaluationSchema.optional(),
+    selection: selectedIdeaSchema.optional(),
+    plan: implementationPlanSchema.optional(),
+    poc: pocDevelopmentStateSchema.optional(),
+    discovery: DiscoveryStateSchema.optional(),
+    artifacts: artifactIndexSchema,
+    turns: z.array(conversationTurnSchema).optional(),
+    errors: z.array(errorRecordSchema).optional(),
+})
+    .passthrough(); // Forward compatibility: preserve unknown fields

package/dist/src/shared/tableRenderer.js

@@ -0,0 +1,20 @@
+/**
+ * Table rendering helper using cli-table3.
+ */
+import Table from 'cli-table3';
+/**
+ * Render a table as a string.
+ */
+export function renderTable(options) {
+    const { head, rows, colWidths } = options;
+    const tableOpts = {};
+    if (head)
+        tableOpts.head = head;
+    if (colWidths)
+        tableOpts.colWidths = colWidths;
+    const table = new Table(tableOpts);
+    for (const row of rows) {
+        table.push(row);
+    }
+    return table.toString();
+}

package/dist/src/vendor/chalk.js

@@ -0,0 +1,2 @@
+// Re-export chalk for consistent imports across the project
+export { default } from 'chalk';

package/dist/src/vendor/cli-table3.js

@@ -0,0 +1,3 @@
+// Re-export cli-table3 for consistent imports across the project
+import Table from 'cli-table3';
+export default Table;

package/dist/src/vendor/commander.js

@@ -0,0 +1,2 @@
+// Re-export commander for consistent imports across the project
+export { Command, Option, Argument } from 'commander';

package/dist/src/vendor/marked-terminal.js

@@ -0,0 +1,3 @@
+// Re-export marked-terminal for consistent imports across the project
+import markedTerminal from 'marked-terminal';
+export default markedTerminal;

package/dist/src/vendor/marked.js

@@ -0,0 +1,2 @@
+// Re-export marked for consistent imports across the project
+export { marked } from 'marked';

package/dist/src/vendor/ora.js

@@ -0,0 +1,2 @@
+// Re-export ora for consistent imports across the project
+export { default } from 'ora';

package/dist/src/vendor/pino.js

@@ -0,0 +1,2 @@
+// Re-export pino for consistent imports across the project
+export { default } from 'pino';

package/dist/src/vendor/zod.js

@@ -0,0 +1,2 @@
+// Re-export zod for consistent imports across the project
+export { z } from 'zod/v4';