sofia-cli 0.1.1

package/src/shared/data/cardsLoader.ts

@@ -0,0 +1,70 @@
+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),
+});
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type CardCategory = string;
+export type DiscoveryCardData = ReturnType<typeof discoveryCardSchema.parse>;
+export type CardsDataset = ReturnType<typeof cardsDatasetSchema.parse>;
+
+// ── Loader ───────────────────────────────────────────────────────────────────
+
+let cachedDataset: CardsDataset | null = null;
+
+/**
+ * Load and validate the AI Discovery Cards dataset.
+ * The result is cached after the first load.
+ */
+export async function loadCardsDataset(): Promise<CardsDataset> {
+  if (cachedDataset) return cachedDataset;
+
+  const filePath = join(__dirname, "cards.json");
+  const raw = await readFile(filePath, "utf-8");
+  const parsed = JSON.parse(raw) as unknown;
+  cachedDataset = cardsDatasetSchema.parse(parsed);
+  return cachedDataset;
+}
+
+/**
+ * Get all cards in a specific category.
+ */
+export async function getCardsByCategory(category: string): Promise<DiscoveryCardData[]> {
+  const dataset = await loadCardsDataset();
+  return dataset.cards.filter((c: DiscoveryCardData) => c.category === category);
+}
+
+/**
+ * Search cards by keyword in title, description, or typicalScenarios.
+ */
+export async function searchCards(query: string): Promise<DiscoveryCardData[]> {
+  const dataset = await loadCardsDataset();
+  const lowerQuery = query.toLowerCase();
+  return dataset.cards.filter(
+    (c: DiscoveryCardData) =>
+      c.title.toLowerCase().includes(lowerQuery) ||
+      c.description.toLowerCase().includes(lowerQuery) ||
+      c.typicalScenarios.some((s: string) => s.toLowerCase().includes(lowerQuery)),
+  );
+}

package/src/shared/errorClassifier.ts

@@ -0,0 +1,160 @@
+/**
+ * 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.)
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ErrorCategory =
+  | 'connection'
+  | 'dns'
+  | 'timeout'
+  | 'auth'
+  | 'rate-limit'
+  | 'not-found'
+  | 'validation'
+  | 'mcp'
+  | 'internal';
+
+export interface ErrorClassification {
+  category: ErrorCategory;
+  recoverable: boolean;
+  message: string;
+  originalError: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Classification
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify any thrown value into a well-defined `ErrorClassification`.
+ */
+export function classifyError(err: unknown): ErrorClassification {
+  // 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 as { code?: string }).code;
+  const statusCode = (err as { statusCode?: number }).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: Record<ErrorCategory, string> = {
+  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: ErrorClassification): string {
+  return USER_MESSAGES[classification.category];
+}

package/src/shared/events.ts

@@ -0,0 +1,103 @@
+/**
+ * Internal event model for sofia CLI.
+ *
+ * Adapts Copilot SDK events into a stable internal model for the
+ * ConversationLoop, streaming renderer, and telemetry.
+ */
+
+export type SofiaEventType =
+  | 'TextDelta'
+  | 'Activity'
+  | 'ToolCall'
+  | 'ToolResult'
+  | 'PhaseChanged'
+  | 'Error';
+
+export interface BaseSofiaEvent {
+  type: SofiaEventType;
+  timestamp: string;
+}
+
+export interface TextDeltaEvent extends BaseSofiaEvent {
+  type: 'TextDelta';
+  text: string;
+}
+
+export interface ActivityEvent extends BaseSofiaEvent {
+  type: 'Activity';
+  message: string;
+  data?: Record<string, unknown>;
+}
+
+export interface ToolCallEvent extends BaseSofiaEvent {
+  type: 'ToolCall';
+  toolName: string;
+  args: Record<string, unknown>;
+}
+
+export interface ToolResultEvent extends BaseSofiaEvent {
+  type: 'ToolResult';
+  toolName: string;
+  result: unknown;
+}
+
+export interface PhaseChangedEvent extends BaseSofiaEvent {
+  type: 'PhaseChanged';
+  fromPhase: string;
+  toPhase: string;
+}
+
+export interface ErrorEvent extends BaseSofiaEvent {
+  type: 'Error';
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export type SofiaEvent =
+  | TextDeltaEvent
+  | ActivityEvent
+  | ToolCallEvent
+  | ToolResultEvent
+  | PhaseChangedEvent
+  | ErrorEvent;
+
+// ── Factory functions ────────────────────────────────────────────────────────
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+export function createTextDeltaEvent(text: string): TextDeltaEvent {
+  return { type: 'TextDelta', timestamp: now(), text };
+}
+
+export function createActivityEvent(
+  message: string,
+  data?: Record<string, unknown>,
+): ActivityEvent {
+  return { type: 'Activity', timestamp: now(), message, data };
+}
+
+export function createToolCallEvent(
+  toolName: string,
+  args: Record<string, unknown>,
+): ToolCallEvent {
+  return { type: 'ToolCall', timestamp: now(), toolName, args };
+}
+
+export function createToolResultEvent(toolName: string, result: unknown): ToolResultEvent {
+  return { type: 'ToolResult', timestamp: now(), toolName, result };
+}
+
+export function createPhaseChangedEvent(fromPhase: string, toPhase: string): PhaseChangedEvent {
+  return { type: 'PhaseChanged', timestamp: now(), fromPhase, toPhase };
+}
+
+export function createErrorEvent(
+  code: string,
+  message: string,
+  details?: Record<string, unknown>,
+): ErrorEvent {
+  return { type: 'Error', timestamp: now(), code, message, details };
+}

package/src/shared/markdownRenderer.ts

@@ -0,0 +1,44 @@
+/**
+ * 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';
+
+export interface RenderOptions {
+  isTTY?: boolean;
+  jsonMode?: boolean;
+}
+
+// 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: string, options: RenderOptions = {}): string {
+  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 }) as string;
+  }
+
+  // Non-TTY: return plain text (strip markdown syntax minimally)
+  return plainMarked.parse(markdown, { async: false }) as string;
+}