docorbit 0.1.0 → 0.1.2

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

@@ -1,59 +0,0 @@
-import type { McpToolHandler } from './types.ts';
-import { SearchDocsTool } from './search-docs.ts';
-import { GetDocTool } from './get-doc.ts';
-import { FindApiTool } from './find-api.ts';
-import { FindExampleTool } from './find-example.ts';
-import { FindPitfallTool } from './find-pitfall.ts';
-import { FindRecipeTool } from './find-recipe.ts';
-import { GetVersionTool } from './get-version.ts';
-import { ListSourcesTool } from './list-sources.ts';
-import { ImplementationContextTool } from './implementation-context.ts';
-import { CheckApiTool } from './check-api.ts';
-import { DiffDocsTool } from './diff-docs.ts';
-import { AnalyzeImpactTool } from './analyze-impact.ts';
-import { GetDocumentationMapTool } from './get-docs-map.ts';
-import { ExportAgentContextTool } from './export-context.ts';
-
-export * from './types.ts';
-export {
-  SearchDocsTool,
-  GetDocTool,
-  FindApiTool,
-  FindExampleTool,
-  FindPitfallTool,
-  FindRecipeTool,
-  GetVersionTool,
-  ListSourcesTool,
-  ImplementationContextTool,
-  ImplementationContextTool as GetImplementationContextTool,
-  CheckApiTool,
-  DiffDocsTool,
-  AnalyzeImpactTool,
-  GetDocumentationMapTool,
-  ExportAgentContextTool,
-};
-
-export function createDefaultTools(): Map<string, McpToolHandler> {
-  const tools = new Map<string, McpToolHandler>();
-  const list: McpToolHandler[] = [
-    new SearchDocsTool(),
-    new GetDocTool(),
-    new FindApiTool(),
-    new FindExampleTool(),
-    new FindPitfallTool(),
-    new FindRecipeTool(),
-    new GetVersionTool(),
-    new ListSourcesTool(),
-    new ImplementationContextTool(),
-    new CheckApiTool(),
-    new DiffDocsTool(),
-    new AnalyzeImpactTool(),
-    new GetDocumentationMapTool(),
-    new ExportAgentContextTool(),
-  ];
-  for (const tool of list) {
-    tools.set(tool.definition.name, tool);
-  }
-  return tools;
-}
-

package/packages/mcp/src/tools/list-sources.ts

@@ -1,85 +0,0 @@
-import type { CallToolResult, McpTool } from '../types.ts';
-import type { McpContext, McpToolHandler } from './types.ts';
-
-export class ListSourcesTool implements McpToolHandler {
-  readonly definition: McpTool = {
-    name: 'list_sources',
-    description: 'List all indexed documentation sources, snapshot records, doc versions, and machine-readability status.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        limit: {
-          type: 'number',
-          description: 'Maximum number of sources to list (default: 50).',
-        },
-      },
-    },
-  };
-
-  async execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult> {
-    const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 50;
-
-    const sources = ctx.repo.listSources().slice(0, limit);
-    const snapshots = ctx.repo.listSnapshots();
-
-    if (sources.length === 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: JSON.stringify({
-              markdown: '### Indexed Documentation Sources\n\nNo documentation sources have been added yet. Use `docorbit add <url>` to ingest documentation.',
-              data: { count: 0, sources: [] },
-            }, null, 2),
-          },
-        ],
-      };
-    }
-
-    const formatted = sources.map(s => {
-      const sourceSnaps = snapshots.filter(sn => sn.sourceId === s.id);
-      return {
-        id: s.id,
-        url: s.url,
-        type: s.type,
-        status: s.status,
-        authority: s.authority,
-        confidence: s.confidence,
-        machineReadable: s.machineReadable,
-        snapshots: sourceSnaps.map(sn => ({
-          id: sn.id,
-          pageCount: sn.pageCount,
-          docVersion: sn.docVersion,
-          capturedAt: sn.capturedAt,
-        })),
-      };
-    });
-
-    const lines: string[] = [`### Indexed Documentation Sources (${sources.length} sources)\n`];
-    for (const s of formatted) {
-      const icon = s.status === 'valid' ? '✓' : '✗';
-      lines.push(`- **${icon} [${s.type}]** ${s.url}`);
-      lines.push(`  *Authority*: ${s.authority} | *Confidence*: ${Math.round(s.confidence * 100)}% | *Machine-Readable*: ${s.machineReadable}`);
-      if (s.snapshots.length > 0) {
-        const snapInfo = s.snapshots.map(sn => `${sn.id}${sn.docVersion ? ` (${sn.docVersion})` : ''} [${sn.pageCount} pages]`).join(', ');
-        lines.push(`  *Snapshots*: ${snapInfo}`);
-      }
-      lines.push('');
-    }
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify({
-            markdown: lines.join('\n'),
-            data: {
-              count: formatted.length,
-              sources: formatted,
-            },
-          }, null, 2),
-        },
-      ],
-    };
-  }
-}

