docorbit 0.1.0

package/packages/export/src/service.ts

@@ -0,0 +1,250 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type {
+  DocOrbitRepository,
+} from '../../storage/src/index.ts';
+import { WorkspaceResolver } from '../../workspace/src/index.ts';
+import { RecipeEngine } from '../../retrieval/src/index.ts';
+import type {
+  ExportFormat,
+  ExportOptions,
+  ExportResult,
+  DocumentationMapResult,
+  ProjectDependency,
+  VersionResolutionResult,
+  ApiEndpoint,
+  Pitfall,
+  Recipe,
+  NormalizedPage,
+  DiscoveredSource,
+} from '../../shared/src/index.ts';
+import { generateAgentsMd } from './agents-md.ts';
+import { generateClaudeMd } from './claude-md.ts';
+import { generateSkillMd } from './skill-md.ts';
+import { generateLlmsTxt } from './llms-txt.ts';
+import { buildDocumentationMap } from './docs-map.ts';
+
+export class ExportService {
+  private repo: DocOrbitRepository;
+  private workspaceResolver: WorkspaceResolver;
+  private recipeEngine: RecipeEngine;
+
+  constructor(repo: DocOrbitRepository) {
+    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: ExportOptions): Promise<ExportResult> {
+    const projectDir = options.projectDir ? path.resolve(options.projectDir) : undefined;
+    const docVersion = options.docVersion;
+
+    // 1. Resolve workspace dependencies if project directory exists
+    const dependencies: Array<{
+      dep: ProjectDependency;
+      resolution?: VersionResolutionResult;
+    }> = [];
+
+    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: Recipe[] = [];
+    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: { sourceId?: string; docVersion?: string } = {}): DocumentationMapResult {
+    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: ExportOptions): Promise<ExportResult> {
+    const result = await this.generateExport(options);
+
+    if (!options.stdout) {
+      let targetFile = options.outputPath;
+      if (!targetFile) {
+        const baseDir = options.projectDir || process.cwd();
+        const defaultNames: Record<ExportFormat, string> = {
+          '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/packages/export/src/skill-md.ts

@@ -0,0 +1,128 @@
+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 function generateSkillMd(data: SkillMdExportData): string {
+  const lines: string[] = [];
+  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

@@ -0,0 +1,46 @@
+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 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';
+export type { HttpTransportOptions } from './transports/http.ts';
+export { StreamableHttpTransport } from './transports/http.ts';

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

@@ -0,0 +1,189 @@
+import type { DocOrbitRepository } from '../../../storage/src/index.ts';
+import type { McpResource, ReadResourceResult, ResourceContent } from '../types.ts';
+
+export interface ResourceManagerOptions {
+  maxResourceBytes?: number;
+}
+
+export class McpResourceManager {
+  private repo: DocOrbitRepository;
+  private maxChars: number;
+
+  constructor(repo: DocOrbitRepository, options: ResourceManagerOptions = {}) {
+    this.repo = repo;
+    // Default 64KB bounded limit
+    this.maxChars = options.maxResourceBytes || 64 * 1024;
+  }
+
+  listResources(): McpResource[] {
+    const resources: McpResource[] = [
+      {
+        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: string): ReadResourceResult {
+    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}`);
+  }
+}