docorbit 0.1.0 → 0.1.2

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

@@ -0,0 +1,11 @@
+import { DatabaseSync } from 'node:sqlite';
+export declare function resolveDefaultDbPath(explicitDbPath?: string, projectDir?: string): string;
+export declare class DocOrbitDb {
+    private db;
+    private ftsAvailable;
+    constructor(dbPath?: string);
+    private migrate;
+    isFtsAvailable(): boolean;
+    getRawDb(): DatabaseSync;
+    close(): void;
+}

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

@@ -0,0 +1,128 @@
+import { DatabaseSync } from 'node:sqlite';
+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:') {
+            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:';
+        }
+        // Enable foreign keys
+        this.db.exec('PRAGMA foreign_keys = ON;');
+        // Enable WAL mode for file-based database for concurrent reads
+        if (targetPath !== ':memory:') {
+            try {
+                this.db.exec('PRAGMA journal_mode = WAL;');
+            }
+            catch {
+                // Ignore if WAL pragma fails on restricted filesystems
+            }
+        }
+        this.migrate();
+    }
+    migrate() {
+        // Base relational tables
+        this.db.exec(SCHEMA_SQL);
+        // Schema evolution migrations
+        try {
+            this.db.exec('ALTER TABLE pages ADD COLUMN provenance_json TEXT;');
+        }
+        catch {
+            // Column already exists
+        }
+        try {
+            this.db.exec('ALTER TABLE snapshots ADD COLUMN doc_version TEXT;');
+        }
+        catch {
+            // Column already exists
+        }
+        try {
+            this.db.exec('ALTER TABLE chunks ADD COLUMN doc_version TEXT;');
+        }
+        catch {
+            // Column already exists
+        }
+        // Test and enable FTS5 virtual table
+        try {
+            this.db.exec(FTS_SCHEMA_SQL);
+            this.ftsAvailable = true;
+        }
+        catch {
+            this.ftsAvailable = false;
+        }
+    }
+    isFtsAvailable() {
+        return this.ftsAvailable;
+    }
+    getRawDb() {
+        return this.db;
+    }
+    close() {
+        this.db.close();
+    }
+}

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

@@ -0,0 +1,10 @@
+export * from "./db.js";
+export * from "./schema.js";
+export * from "./repository.js";
+export * from "./search-tokens.js";
+export * from "./repositories/source-repository.js";
+export * from "./repositories/page-repository.js";
+export * from "./repositories/chunk-repository.js";
+export * from "./repositories/api-repository.js";
+export * from "./repositories/example-repository.js";
+export * from "./repositories/pitfall-repository.js";

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

