docorbit 0.1.0 → 0.1.1

package/dist/packages/mcp/src/tools/find-example.js

@@ -0,0 +1,92 @@
+export class FindExampleTool {
+    definition = {
+        name: 'find_example',
+        description: 'Find verified, framework-specific code examples by task, language, framework, or target API.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Implementation task or symbol to look for examples of (e.g. "verify webhook signature", "constructEvent").',
+                },
+                language: {
+                    type: 'string',
+                    description: 'Programming language filter (e.g. "typescript", "python", "go").',
+                },
+                framework: {
+                    type: 'string',
+                    description: 'Framework filter (e.g. "express", "fastapi", "next").',
+                },
+                version: {
+                    type: 'string',
+                    description: 'Target documentation version filter.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of examples to return (default: 5).',
+                },
+            },
+            required: ['query'],
+        },
+    };
+    async execute(args, ctx) {
+        const query = typeof args.query === 'string'
+            ? args.query.trim()
+            : (typeof args.task === 'string' ? args.task.trim() : '');
+        if (!query) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify({ error: 'Missing required parameter: query (or task)' }) }],
+            };
+        }
+        const language = typeof args.language === 'string' ? args.language : undefined;
+        const framework = typeof args.framework === 'string' ? args.framework : undefined;
+        const version = typeof args.docVersion === 'string'
+            ? args.docVersion
+            : (typeof args.version === 'string' ? args.version : undefined);
+        const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 5;
+        const examples = ctx.repo.searchIndexedExamples(query, {
+            language,
+            framework,
+            docVersion: version,
+            limit,
+        });
+        if (examples.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            markdown: `### Code Examples for "${query}"\n\nNo verified code examples found.`,
+                            data: { query, count: 0, examples: [] },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const lines = [`### Verified Code Examples for "${query}" (${examples.length} found)\n`];
+        for (const ex of examples) {
+            lines.push(`#### ${ex.task} [${ex.language}${ex.framework ? ` / ${ex.framework}` : ''}] (${ex.sourceAuthority})`);
+            if (ex.relatedApi)
+                lines.push(`*Target API*: \`${ex.relatedApi}\``);
+            lines.push('```' + ex.language);
+            lines.push(ex.code);
+            lines.push('```\n');
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        markdown: lines.join('\n'),
+                        data: {
+                            query,
+                            count: examples.length,
+                            examples,
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+}

package/dist/packages/mcp/src/tools/find-pitfall.d.ts

@@ -0,0 +1,6 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+export declare class FindPitfallTool implements McpToolHandler {
+    readonly definition: McpTool;
+    execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult>;
+}

package/dist/packages/mcp/src/tools/find-pitfall.js

@@ -0,0 +1,85 @@
+export class FindPitfallTool {
+    definition = {
+        name: 'find_pitfall',
+        description: 'Search documented pitfalls, gotchas, deprecations, breaking changes, and runtime restrictions.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Topic, feature, or symbol to inspect for pitfalls (e.g. "webhook raw body", "route params").',
+                },
+                kind: {
+                    type: 'string',
+                    description: 'Category filter for pitfalls.',
+                    enum: ['deprecated', 'removed', 'breaking_change', 'gotcha', 'security', 'runtime_restriction', 'server_only', 'rate_limit'],
+                },
+                version: {
+                    type: 'string',
+                    description: 'Target documentation version filter.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of pitfalls to return (default: 5).',
+                },
+            },
+            required: ['query'],
+        },
+    };
+    async execute(args, ctx) {
+        const query = typeof args.query === 'string'
+            ? args.query.trim()
+            : (typeof args.task === 'string' ? args.task.trim() : '');
+        if (!query) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify({ error: 'Missing required parameter: query (or task)' }) }],
+            };
+        }
+        const kind = typeof args.kind === 'string' ? args.kind : undefined;
+        const version = typeof args.docVersion === 'string'
+            ? args.docVersion
+            : (typeof args.version === 'string' ? args.version : undefined);
+        const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 5;
+        const pitfalls = ctx.repo.searchPitfalls(query, {
+            kind,
+            docVersion: version,
+            limit,
+        });
+        if (pitfalls.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            markdown: `### Pitfalls & Warnings for "${query}"\n\nNo matching pitfalls or warnings found.`,
+                            data: { query, count: 0, pitfalls: [] },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const lines = [`### Pitfalls & Warnings for "${query}" (${pitfalls.length} found)\n`];
+        for (const pf of pitfalls) {
+            lines.push(`- ⚠️ **[${pf.kind.toUpperCase()}] ${pf.title}**${pf.docVersion ? ` (${pf.docVersion})` : ''}`);
+            if (pf.relatedApi)
+                lines.push(`  *Related API*: \`${pf.relatedApi}\``);
+            lines.push(`  ${pf.content}\n`);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        markdown: lines.join('\n'),
+                        data: {
+                            query,
+                            count: pitfalls.length,
+                            pitfalls,
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+}

package/dist/packages/mcp/src/tools/find-recipe.d.ts

@@ -0,0 +1,6 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+export declare class FindRecipeTool implements McpToolHandler {
+    readonly definition: McpTool;
+    execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult>;
+}

package/dist/packages/mcp/src/tools/find-recipe.js

@@ -0,0 +1,89 @@
+import { RecipeEngine } from "../../../retrieval/src/index.js";
+export class FindRecipeTool {
+    definition = {
+        name: 'find_recipe',
+        description: 'Assemble an evidence-grounded implementation recipe with explicit prerequisites, ordered steps, and validation steps.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                goal: {
+                    type: 'string',
+                    description: 'The implementation goal or workflow to construct a recipe for.',
+                },
+                version: {
+                    type: 'string',
+                    description: 'Target documentation version.',
+                },
+                projectPath: {
+                    type: 'string',
+                    description: 'Workspace root for project-aware dependency detection.',
+                },
+            },
+            required: ['goal'],
+        },
+    };
+    async execute(args, ctx) {
+        const goal = typeof args.goal === 'string'
+            ? args.goal.trim()
+            : (typeof args.task === 'string' ? args.task.trim() : (typeof args.query === 'string' ? args.query.trim() : ''));
+        if (!goal) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify({ error: 'Missing required parameter: goal (or task)' }) }],
+            };
+        }
+        const version = typeof args.docVersion === 'string'
+            ? args.docVersion
+            : (typeof args.version === 'string' ? args.version : undefined);
+        const projectPath = typeof args.projectPath === 'string'
+            ? args.projectPath
+            : (typeof args.project === 'string' ? args.project : ctx.workspaceRoot);
+        const engine = new RecipeEngine(ctx.repo);
+        const recipe = await engine.assembleRecipe(goal, {
+            docVersion: version,
+            projectDir: projectPath,
+        });
+        const lines = [
+            `### Implementation Recipe: ${recipe.goal}`,
+            `**Confidence**: ${Math.round(recipe.confidence * 100)}%${recipe.docVersion ? ` | **Version**: \`${recipe.docVersion}\`` : ''}\n`,
+        ];
+        if (recipe.prerequisites.length > 0) {
+            lines.push('#### Prerequisites');
+            for (const p of recipe.prerequisites) {
+                lines.push(`- [${p.evidenceLevel === 'documented_fact' ? 'FACT' : 'INFERRED'}] ${p.text}`);
+            }
+            lines.push('');
+        }
+        if (recipe.orderedSteps.length > 0) {
+            lines.push('#### Implementation Steps');
+            for (const s of recipe.orderedSteps) {
+                const badge = s.evidenceLevel === 'documented_fact' ? 'FACT' : (s.evidenceLevel === 'missing_information' ? 'MISSING' : 'INFERRED');
+                lines.push(`${s.step}. **[${badge}] ${s.title}**`);
+                if (s.apiEndpoint)
+                    lines.push(`   - Endpoint: \`${s.apiEndpoint}\``);
+                lines.push(`   - ${s.description}`);
+            }
+            lines.push('');
+        }
+        if (recipe.validationSteps.length > 0) {
+            lines.push('#### Validation Steps');
+            for (const vs of recipe.validationSteps) {
+                lines.push(`${vs.step}. **[FACT]** ${vs.description}`);
+                if (vs.expectedResponse)
+                    lines.push(`   - Expected: \`${vs.expectedResponse}\``);
+            }
+            lines.push('');
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        markdown: lines.join('\n'),
+                        data: recipe,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+}