package/packages/mcp/src/tools/search-docs.ts

@@ -1,123 +0,0 @@
-import { RetrievalEngine } from '../../../retrieval/src/index.ts';
-import type { CallToolResult, McpTool } from '../types.ts';
-import type { McpContext, McpToolHandler } from './types.ts';
-
-export class SearchDocsTool implements McpToolHandler {
-  readonly definition: McpTool = {
-    name: 'search_docs',
-    description: 'Search documentation chunks using hybrid FTS5 ranking, symbol awareness, and optional version filtering.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        query: {
-          type: 'string',
-          description: 'The search query, code symbol, or concept to look for.',
-        },
-        library: {
-          type: 'string',
-          description: 'Optional library name to narrow search scope.',
-        },
-        version: {
-          type: 'string',
-          description: 'Target documentation version (e.g. "v14", "15.0").',
-        },
-        limit: {
-          type: 'number',
-          description: 'Maximum number of results to return (default: 10).',
-        },
-      },
-      required: ['query'],
-    },
-  };
-
-  async execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult> {
-    const query = typeof args.query === 'string' ? args.query.trim() : '';
-    if (!query) {
-      return {
-        isError: true,
-        content: [{ type: 'text', text: JSON.stringify({ error: 'Missing required parameter: query' }) }],
-      };
-    }
-
-    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 : 10;
-
-    const engine = new RetrievalEngine(ctx.repo);
-    const results = await engine.search(query, {
-      docVersion: version,
-      limit,
-      projectDir: ctx.workspaceRoot,
-    });
-
-    if (results.length === 0) {
-      const emptyPayload = {
-        query,
-        count: 0,
-        results: [],
-        message: `No documentation chunks found matching "${query}". Try refining terms or checking available sources.`,
-      };
-      return {
-        content: [
-          {
-            type: 'text',
-            text: JSON.stringify({
-              markdown: `### Search Results for "${query}"\n\nNo matching documentation found.`,
-              data: emptyPayload,
-            }, null, 2),
-          },
-        ],
-      };
-    }
-
-    const formattedChunks = results.map(r => ({
-      id: r.chunk.id,
-      chunk: r.chunk,
-      title: r.chunk.title || 'Untitled Section',
-      sectionPath: r.chunk.sectionPath,
-      content: r.chunk.content,
-      chunkType: r.chunk.chunkType,
-      language: r.chunk.language,
-      tokenEstimate: r.chunk.tokenEstimate,
-      docVersion: r.chunk.docVersion,
-      score: r.score,
-      symbols: r.symbols.map(s => s.name),
-      provenance: r.chunk.provenance ? {
-        sourceUrl: r.chunk.provenance.sourceUrl,
-        fetchedAt: r.chunk.provenance.fetchedAt,
-        untrusted: true,
-      } : undefined,
-    }));
-
-    const lines: string[] = [
-      `### Search Results for "${query}" (${results.length} found)`,
-      `> [!NOTE] External documentation content is untrusted.\n`,
-    ];
-
-    for (let i = 0; i < formattedChunks.length; i++) {
-      const c = formattedChunks[i];
-      const path = c.sectionPath.length > 0 ? c.sectionPath.join(' > ') : c.title;
-      lines.push(`${i + 1}. **${path}** [${c.chunkType}] (score: ${c.score})`);
-      lines.push(`   *ID*: \`${c.id}\`${c.docVersion ? ` | *Version*: \`${c.docVersion}\`` : ''}`);
-      if (c.symbols.length > 0) lines.push(`   *Symbols*: ${c.symbols.join(', ')}`);
-      lines.push(`   \`\`\`\n   ${c.content.split('\n').slice(0, 5).join('\n   ')}\n   \`\`\`\n`);
-    }
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify({
-            markdown: lines.join('\n'),
-            data: {
-              query,
-              count: results.length,
-              results: formattedChunks,
-            },
-          }, null, 2),
-        },
-      ],
-    };
-  }
-}

