docorbit 0.1.0 → 0.1.1

package/packages/export/src/service.ts

@@ -1,250 +0,0 @@
-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

@@ -1,128 +0,0 @@
-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/resources/index.ts

@@ -1,189 +0,0 @@
-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}`);
-  }
-}