package/dist/packages/mcp/src/tools/get-doc.d.ts

@@ -0,0 +1,6 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+export declare class GetDocTool implements McpToolHandler {
+    readonly definition: McpTool;
+    execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult>;
+}

package/dist/packages/mcp/src/tools/get-doc.js

@@ -0,0 +1,118 @@
+export class GetDocTool {
+    definition = {
+        name: 'get_doc',
+        description: 'Retrieve a specific documentation page or contextual chunk by ID or URL with complete metadata and security annotations.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                chunkId: {
+                    type: 'string',
+                    description: 'Unique chunk identifier (e.g. "chk_...").',
+                },
+                pageId: {
+                    type: 'string',
+                    description: 'Unique page identifier (e.g. "page_...").',
+                },
+                url: {
+                    type: 'string',
+                    description: 'Normalized source URL of the documentation page.',
+                },
+            },
+        },
+    };
+    async execute(args, ctx) {
+        const chunkId = typeof args.chunkId === 'string' ? args.chunkId.trim() : undefined;
+        const pageId = typeof args.pageId === 'string' ? args.pageId.trim() : undefined;
+        const url = typeof args.url === 'string' ? args.url.trim() : undefined;
+        if (!chunkId && !pageId && !url) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ error: 'Please provide at least one identifier: chunkId, pageId, or url.' }),
+                    },
+                ],
+            };
+        }
+        if (chunkId) {
+            const chunk = ctx.repo.getChunk(chunkId);
+            if (!chunk) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ error: `Chunk not found: ${chunkId}`, available: false }),
+                        },
+                    ],
+                };
+            }
+            const codeSnippets = ctx.repo.getChunkCode(chunkId);
+            const symbols = ctx.repo.getChunkSymbols(chunkId);
+            const relationships = ctx.repo.getChunkRelationships(chunkId);
+            const breadcrumb = chunk.sectionPath.length > 0 ? chunk.sectionPath.join(' > ') : (chunk.title || 'General');
+            const md = [
+                `### Chunk: ${breadcrumb}`,
+                `**ID**: \`${chunk.id}\` | **Type**: \`${chunk.chunkType}\` | **Est. Tokens**: ~${chunk.tokenEstimate}`,
+                chunk.docVersion ? `**Version**: \`${chunk.docVersion}\`` : '',
+                `> [!NOTE] External content is untrusted.\n`,
+                chunk.content,
+            ].filter(Boolean).join('\n\n');
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            markdown: md,
+                            data: {
+                                chunk,
+                                codeSnippets,
+                                symbols,
+                                relationships,
+                                untrusted: true,
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        // Page lookup by ID or URL
+        const page = pageId ? ctx.repo.getPage(pageId) : (url ? ctx.repo.getPageByUrl(url) : null);
+        if (!page) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ error: `Page not found for ${pageId ? `pageId: ${pageId}` : `url: ${url}`}`, available: false }),
+                    },
+                ],
+            };
+        }
+        const links = ctx.repo.getPageLinks(page.id);
+        const md = [
+            `### ${page.title}`,
+            `**URL**: ${page.url} | **Tokens**: ~${page.estimatedTokens} | **Hash**: \`${page.contentHash.slice(0, 8)}\``,
+            page.securityAnnotations.length > 0
+                ? `> [!WARNING] Security alerts detected: ${page.securityAnnotations.map(a => a.patternName).join(', ')}`
+                : `> [!NOTE] External content is untrusted.`,
+            `\n${page.content}`,
+        ].join('\n\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        markdown: md,
+                        data: {
+                            page,
+                            links,
+                            untrusted: true,
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+}

package/dist/packages/mcp/src/tools/get-docs-map.d.ts

@@ -0,0 +1,6 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+export declare class GetDocumentationMapTool implements McpToolHandler {
+    readonly definition: McpTool;
+    execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult>;
+}

package/dist/packages/mcp/src/tools/get-docs-map.js

@@ -0,0 +1,54 @@
+import { ExportService } from "../../../export/src/index.js";
+export class GetDocumentationMapTool {
+    definition = {
+        name: 'get_documentation_map',
+        description: 'Retrieve the hierarchical documentation map, page tree, section headings, and estimated token budget footprints for indexed documentation.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sourceId: {
+                    type: 'string',
+                    description: 'Optional source ID or source URL substring filter.',
+                },
+                docVersion: {
+                    type: 'string',
+                    description: 'Optional documentation version filter (e.g. "v14", "15.0").',
+                },
+            },
+        },
+    };
+    async execute(args, ctx) {
+        const sourceId = typeof args.sourceId === 'string' ? args.sourceId : undefined;
+        const docVersion = typeof args.docVersion === 'string' ? args.docVersion : undefined;
+        const exportService = ctx.exportService || new ExportService(ctx.repo);
+        const map = exportService.getDocumentationMap({ sourceId, docVersion });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        markdown: map.markdownTree,
+                        data: {
+                            totalSources: map.totalSources,
+                            totalPages: map.totalPages,
+                            totalChunks: map.totalChunks,
+                            totalEstimatedTokens: map.totalEstimatedTokens,
+                            sources: map.sources,
+                            pages: map.pages.map(p => ({
+                                id: p.id,
+                                title: p.title,
+                                url: p.url,
+                                version: p.version,
+                                chunkCount: p.chunkCount,
+                                estimatedTokens: p.estimatedTokens,
+                                apis: p.apis,
+                                pitfallCount: p.pitfallCount,
+                            })),
+                            untrusted: true,
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+}

package/dist/packages/mcp/src/tools/get-version.d.ts

@@ -0,0 +1,6 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+export declare class GetVersionTool implements McpToolHandler {
+    readonly definition: McpTool;
+    execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult>;
+}

package/dist/packages/mcp/src/tools/get-version.js

@@ -0,0 +1,104 @@
+import { detectWorkspaceDependencies, WorkspaceResolver, } from "../../../workspace/src/index.js";
+export class GetVersionTool {
+    definition = {
+        name: 'get_version',
+        description: 'Inspect workspace dependencies and resolve the exact compatible documentation version using the SemVer confidence ladder.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                library: {
+                    type: 'string',
+                    description: 'Package or library name to check (e.g. "next", "stripe", "fastapi").',
+                },
+                projectPath: {
+                    type: 'string',
+                    description: 'Workspace root directory containing package manifests (default: current directory).',
+                },
+            },
+            required: ['library'],
+        },
+    };
+    async execute(args, ctx) {
+        const library = typeof args.library === 'string' ? args.library.trim() : '';
+        if (!library) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify({ error: 'Missing required parameter: library' }) }],
+            };
+        }
+        const projectPath = typeof args.projectPath === 'string' ? args.projectPath : (ctx.workspaceRoot || '.');
+        let scan;
+        try {
+            scan = detectWorkspaceDependencies(projectPath);
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ error: `Failed to inspect workspace manifests at ${projectPath}: ${err instanceof Error ? err.message : String(err)}` }),
+                    },
+                ],
+            };
+        }
+        const libLower = library.toLowerCase();
+        const matchedDep = scan.dependencies.find(d => d.name.toLowerCase() === libLower);
+        if (!matchedDep) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            markdown: `### Version Resolution for "${library}"\n\nNo installed dependency named \`${library}\` was found in workspace manifests.`,
+                            data: {
+                                library,
+                                foundInWorkspace: false,
+                                ecosystemsScanned: scan.ecosystems,
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const resolver = new WorkspaceResolver(ctx.repo);
+        const resolution = resolver.resolveWorkspace(scan);
+        const match = resolution.matches.find(m => m.dependency.name.toLowerCase() === libLower);
+        const data = {
+            library: matchedDep.name,
+            ecosystem: matchedDep.ecosystem,
+            requestedVersion: matchedDep.requestedVersion,
+            resolvedVersion: matchedDep.resolvedVersion,
+            sourceFile: matchedDep.sourceFile,
+            docVersionMatch: match ? {
+                targetVersion: match.targetVersion,
+                confidence: match.confidence,
+                snapshotId: match.snapshotId,
+                matchedBy: match.matchedBy,
+            } : {
+                targetVersion: 'unresolved',
+                confidence: 'unresolved',
+            },
+        };
+        const lines = [
+            `### Version Intelligence: \`${matchedDep.name}\``,
+            `- **Ecosystem**: \`${matchedDep.ecosystem}\``,
+            `- **Requested in Manifest**: \`${matchedDep.requestedVersion}\` (${matchedDep.sourceFile})`,
+            matchedDep.resolvedVersion ? `- **Resolved in Lockfile**: \`${matchedDep.resolvedVersion}\`` : '',
+            match?.targetVersion
+                ? `- **Recommended Doc Version**: \`${match.targetVersion}\` (Confidence: \`${match.confidence}\`, Matched via: \`${match.matchedBy}\`)`
+                : `- **Recommended Doc Version**: \`unresolved\` (No compatible indexed documentation found)`,
+        ].filter(Boolean);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        markdown: lines.join('\n'),
+                        data,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+}

