docorbit 0.1.0 → 0.1.2

package/dist/packages/export/src/service.js

@@ -0,0 +1,210 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { WorkspaceResolver } from "../../workspace/src/index.js";
+import { RecipeEngine } from "../../retrieval/src/index.js";
+import { generateAgentsMd } from "./agents-md.js";
+import { generateClaudeMd } from "./claude-md.js";
+import { generateSkillMd } from "./skill-md.js";
+import { generateLlmsTxt } from "./llms-txt.js";
+import { buildDocumentationMap } from "./docs-map.js";
+export class ExportService {
+    repo;
+    workspaceResolver;
+    recipeEngine;
+    constructor(repo) {
+        this.repo = repo;
+        this.workspaceResolver = new WorkspaceResolver(repo);
+        this.recipeEngine = new RecipeEngine(repo);
+    }
+    /**
+     * Generates agent documentation export deterministically based on indexed evidence.
+     */
+    async generateExport(options) {
+        const projectDir = options.projectDir ? path.resolve(options.projectDir) : undefined;
+        const docVersion = options.docVersion;
+        // 1. Resolve workspace dependencies if project directory exists
+        const dependencies = [];
+        if (projectDir && fs.existsSync(projectDir)) {
+            try {
+                const resolvedMap = await this.workspaceResolver.resolveAllDependencies(projectDir);
+                for (const [, item] of resolvedMap) {
+                    dependencies.push({
+                        dep: item.dependency,
+                        resolution: item.resolution,
+                    });
+                }
+            }
+            catch {
+                // Workspace detection is best-effort
+            }
+        }
+        // 2. Fetch indexed sources & pages
+        const sources = this.repo.sources.listSources();
+        const sourceUrls = sources.map(s => s.url);
+        const pages = this.repo.pages.listPages(1000);
+        // 3. Fetch endpoints (filtered by docVersion if provided)
+        const endpoints = this.repo.apis.searchApiEndpoints('', {
+            docVersion,
+            limit: 200,
+        });
+        // 4. Fetch pitfalls (filtered by docVersion if provided)
+        const pitfalls = this.repo.pitfalls.searchPitfalls('', {
+            docVersion,
+            limit: 100,
+        });
+        // 5. Fetch code examples
+        const examples = this.repo.examples.searchIndexedExamples('', {
+            docVersion,
+            limit: 100,
+        });
+        // 6. Build recipes for common goals
+        const recipes = [];
+        const candidateGoals = [
+            'Stripe webhook signature verification',
+            'Handle webhook events',
+            'Create customer subscription',
+            'Dynamic route parameter migration',
+            'Authenticate API request',
+        ];
+        for (const goal of candidateGoals) {
+            try {
+                const recipe = this.recipeEngine.assembleRecipe(goal, { docVersion });
+                if (recipe.prerequisites.length > 0 || recipe.steps.length > 0) {
+                    recipes.push(recipe);
+                }
+            }
+            catch {
+                // Goal not covered by current index
+            }
+        }
+        // 7. Format generation
+        let content = '';
+        const format = options.format;
+        switch (format) {
+            case 'agents.md': {
+                content = generateAgentsMd({
+                    projectDir,
+                    docVersion,
+                    dependencies,
+                    endpoints,
+                    pitfalls,
+                    recipes,
+                    sources: sourceUrls,
+                });
+                break;
+            }
+            case 'claude.md': {
+                content = generateClaudeMd({
+                    projectDir,
+                    docVersion,
+                    dependencies,
+                    endpoints,
+                    pitfalls,
+                    sources: sourceUrls,
+                });
+                break;
+            }
+            case 'skill.md': {
+                content = generateSkillMd({
+                    skillName: options.targetSource || 'docorbit-agent-skill',
+                    docVersion,
+                    endpoints,
+                    pitfalls,
+                    recipes,
+                    sources: sourceUrls,
+                });
+                break;
+            }
+            case 'llms.txt': {
+                content = generateLlmsTxt({
+                    title: options.targetSource || 'Indexed Documentation',
+                    docVersion,
+                    pages,
+                    endpoints,
+                    pitfalls,
+                });
+                break;
+            }
+            case 'docs-map.md': {
+                const map = buildDocumentationMap({
+                    sources,
+                    pages,
+                    endpoints,
+                    pitfalls,
+                    docVersion,
+                });
+                content = map.markdownTree;
+                break;
+            }
+            default:
+                throw new Error(`Unsupported export format: ${format}`);
+        }
+        const tokenEstimate = Math.ceil(content.length / 4);
+        return {
+            format,
+            content,
+            outputPath: options.outputPath,
+            metadata: {
+                generatedAt: '2026-09-06T00:00:00.000Z', // Deterministic baseline timestamp
+                sources: sourceUrls,
+                docVersion,
+                projectDependencies: dependencies.map(d => ({
+                    name: d.dep.name,
+                    version: d.resolution?.targetVersion || d.dep.requestedVersion,
+                    matchType: d.resolution?.matchedBy || 'unresolved',
+                })),
+                totalApis: endpoints.length,
+                totalPitfalls: pitfalls.length,
+                totalExamples: examples.length,
+                tokenEstimate,
+                untrusted: true,
+            },
+        };
+    }
+    /**
+     * Retrieves the structured documentation map.
+     */
+    getDocumentationMap(options = {}) {
+        let sources = this.repo.sources.listSources();
+        if (options.sourceId) {
+            sources = sources.filter(s => s.id === options.sourceId || s.url.includes(options.sourceId));
+        }
+        const pages = this.repo.pages.listPages(1000);
+        const endpoints = this.repo.apis.searchApiEndpoints('', { docVersion: options.docVersion, limit: 500 });
+        const pitfalls = this.repo.pitfalls.searchPitfalls('', { docVersion: options.docVersion, limit: 200 });
+        return buildDocumentationMap({
+            sources,
+            pages,
+            endpoints,
+            pitfalls,
+            docVersion: options.docVersion,
+        });
+    }
+    /**
+     * Generates export and writes directly to workspace file.
+     */
+    async writeExport(options) {
+        const result = await this.generateExport(options);
+        if (!options.stdout) {
+            let targetFile = options.outputPath;
+            if (!targetFile) {
+                const baseDir = options.projectDir || process.cwd();
+                const defaultNames = {
+                    'agents.md': 'AGENTS.md',
+                    'claude.md': 'CLAUDE.md',
+                    'skill.md': 'skill.md',
+                    'llms.txt': 'llms.txt',
+                    'docs-map.md': 'docs-map.md',
+                };
+                targetFile = path.join(baseDir, defaultNames[options.format]);
+            }
+            const dir = path.dirname(targetFile);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.writeFileSync(targetFile, result.content, 'utf-8');
+            result.outputPath = targetFile;
+        }
+        return result;
+    }
+}