package/packages/mcp/src/tools/types.ts

@@ -1,28 +0,0 @@
-import type { DocOrbitRepository } from '../../../storage/src/index.ts';
-import type { ImplementationContextService } from '../../../core/src/index.ts';
-import type { WorkspaceResolver } from '../../../workspace/src/index.ts';
-import type {
-  VerificationService,
-  DiffService,
-  ImpactAnalysisService,
-} from '../../../verification/src/index.ts';
-import type { ExportService } from '../../../export/src/index.ts';
-import type { CallToolResult, McpTool } from '../types.ts';
-
-export interface McpContext {
-  repo: DocOrbitRepository;
-  implService: ImplementationContextService;
-  implementationService: ImplementationContextService;
-  workspaceRoot?: string;
-  projectDir?: string;
-  resolver?: WorkspaceResolver;
-  verificationService?: VerificationService;
-  diffService?: DiffService;
-  impactService?: ImpactAnalysisService;
-  exportService?: ExportService;
-}
-
-export interface McpToolHandler {
-  readonly definition: McpTool;
-  execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult>;
-}

package/packages/mcp/src/transports/http.ts

@@ -1,256 +0,0 @@
-import * as http from 'node:http';
-import type { McpServer } from '../server.ts';
-import type { McpTransport } from './types.ts';
-import { JSONRPC_ERRORS } from '../types.ts';
-
-export interface HttpTransportOptions {
-  port?: number;
-  host?: string;
-  maxBodyBytes?: number;
-  noListen?: boolean;
-}
-
-export class StreamableHttpTransport implements McpTransport {
-  private port: number;
-  private host: string;
-  private maxBodyBytes: number;
-  private noListen: boolean;
-  private serverInstance: http.Server | null = null;
-  private mcpServer: McpServer | null = null;
-  private sseClients: Set<http.ServerResponse> = new Set();
-  private heartbeatTimer: NodeJS.Timeout | null = null;
-
-  constructor(options: HttpTransportOptions = {}) {
-    this.port = options.port ?? 3000;
-    this.host = options.host ?? '127.0.0.1';
-    this.maxBodyBytes = options.maxBodyBytes ?? 10 * 1024 * 1024; // 10MB
-    this.noListen = options.noListen ?? false;
-  }
-
-  getServerInstance(): http.Server | null {
-    return this.serverInstance;
-  }
-
-  async dispatch(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
-    return this.handleHttpRequest(req, res);
-  }
-
-  getPort(): number {
-    if (this.serverInstance) {
-      const addr = this.serverInstance.address();
-      if (addr && typeof addr === 'object') {
-        return addr.port;
-      }
-    }
-    return this.port;
-  }
-
-  async start(server: McpServer): Promise<void> {
-    this.mcpServer = server;
-
-    this.serverInstance = http.createServer((req, res) => {
-      this.handleHttpRequest(req, res).catch(err => {
-        if (!res.headersSent) {
-          res.writeHead(500, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
-        }
-      });
-    });
-
-    if (this.noListen) {
-      return;
-    }
-
-    return new Promise((resolve, reject) => {
-      this.serverInstance!.on('error', reject);
-
-      this.serverInstance!.listen(this.port, this.host, () => {
-        this.startHeartbeats();
-        resolve();
-      });
-    });
-  }
-
-  private setCorsHeaders(res: http.ServerResponse): void {
-    res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, Accept');
-  }
-
-  private async handleHttpRequest(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
-    this.setCorsHeaders(res);
-
-    if (req.method === 'OPTIONS') {
-      res.writeHead(204);
-      res.end();
-      return;
-    }
-
-    const url = new URL(req.url || '/', `http://${this.host}:${this.port}`);
-    const pathname = url.pathname;
-
-    if (req.method === 'GET' && (pathname === '/health' || pathname === '/')) {
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({
-        status: 'ok',
-        server: 'docorbit-mcp',
-        version: '0.5.0',
-        endpoints: {
-          mcp: '/mcp',
-          sse: '/sse',
-          health: '/health',
-        },
-      }));
-      return;
-    }
-
-    if (req.method === 'GET' && pathname === '/sse') {
-      this.handleSseConnection(req, res);
-      return;
-    }
-
-    if (req.method === 'POST' && pathname === '/mcp') {
-      await this.handleMcpPost(req, res);
-      return;
-    }
-
-    res.writeHead(404, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ error: `Not found: ${req.method} ${pathname}` }));
-  }
-
-  private handleSseConnection(req: http.IncomingMessage, res: http.ServerResponse): void {
-    res.writeHead(200, {
-      'Content-Type': 'text/event-stream',
-      'Cache-Control': 'no-cache',
-      'Connection': 'keep-alive',
-    });
-
-    // Send endpoint notification so client knows where to POST messages
-    res.write('event: endpoint\ndata: /mcp\n\n');
-
-    this.sseClients.add(res);
-
-    req.on('close', () => {
-      this.sseClients.delete(res);
-    });
-  }
-
-  private async handleMcpPost(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
-    const rawBody = await this.readBody(req);
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(rawBody);
-    } catch {
-      res.writeHead(400, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({
-        jsonrpc: '2.0',
-        id: null,
-        error: {
-          code: JSONRPC_ERRORS.PARSE_ERROR,
-          message: 'Parse error: invalid JSON payload.',
-        },
-      }));
-      return;
-    }
-
-    if (!this.mcpServer) {
-      res.writeHead(503, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ error: 'Server not initialized' }));
-      return;
-    }
-
-    let responsePayload: unknown;
-    if (Array.isArray(parsed)) {
-      const responses = await Promise.all(parsed.map(item => this.mcpServer!.handleMessage(item)));
-      responsePayload = responses.filter(r => r !== null);
-    } else {
-      responsePayload = await this.mcpServer.handleMessage(parsed);
-    }
-
-    const acceptHeader = req.headers['accept'] || '';
-    const wantsSse = acceptHeader.includes('text/event-stream');
-
-    if (wantsSse) {
-      // Modern Streamable HTTP response over SSE chunk
-      res.writeHead(200, {
-        'Content-Type': 'text/event-stream',
-        'Cache-Control': 'no-cache',
-        'Connection': 'keep-alive',
-      });
-      if (responsePayload !== null && responsePayload !== undefined) {
-        res.write(`event: message\ndata: ${JSON.stringify(responsePayload)}\n\n`);
-      }
-      res.end();
-      return;
-    }
-
-    // Standard JSON response
-    if (responsePayload === null || responsePayload === undefined) {
-      res.writeHead(204);
-      res.end();
-      return;
-    }
-
-    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-    res.end(JSON.stringify(responsePayload));
-  }
-
-  private readBody(req: http.IncomingMessage): Promise<string> {
-    return new Promise((resolve, reject) => {
-      const chunks: Buffer[] = [];
-      let totalLength = 0;
-
-      req.on('data', chunk => {
-        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        totalLength += buf.length;
-        if (totalLength > this.maxBodyBytes) {
-          req.destroy(new Error(`Payload exceeds maximum limit of ${this.maxBodyBytes} bytes`));
-          return;
-        }
-        chunks.push(buf);
-      });
-
-      req.on('end', () => {
-        resolve(Buffer.concat(chunks).toString('utf-8'));
-      });
-
-      req.on('error', reject);
-    });
-  }
-
-  private startHeartbeats(): void {
-    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
-    this.heartbeatTimer = setInterval(() => {
-      for (const client of this.sseClients) {
-        try {
-          client.write(': ping\n\n');
-        } catch {
-          this.sseClients.delete(client);
-        }
-      }
-    }, 15000);
-  }
-
-  async close(): Promise<void> {
-    if (this.heartbeatTimer) {
-      clearInterval(this.heartbeatTimer);
-      this.heartbeatTimer = null;
-    }
-
-    for (const client of this.sseClients) {
-      try {
-        client.end();
-      } catch {
-        // Continue
-      }
-    }
-    this.sseClients.clear();
-
-    if (this.serverInstance) {
-      await new Promise<void>((resolve) => {
-        this.serverInstance!.close(() => resolve());
-      });
-      this.serverInstance = null;
-    }
-  }
-}

