docorbit 0.1.0 → 0.1.1

package/dist/apps/cli/src/commands/mcp.js

@@ -0,0 +1,49 @@
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { WorkspaceResolver } from "../../../../packages/workspace/src/index.js";
+import { McpServer, StdioServerTransport, StreamableHttpTransport, } from "../../../../packages/mcp/src/index.js";
+export async function runMcpCommand(options = {}) {
+    const dbPath = options.dbPath || '.docorbit/docorbit.db';
+    const projectDir = options.projectDir || process.cwd();
+    const db = new DocOrbitDb(dbPath);
+    const repo = new DocOrbitRepository(db);
+    const resolver = new WorkspaceResolver(repo);
+    const server = new McpServer({
+        repo,
+        resolver,
+        projectDir,
+        serverName: 'docorbit-mcp',
+        serverVersion: '0.5.0',
+    });
+    const isHttp = typeof options.port === 'number' && options.port > 0;
+    if (isHttp) {
+        const port = options.port;
+        const host = options.host || '127.0.0.1';
+        const transport = new StreamableHttpTransport({ port, host });
+        await transport.start(server);
+        const activePort = transport.getPort();
+        process.stderr.write(`[DocOrbit MCP] Streamable HTTP server listening on http://${host}:${activePort}\n` +
+            `  - MCP endpoint: POST http://${host}:${activePort}/mcp\n` +
+            `  - SSE fallback: GET http://${host}:${activePort}/sse\n` +
+            `  - Health check: GET http://${host}:${activePort}/health\n`);
+        const shutdown = async () => {
+            process.stderr.write('[DocOrbit MCP] Shutting down HTTP server...\n');
+            await transport.close();
+            db.close();
+            process.exit(0);
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    }
+    else {
+        // Default to Stdio transport
+        const transport = new StdioServerTransport();
+        await transport.start(server);
+        const shutdown = async () => {
+            await transport.close();
+            db.close();
+            process.exit(0);
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    }
+}

package/dist/apps/cli/src/commands/pitfalls.d.ts

@@ -0,0 +1,2 @@
+import type { PitfallsCommandOptions } from '../../../../packages/shared/src/index.ts';
+export declare function runPitfallsCommand(task?: string, options?: PitfallsCommandOptions): Promise<void>;

package/dist/apps/cli/src/commands/pitfalls.js

@@ -0,0 +1,35 @@
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { resolveProjectContext } from "../../../../packages/workspace/src/index.js";
+import { formatPitfalls } from "../formatters/terminal.js";
+export async function runPitfallsCommand(task = '', options = {}) {
+    const dbPath = options.dbPath || '.docorbit/docorbit.db';
+    const db = new DocOrbitDb(dbPath);
+    const repository = new DocOrbitRepository(db);
+    try {
+        let effectiveDocVersion = options.docVersion;
+        if (options.projectDir) {
+            const projContext = resolveProjectContext(options.projectDir, task, repository);
+            if (projContext.matchedDependency && !effectiveDocVersion) {
+                effectiveDocVersion = projContext.matchedDependency.targetDocVersion;
+            }
+        }
+        const pitfalls = repository.searchPitfalls(task, {
+            kind: options.kind,
+            docVersion: effectiveDocVersion,
+            limit: options.limit || 10,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(pitfalls, null, 2));
+        }
+        else {
+            console.log(formatPitfalls(pitfalls, task));
+        }
+    }
+    catch (err) {
+        console.error(`DocOrbit Pitfalls Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/apps/cli/src/commands/recipes.d.ts

@@ -0,0 +1,2 @@
+import type { RecipesCommandOptions } from '../../../../packages/shared/src/index.ts';
+export declare function runRecipesCommand(goal: string, options?: RecipesCommandOptions): Promise<void>;

package/dist/apps/cli/src/commands/recipes.js

@@ -0,0 +1,33 @@
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { RecipeEngine } from "../../../../packages/retrieval/src/index.js";
+import { formatRecipe } from "../formatters/terminal.js";
+export async function runRecipesCommand(goal, options = {}) {
+    if (!goal) {
+        console.error('Error: Please provide an implementation goal.');
+        console.error('Usage: docorbit recipes "<goal>" [--doc-version <ver>] [--project <dir>] [--json] [--db <path>]');
+        process.exit(1);
+    }
+    const dbPath = options.dbPath || '.docorbit/docorbit.db';
+    const db = new DocOrbitDb(dbPath);
+    const repository = new DocOrbitRepository(db);
+    const recipeEngine = new RecipeEngine(repository);
+    try {
+        const recipe = await recipeEngine.assembleRecipe(goal, {
+            docVersion: options.docVersion,
+            projectDir: options.projectDir,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(recipe, null, 2));
+        }
+        else {
+            console.log(formatRecipe(recipe));
+        }
+    }
+    catch (err) {
+        console.error(`DocOrbit Recipes Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/apps/cli/src/commands/search.d.ts

@@ -0,0 +1,11 @@
+import type { ChunkType } from '../../../../packages/shared/src/index.ts';
+export interface SearchCommandOptions {
+    json?: boolean;
+    dbPath?: string;
+    limit?: number;
+    chunkType?: ChunkType;
+    snapshotId?: string;
+    docVersion?: string;
+    projectDir?: string;
+}
+export declare function runSearchCommand(query: string, options?: SearchCommandOptions): Promise<void>;

package/dist/apps/cli/src/commands/search.js

@@ -0,0 +1,36 @@
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { RetrievalEngine } from "../../../../packages/retrieval/src/index.js";
+import { formatSearchResults } from "../formatters/terminal.js";
+export async function runSearchCommand(query, options = {}) {
+    if (!query) {
+        console.error('Error: Please provide a search query.');
+        console.error('Usage: docorbit search "<query>" [--limit <n>] [--type <type>] [--doc-version <ver>] [--project <dir>] [--json] [--db <path>]');
+        process.exit(1);
+    }
+    const dbPath = options.dbPath || '.docorbit/docorbit.db';
+    const db = new DocOrbitDb(dbPath);
+    const repository = new DocOrbitRepository(db);
+    const engine = new RetrievalEngine(repository);
+    try {
+        const results = await engine.search(query, {
+            limit: options.limit || 10,
+            chunkType: options.chunkType,
+            snapshotId: options.snapshotId,
+            docVersion: options.docVersion,
+            projectDir: options.projectDir,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(results, null, 2));
+        }
+        else {
+            console.log(formatSearchResults(query, results));
+        }
+    }
+    catch (err) {
+        console.error(`DocOrbit Search Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/apps/cli/src/commands/update.d.ts

@@ -0,0 +1,6 @@
+export interface UpdateCommandOptions {
+    json?: boolean;
+    dbPath?: string;
+    projectDir?: string;
+}
+export declare function runUpdateCommand(targetPackage?: string, options?: UpdateCommandOptions): Promise<void>;

package/dist/apps/cli/src/commands/update.js

@@ -0,0 +1,53 @@
+import { resolve } from 'node:path';
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { detectWorkspaceDependencies, readDocsLock, updateDocsLock, writeDocsLock, } from "../../../../packages/workspace/src/index.js";
+import { runInitCommand } from "./init.js";
+export async function runUpdateCommand(targetPackage, options = {}) {
+    const projectDir = resolve(options.projectDir || '.');
+    const existingLock = readDocsLock(projectDir);
+    if (!existingLock) {
+        console.log(`No docs.lock found at ${projectDir}. Initializing first...`);
+        await runInitCommand(projectDir, { json: options.json, dbPath: options.dbPath });
+        return;
+    }
+    const dbPath = options.dbPath || '.docorbit/docorbit.db';
+    const db = new DocOrbitDb(dbPath);
+    const repository = new DocOrbitRepository(db);
+    try {
+        const scanResult = detectWorkspaceDependencies(projectDir);
+        const updated = updateDocsLock(scanResult, repository, existingLock, targetPackage);
+        writeDocsLock(projectDir, updated);
+        if (options.json) {
+            console.log(JSON.stringify(updated, null, 2));
+            return;
+        }
+        console.log(`\n=== DocOrbit docs.lock Updated ===`);
+        if (targetPackage) {
+            console.log(`Target Package: ${targetPackage}`);
+        }
+        else {
+            console.log(`Updated all resolved dependencies.`);
+        }
+        const lockedCount = Object.keys(updated.dependencies).length;
+        console.log(`Total Locked Docs: ${lockedCount}\n`);
+        console.log('-----------------------------------------------------------------------------');
+        console.log('| Package               | Project Ver | Doc Ver  | Match       | Confidence |');
+        console.log('-----------------------------------------------------------------------------');
+        for (const [key, dep] of Object.entries(updated.dependencies)) {
+            const pkgPad = key.padEnd(21).slice(0, 21);
+            const projPad = dep.resolvedDependencyVersion.padEnd(11).slice(0, 11);
+            const docPad = dep.docVersion.padEnd(8).slice(0, 8);
+            const matchPad = dep.matchType.padEnd(11).slice(0, 11);
+            const confPad = (dep.confidence * 100).toFixed(0) + '%';
+            console.log(`| ${pkgPad} | ${projPad} | ${docPad} | ${matchPad} | ${confPad.padEnd(10)} |`);
+        }
+        console.log('-----------------------------------------------------------------------------\n');
+    }
+    catch (err) {
+        console.error(`DocOrbit Update Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/apps/cli/src/commands/verify.d.ts

@@ -0,0 +1,2 @@
+import type { VerifyCommandOptions } from '../../../../packages/shared/src/index.ts';
+export declare function runVerifyCommand(codeOrFile?: string, options?: VerifyCommandOptions): Promise<void>;

package/dist/apps/cli/src/commands/verify.js

@@ -0,0 +1,44 @@
+import * as fs from 'node:fs';
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { VerificationService } from "../../../../packages/verification/src/index.js";
+import { formatVerificationReport } from "../formatters/terminal.js";
+export async function runVerifyCommand(codeOrFile = '', options = {}) {
+    if (!codeOrFile) {
+        console.error('Error: "verify" command requires code snippet or file path as an argument.');
+        process.exit(1);
+    }
+    let code = codeOrFile;
+    let filePath;
+    // Check if argument is a file path
+    if (fs.existsSync(codeOrFile) && fs.statSync(codeOrFile).isFile()) {
+        filePath = codeOrFile;
+        code = fs.readFileSync(codeOrFile, 'utf8');
+    }
+    const dbPath = options.dbPath || '.docorbit/docorbit.db';
+    const db = new DocOrbitDb(dbPath);
+    const repo = new DocOrbitRepository(db);
+    try {
+        const service = new VerificationService(repo);
+        const { result } = service.verifyCode({
+            code,
+            filePath,
+            language: options.language,
+            library: options.library,
+            version: options.docVersion,
+            projectDir: options.projectDir || process.cwd(),
+        });
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(formatVerificationReport(result));
+        }
+    }
+    catch (err) {
+        console.error(`DocOrbit Verify Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/apps/cli/src/formatters/colors.d.ts

@@ -0,0 +1,21 @@
+export declare const RESET = "\u001B[0m";
+export declare const BOLD = "\u001B[1m";
+export declare const DIM = "\u001B[2m";
+export declare const GREEN = "\u001B[32m";
+export declare const BLUE = "\u001B[34m";
+export declare const CYAN = "\u001B[36m";
+export declare const YELLOW = "\u001B[33m";
+export declare const RED = "\u001B[31m";
+export declare const MAGENTA = "\u001B[35m";
+export declare const c: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    green: (s: string) => string;
+    blue: (s: string) => string;
+    cyan: (s: string) => string;
+    yellow: (s: string) => string;
+    red: (s: string) => string;
+    magenta: (s: string) => string;
+    gray: (s: string) => string;
+    underline: (s: string) => string;
+};

package/dist/apps/cli/src/formatters/colors.js

@@ -0,0 +1,22 @@
+// ANSI colors
+export const RESET = '\x1b[0m';
+export const BOLD = '\x1b[1m';
+export const DIM = '\x1b[2m';
+export const GREEN = '\x1b[32m';
+export const BLUE = '\x1b[34m';
+export const CYAN = '\x1b[36m';
+export const YELLOW = '\x1b[33m';
+export const RED = '\x1b[31m';
+export const MAGENTA = '\x1b[35m';
+export const c = {
+    bold: (s) => `${BOLD}${s}${RESET}`,
+    dim: (s) => `${DIM}${s}${RESET}`,
+    green: (s) => `${GREEN}${s}${RESET}`,
+    blue: (s) => `${BLUE}${s}${RESET}`,
+    cyan: (s) => `${CYAN}${s}${RESET}`,
+    yellow: (s) => `${YELLOW}${s}${RESET}`,
+    red: (s) => `${RED}${s}${RESET}`,
+    magenta: (s) => `${MAGENTA}${s}${RESET}`,
+    gray: (s) => `${DIM}${s}${RESET}`,
+    underline: (s) => `\x1b[4m${s}${RESET}`,
+};

package/dist/apps/cli/src/formatters/inspection.d.ts

@@ -0,0 +1,3 @@
+import type { InspectionReport, IngestionResult } from '../../../../packages/core/src/index.ts';
+export declare function formatInspectionReport(report: InspectionReport): string;
+export declare function formatIngestionResult(result: IngestionResult): string;

package/dist/apps/cli/src/formatters/inspection.js

@@ -0,0 +1,88 @@
+import { RESET, BOLD, DIM, GREEN, BLUE, CYAN, YELLOW, RED, MAGENTA } from "./colors.js";
+export function formatInspectionReport(report) {
+    const lines = [];
+    lines.push('');
+    lines.push(`${BOLD}${CYAN}DocOrbit${RESET} ${DIM}— Documentation Intelligence Report${RESET}`);
+    lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+    lines.push(`${BOLD}Target URL:${RESET} ${BLUE}${report.targetUrl}${RESET}`);
+    lines.push('');
+    // Sources Table
+    lines.push(`${BOLD}Discovered Sources (${report.summary.totalFound}):${RESET}`);
+    lines.push(`${DIM}${'─'.repeat(64)}${RESET}`);
+    if (report.sourcesDiscovered.length === 0) {
+        lines.push(`  ${YELLOW}No machine-readable sources discovered.${RESET}`);
+    }
+    else {
+        for (const src of report.sourcesDiscovered) {
+            const icon = src.status === 'valid' ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`;
+            const typeStr = `[${src.type}]`.padEnd(16);
+            const mr = src.machineReadable ? `${GREEN}machine-readable${RESET}` : `${DIM}human-html${RESET}`;
+            const auth = `${src.authority}`;
+            lines.push(`  ${icon} ${BOLD}${typeStr}${RESET} ${mr.padEnd(26)} ${DIM}(${auth}, conf: ${Math.round(src.confidence * 100)}%)${RESET}`);
+            lines.push(`    ${DIM}↳ ${src.url}${RESET}`);
+        }
+    }
+    lines.push('');
+    lines.push(`${BOLD}Purpose-Based Source Recommendations:${RESET}`);
+    lines.push(`${DIM}${'─'.repeat(64)}${RESET}`);
+    const purposes = [
+        { key: 'navigation', label: 'Navigation    ' },
+        { key: 'conceptual', label: 'Conceptual    ' },
+        { key: 'api', label: 'API Reference ' },
+        { key: 'examples', label: 'Code Examples ' },
+        { key: 'implementation', label: 'Implementation' },
+    ];
+    for (const p of purposes) {
+        const rec = report.recommendations[p.key];
+        if (rec && rec.recommended) {
+            lines.push(`  ${CYAN}${p.label}${RESET} → ${GREEN}${rec.recommended.type}${RESET} ${DIM}(${rec.recommended.url})${RESET}`);
+        }
+        else {
+            lines.push(`  ${CYAN}${p.label}${RESET} → ${DIM}No dedicated source${RESET}`);
+        }
+    }
+    lines.push('');
+    lines.push(`${BOLD}Summary:${RESET}`);
+    lines.push(`  Machine-readable sources: ${GREEN}${report.summary.machineReadableCount}${RESET}`);
+    lines.push(`  Official sources:         ${GREEN}${report.summary.officialCount}${RESET}`);
+    lines.push(`  OpenAPI detected:         ${report.summary.hasOpenApi ? `${GREEN}Yes${RESET}` : `${DIM}No${RESET}`}`);
+    lines.push(`  llms.txt detected:        ${report.summary.hasLlmsTxt ? `${GREEN}Yes${RESET}` : `${DIM}No${RESET}`}`);
+    lines.push(`  skill.md detected:        ${report.summary.hasSkill ? `${GREEN}Yes${RESET}` : `${DIM}No${RESET}`}`);
+    lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+    lines.push('');
+    return lines.join('\n');
+}
+export function formatIngestionResult(result) {
+    const lines = [];
+    lines.push('');
+    lines.push(`${BOLD}${GREEN}DocOrbit${RESET} ${DIM}— Documentation Ingested Successfully${RESET}`);
+    lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+    lines.push(`${BOLD}Target URL:${RESET}  ${BLUE}${result.targetUrl}${RESET}`);
+    lines.push(`${BOLD}Snapshot ID:${RESET} ${MAGENTA}${result.snapshotId}${RESET}`);
+    lines.push(`${BOLD}Duration:${RESET}    ${result.durationMs}ms`);
+    lines.push('');
+    lines.push(`${BOLD}Ingested Pages (${result.pages.length}):${RESET}`);
+    lines.push(`${DIM}${'─'.repeat(64)}${RESET}`);
+    for (let i = 0; i < result.pages.length; i++) {
+        const p = result.pages[i];
+        const warnBadge = p.securityAnnotations.length > 0
+            ? ` ${YELLOW}[${p.securityAnnotations.length} alert(s)]${RESET}`
+            : '';
+        lines.push(`  ${BOLD}${i + 1}.${RESET} ${CYAN}${p.title}${RESET}${warnBadge}`);
+        lines.push(`     ${DIM}URL:    ${p.url}${RESET}`);
+        lines.push(`     ${DIM}Tokens: ~${p.estimatedTokens} | Code blocks: ${p.codeExamples.length} | Hash: ${p.contentHash.slice(0, 8)}${RESET}`);
+    }
+    lines.push('');
+    lines.push(`${BOLD}Ingestion Summary:${RESET}`);
+    lines.push(`  Total Pages:            ${BOLD}${result.stats.totalPages}${RESET}`);
+    lines.push(`  Total Raw Bytes:        ${(result.stats.totalBytes / 1024).toFixed(1)} KB`);
+    lines.push(`  Estimated Tokens:       ~${result.stats.totalEstimatedTokens}`);
+    lines.push(`  Total Code Examples:    ${result.stats.totalCodeExamples}`);
+    lines.push(`  Machine-readable types: ${result.stats.machineReadableSources}`);
+    if (result.stats.totalChunks !== undefined) {
+        lines.push(`  Total Chunks:           ${BOLD}${result.stats.totalChunks}${RESET}`);
+    }
+    lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/apps/cli/src/formatters/knowledge.d.ts

@@ -0,0 +1,5 @@
+import type { ApiEndpoint, IndexedExample, Pitfall, Recipe } from '../../../../packages/shared/src/index.ts';
+export declare function formatApiEndpoints(endpoints: ApiEndpoint[], query?: string): string;
+export declare function formatIndexedExamples(examples: IndexedExample[], task?: string): string;
+export declare function formatPitfalls(pitfalls: Pitfall[], task?: string): string;
+export declare function formatRecipe(recipe: Recipe): string;

package/dist/apps/cli/src/formatters/knowledge.js

@@ -0,0 +1,229 @@
+import { RESET, BOLD, DIM, GREEN, BLUE, CYAN, YELLOW, RED, MAGENTA } from "./colors.js";
+export function formatApiEndpoints(endpoints, query) {
+    const lines = [];
+    lines.push('');
+    lines.push(`${BOLD}${CYAN}DocOrbit${RESET} ${DIM}— API Intelligence for: "${query || '*'}"${RESET}`);
+    lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+    if (endpoints.length === 0) {
+        lines.push(`  ${YELLOW}No matching API endpoints found.${RESET}`);
+        lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+        lines.push('');
+        return lines.join('\n');
+    }
+    for (let i = 0; i < endpoints.length; i++) {
+        const ep = endpoints[i];
+        let methodColor = GREEN;
+        if (ep.method === 'post')
+            methodColor = BLUE;
+        else if (ep.method === 'put')
+            methodColor = YELLOW;
+        else if (ep.method === 'delete')
+            methodColor = RED;
+        else if (ep.method === 'patch')
+            methodColor = MAGENTA;
+        const methodBadge = `${methodColor}${BOLD}[${ep.method.toUpperCase()}]${RESET}`;
+        const depBadge = ep.deprecated ? ` ${RED}${BOLD}[DEPRECATED]${RESET}` : '';
+        const verBadge = ep.docVersion ? ` ${DIM}(${ep.docVersion})${RESET}` : '';
+        lines.push(`  ${BOLD}${i + 1}.${RESET} ${methodBadge} ${BOLD}${CYAN}${ep.path}${RESET}${depBadge}${verBadge}`);
+        if (ep.summary) {
+            lines.push(`     ${BOLD}${ep.summary}${RESET}`);
+        }
+        if (ep.description && ep.description !== ep.summary) {
+            lines.push(`     ${DIM}${ep.description.slice(0, 120)}${ep.description.length > 120 ? '...' : ''}${RESET}`);
+        }
+        if (ep.parameters.length > 0) {
+            const paramStr = ep.parameters.map(p => {
+                const req = p.required ? `${RED}*${RESET}` : '';
+                return `${p.name}${req} (${p.in}:${p.type || 'any'})`;
+            }).join(', ');
+            lines.push(`     ${DIM}Params: ${paramStr}${RESET}`);
+        }
+        if (ep.auth.length > 0) {
+            const authStr = ep.auth.map(a => `${a.type}${a.scheme ? `:${a.scheme}` : ''}`).join(', ');
+            lines.push(`     ${DIM}Auth: ${authStr}${RESET}`);
+        }
+        if (ep.pagination) {
+            lines.push(`     ${DIM}Pagination: ${ep.pagination.type} (${ep.pagination.parameters.join(', ')})${RESET}`);
+        }
+        if (ep.errors.length > 0) {
+            const errorCodes = ep.errors.map(e => e.statusCode).join(', ');
+            lines.push(`     ${DIM}Error Codes: ${errorCodes}${RESET}`);
+        }
+        if (ep.provenance?.sourceUrl) {
+            lines.push(`     ${DIM}Source: ${ep.provenance.sourceUrl}${RESET}`);
+        }
+        lines.push('');
+    }
+    lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+    lines.push('');
+    return lines.join('\n');
+}
+export function formatIndexedExamples(examples, task) {
+    const lines = [];
+    lines.push('');
+    lines.push(`${BOLD}${CYAN}DocOrbit${RESET} ${DIM}— Code Example Intelligence for: "${task || '*'}"${RESET}`);
+    lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+    if (examples.length === 0) {
+        lines.push(`  ${YELLOW}No matching code examples found.${RESET}`);
+        lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+        lines.push('');
+        return lines.join('\n');
+    }
+    for (let i = 0; i < examples.length; i++) {
+        const ex = examples[i];
+        const fwBadge = ex.framework ? ` ${MAGENTA}[${ex.framework}]${RESET}` : '';
+        const langBadge = `${GREEN}[${ex.language}]${RESET}`;
+        const verBadge = ex.docVersion ? ` ${DIM}(${ex.docVersion})${RESET}` : '';
+        const authBadge = ex.sourceAuthority === 'official' ? `${BLUE}[official]${RESET}` : `${DIM}[community]${RESET}`;
+        lines.push(`  ${BOLD}${i + 1}.${RESET} ${CYAN}${ex.task}${RESET} ${langBadge}${fwBadge} ${authBadge}${verBadge}`);
+        if (ex.relatedApi) {
+            lines.push(`     ${BOLD}Target API:${RESET} ${BLUE}${ex.relatedApi}${RESET}`);
+        }
+        if (ex.relatedSymbol) {
+            lines.push(`     ${BOLD}Symbol:${RESET} ${MAGENTA}${ex.relatedSymbol}${RESET}`);
+        }
+        lines.push(`     ${DIM}┌── code snippet ──────────────────────────${RESET}`);
+        const codeLines = ex.code.split('\n').slice(0, 15);
+        for (const cl of codeLines) {
+            lines.push(`     ${DIM}│${RESET} ${cl}`);
+        }
+        if (ex.code.split('\n').length > 15) {
+            lines.push(`     ${DIM}│ ... (${ex.code.split('\n').length - 15} more lines)${RESET}`);
+        }
+        lines.push(`     ${DIM}└──────────────────────────────────────────${RESET}`);
+        lines.push(`     ${DIM}Source: ${ex.sourceUrl}${RESET}`);
+        lines.push('');
+    }
+    lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+    lines.push('');
+    return lines.join('\n');
+}
+export function formatPitfalls(pitfalls, task) {
+    const lines = [];
+    lines.push('');
+    lines.push(`${BOLD}${YELLOW}DocOrbit${RESET} ${DIM}— Pitfalls & Warnings for: "${task || '*'}"${RESET}`);
+    lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+    if (pitfalls.length === 0) {
+        lines.push(`  ${GREEN}No matching pitfalls or warnings found.${RESET}`);
+        lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+        lines.push('');
+        return lines.join('\n');
+    }
+    for (let i = 0; i < pitfalls.length; i++) {
+        const pf = pitfalls[i];
+        let badgeColor = YELLOW;
+        if (pf.kind === 'breaking_change' || pf.kind === 'removed' || pf.kind === 'security') {
+            badgeColor = RED;
+        }
+        else if (pf.kind === 'deprecated') {
+            badgeColor = MAGENTA;
+        }
+        const kindBadge = `${badgeColor}${BOLD}[${pf.kind.toUpperCase().replace(/_/g, ' ')}]${RESET}`;
+        const verBadge = pf.docVersion ? ` ${DIM}(${pf.docVersion})${RESET}` : '';
+        lines.push(`  ${BOLD}${i + 1}.${RESET} ${kindBadge} ${BOLD}${pf.title}${RESET}${verBadge}`);
+        if (pf.relatedApi) {
+            lines.push(`     ${DIM}Related API: ${BLUE}${pf.relatedApi}${RESET}`);
+        }
+        lines.push(`     ${DIM}│${RESET} ${pf.content}`);
+        if (pf.provenance?.sourceUrl) {
+            lines.push(`     ${DIM}Source: ${pf.provenance.sourceUrl}${RESET}`);
+        }
+        lines.push('');
+    }
+    lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+    lines.push('');
+    return lines.join('\n');
+}
+export function formatRecipe(recipe) {
+    const lines = [];
+    const confidencePct = Math.round(recipe.confidence * 100);
+    const confColor = confidencePct >= 70 ? GREEN : (confidencePct >= 40 ? YELLOW : RED);
+    lines.push('');
+    lines.push(`${BOLD}${GREEN}DocOrbit${RESET} ${DIM}— Implementation Recipe${RESET}`);
+    lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+    lines.push(`${BOLD}Goal:${RESET}       ${CYAN}${recipe.goal}${RESET}`);
+    lines.push(`${BOLD}Confidence:${RESET} ${confColor}${confidencePct}%${RESET}`);
+    if (recipe.docVersion) {
+        lines.push(`${BOLD}Version:${RESET}    ${MAGENTA}${recipe.docVersion}${RESET}`);
+    }
+    lines.push('');
+    // Prerequisites
+    lines.push(`${BOLD}Prerequisites (${recipe.prerequisites.length}):${RESET}`);
+    lines.push(`${DIM}${'─'.repeat(64)}${RESET}`);
+    if (recipe.prerequisites.length === 0) {
+        lines.push(`  ${DIM}No special prerequisites documented.${RESET}`);
+    }
+    else {
+        for (const pre of recipe.prerequisites) {
+            const badge = pre.evidenceLevel === 'documented_fact'
+                ? `${GREEN}[FACT]${RESET}`
+                : `${YELLOW}[INFERRED]${RESET}`;
+            lines.push(`  • ${badge} ${pre.text}`);
+        }
+    }
+    lines.push('');
+    // Ordered Implementation Steps
+    lines.push(`${BOLD}Implementation Steps (${recipe.orderedSteps.length}):${RESET}`);
+    lines.push(`${DIM}${'─'.repeat(64)}${RESET}`);
+    for (const s of recipe.orderedSteps) {
+        let badge = `${GREEN}[FACT]${RESET}`;
+        if (s.evidenceLevel === 'inferred_relationship')
+            badge = `${YELLOW}[INFERRED]${RESET}`;
+        else if (s.evidenceLevel === 'missing_information')
+            badge = `${RED}[MISSING]${RESET}`;
+        lines.push(`  ${BOLD}${s.step}.${RESET} ${badge} ${BOLD}${CYAN}${s.title}${RESET}`);
+        if (s.apiEndpoint) {
+            lines.push(`     ${BOLD}API Endpoint:${RESET} ${BLUE}${s.apiEndpoint}${RESET}`);
+        }
+        lines.push(`     ${s.description}`);
+        if (s.exampleCode) {
+            lines.push(`     ${DIM}┌── example ────────────────────────────────${RESET}`);
+            const codeLines = s.exampleCode.split('\n').slice(0, 10);
+            for (const cl of codeLines) {
+                lines.push(`     ${DIM}│${RESET} ${cl}`);
+            }
+            if (s.exampleCode.split('\n').length > 10) {
+                lines.push(`     ${DIM}│ ... (${s.exampleCode.split('\n').length - 10} more lines)${RESET}`);
+            }
+            lines.push(`     ${DIM}└──────────────────────────────────────────${RESET}`);
+        }
+        if (s.pitfalls && s.pitfalls.length > 0) {
+            for (const pf of s.pitfalls) {
+                lines.push(`     ${YELLOW}⚠ ${pf}${RESET}`);
+            }
+        }
+        if (s.sourceUrl) {
+            lines.push(`     ${DIM}Source: ${s.sourceUrl}${RESET}`);
+        }
+        lines.push('');
+    }
+    // Evidence-Based Validation Steps
+    lines.push(`${BOLD}Validation Steps (${recipe.validationSteps.length}):${RESET}`);
+    lines.push(`${DIM}${'─'.repeat(64)}${RESET}`);
+    for (const vs of recipe.validationSteps) {
+        let badge = `${GREEN}[FACT]${RESET}`;
+        if (vs.evidenceLevel === 'inferred_relationship')
+            badge = `${YELLOW}[INFERRED]${RESET}`;
+        else if (vs.evidenceLevel === 'missing_information')
+            badge = `${RED}[MISSING]${RESET}`;
+        lines.push(`  ${BOLD}${vs.step}.${RESET} ${badge} ${vs.description}`);
+        if (vs.expectedResponse) {
+            lines.push(`     ${DIM}Expected Response:${RESET} ${vs.expectedResponse.slice(0, 100)}`);
+        }
+        if (vs.testPattern) {
+            lines.push(`     ${DIM}Test Pattern:${RESET} ${vs.testPattern.slice(0, 100)}`);
+        }
+    }
+    lines.push('');
+    // Sources consulted
+    if (recipe.sources.length > 0) {
+        lines.push(`${BOLD}Sources Consulted:${RESET}`);
+        for (const src of recipe.sources) {
+            lines.push(`  ${DIM}• ${src}${RESET}`);
+        }
+        lines.push('');
+    }
+    lines.push(`${DIM}${'═'.repeat(64)}${RESET}`);
+    lines.push('');
+    return lines.join('\n');
+}