@@ -0,0 +1,83 @@
+import type { DiscoveredSource, NormalizedPage, DocumentChunk, ChunkCode, SymbolReference, ChunkRelationship, ChunkType, ApiEndpoint, IndexedExample, Pitfall, PitfallKind } from '../../shared/src/index.ts';
+export interface Snapshot {
+    id: string;
+    sourceId: string;
+    hash: string;
+    pageCount: number;
+    docVersion?: string;
+    createdAt: string;
+}
+export interface ISourceRepository {
+    saveSource(source: DiscoveredSource): string;
+    getSource(id: string): DiscoveredSource | null;
+    getSourceByUrl(url: string): DiscoveredSource | null;
+    listSources(): DiscoveredSource[];
+    createSnapshot(sourceId: string, metadata?: Record<string, unknown>, docVersion?: string): string;
+    saveSnapshot(snapshot: Snapshot): void;
+    getSnapshot(id: string): Snapshot | null;
+    getLatestSnapshot(sourceId: string): Snapshot | null;
+    listSnapshots(sourceId: string): Snapshot[];
+    linkSnapshotPages(snapshotId: string, pageIds: string[]): void;
+    getSnapshotPages(snapshotId: string): NormalizedPage[];
+}
+export interface IPageRepository {
+    savePage(page: NormalizedPage): void;
+    getPage(id: string): NormalizedPage | null;
+    getPageByUrl(normalizedUrl: string): NormalizedPage | null;
+    listPages(limit?: number, offset?: number): NormalizedPage[];
+    countPages(sourceId?: string): number;
+    savePageLinks(pageId: string, targetUrls: string[]): void;
+    getPageLinks(pageId: string): string[];
+    searchPagesFts(query: string, limit?: number): NormalizedPage[];
+}
+export interface IChunkRepository {
+    saveChunks(chunks: DocumentChunk[], relationships?: ChunkRelationship[], codeSnippets?: ChunkCode[], symbols?: SymbolReference[]): void;
+    getChunk(id: string): DocumentChunk | null;
+    getChunksByPage(pageId: string): DocumentChunk[];
+    getChunksBySnapshot(snapshotId: string): DocumentChunk[];
+    getChunksByVersion(docVersion: string): DocumentChunk[];
+    getChunkCode(chunkId: string): ChunkCode[];
+    getChunkSymbols(chunkId: string): SymbolReference[];
+    getChunkRelationships(chunkId: string): ChunkRelationship[];
+    countChunks(snapshotId?: string): number;
+    searchChunksFts(query: string, options?: {
+        limit?: number;
+        snapshotId?: string;
+        chunkType?: ChunkType;
+        docVersion?: string;
+    }): Array<{
+        chunk: DocumentChunk;
+        ftsRank: number;
+        symbols: SymbolReference[];
+        codeSnippets: ChunkCode[];
+    }>;
+}
+export interface IApiRepository {
+    saveApiEndpoints(endpoints: ApiEndpoint[]): void;
+    getApiEndpoint(id: string): ApiEndpoint | null;
+    getApiEndpointsBySnapshot(snapshotId: string): ApiEndpoint[];
+    searchApiEndpoints(query: string, options?: {
+        method?: string;
+        docVersion?: string;
+        limit?: number;
+    }): ApiEndpoint[];
+}
+export interface IExampleRepository {
+    saveIndexedExamples(examples: IndexedExample[]): void;
+    getIndexedExamplesBySnapshot(snapshotId: string): IndexedExample[];
+    searchIndexedExamples(query: string, options?: {
+        language?: string;
+        framework?: string;
+        docVersion?: string;
+        limit?: number;
+    }): IndexedExample[];
+}
+export interface IPitfallRepository {
+    savePitfalls(pitfalls: Pitfall[]): void;
+    getPitfallsBySnapshot(snapshotId: string): Pitfall[];
+    searchPitfalls(query: string, options?: {
+        kind?: PitfallKind;
+        docVersion?: string;
+        limit?: number;
+    }): Pitfall[];
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/packages/storage/src/repositories/api-repository.d.ts

@@ -0,0 +1,16 @@
+import type { ApiEndpoint } from '../../../shared/src/index.ts';
+import type { DocOrbitDb } from '../db.ts';
+import type { IApiRepository } from '../interfaces.ts';
+export declare class ApiRepository implements IApiRepository {
+    private db;
+    constructor(db: DocOrbitDb);
+    saveApiEndpoints(endpoints: ApiEndpoint[]): void;
+    getApiEndpoint(id: string): ApiEndpoint | null;
+    getApiEndpointsBySnapshot(snapshotId: string): ApiEndpoint[];
+    searchApiEndpoints(query: string, options?: {
+        method?: string;
+        docVersion?: string;
+        limit?: number;
+    }): ApiEndpoint[];
+    private hydrateApiEndpoint;
+}

package/dist/packages/storage/src/repositories/api-repository.js

@@ -0,0 +1,169 @@
+import { extractSearchTokens } from "../search-tokens.js";
+export class ApiRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    saveApiEndpoints(endpoints) {
+        if (endpoints.length === 0)
+            return;
+        const raw = this.db.getRawDb();
+        const insertEp = raw.prepare(`
+      INSERT INTO api_endpoints (
+        id, page_id, snapshot_id, method, path, summary, description,
+        operation_id, parameters_json, request_schema_json, response_schema_json,
+        auth_json, errors_json, pagination_json, deprecated, doc_version,
+        provenance_json, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        method = excluded.method,
+        path = excluded.path,
+        summary = excluded.summary,
+        description = excluded.description,
+        operation_id = excluded.operation_id,
+        parameters_json = excluded.parameters_json,
+        request_schema_json = excluded.request_schema_json,
+        response_schema_json = excluded.response_schema_json,
+        auth_json = excluded.auth_json,
+        errors_json = excluded.errors_json,
+        pagination_json = excluded.pagination_json,
+        deprecated = excluded.deprecated,
+        doc_version = excluded.doc_version,
+        provenance_json = excluded.provenance_json
+    `);
+        const insertFts = this.db.isFtsAvailable()
+            ? raw.prepare(`
+          INSERT INTO api_endpoints_fts (endpoint_id, method, path, summary, description, parameters)
+          VALUES (?, ?, ?, ?, ?, ?)
+        `)
+            : null;
+        const deleteFts = this.db.isFtsAvailable()
+            ? raw.prepare('DELETE FROM api_endpoints_fts WHERE endpoint_id = ?')
+            : null;
+        raw.exec('BEGIN TRANSACTION;');
+        try {
+            for (const ep of endpoints) {
+                insertEp.run(ep.id, ep.pageId, ep.snapshotId || 'snap_default', ep.method, ep.path, ep.summary || null, ep.description || null, ep.operationId || null, JSON.stringify(ep.parameters || []), ep.requestSchema ? JSON.stringify(ep.requestSchema) : null, ep.responseSchema ? JSON.stringify(ep.responseSchema) : null, ep.auth ? JSON.stringify(ep.auth) : '[]', ep.errors ? JSON.stringify(ep.errors) : '[]', ep.pagination ? JSON.stringify(ep.pagination) : null, ep.deprecated ? 1 : 0, ep.docVersion || null, ep.provenance ? JSON.stringify(ep.provenance) : null, ep.createdAt || new Date().toISOString());
+                if (insertFts && deleteFts) {
+                    deleteFts.run(ep.id);
+                    const paramNames = (ep.parameters || []).map(p => p.name).join(' ');
+                    insertFts.run(ep.id, ep.method, ep.path, ep.summary || '', ep.description || '', paramNames);
+                }
+            }
+            raw.exec('COMMIT;');
+        }
+        catch (err) {
+            raw.exec('ROLLBACK;');
+            throw err;
+        }
+    }
+    getApiEndpoint(id) {
+        const raw = this.db.getRawDb();
+        const row = raw.prepare('SELECT * FROM api_endpoints WHERE id = ?').get(id);
+        return row ? this.hydrateApiEndpoint(row) : null;
+    }
+    getApiEndpointsBySnapshot(snapshotId) {
+        const raw = this.db.getRawDb();
+        const rows = raw.prepare('SELECT * FROM api_endpoints WHERE snapshot_id = ? ORDER BY path, method').all(snapshotId);
+        return rows.map(r => this.hydrateApiEndpoint(r));
+    }
+    searchApiEndpoints(query, options = {}) {
+        const raw = this.db.getRawDb();
+        const limit = options.limit || 20;
+        const cleanQuery = query.trim();
+        // Check if query specifies method at start (e.g. "POST /v1/...")
+        let effectiveMethod = options.method?.toLowerCase();
+        let term = cleanQuery;
+        const methodMatch = cleanQuery.match(/^(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s+(.*)$/i);
+        if (methodMatch) {
+            effectiveMethod = methodMatch[1].toLowerCase();
+            term = methodMatch[2].trim();
+        }
+        // Try FTS if available and term exists
+        if (this.db.isFtsAvailable() && term.length > 0) {
+            const cleanTokens = extractSearchTokens(term);
+            if (cleanTokens.length > 0) {
+                const sanitizedFts = cleanTokens
+                    .map(t => t.length >= 4 ? `"${t.replace(/"/g, '""')}"*` : `"${t.replace(/"/g, '""')}"`)
+                    .join(' OR ');
+                try {
+                    let sql = `
+            SELECT ep.*, fts.rank as fts_rank
+            FROM api_endpoints ep
+            JOIN api_endpoints_fts fts ON ep.id = fts.endpoint_id
+            WHERE api_endpoints_fts MATCH ?
+          `;
+                    const params = [sanitizedFts];
+                    if (effectiveMethod) {
+                        sql += ' AND lower(ep.method) = ?';
+                        params.push(effectiveMethod);
+                    }
+                    if (options.docVersion) {
+                        sql += ' AND (ep.doc_version = ? OR ep.doc_version IS NULL)';
+                        params.push(options.docVersion);
+                    }
+                    sql += ' ORDER BY fts.rank LIMIT ?';
+                    params.push(limit);
+                    const rows = raw.prepare(sql).all(...params);
+                    if (rows.length > 0) {
+                        return rows.map(r => this.hydrateApiEndpoint(r));
+                    }
+                }
+                catch {
+                    // Fall through to LIKE search
+                }
+            }
+        }
+        // LIKE fallback search
+        let sql = 'SELECT * FROM api_endpoints WHERE 1=1';
+        const params = [];
+        if (effectiveMethod) {
+            sql += ' AND lower(method) = ?';
+            params.push(effectiveMethod);
+        }
+        if (options.docVersion) {
+            sql += ' AND (doc_version = ? OR doc_version IS NULL)';
+            params.push(options.docVersion);
+        }
+        if (term.length > 0) {
+            const tokens = extractSearchTokens(term);
+            if (tokens.length > 0) {
+                const tokenClauses = tokens.map(() => '(path LIKE ? OR summary LIKE ? OR description LIKE ? OR parameters_json LIKE ?)');
+                sql += ` AND (${tokenClauses.join(' OR ')})`;
+                for (const t of tokens) {
+                    const lp = `%${t}%`;
+                    params.push(lp, lp, lp, lp);
+                }
+            }
+            else {
+                return [];
+            }
+        }
+        sql += ' ORDER BY path, method LIMIT ?';
+        params.push(limit);
+        const rows = raw.prepare(sql).all(...params);
+        return rows.map(r => this.hydrateApiEndpoint(r));
+    }
+    hydrateApiEndpoint(row) {
+        return {
+            id: String(row.id),
+            pageId: String(row.page_id),
+            snapshotId: String(row.snapshot_id),
+            method: String(row.method),
+            path: String(row.path),
+            summary: row.summary ? String(row.summary) : undefined,
+            description: row.description ? String(row.description) : undefined,
+            operationId: row.operation_id ? String(row.operation_id) : undefined,
+            parameters: row.parameters_json ? JSON.parse(String(row.parameters_json)) : [],
+            requestSchema: row.request_schema_json ? JSON.parse(String(row.request_schema_json)) : undefined,
+            responseSchema: row.response_schema_json ? JSON.parse(String(row.response_schema_json)) : undefined,
+            auth: row.auth_json ? JSON.parse(String(row.auth_json)) : [],
+            errors: row.errors_json ? JSON.parse(String(row.errors_json)) : [],
+            pagination: row.pagination_json ? JSON.parse(String(row.pagination_json)) : undefined,
+            deprecated: Number(row.deprecated) === 1,
+            docVersion: row.doc_version ? String(row.doc_version) : undefined,
+            provenance: row.provenance_json ? JSON.parse(String(row.provenance_json)) : undefined,
+            createdAt: String(row.created_at),
+        };
+    }
+}

package/dist/packages/storage/src/repositories/chunk-repository.d.ts

@@ -0,0 +1,32 @@
+import type { DocumentChunk, ChunkRelationship, ChunkCode, SymbolReference, ChunkType } from '../../../shared/src/index.ts';
+import type { DocOrbitDb } from '../db.ts';
+import type { IChunkRepository } from '../interfaces.ts';
+export declare class ChunkRepository implements IChunkRepository {
+    private db;
+    constructor(db: DocOrbitDb);
+    /**
+     * Saves chunks, code snippets, symbols, and relationships in a single atomic transaction.
+     * Transactionally synchronizes the FTS5 chunks_fts table with chunks.
+     */
+    saveChunks(chunks: DocumentChunk[], relationships?: ChunkRelationship[], codeSnippets?: ChunkCode[], symbols?: SymbolReference[]): void;
+    getChunk(id: string): DocumentChunk | null;
+    getChunksByPage(pageId: string): DocumentChunk[];
+    getChunksBySnapshot(snapshotId: string): DocumentChunk[];
+    getChunksByVersion(docVersion: string): DocumentChunk[];
+    getChunkCode(chunkId: string): ChunkCode[];
+    getChunkSymbols(chunkId: string): SymbolReference[];
+    getChunkRelationships(chunkId: string): ChunkRelationship[];
+    countChunks(snapshotId?: string): number;
+    searchChunksFts(query: string, options?: {
+        limit?: number;
+        snapshotId?: string;
+        chunkType?: ChunkType;
+        docVersion?: string;
+    }): Array<{
+        chunk: DocumentChunk;
+        ftsRank: number;
+        symbols: SymbolReference[];
+        codeSnippets: ChunkCode[];
+    }>;
+    private hydrateChunk;
+}