package/packages/mcp/src/transports/stdio.ts

@@ -1,105 +0,0 @@
-import * as readline from 'node:readline';
-import type { Readable, Writable } from 'node:stream';
-import type { McpServer } from '../server.ts';
-import type { McpTransport } from './types.ts';
-import { JSONRPC_ERRORS } from '../types.ts';
-
-export interface StdioTransportOptions {
-  input?: Readable;
-  output?: Writable;
-  errorOutput?: Writable;
-}
-
-export class StdioServerTransport implements McpTransport {
-  private input: Readable;
-  private output: Writable;
-  private errorOutput: Writable;
-  private rl: readline.Interface | null = null;
-  private server: McpServer | null = null;
-  private running: boolean = false;
-
-  constructor(options: StdioTransportOptions = {}) {
-    this.input = options.input || process.stdin;
-    this.output = options.output || process.stdout;
-    this.errorOutput = options.errorOutput || process.stderr;
-  }
-
-  async start(server: McpServer): Promise<void> {
-    this.server = server;
-    this.running = true;
-
-    this.rl = readline.createInterface({
-      input: this.input,
-      terminal: false,
-    });
-
-    this.log('[DocOrbit MCP] Stdio transport started.');
-
-    this.rl.on('line', async (line: string) => {
-      try {
-        await this.processLine(line);
-      } catch (err) {
-        this.log(`[DocOrbit MCP] Stdio error processing line: ${err instanceof Error ? err.message : String(err)}`);
-      }
-    });
-
-    this.rl.on('close', () => {
-      this.running = false;
-      this.log('[DocOrbit MCP] Stdio transport stream closed.');
-    });
-  }
-
-  private async processLine(line: string): Promise<void> {
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(line);
-    } catch {
-      const parseError = {
-        jsonrpc: '2.0',
-        id: null,
-        error: {
-          code: JSONRPC_ERRORS.PARSE_ERROR,
-          message: 'Parse error: invalid JSON payload.',
-        },
-      };
-      this.send(parseError);
-      return;
-    }
-
-    if (!this.server) return;
-
-    if (Array.isArray(parsed)) {
-      // JSON-RPC Batch
-      const responses = await Promise.all(parsed.map(item => this.server!.handleMessage(item)));
-      const filtered = responses.filter(r => r !== null);
-      if (filtered.length > 0) {
-        this.send(filtered);
-      }
-      return;
-    }
-
-    const response = await this.server.handleMessage(parsed);
-    if (response !== null) {
-      this.send(response);
-    }
-  }
-
-  private send(payload: unknown): void {
-    if (!this.running) return;
-    const serialized = JSON.stringify(payload) + '\n';
-    this.output.write(serialized);
-  }
-
-  private log(message: string): void {
-    // Isolated to stderr to never corrupt stdout JSON-RPC stream
-    this.errorOutput.write(`${message}\n`);
-  }
-
-  async close(): Promise<void> {
-    this.running = false;
-    if (this.rl) {
-      this.rl.close();
-      this.rl = null;
-    }
-  }
-}