docorbit 0.1.1 → 0.1.2

package/README.md

@@ -64,19 +64,32 @@ docorbit/
 ## Getting Started
 
 ### Requirements
-- **Node.js 24.0.0+** (utilizes native `--experimental-strip-types` and `node:sqlite`)
-- **No `npm install` needed** for core runtime!
+- **Node.js 22.5.0+** (uses built-in `node:sqlite`)
+- **Zero native dependencies**
 
 ### Installation
-Clone the repository and link or run directly:
 
+#### Global or npx (Recommended)
+```bash
+# Run directly without install
+npx docorbit --help
+
+# Or install globally
+npm install -g docorbit
+docorbit --help
+```
+
+#### From Source
 ```bash
 # Clone repository
-git clone https://github.com/your-org/docorbit.git
+git clone https://github.com/HakashiKatake/docorbit.git
 cd docorbit
 
-# Run CLI directly
-node --experimental-strip-types bin/docorbit.js --help
+# Build distribution bundle
+npm run build
+
+# Run CLI
+node bin/docorbit.js --help
 ```
 
 ---
@@ -425,18 +438,19 @@ node --experimental-strip-types bin/docorbit.js export agents.md --output docs/A
 Start DocOrbit as an agent-native MCP server communicating via JSON-RPC 2.0. Coding agents (Claude Code, Cursor, Windsurf, OpenCode) can interact over standard input/output (`stdio`) or Streamable HTTP:
 
 ```bash
-# Start in Stdio mode (for CLI agents like Claude Code, Cursor, OpenCode)
-node --experimental-strip-types bin/docorbit.js mcp --stdio
+# Start in Stdio mode (for CLI agents like Claude Code, Cursor, Windsurf)
+npx -y docorbit mcp --stdio
 
 # Or start in Streamable HTTP mode (supports POST /mcp, GET /sse, GET /health)
-node --experimental-strip-types bin/docorbit.js mcp --port 3000 --host 127.0.0.1
+npx -y docorbit mcp --port 3000 --host 127.0.0.1
 ```
 
-#### The 14 Agent-Native Tools:
+#### The 15 Agent-Native Tools:
 
 | Tool Name | Type | Description |
 | :--- | :--- | :--- |
-| `get_implementation_context` | **High-Level Centerpiece** | Orchestrates task → project/dependency detection → version resolution → intent → retrieval → APIs → examples → pitfalls → recipe → token-budgeted context → provenance → verification hints. |
+| `ingest_doc` | **Ingestion & Loop Starter** | Ingests, crawls, and indexes documentation from any URL or raw content directly into local SQLite store, with optional instant implementation recipe synthesis. |
+| `get_implementation_context` | **High-Level Centerpiece** | Orchestrates task → project/dependency detection → version resolution → intent → retrieval → APIs → examples → pitfalls → recipe → token-budgeted context → provenance → verification hints (supports auto-ingestion from `url`). |
 | `check_api` | Verification | Deterministically checks code against indexed OpenAPI schemas, parameters, required body fields, deprecations, and version contracts. |
 | `diff_docs` | Intelligence | Compares documentation versions/snapshots to detect added, removed, modified, and deprecated endpoints/pitfalls. |
 | `analyze_impact` | Intelligence | Scans workspace project files for breaking changes and deprecated APIs, returning line, snippet, and certainty. |
@@ -458,8 +472,8 @@ node --experimental-strip-types bin/docorbit.js mcp --port 3000 --host 127.0.0.1
 {
   "mcpServers": {
     "docorbit": {
-      "command": "node",
-      "args": ["--experimental-strip-types", "/path/to/docorbit/bin/docorbit.js", "mcp", "--stdio"]
+      "command": "npx",
+      "args": ["-y", "docorbit", "mcp", "--stdio"]
     }
   }
 }
@@ -470,8 +484,8 @@ node --experimental-strip-types bin/docorbit.js mcp --port 3000 --host 127.0.0.1
 {
   "mcpServers": {
     "docorbit": {
-      "command": "node",
-      "args": ["--experimental-strip-types", "/path/to/docorbit/bin/docorbit.js", "mcp", "--stdio"]
+      "command": "npx",
+      "args": ["-y", "docorbit", "mcp", "--stdio"]
     }
   }
 }

package/dist/apps/cli/src/commands/add.js