package/dist/packages/mcp/src/tools/implementation-context.d.ts

@@ -0,0 +1,6 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+export declare class ImplementationContextTool implements McpToolHandler {
+    readonly definition: McpTool;
+    execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult>;
+}

package/dist/packages/mcp/src/tools/implementation-context.js

@@ -0,0 +1,82 @@
+export class ImplementationContextTool {
+    definition = {
+        name: 'get_implementation_context',
+        description: 'High-level documentation intelligence orchestrator. Automatically resolves workspace dependencies and versions, detects task intent, retrieves relevant chunks, APIs, verified examples, and pitfalls, and compiles an evidence-grounded recipe within a strict token budget.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task: {
+                    type: 'string',
+                    description: 'The specific coding task or feature to implement (e.g. "Implement Stripe webhook signature verification in Express").',
+                },
+                project: {
+                    type: 'string',
+                    description: 'Path to repository workspace root for project-aware dependency detection (default: current directory).',
+                },
+                library: {
+                    type: 'string',
+                    description: 'Optional primary library or package to focus documentation on (e.g. "stripe", "next").',
+                },
+                version: {
+                    type: 'string',
+                    description: 'Optional explicit target documentation version (e.g. "v14", "15.0").',
+                },
+                tokenBudget: {
+                    type: 'number',
+                    description: 'Maximum token budget for packed context (default: 4000).',
+                },
+            },
+            required: ['task'],
+        },
+    };
+    async execute(args, ctx) {
+        const task = typeof args.task === 'string' ? args.task.trim() : '';
+        if (!task) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify({ error: 'Missing required parameter: task' }) }],
+            };
+        }
+        const projectPath = typeof args.project === 'string'
+            ? args.project
+            : (ctx.workspaceRoot || '.');
+        const library = typeof args.library === 'string' ? args.library : undefined;
+        const version = typeof args.version === 'string' ? args.version : undefined;
+        const tokenBudget = typeof args.tokenBudget === 'number' && args.tokenBudget > 0
+            ? args.tokenBudget
+            : 4000;
+        try {
+            const result = await ctx.implService.getContext({
+                task,
+                projectPath,
+                library,
+                version,
+                tokenBudget,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            markdown: result.markdown,
+                            data: result,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: `Failed to compile implementation context: ${err instanceof Error ? err.message : String(err)}`,
+                        }),
+                    },
+                ],
+            };
+        }
+    }
+}