package/dist/packages/export/src/skill-md.d.ts

@@ -0,0 +1,14 @@
+import type { ApiEndpoint, Pitfall, Recipe } from '../../shared/src/index.ts';
+export interface SkillMdExportData {
+    skillName?: string;
+    docVersion?: string;
+    endpoints: ApiEndpoint[];
+    pitfalls: Pitfall[];
+    recipes: Recipe[];
+    sources: string[];
+}
+/**
+ * Generates a skill.md file compatible with AI agent skill systems.
+ * Embeds YAML frontmatter, deterministic recipes, and verified schemas.
+ */
+export declare function generateSkillMd(data: SkillMdExportData): string;

package/dist/packages/export/src/skill-md.js

@@ -0,0 +1,107 @@
+/**
+ * Generates a skill.md file compatible with AI agent skill systems.
+ * Embeds YAML frontmatter, deterministic recipes, and verified schemas.
+ */
+export function generateSkillMd(data) {
+    const lines = [];
+    const skillName = data.skillName || 'docorbit-implementation-skill';
+    const version = data.docVersion || '0.1.0';
+    // Frontmatter
+    lines.push('---');
+    lines.push(`name: ${skillName}`);
+    lines.push('description: Evidence-grounded documentation intelligence and API implementation recipes.');
+    lines.push(`version: ${version}`);
+    lines.push('untrusted_documentation: true');
+    lines.push('grounding: strict_evidence');
+    lines.push('---');
+    lines.push('');
+    lines.push(`# Skill: ${skillName} (${version})`);
+    lines.push('');
+    lines.push('This agent skill contains deterministic recipes and verified API signatures generated from authoritative');
+    lines.push('documentation. Never fabricate undocumented steps or validation rules.');
+    lines.push('');
+    // 1. Recipes
+    lines.push('## 1. Actionable Implementation Recipes');
+    lines.push('');
+    if (data.recipes.length > 0) {
+        for (const r of data.recipes) {
+            lines.push(`### Recipe: ${r.title}`);
+            lines.push(`- **Goal**: ${r.goal}`);
+            lines.push(`- **Evidence Status**: ${r.evidenceLevels.strictGrounded ? 'Grounded' : 'Partial'}`);
+            lines.push('');
+            if (r.prerequisites.length > 0) {
+                lines.push('**Prerequisites:**');
+                for (const pre of r.prerequisites) {
+                    lines.push(`- [${pre.evidenceLevel}] ${pre.description}`);
+                }
+                lines.push('');
+            }
+            if (r.steps.length > 0) {
+                lines.push('**Steps:**');
+                for (const step of r.steps) {
+                    lines.push(`${step.stepNumber}. [${step.evidenceLevel}] **${step.title}**: ${step.action}`);
+                    if (step.codeSnippet) {
+                        lines.push('   ```' + (step.codeSnippet.language || 'typescript'));
+                        lines.push(step.codeSnippet.code.trim().split('\n').map(l => '   ' + l).join('\n'));
+                        lines.push('   ```');
+                    }
+                }
+                lines.push('');
+            }
+            if (r.validationSteps.length > 0) {
+                lines.push('**Evidence-Based Validation:**');
+                for (const v of r.validationSteps) {
+                    lines.push(`- Verify: ${v.assertion} (Expected: \`${v.expectedOutcome}\`)`);
+                }
+                lines.push('');
+            }
+        }
+    }
+    else {
+        lines.push('- *No compiled recipes available for this scope.*');
+        lines.push('');
+    }
+    // 2. API Reference
+    lines.push('## 2. API Reference & Schemas');
+    lines.push('');
+    if (data.endpoints.length > 0) {
+        const sortedEndpoints = [...data.endpoints].sort((a, b) => {
+            const cmp = a.path.localeCompare(b.path);
+            return cmp !== 0 ? cmp : a.method.localeCompare(b.method);
+        });
+        for (const ep of sortedEndpoints) {
+            lines.push(`### \`${ep.method.toUpperCase()} ${ep.path}\``);
+            if (ep.summary)
+                lines.push(ep.summary);
+            if (ep.parameters && ep.parameters.length > 0) {
+                lines.push('Parameters:');
+                for (const p of ep.parameters) {
+                    lines.push(`- \`${p.name}\` (${p.in}, ${p.required ? 'required' : 'optional'})`);
+                }
+            }
+            lines.push('');
+        }
+    }
+    else {
+        lines.push('- *No endpoints indexed.*');
+        lines.push('');
+    }
+    // 3. Known Pitfalls
+    lines.push('## 3. Known Pitfalls & Defenses');
+    lines.push('');
+    if (data.pitfalls.length > 0) {
+        const sortedPitfalls = [...data.pitfalls].sort((a, b) => a.title.localeCompare(b.title));
+        for (const pf of sortedPitfalls) {
+            lines.push(`- **[${pf.kind}] ${pf.title}**: ${pf.message}`);
+            if (pf.mitigation) {
+                lines.push(`  - Defense: ${pf.mitigation}`);
+            }
+        }
+        lines.push('');
+    }
+    else {
+        lines.push('- *No pitfalls recorded.*');
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/{packages/mcp/src/index.ts → dist/packages/mcp/src/index.d.ts}

@@ -1,44 +1,11 @@
-export type {
-  JsonRpcRequest,
-  JsonRpcResponse,
-  JsonRpcNotification,
-  JsonRpcErrorObject,
-  ToolInputSchema,
-  McpTool,
-  ToolContentItem,
-  CallToolResult,
-  McpResource,
-  ResourceContent,
-  ReadResourceResult,
-  ServerCapabilities,
-  InitializeResult,
-} from './types.ts';
-
+export type { JsonRpcRequest, JsonRpcResponse, JsonRpcNotification, JsonRpcErrorObject, ToolInputSchema, McpTool, ToolContentItem, CallToolResult, McpResource, ResourceContent, ReadResourceResult, ServerCapabilities, InitializeResult, } from './types.ts';
 export { JSONRPC_ERRORS } from './types.ts';
-
 export type { McpContext, McpToolHandler } from './tools/types.ts';
-export {
-  createDefaultTools,
-  SearchDocsTool,
-  GetDocTool,
-  FindApiTool,
-  FindExampleTool,
-  FindPitfallTool,
-  FindRecipeTool,
-  GetVersionTool,
-  ListSourcesTool,
-  GetImplementationContextTool,
-  CheckApiTool,
-  DiffDocsTool,
-  AnalyzeImpactTool,
-} from './tools/index.ts';
-
+export { createDefaultTools, SearchDocsTool, GetDocTool, FindApiTool, FindExampleTool, FindPitfallTool, FindRecipeTool, GetVersionTool, ListSourcesTool, GetImplementationContextTool, CheckApiTool, DiffDocsTool, AnalyzeImpactTool, GetDocumentationMapTool, ExportAgentContextTool, IngestDocTool, } from './tools/index.ts';
 export type { ResourceManagerOptions } from './resources/index.ts';
 export { McpResourceManager } from './resources/index.ts';
-
 export type { McpServerOptions } from './server.ts';
 export { McpServer } from './server.ts';
-
 export type { McpTransport } from './transports/types.ts';
 export type { StdioTransportOptions } from './transports/stdio.ts';
 export { StdioServerTransport } from './transports/stdio.ts';

package/dist/packages/mcp/src/index.js

@@ -0,0 +1,6 @@
+export { JSONRPC_ERRORS } from "./types.js";
+export { createDefaultTools, SearchDocsTool, GetDocTool, FindApiTool, FindExampleTool, FindPitfallTool, FindRecipeTool, GetVersionTool, ListSourcesTool, GetImplementationContextTool, CheckApiTool, DiffDocsTool, AnalyzeImpactTool, GetDocumentationMapTool, ExportAgentContextTool, IngestDocTool, } from "./tools/index.js";
+export { McpResourceManager } from "./resources/index.js";
+export { McpServer } from "./server.js";
+export { StdioServerTransport } from "./transports/stdio.js";
+export { StreamableHttpTransport } from "./transports/http.js";

package/dist/packages/mcp/src/resources/index.d.ts

@@ -0,0 +1,12 @@
+import type { DocOrbitRepository } from '../../../storage/src/index.ts';
+import type { McpResource, ReadResourceResult } from '../types.ts';
+export interface ResourceManagerOptions {
+    maxResourceBytes?: number;
+}
+export declare class McpResourceManager {
+    private repo;
+    private maxChars;
+    constructor(repo: DocOrbitRepository, options?: ResourceManagerOptions);
+    listResources(): McpResource[];
+    readResource(uri: string): ReadResourceResult;
+}

package/dist/packages/mcp/src/resources/index.js

@@ -0,0 +1,165 @@
+export class McpResourceManager {
+    repo;
+    maxChars;
+    constructor(repo, options = {}) {
+        this.repo = repo;
+        // Default 64KB bounded limit
+        this.maxChars = options.maxResourceBytes || 64 * 1024;
+    }
+    listResources() {
+        const resources = [
+            {
+                uri: 'docorbit://sources',
+                name: 'Indexed Documentation Sources',
+                description: 'Collection of all indexed documentation sources, version status, and snapshots.',
+                mimeType: 'application/json',
+            },
+        ];
+        try {
+            const sources = this.repo.listSources();
+            for (const source of sources) {
+                resources.push({
+                    uri: `docorbit://sources/${source.id}`,
+                    name: `Source: ${source.url}`,
+                    description: `Indexed documentation source (${source.type}, authority: ${source.authority})`,
+                    mimeType: 'application/json',
+                });
+            }
+        }
+        catch {
+            // Continue if database is empty or error occurs
+        }
+        try {
+            const pages = this.repo.listPages(100);
+            for (const page of pages) {
+                resources.push({
+                    uri: `docorbit://pages/${page.id}`,
+                    name: `Page: ${page.title || page.url}`,
+                    description: `Documentation page at ${page.url} (~${page.estimatedTokens} tokens)`,
+                    mimeType: 'text/markdown',
+                });
+            }
+        }
+        catch {
+            // Continue
+        }
+        return resources;
+    }
+    readResource(uri) {
+        if (uri === 'docorbit://sources') {
+            const sources = this.repo.listSources();
+            const snapshots = this.repo.listSnapshots();
+            const payload = sources.map(s => ({
+                id: s.id,
+                url: s.url,
+                type: s.type,
+                authority: s.authority,
+                confidence: s.confidence,
+                status: s.status,
+                machineReadable: s.machineReadable,
+                snapshots: snapshots.filter(sn => sn.sourceId === s.id).map(sn => ({
+                    id: sn.id,
+                    pageCount: sn.pageCount,
+                    docVersion: sn.docVersion,
+                    capturedAt: sn.capturedAt,
+                })),
+            }));
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(payload, null, 2),
+                    },
+                ],
+            };
+        }
+        if (uri.startsWith('docorbit://sources/')) {
+            const sourceId = uri.slice('docorbit://sources/'.length);
+            const source = this.repo.getSource(sourceId);
+            if (!source) {
+                throw new Error(`Resource not found: ${uri}`);
+            }
+            const snapshots = this.repo.listSnapshots().filter(sn => sn.sourceId === source.id);
+            const pageCount = this.repo.countPages(source.id);
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: 'application/json',
+                        text: JSON.stringify({
+                            source,
+                            pageCount,
+                            snapshots,
+                            untrusted: true,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        if (uri.startsWith('docorbit://pages/')) {
+            const pageId = uri.slice('docorbit://pages/'.length);
+            const page = this.repo.getPage(pageId);
+            if (!page) {
+                throw new Error(`Resource not found: ${uri}`);
+            }
+            let content = page.content;
+            let truncated = false;
+            if (content.length > this.maxChars) {
+                content = content.slice(0, this.maxChars) + '\n\n[Content truncated at 64KB bounded resource limit...]';
+                truncated = true;
+            }
+            const header = [
+                `# ${page.title}`,
+                `**URL**: ${page.url}`,
+                `**Tokens**: ~${page.estimatedTokens} | **Content Hash**: \`${page.contentHash.slice(0, 8)}\``,
+                page.securityAnnotations.length > 0
+                    ? `> [!WARNING] Security alerts: ${page.securityAnnotations.map(a => a.patternName).join(', ')}`
+                    : `> [!NOTE] External content is untrusted.`,
+                truncated ? `> [!IMPORTANT] Output was truncated to meet resource limits.` : '',
+                '---\n',
+            ].filter(Boolean).join('\n');
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: 'text/markdown',
+                        text: `${header}\n${content}`,
+                    },
+                ],
+            };
+        }
+        if (uri.startsWith('docorbit://chunks/')) {
+            const chunkId = uri.slice('docorbit://chunks/'.length);
+            const chunk = this.repo.getChunk(chunkId);
+            if (!chunk) {
+                throw new Error(`Resource not found: ${uri}`);
+            }
+            let content = chunk.content;
+            let truncated = false;
+            if (content.length > this.maxChars) {
+                content = content.slice(0, this.maxChars) + '\n\n[Content truncated at bounded limit...]';
+                truncated = true;
+            }
+            const breadcrumb = chunk.sectionPath.length > 0 ? chunk.sectionPath.join(' > ') : (chunk.title || 'General');
+            const header = [
+                `### Chunk: ${breadcrumb}`,
+                `**ID**: \`${chunk.id}\` | **Type**: \`${chunk.chunkType}\` | **Est. Tokens**: ~${chunk.tokenEstimate}`,
+                chunk.docVersion ? `**Doc Version**: \`${chunk.docVersion}\`` : '',
+                `> [!NOTE] External content is untrusted.\n`,
+                truncated ? `> [!IMPORTANT] Output was truncated to meet resource limits.\n` : '',
+                '---\n',
+            ].filter(Boolean).join('\n');
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: 'text/markdown',
+                        text: `${header}\n${content}`,
+                    },
+                ],
+            };
+        }
+        throw new Error(`Unsupported resource URI: ${uri}`);
+    }
+}

package/dist/packages/mcp/src/server.d.ts

@@ -0,0 +1,30 @@
+import type { DocOrbitRepository } from '../../storage/src/index.ts';
+import type { WorkspaceResolver } from '../../workspace/src/index.ts';
+import type { JsonRpcResponse, McpTool } from './types.ts';
+import type { McpContext, McpToolHandler } from './tools/types.ts';
+import { McpResourceManager } from './resources/index.ts';
+export interface McpServerOptions {
+    repo: DocOrbitRepository;
+    resolver?: WorkspaceResolver;
+    projectDir?: string;
+    serverName?: string;
+    serverVersion?: string;
+    tools?: Map<string, McpToolHandler>;
+    maxResourceBytes?: number;
+}
+export declare class McpServer {
+    private repo;
+    private resolver?;
+    private projectDir?;
+    private serverName;
+    private serverVersion;
+    private tools;
+    private resourceManager;
+    private context;
+    private initialized;
+    constructor(options: McpServerOptions);
+    getContext(): McpContext;
+    getResourceManager(): McpResourceManager;
+    getTools(): McpTool[];
+    handleMessage(raw: unknown): Promise<JsonRpcResponse | null>;
+}