@@ -1,4 +1,4 @@
-import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { DocOrbitDb, DocOrbitRepository, resolveDefaultDbPath } from "../../../../packages/storage/src/index.js";
 import { IngestionPipeline } from "../../../../packages/core/src/index.js";
 import { formatIngestionResult } from "../formatters/terminal.js";
 export async function runAddCommand(targetUrl, options = {}) {
@@ -7,7 +7,7 @@ export async function runAddCommand(targetUrl, options = {}) {
         console.error('Usage: docorbit add <url> [--json] [--db <path>]');
         process.exit(1);
     }
-    const dbPath = options.dbPath || '.docorbit/docorbit.db';
+    const dbPath = resolveDefaultDbPath(options.dbPath);
     const db = new DocOrbitDb(dbPath);
     const repository = new DocOrbitRepository(db);
     try {

package/dist/apps/cli/src/commands/mcp.js

@@ -1,9 +1,9 @@
-import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { DocOrbitDb, DocOrbitRepository, resolveDefaultDbPath } from "../../../../packages/storage/src/index.js";
 import { WorkspaceResolver } from "../../../../packages/workspace/src/index.js";
 import { McpServer, StdioServerTransport, StreamableHttpTransport, } from "../../../../packages/mcp/src/index.js";
 export async function runMcpCommand(options = {}) {
-    const dbPath = options.dbPath || '.docorbit/docorbit.db';
     const projectDir = options.projectDir || process.cwd();
+    const dbPath = resolveDefaultDbPath(options.dbPath, projectDir);
     const db = new DocOrbitDb(dbPath);
     const repo = new DocOrbitRepository(db);
     const resolver = new WorkspaceResolver(repo);

package/dist/apps/cli/src/commands/search.js

@@ -1,4 +1,4 @@
-import { DocOrbitDb, DocOrbitRepository } from "../../../../packages/storage/src/index.js";
+import { DocOrbitDb, DocOrbitRepository, resolveDefaultDbPath } from "../../../../packages/storage/src/index.js";
 import { RetrievalEngine } from "../../../../packages/retrieval/src/index.js";
 import { formatSearchResults } from "../formatters/terminal.js";
 export async function runSearchCommand(query, options = {}) {
@@ -7,7 +7,7 @@ export async function runSearchCommand(query, options = {}) {
         console.error('Usage: docorbit search "<query>" [--limit <n>] [--type <type>] [--doc-version <ver>] [--project <dir>] [--json] [--db <path>]');
         process.exit(1);
     }
-    const dbPath = options.dbPath || '.docorbit/docorbit.db';
+    const dbPath = resolveDefaultDbPath(options.dbPath, options.projectDir);
     const db = new DocOrbitDb(dbPath);
     const repository = new DocOrbitRepository(db);
     const engine = new RetrievalEngine(repository);

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

@@ -1,7 +1,7 @@
 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';

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

@@ -1,5 +1,5 @@
 export { JSONRPC_ERRORS } from "./types.js";
-export { createDefaultTools, SearchDocsTool, GetDocTool, FindApiTool, FindExampleTool, FindPitfallTool, FindRecipeTool, GetVersionTool, ListSourcesTool, GetImplementationContextTool, CheckApiTool, DiffDocsTool, AnalyzeImpactTool, } from "./tools/index.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";

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

@@ -1,3 +1,4 @@
+import { IngestionPipeline } from "../../../core/src/index.js";
 export class ImplementationContextTool {
     definition = {
         name: 'get_implementation_context',
@@ -9,6 +10,10 @@ export class ImplementationContextTool {
                     type: 'string',
                     description: 'The specific coding task or feature to implement (e.g. "Implement Stripe webhook signature verification in Express").',
                 },
+                url: {
+                    type: 'string',
+                    description: 'Optional documentation target URL. If provided and not yet indexed in DocOrbit, DocOrbit will automatically ingest and index it before compiling context.',
+                },
                 project: {
                     type: 'string',
                     description: 'Path to repository workspace root for project-aware dependency detection (default: current directory).',
@@ -45,7 +50,22 @@ export class ImplementationContextTool {
         const tokenBudget = typeof args.tokenBudget === 'number' && args.tokenBudget > 0
             ? args.tokenBudget
             : 4000;
+        const url = typeof args.url === 'string' ? args.url.trim() : undefined;
         try {
+            if (url) {
+                const existing = ctx.repo.getSourceByUrl(url);
+                if (!existing) {
+                    try {
+                        const pipeline = new IngestionPipeline(ctx.repo, {
+                            crawlerConfig: { maxPages: 20 },
+                        });
+                        await pipeline.ingest(url);
+                    }
+                    catch {
+                        // Proceed gracefully with available context if crawling fails
+                    }
+                }
+            }
             const result = await ctx.implService.getContext({
                 task,
                 projectPath,

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

@@ -13,6 +13,7 @@ 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';
+import { IngestDocTool } from './ingest-doc.ts';
 export * from './types.ts';
-export { SearchDocsTool, GetDocTool, FindApiTool, FindExampleTool, FindPitfallTool, FindRecipeTool, GetVersionTool, ListSourcesTool, ImplementationContextTool, ImplementationContextTool as GetImplementationContextTool, CheckApiTool, DiffDocsTool, AnalyzeImpactTool, GetDocumentationMapTool, ExportAgentContextTool, };
+export { SearchDocsTool, GetDocTool, FindApiTool, FindExampleTool, FindPitfallTool, FindRecipeTool, GetVersionTool, ListSourcesTool, ImplementationContextTool, ImplementationContextTool as GetImplementationContextTool, CheckApiTool, DiffDocsTool, AnalyzeImpactTool, GetDocumentationMapTool, ExportAgentContextTool, IngestDocTool, };
 export declare function createDefaultTools(): Map<string, McpToolHandler>;

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

@@ -12,8 +12,9 @@ import { DiffDocsTool } from "./diff-docs.js";
 import { AnalyzeImpactTool } from "./analyze-impact.js";
 import { GetDocumentationMapTool } from "./get-docs-map.js";
 import { ExportAgentContextTool } from "./export-context.js";
+import { IngestDocTool } from "./ingest-doc.js";
 export * from "./types.js";
-export { SearchDocsTool, GetDocTool, FindApiTool, FindExampleTool, FindPitfallTool, FindRecipeTool, GetVersionTool, ListSourcesTool, ImplementationContextTool, ImplementationContextTool as GetImplementationContextTool, CheckApiTool, DiffDocsTool, AnalyzeImpactTool, GetDocumentationMapTool, ExportAgentContextTool, };
+export { SearchDocsTool, GetDocTool, FindApiTool, FindExampleTool, FindPitfallTool, FindRecipeTool, GetVersionTool, ListSourcesTool, ImplementationContextTool, ImplementationContextTool as GetImplementationContextTool, CheckApiTool, DiffDocsTool, AnalyzeImpactTool, GetDocumentationMapTool, ExportAgentContextTool, IngestDocTool, };
 export function createDefaultTools() {
     const tools = new Map();
     const list = [
@@ -31,6 +32,7 @@ export function createDefaultTools() {
         new AnalyzeImpactTool(),
         new GetDocumentationMapTool(),
         new ExportAgentContextTool(),
+        new IngestDocTool(),
     ];
     for (const tool of list) {
         tools.set(tool.definition.name, tool);

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

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

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

@@ -0,0 +1,264 @@
+import { IngestionPipeline } from "../../../core/src/index.js";
+import { buildNormalizedPage, slicePageIntoChunks } from "../../../normalizer/src/index.js";
+export class IngestDocTool {
+    definition = {
+        name: 'ingest_doc',
+        description: 'Ingest, crawl, parse, and index authoritative documentation from any URL or raw content directly into DocOrbit. Extracts semantic chunks, OpenAPI endpoints, code examples, and pitfalls. If taskContext is provided, immediately synthesizes and returns an evidence-grounded implementation recipe with exact code and API details.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: {
+                    type: 'string',
+                    description: 'Documentation target URL to crawl and ingest (e.g. "https://nextjs.org/docs" or "https://support.atlassian.com/...").',
+                },
+                taskContext: {
+                    type: 'string',
+                    description: 'Optional coding task or intent (e.g. "Connect Atlassian Remote MCP" or "Implement Stripe payment element"). If provided, DocOrbit compiles and returns an immediate implementation recipe using the newly ingested docs.',
+                },
+                maxPages: {
+                    type: 'number',
+                    description: 'Maximum number of pages to crawl (default: 20, max: 50).',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Optional raw markdown/HTML documentation content to index directly without fetching from the web.',
+                },
+                title: {
+                    type: 'string',
+                    description: 'Optional title when ingesting raw content or overriding page title.',
+                },
+                allowLocalhost: {
+                    type: 'boolean',
+                    description: 'Allow crawling localhost endpoints for testing (default: false).',
+                },
+            },
+        },
+    };
+    async execute(args, ctx) {
+        const rawUrl = typeof args.url === 'string' ? args.url.trim() : '';
+        const rawContent = typeof args.content === 'string' ? args.content.trim() : '';
+        const title = typeof args.title === 'string' ? args.title.trim() : undefined;
+        const taskContext = typeof args.taskContext === 'string' ? args.taskContext.trim() : undefined;
+        const allowLocalhost = Boolean(args.allowLocalhost);
+        const maxPages = typeof args.maxPages === 'number' && args.maxPages > 0
+            ? Math.min(args.maxPages, 50)
+            : 20;
+        if (!rawUrl && !rawContent) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: 'Missing required parameter: provide either "url" to crawl documentation from the web or "content" to index raw documentation.',
+                        }),
+                    },
+                ],
+            };
+        }
+        try {
+            let targetUrl = rawUrl;
+            let snapshotId = '';
+            let pagesCount = 0;
+            let chunksCount = 0;
+            let codeExamplesCount = 0;
+            let estimatedTokens = 0;
+            let durationMs = 0;
+            const pagesSummary = [];
+            if (rawContent) {
+                const startTime = Date.now();
+                targetUrl = rawUrl || 'local://direct-content';
+                const sourceId = ctx.repo.saveSource({
+                    url: targetUrl,
+                    type: 'web',
+                    discoveredBy: 'direct',
+                    status: 'valid',
+                    confidence: 1.0,
+                    authority: 'official',
+                    machineReadable: false,
+                });
+                snapshotId = ctx.repo.createSnapshot(sourceId, {
+                    targetUrl,
+                    pageCount: 1,
+                    ingestedAt: new Date().toISOString(),
+                });
+                const page = buildNormalizedPage({
+                    sourceId,
+                    url: targetUrl,
+                    rawContent,
+                    contentType: 'text/markdown',
+                    sourceUrl: targetUrl,
+                    targetUrl,
+                    title: title || 'Direct Content Ingestion',
+                    discoveredBy: 'direct',
+                    fetchedAt: new Date().toISOString(),
+                });
+                ctx.repo.savePage(page);
+                const slicing = slicePageIntoChunks(page, snapshotId);
+                ctx.repo.saveChunks(slicing.chunks, slicing.relationships, slicing.codeSnippets, slicing.symbols);
+                pagesCount = 1;
+                chunksCount = slicing.chunks.length;
+                codeExamplesCount = page.codeExamples.length;
+                estimatedTokens = page.estimatedTokens;
+                durationMs = Date.now() - startTime;
+                pagesSummary.push({
+                    title: page.title,
+                    url: page.url,
+                    tokens: page.estimatedTokens,
+                    codeBlocks: page.codeExamples.length,
+                });
+            }
+            else {
+                const pipeline = new IngestionPipeline(ctx.repo, {
+                    allowLocalhostForTesting: allowLocalhost,
+                    crawlerConfig: {
+                        maxPages,
+                    },
+                });
+                const result = await pipeline.ingest(rawUrl);
+                targetUrl = result.targetUrl;
+                snapshotId = result.snapshotId;
+                pagesCount = result.stats.totalPages;
+                chunksCount = result.stats.totalChunks;
+                codeExamplesCount = result.stats.totalCodeExamples;
+                estimatedTokens = result.stats.totalEstimatedTokens;
+                durationMs = result.durationMs;
+                for (const p of result.pages) {
+                    pagesSummary.push({
+                        title: p.title,
+                        url: p.url,
+                        tokens: p.estimatedTokens,
+                        codeBlocks: p.codeExamples.length,
+                    });
+                }
+            }
+            // If user provided a specific task context, compile an immediate implementation context recipe!
+            if (taskContext) {
+                const implResult = await ctx.implService.getContext({
+                    task: taskContext,
+                    projectPath: ctx.projectDir || ctx.workspaceRoot,
+                    tokenBudget: 4000,
+                });
+                const lines = [
+                    `# 🛰️ DocOrbit: Ingested & Context Compiled`,
+                    `> [!NOTE]`,
+                    `> Successfully ingested **${targetUrl}** and compiled implementation context for: *"${taskContext}"*`,
+                    ``,
+                    `### Ingestion Metrics`,
+                    `- **Pages Ingested**: ${pagesCount}`,
+                    `- **Chunks Indexed**: ${chunksCount}`,
+                    `- **Code Examples Extracted**: ${codeExamplesCount}`,
+                    `- **Estimated Tokens**: ~${estimatedTokens}`,
+                    `- **Snapshot ID**: \`${snapshotId}\` (${durationMs}ms)`,
+                    ``,
+                    `---`,
+                    ``,
+                    implResult.markdown,
+                ];
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                markdown: lines.join('\n'),
+                                data: {
+                                    targetUrl,
+                                    snapshotId,
+                                    taskContext,
+                                    stats: {
+                                        pagesCount,
+                                        chunksCount,
+                                        codeExamplesCount,
+                                        estimatedTokens,
+                                        durationMs,
+                                    },
+                                    implementationContext: implResult,
+                                },
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            // Query any extracted APIs, examples, and pitfalls from the new documentation
+            const apiEndpoints = ctx.repo.searchApiEndpoints(targetUrl, { limit: 5 });
+            const codeExamples = ctx.repo.searchIndexedExamples(targetUrl, { limit: 3 });
+            const pitfalls = ctx.repo.searchPitfalls(targetUrl, { limit: 4 });
+            const lines = [
+                `# 🛰️ DocOrbit: Documentation Ingested Successfully`,
+                `> **Target**: \`${targetUrl}\` | **Snapshot**: \`${snapshotId}\` | **Duration**: ${durationMs}ms`,
+                ``,
+                `### Ingestion Statistics`,
+                `- **Pages Ingested**: ${pagesCount}`,
+                `- **Chunks Indexed**: ${chunksCount}`,
+                `- **Code Examples Indexed**: ${codeExamplesCount}`,
+                `- **Total Estimated Tokens**: ~${estimatedTokens}`,
+                ``,
+                `### Ingested Pages Directory`,
+            ];
+            for (let i = 0; i < pagesSummary.length; i++) {
+                const p = pagesSummary[i];
+                lines.push(`${i + 1}. **${p.title}** - \`${p.url}\` (~${p.tokens} tokens, ${p.codeBlocks} code snippets)`);
+            }
+            if (apiEndpoints.length > 0) {
+                lines.push(``, `### Discovered API Endpoints`);
+                for (const ep of apiEndpoints) {
+                    lines.push(`- **\`${ep.method.toUpperCase()} ${ep.path}\`**: ${ep.summary || ep.description || 'No description'}`);
+                }
+            }
+            if (codeExamples.length > 0) {
+                lines.push(``, `### Extracted Code Patterns`);
+                for (const ex of codeExamples) {
+                    lines.push(`#### ${ex.task} (${ex.language}${ex.framework ? `, ${ex.framework}` : ''})`);
+                    lines.push('```' + ex.language);
+                    lines.push(ex.code);
+                    lines.push('```\n');
+                }
+            }
+            if (pitfalls.length > 0) {
+                lines.push(``, `### Pitfalls & Deprecation Notices`);
+                for (const pf of pitfalls) {
+                    lines.push(`- ⚠️ **[${pf.kind.toUpperCase()}] ${pf.title}**: ${pf.content}`);
+                }
+            }
+            lines.push(``, `### Recommended Agent Loop Actions`, `- **Compile Recipe**: Call \`get_implementation_context(task: "...")\` to assemble a grounded blueprint with ordered steps and validation criteria.`, `- **Inspect Endpoints**: Call \`find_api(query: "...")\` for parameters, auth, schemas, and error responses.`, `- **Code Examples**: Call \`find_example(task: "...")\` for targeted snippets matching your framework.`, `- **Check Constraints**: Call \`find_pitfall(query: "...")\` to avoid deprecations or runtime traps.`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            markdown: lines.join('\n'),
+                            data: {
+                                targetUrl,
+                                snapshotId,
+                                stats: {
+                                    pagesCount,
+                                    chunksCount,
+                                    codeExamplesCount,
+                                    estimatedTokens,
+                                    durationMs,
+                                },
+                                pages: pagesSummary,
+                                apiEndpoints,
+                                codeExamples,
+                                pitfalls,
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: `DocOrbit Ingestion Failed: ${err instanceof Error ? err.message : String(err)}`,
+                        }),
+                    },
+                ],
+            };
+        }
+    }
+}

package/dist/packages/storage/src/db.d.ts

@@ -1,4 +1,5 @@
 import { DatabaseSync } from 'node:sqlite';
+export declare function resolveDefaultDbPath(explicitDbPath?: string, projectDir?: string): string;
 export declare class DocOrbitDb {
     private db;
     private ftsAvailable;

package/dist/packages/storage/src/db.js

@@ -1,20 +1,87 @@
 import { DatabaseSync } from 'node:sqlite';
-import { dirname } from 'node:path';
-import { mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { mkdirSync, existsSync } from 'node:fs';
+import { homedir as getHomedir, tmpdir as getTmpdir } from 'node:os';
 import { SCHEMA_SQL, FTS_SCHEMA_SQL } from "./schema.js";
+export function resolveDefaultDbPath(explicitDbPath, projectDir) {
+    if (explicitDbPath && explicitDbPath !== ':memory:') {
+        return explicitDbPath;
+    }
+    if (explicitDbPath === ':memory:') {
+        return ':memory:';
+    }
+    // 1. If projectDir has an existing .docorbit/docorbit.db, prefer it
+    if (projectDir) {
+        const projectDb = join(projectDir, '.docorbit', 'docorbit.db');
+        if (existsSync(projectDb)) {
+            return projectDb;
+        }
+    }
+    // 2. If current working directory has .docorbit/docorbit.db, prefer it
+    try {
+        const cwd = process.cwd();
+        if (cwd && cwd !== '/') {
+            const localDb = join(cwd, '.docorbit', 'docorbit.db');
+            if (existsSync(localDb)) {
+                return localDb;
+            }
+        }
+    }
+    catch { }
+    // 3. Canonical global user store: ~/.docorbit/docorbit.db
+    const userHome = process.env.HOME || process.env.USERPROFILE || getHomedir();
+    if (userHome) {
+        return join(userHome, '.docorbit', 'docorbit.db');
+    }
+    return join(getTmpdir(), '.docorbit', 'docorbit.db');
+}
 export class DocOrbitDb {
     db;
     ftsAvailable = false;
     constructor(dbPath = ':memory:') {
+        let targetPath = dbPath;
         if (dbPath !== ':memory:') {
-            mkdirSync(dirname(dbPath), { recursive: true });
+            try {
+                mkdirSync(dirname(dbPath), { recursive: true });
+            }
+            catch {
+                // When running in environments where cwd is read-only (e.g. root '/' in MCP clients),
+                // fallback to user home directory or system tmpdir
+                const userHome = process.env.HOME || process.env.USERPROFILE || getHomedir();
+                const fallbackDir = userHome ? join(userHome, '.docorbit') : join(getTmpdir(), '.docorbit');
+                try {
+                    mkdirSync(fallbackDir, { recursive: true });
+                    targetPath = join(fallbackDir, 'docorbit.db');
+                }
+                catch {
+                    try {
+                        const tmpFallback = join(getTmpdir(), '.docorbit');
+                        mkdirSync(tmpFallback, { recursive: true });
+                        targetPath = join(tmpFallback, 'docorbit.db');
+                    }
+                    catch {
+                        targetPath = ':memory:';
+                    }
+                }
+            }
+        }
+        try {
+            this.db = new DatabaseSync(targetPath);
+        }
+        catch {
+            this.db = new DatabaseSync(':memory:');
+            targetPath = ':memory:';
         }
-        this.db = new DatabaseSync(dbPath);
         // Enable foreign keys
         this.db.exec('PRAGMA foreign_keys = ON;');
         // Enable WAL mode for file-based database for concurrent reads
-        if (dbPath !== ':memory:') {
-            this.db.exec('PRAGMA journal_mode = WAL;');
+        if (targetPath !== ':memory:') {
+            try {
+                this.db.exec('PRAGMA journal_mode = WAL;');
+            }
+            catch {
+                // Ignore if WAL pragma fails on restricted filesystems
+            }
         }
         this.migrate();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docorbit",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "The Documentation Intelligence Layer for AI Coding Agents",
   "type": "module",
   "main": "./dist/packages/core/src/index.js",
@@ -43,5 +43,8 @@
     "context"
   ],
   "author": "DocOrbit Team",
-  "license": "MIT"
-}
+  "license": "MIT",
+  "dependencies": {
+    "docorbit": "^0.1.1"
+  }
+}