docorbit 0.1.0 → 0.1.1

package/bin/docorbit.js

@@ -1,6 +1,6 @@
-#!/usr/bin/env -S node --experimental-strip-types
+#!/usr/bin/env node
 
-import { main } from '../apps/cli/src/index.ts';
+import { main } from '../dist/apps/cli/src/index.js';
 
 main().catch(err => {
   console.error('Fatal DocOrbit Error:', err);

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

@@ -0,0 +1,7 @@
+export interface AddCommandOptions {
+    json?: boolean;
+    dbPath?: string;
+    maxPages?: number;
+    allowLocalhost?: boolean;
+}
+export declare function runAddCommand(targetUrl: string, options?: AddCommandOptions): Promise<void>;

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

@@ -0,0 +1,35 @@
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { IngestionPipeline } from "../../../../packages/core/src/index.js";
+import { formatIngestionResult } from "../formatters/terminal.js";
+export async function runAddCommand(targetUrl, options = {}) {
+    if (!targetUrl) {
+        console.error('Error: Please provide a documentation target URL.');
+        console.error('Usage: docorbit add <url> [--json] [--db <path>]');
+        process.exit(1);
+    }
+    const dbPath = options.dbPath || '.docorbit/docorbit.db';
+    const db = new DocOrbitDb(dbPath);
+    const repository = new DocOrbitRepository(db);
+    try {
+        const pipeline = new IngestionPipeline(repository, {
+            allowLocalhostForTesting: options.allowLocalhost,
+            crawlerConfig: {
+                maxPages: options.maxPages || 50,
+            },
+        });
+        const result = await pipeline.ingest(targetUrl);
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(formatIngestionResult(result));
+        }
+    }
+    catch (err) {
+        console.error(`DocOrbit Ingestion Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    finally {
+        db.close();
+    }
+}

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

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

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

@@ -0,0 +1,35 @@
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { resolveProjectContext } from "../../../../packages/workspace/src/index.js";
+import { formatApiEndpoints } from "../formatters/terminal.js";
+export async function runApiCommand(query = '', 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, query, repository);
+            if (projContext.matchedDependency && !effectiveDocVersion) {
+                effectiveDocVersion = projContext.matchedDependency.targetDocVersion;
+            }
+        }
+        const endpoints = repository.searchApiEndpoints(query, {
+            method: options.method,
+            docVersion: effectiveDocVersion,
+            limit: options.limit || 20,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(endpoints, null, 2));
+        }
+        else {
+            console.log(formatApiEndpoints(endpoints, query));
+        }
+    }
+    catch (err) {
+        console.error(`DocOrbit API Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    finally {
+        db.close();
+    }
+}

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

@@ -0,0 +1,10 @@
+export interface ContextCommandOptions {
+    json?: boolean;
+    dbPath?: string;
+    tokens?: number;
+    maxChunks?: number;
+    snapshotId?: string;
+    docVersion?: string;
+    projectDir?: string;
+}
+export declare function runContextCommand(task: string, options?: ContextCommandOptions): Promise<void>;

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

@@ -0,0 +1,36 @@
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { RetrievalEngine } from "../../../../packages/retrieval/src/index.js";
+import { formatContextPackage } from "../formatters/terminal.js";
+export async function runContextCommand(task, options = {}) {
+    if (!task) {
+        console.error('Error: Please provide a coding task description.');
+        console.error('Usage: docorbit context "<task>" [--tokens <n>] [--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 pkg = await engine.buildContext(task, {
+            tokenBudget: options.tokens || 3000,
+            maxChunks: options.maxChunks,
+            snapshotId: options.snapshotId,
+            docVersion: options.docVersion,
+            projectDir: options.projectDir,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(pkg, null, 2));
+        }
+        else {
+            console.log(formatContextPackage(pkg));
+        }
+    }
+    catch (err) {
+        console.error(`DocOrbit Context Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    finally {
+        db.close();
+    }
+}

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

@@ -0,0 +1,8 @@
+export interface DashboardCommandOptions {
+    port?: number;
+    host?: string;
+    projectDir?: string;
+    dbPath?: string;
+    noOpen?: boolean;
+}
+export declare function runDashboardCommand(options?: DashboardCommandOptions): Promise<void>;

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

@@ -0,0 +1,43 @@
+import path from 'node:path';
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { DashboardServer } from "../../../../packages/core/src/index.js";
+import { c } from "../formatters/colors.js";
+export async function runDashboardCommand(options = {}) {
+    const projectDir = options.projectDir ? path.resolve(options.projectDir) : process.cwd();
+    const dbPath = options.dbPath || path.join(projectDir, '.docorbit', 'docorbit.db');
+    const port = options.port || 3737;
+    const host = options.host || '127.0.0.1';
+    const db = new DocOrbitDb(dbPath);
+    const repo = new DocOrbitRepository(db);
+    const server = new DashboardServer({
+        repo,
+        projectDir,
+        dbPath,
+    });
+    try {
+        const info = await server.start(port, host);
+        console.log(`\n${c.bold(c.cyan('DocOrbit Local Dashboard'))}`);
+        console.log(`${c.dim('Documentation Intelligence & Verification Layer')}\n`);
+        console.log(`  ${c.green('●')} Server running at: ${c.bold(c.underline(info.url))}`);
+        console.log(`  ${c.dim('Database:')} ${dbPath}`);
+        console.log(`  ${c.dim('Workspace:')} ${projectDir}`);
+        console.log(`  ${c.dim('Security:')} ${c.yellow('untrusted documentation boundary enforced')}\n`);
+        console.log(c.dim('Press Ctrl+C to stop.\n'));
+        // Keep process alive until interrupted
+        await new Promise((resolve) => {
+            const shutdown = async () => {
+                console.log(`\n${c.dim('Stopping dashboard server...')}`);
+                await server.stop();
+                db.close();
+                resolve();
+            };
+            process.on('SIGINT', shutdown);
+            process.on('SIGTERM', shutdown);
+        });
+    }
+    catch (err) {
+        db.close();
+        console.error(c.red(`Failed to start dashboard server: ${err.message}`));
+        process.exit(1);
+    }
+}

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

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

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

@@ -0,0 +1,29 @@
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { DiffService } from "../../../../packages/verification/src/index.js";
+import { formatDiffReport } from "../formatters/terminal.js";
+export async function runDiffCommand(target = '', options = {}) {
+    const dbPath = options.dbPath || '.docorbit/docorbit.db';
+    const db = new DocOrbitDb(dbPath);
+    const repo = new DocOrbitRepository(db);
+    try {
+        const service = new DiffService(repo);
+        const { result } = service.diffDocs({
+            fromVersion: options.from,
+            toVersion: options.to,
+            sourceId: options.source || (target && !target.startsWith('-') ? target : undefined),
+        });
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(formatDiffReport(result));
+        }
+    }
+    catch (err) {
+        console.error(`DocOrbit Diff Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    finally {
+        db.close();
+    }
+}

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

@@ -0,0 +1,11 @@
+export interface EvaluateCommandOptions {
+    split?: string;
+    strategy?: string;
+    task?: string;
+    output?: string;
+    json?: boolean;
+    verbose?: boolean;
+    /** Offline simulation mode — no network required, for CI regression only */
+    simulation?: boolean;
+}
+export declare function handleEvaluateCommand(options?: EvaluateCommandOptions): Promise<void>;

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

@@ -0,0 +1,101 @@
+import { BenchmarkRunner } from "../../../../packages/evaluation/src/index.js";
+import { c } from "../formatters/colors.js";
+export async function handleEvaluateCommand(options = {}) {
+    const sim = options.simulation ?? false;
+    const runner = new BenchmarkRunner({ simulation: sim });
+    const split = options.split === 'train'
+        ? 'train'
+        : options.split === 'eval'
+            ? 'eval'
+            : options.split === 'verification'
+                ? 'verification'
+                : 'all';
+    let strategies;
+    if (options.strategy) {
+        const list = options.strategy.split(',').map((s) => s.trim());
+        strategies = list;
+    }
+    const tasks = options.task ? [options.task] : undefined;
+    if (!options.json) {
+        const modeLabel = sim
+            ? c.yellow('[SIMULATION MODE — offline CI, no network]')
+            : c.green('[REAL MODE — requires network access]');
+        console.log(c.bold(c.cyan('\n=== DocOrbit Real-World Agent Evaluation Benchmark ===')));
+        console.log(modeLabel);
+        if (!sim) {
+            console.log(c.gray('  Context7: real context7-mcp stdio subprocess (context7.com)'));
+            console.log(c.gray('  Firecrawl: real /v1/scrape API (api.firecrawl.dev)'));
+            console.log(c.gray('  Official Docs Fetch: direct HTTPS fetch to official docs URLs'));
+            console.log(c.gray('  DocOrbit: real in-process MCP server\n'));
+        }
+        console.log(`Split: ${c.yellow(split)} | Strategies: ${strategies ? strategies.join(', ') : 'all'}`);
+        console.log(`Artifacts: ${options.output || 'eval-results/'}\n`);
+    }
+    const report = await runner.run({
+        split,
+        strategies,
+        tasks,
+        outputDir: options.output,
+        verbose: options.verbose,
+        simulation: sim,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    const modeTag = sim ? ' [SIMULATION]' : ' [REAL]';
+    console.log(c.bold(c.green(`\nEvaluation Complete${modeTag} — ${report.totalTasks} tasks\n`)));
+    const sDocs = report.byStrategy.agent_official_docs_fetch || report.byStrategy.agent_web_search;
+    const sFC = report.byStrategy.agent_firecrawl;
+    const sDR = report.byStrategy.agent_docorbit;
+    if (sDocs && sC7 && sDR) {
+        const pct = (n) => `${(n * 100).toFixed(1)}%`;
+        if (sFC) {
+            const hr = '---------------------------------------------------------------------------------------------------------------------';
+            console.log(hr);
+            console.log(c.bold(`| ${'Metric'.padEnd(32)}| ${'Official Docs Fetch'.padEnd(21)}| ${'Firecrawl'.padEnd(14)}| ${'Context7'.padEnd(14)}| ${'DocOrbit'.padEnd(14)}|`));
+            console.log(hr);
+            const row = (label, vDocs, vFC, vC7, vDR) => `| ${label.padEnd(32)}| ${vDocs.padEnd(21)}| ${vFC.padEnd(14)}| ${vC7.padEnd(14)}| ${vDR.padEnd(14)}|`;
+            console.log(row('Overall Task Success Rate', pct(sDocs.overallSuccessRate), pct(sFC.overallSuccessRate), pct(sC7.overallSuccessRate), pct(sDR.overallSuccessRate)));
+            console.log(row('Held-Out Eval Success Rate', pct(sDocs.evalSuccessRate), pct(sFC.evalSuccessRate), pct(sC7.evalSuccessRate), pct(sDR.evalSuccessRate)));
+            console.log(row('Correct Version Selection', pct(sDocs.versionAccuracy), pct(sFC.versionAccuracy), pct(sC7.versionAccuracy), pct(sDR.versionAccuracy)));
+            console.log(row('Retrieval Precision@k', pct(sDocs.meanPrecision), pct(sFC.meanPrecision), pct(sC7.meanPrecision), pct(sDR.meanPrecision)));
+            console.log(row('Retrieval Recall@k', pct(sDocs.meanRecall), pct(sFC.meanRecall), pct(sC7.meanRecall), pct(sDR.meanRecall)));
+            console.log(row('Mean Token Ingestion', `~${Math.round(sDocs.meanTokens)}`, `~${Math.round(sFC.meanTokens)}`, `~${Math.round(sC7.meanTokens)}`, `~${Math.round(sDR.meanTokens)}`));
+            console.log(row('Context Prep Latency', `~${sDocs.meanLatencyMs.toFixed(0)}ms`, `~${sFC.meanLatencyMs.toFixed(0)}ms`, `~${sC7.meanLatencyMs.toFixed(0)}ms`, `~${sDR.meanLatencyMs.toFixed(0)}ms`));
+            console.log(row('Avg Tool Calls per Task', sDocs.meanToolCalls.toFixed(1), sFC.meanToolCalls.toFixed(1), sC7.meanToolCalls.toFixed(1), sDR.meanToolCalls.toFixed(1)));
+            console.log(row('AST Verification Catches', '—', '—', '—', String(sDR.totalVerificationCatches)));
+            console.log(row('Verification False Positives', '—', '—', '—', String(sDR.falsePositives)));
+            console.log(hr);
+        }
+        else {
+            const hr = '--------------------------------------------------------------------------------------------------';
+            console.log(hr);
+            console.log(c.bold(`| ${'Metric'.padEnd(36)}| ${'Official Docs Fetch'.padEnd(21)}| ${'Context7'.padEnd(14)}| ${'DocOrbit'.padEnd(14)}|`));
+            console.log(hr);
+            const row = (label, vDocs, vC7, vDR) => `| ${label.padEnd(36)}| ${vDocs.padEnd(21)}| ${vC7.padEnd(14)}| ${vDR.padEnd(14)}|`;
+            console.log(row('Overall Task Success Rate', pct(sDocs.overallSuccessRate), pct(sC7.overallSuccessRate), pct(sDR.overallSuccessRate)));
+            console.log(row('Held-Out Eval Success Rate', pct(sDocs.evalSuccessRate), pct(sC7.evalSuccessRate), pct(sDR.evalSuccessRate)));
+            console.log(row('Correct Version Selection', pct(sDocs.versionAccuracy), pct(sC7.versionAccuracy), pct(sDR.versionAccuracy)));
+            console.log(row('Retrieval Precision@k', pct(sDocs.meanPrecision), pct(sC7.meanPrecision), pct(sDR.meanPrecision)));
+            console.log(row('Retrieval Recall@k', pct(sDocs.meanRecall), pct(sC7.meanRecall), pct(sDR.meanRecall)));
+            console.log(row('Mean Token Ingestion', `~${Math.round(sDocs.meanTokens)}`, `~${Math.round(sC7.meanTokens)}`, `~${Math.round(sDR.meanTokens)}`));
+            console.log(row('Context Prep Latency', `~${sDocs.meanLatencyMs.toFixed(0)}ms`, `~${sC7.meanLatencyMs.toFixed(0)}ms`, `~${sDR.meanLatencyMs.toFixed(0)}ms`));
+            console.log(row('Avg Tool Calls per Task', sDocs.meanToolCalls.toFixed(1), sC7.meanToolCalls.toFixed(1), sDR.meanToolCalls.toFixed(1)));
+            console.log(row('AST Verification Catches', '—', '—', String(sDR.totalVerificationCatches)));
+            console.log(row('Verification False Positives', '—', '—', String(sDR.falsePositives)));
+            console.log(hr);
+        }
+        if (sDR) {
+            console.log(c.bold(c.cyan('\nAST Code Verification (`check_api`) Performance:')));
+            console.log(`  Total Verification Catches: ${c.bold(String(sDR.totalVerificationCatches))}`);
+            console.log(`  False Positives on Valid Code: ${c.bold(String(sDR.falsePositives))}`);
+            console.log(`  Dynamic/Ambiguous Fallback Rate: ${c.bold(pct(sDR.insufficientEvidenceRate))}`);
+        }
+        if (sim) {
+            console.log(c.yellow('\n⚠  Results above are from simulated runners. Run without --simulation for real results.'));
+        }
+        console.log(c.gray('\n* Official Docs Fetch baseline directly fetches known official documentation URLs over HTTPS rather than querying a search engine.'));
+    }
+    console.log(`\nRaw artifacts: ${c.cyan(options.output || 'eval-results/')}\n`);
+}

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

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

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

@@ -0,0 +1,36 @@
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { resolveProjectContext } from "../../../../packages/workspace/src/index.js";
+import { formatIndexedExamples } from "../formatters/terminal.js";
+export async function runExamplesCommand(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 examples = repository.searchIndexedExamples(task, {
+            language: options.language,
+            framework: options.framework,
+            docVersion: effectiveDocVersion,
+            limit: options.limit || 10,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(examples, null, 2));
+        }
+        else {
+            console.log(formatIndexedExamples(examples, task));
+        }
+    }
+    catch (err) {
+        console.error(`DocOrbit Examples Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    finally {
+        db.close();
+    }
+}

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

@@ -0,0 +1,11 @@
+export interface ExportCommandOptions {
+    format?: string;
+    output?: string;
+    stdout?: boolean;
+    projectDir?: string;
+    docVersion?: string;
+    targetSource?: string;
+    json?: boolean;
+    dbPath?: string;
+}
+export declare function runExportCommand(formatArg?: string, options?: ExportCommandOptions): Promise<void>;

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

@@ -0,0 +1,72 @@
+import path from 'node:path';
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { ExportService } from "../../../../packages/export/src/index.js";
+import { c } from "../formatters/colors.js";
+export async function runExportCommand(formatArg, options = {}) {
+    const rawFormat = (formatArg || options.format || 'agents.md').toLowerCase();
+    const validFormats = ['agents.md', 'claude.md', 'skill.md', 'llms.txt', 'docs-map.md'];
+    let format = 'agents.md';
+    if (validFormats.includes(rawFormat)) {
+        format = rawFormat;
+    }
+    else if (rawFormat === 'agents' || rawFormat === 'agent') {
+        format = 'agents.md';
+    }
+    else if (rawFormat === 'claude') {
+        format = 'claude.md';
+    }
+    else if (rawFormat === 'skill') {
+        format = 'skill.md';
+    }
+    else if (rawFormat === 'llms' || rawFormat === 'llms.txt') {
+        format = 'llms.txt';
+    }
+    else if (rawFormat === 'map' || rawFormat === 'docs-map') {
+        format = 'docs-map.md';
+    }
+    const projectDir = options.projectDir ? path.resolve(options.projectDir) : process.cwd();
+    const dbPath = options.dbPath || path.join(projectDir, '.docorbit', 'docorbit.db');
+    const db = new DocOrbitDb(dbPath);
+    const repo = new DocOrbitRepository(db);
+    const service = new ExportService(repo);
+    try {
+        if (options.stdout) {
+            const result = await service.generateExport({
+                format,
+                projectDir,
+                docVersion: options.docVersion,
+                targetSource: options.targetSource,
+                stdout: true,
+            });
+            if (options.json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                process.stdout.write(result.content);
+            }
+            return;
+        }
+        const result = await service.writeExport({
+            format,
+            projectDir,
+            docVersion: options.docVersion,
+            targetSource: options.targetSource,
+            outputPath: options.output,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`\n${c.bold(c.green('✓'))} Generated ${c.bold(format)} for coding agents`);
+        console.log(`  ${c.dim('Output file:')}      ${c.cyan(result.outputPath || 'stdout')}`);
+        console.log(`  ${c.dim('Doc Version:')}      ${result.metadata.docVersion || 'global/latest'}`);
+        console.log(`  ${c.dim('Estimated Tokens:')} ~${result.metadata.tokenEstimate.toLocaleString()}`);
+        console.log(`  ${c.dim('APIs Included:')}    ${result.metadata.totalApis}`);
+        console.log(`  ${c.dim('Pitfalls Included:')}${result.metadata.totalPitfalls}`);
+        console.log(`  ${c.dim('Indexed Sources:')}  ${result.metadata.sources.length}`);
+        console.log(`  ${c.dim('Security Boundary:')}${c.yellow('untrusted documentation preserved')}\n`);
+    }
+    finally {
+        db.close();
+    }
+}

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

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

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

@@ -0,0 +1,30 @@
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { ImpactAnalysisService } from "../../../../packages/verification/src/index.js";
+import { formatImpactReport } from "../formatters/terminal.js";
+export async function runImpactCommand(target = '', options = {}) {
+    const dbPath = options.dbPath || '.docorbit/docorbit.db';
+    const db = new DocOrbitDb(dbPath);
+    const repo = new DocOrbitRepository(db);
+    try {
+        const service = new ImpactAnalysisService(repo);
+        const { result } = service.analyzeImpact({
+            projectDir: options.projectDir || process.cwd(),
+            fromVersion: options.from,
+            toVersion: options.to,
+            sourceId: options.source || (target && !target.startsWith('-') ? target : undefined),
+        });
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(formatImpactReport(result));
+        }
+    }
+    catch (err) {
+        console.error(`DocOrbit Impact Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    finally {
+        db.close();
+    }
+}

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

@@ -0,0 +1,5 @@
+export interface InitCommandOptions {
+    json?: boolean;
+    dbPath?: string;
+}
+export declare function runInitCommand(targetDir?: string, options?: InitCommandOptions): Promise<void>;

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

@@ -0,0 +1,52 @@
+import { resolve } from 'node:path';
+import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { detectWorkspaceDependencies, generateDocsLock, readDocsLock, writeDocsLock, } from "../../../../packages/workspace/src/index.js";
+export async function runInitCommand(targetDir = '.', options = {}) {
+    const projectDir = resolve(targetDir);
+    const dbPath = options.dbPath || '.docorbit/docorbit.db';
+    const db = new DocOrbitDb(dbPath);
+    const repository = new DocOrbitRepository(db);
+    try {
+        const scanResult = detectWorkspaceDependencies(projectDir);
+        const existingLock = readDocsLock(projectDir);
+        const lock = generateDocsLock(scanResult, repository, existingLock);
+        writeDocsLock(projectDir, lock);
+        if (options.json) {
+            console.log(JSON.stringify(lock, null, 2));
+            return;
+        }
+        console.log(`\n=== DocOrbit Project Initialization ===`);
+        console.log(`Workspace Root:  ${projectDir}`);
+        console.log(`Ecosystems:     ${scanResult.ecosystems.length > 0 ? scanResult.ecosystems.join(', ') : 'None detected'}`);
+        console.log(`Manifests:       ${scanResult.manifestsFound.join(', ') || 'None'}`);
+        console.log(`Dependencies:    ${scanResult.dependencies.length} detected`);
+        const lockedCount = Object.keys(lock.dependencies).length;
+        console.log(`Locked Docs:     ${lockedCount} dependencies resolved to documentation\n`);
+        if (lockedCount > 0) {
+            console.log('-----------------------------------------------------------------------------');
+            console.log('| Package               | Project Ver | Doc Ver  | Match       | Confidence |');
+            console.log('-----------------------------------------------------------------------------');
+            for (const [key, dep] of Object.entries(lock.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('-----------------------------------------------------------------------------');
+            console.log(`\nGenerated deterministic docs.lock at: ${projectDir}/docs.lock\n`);
+        }
+        else {
+            console.log('Note: No ingested documentation matched detected dependencies.');
+            console.log('Tip: Use `docorbit add <url>` to ingest official docs for your dependencies, then re-run `docorbit init`.\n');
+        }
+    }
+    catch (err) {
+        console.error(`DocOrbit Init Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    finally {
+        db.close();
+    }
+}

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

@@ -0,0 +1,5 @@
+export interface InspectCommandOptions {
+    json?: boolean;
+    allowLocalhost?: boolean;
+}
+export declare function runInspectCommand(targetUrl: string, options?: InspectCommandOptions): Promise<void>;

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

@@ -0,0 +1,24 @@
+import { inspectDocumentation } from "../../../../packages/core/src/index.js";
+import { formatInspectionReport } from "../formatters/terminal.js";
+export async function runInspectCommand(targetUrl, options = {}) {
+    if (!targetUrl) {
+        console.error('Error: Please provide a documentation target URL.');
+        console.error('Usage: docorbit inspect <url> [--json]');
+        process.exit(1);
+    }
+    try {
+        const report = await inspectDocumentation(targetUrl, {
+            allowLocalhostForTesting: options.allowLocalhost,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log(formatInspectionReport(report));
+        }
+    }
+    catch (err) {
+        console.error(`DocOrbit Inspection Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+}

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

@@ -0,0 +1,8 @@
+export interface McpCommandOptions {
+    stdio?: boolean;
+    port?: number;
+    host?: string;
+    dbPath?: string;
+    projectDir?: string;
+}
+export declare function runMcpCommand(options?: McpCommandOptions): Promise<void>;