docorbit 0.1.0

package/apps/cli/src/commands/mcp.ts

@@ -0,0 +1,72 @@
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import { WorkspaceResolver } from '../../../../packages/workspace/src/index.ts';
+import {
+  McpServer,
+  StdioServerTransport,
+  StreamableHttpTransport,
+} from '../../../../packages/mcp/src/index.ts';
+
+export interface McpCommandOptions {
+  stdio?: boolean;
+  port?: number;
+  host?: string;
+  dbPath?: string;
+  projectDir?: string;
+}
+
+export async function runMcpCommand(options: McpCommandOptions = {}): Promise<void> {
+  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/apps/cli/src/commands/pitfalls.ts

@@ -0,0 +1,38 @@
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import { resolveProjectContext } from '../../../../packages/workspace/src/index.ts';
+import type { PitfallsCommandOptions } from '../../../../packages/shared/src/index.ts';
+import { formatPitfalls } from '../formatters/terminal.ts';
+
+export async function runPitfallsCommand(task: string = '', options: PitfallsCommandOptions = {}): Promise<void> {
+  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: unknown) {
+    console.error(`DocOrbit Pitfalls Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  } finally {
+    db.close();
+  }
+}

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

@@ -0,0 +1,35 @@
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import { RecipeEngine } from '../../../../packages/retrieval/src/index.ts';
+import type { RecipesCommandOptions } from '../../../../packages/shared/src/index.ts';
+import { formatRecipe } from '../formatters/terminal.ts';
+
+export async function runRecipesCommand(goal: string, options: RecipesCommandOptions = {}): Promise<void> {
+  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: unknown) {
+    console.error(`DocOrbit Recipes Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  } finally {
+    db.close();
+  }
+}

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

@@ -0,0 +1,48 @@
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import { RetrievalEngine } from '../../../../packages/retrieval/src/index.ts';
+import type { ChunkType } from '../../../../packages/shared/src/index.ts';
+import { formatSearchResults } from '../formatters/terminal.ts';
+
+export interface SearchCommandOptions {
+  json?: boolean;
+  dbPath?: string;
+  limit?: number;
+  chunkType?: ChunkType;
+  snapshotId?: string;
+  docVersion?: string;
+  projectDir?: string;
+}
+
+export async function runSearchCommand(query: string, options: SearchCommandOptions = {}): Promise<void> {
+  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: unknown) {
+    console.error(`DocOrbit Search Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  } finally {
+    db.close();
+  }
+}

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

@@ -0,0 +1,73 @@
+import { resolve } from 'node:path';
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import {
+  detectWorkspaceDependencies,
+  readDocsLock,
+  updateDocsLock,
+  writeDocsLock,
+} from '../../../../packages/workspace/src/index.ts';
+import { runInitCommand } from './init.ts';
+
+export interface UpdateCommandOptions {
+  json?: boolean;
+  dbPath?: string;
+  projectDir?: string;
+}
+
+export async function runUpdateCommand(
+  targetPackage?: string,
+  options: UpdateCommandOptions = {}
+): Promise<void> {
+  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: unknown) {
+    console.error(`DocOrbit Update Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  } finally {
+    db.close();
+  }
+}

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

@@ -0,0 +1,48 @@
+import * as fs from 'node:fs';
+import { DocOrbitDb, DocOrbitRepository } from '../../../../packages/storage/src/index.ts';
+import { VerificationService } from '../../../../packages/verification/src/index.ts';
+import type { VerifyCommandOptions } from '../../../../packages/shared/src/index.ts';
+import { formatVerificationReport } from '../formatters/terminal.ts';
+
+export async function runVerifyCommand(codeOrFile: string = '', options: VerifyCommandOptions = {}): Promise<void> {
+  if (!codeOrFile) {
+    console.error('Error: "verify" command requires code snippet or file path as an argument.');
+    process.exit(1);
+  }
+
+  let code = codeOrFile;
+  let filePath: string | undefined;
+
+  // 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: unknown) {
+    console.error(`DocOrbit Verify Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  } finally {
+    db.close();
+  }
+}

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

@@ -0,0 +1,23 @@
+// 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: string) => `${BOLD}${s}${RESET}`,
+  dim: (s: string) => `${DIM}${s}${RESET}`,
+  green: (s: string) => `${GREEN}${s}${RESET}`,
+  blue: (s: string) => `${BLUE}${s}${RESET}`,
+  cyan: (s: string) => `${CYAN}${s}${RESET}`,
+  yellow: (s: string) => `${YELLOW}${s}${RESET}`,
+  red: (s: string) => `${RED}${s}${RESET}`,
+  magenta: (s: string) => `${MAGENTA}${s}${RESET}`,
+  gray: (s: string) => `${DIM}${s}${RESET}`,
+  underline: (s: string) => `\x1b[4m${s}${RESET}`,
+};

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

@@ -0,0 +1,102 @@
+import type { InspectionReport, IngestionResult } from '../../../../packages/core/src/index.ts';
+import { RESET, BOLD, DIM, GREEN, BLUE, CYAN, YELLOW, RED, MAGENTA } from './colors.ts';
+
+export function formatInspectionReport(report: InspectionReport): string {
+  const lines: string[] = [];
+
+  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' },
+  ] as const;
+
+  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: IngestionResult): string {
+  const lines: string[] = [];
+
+  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');
+}