@noyrax/5d-database-plugin 0.1.14-beta.4 → 0.1.14-beta.6

package/out/api/source-access-contract-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-access-contract-api.js","sourceRoot":"","sources":["../../src/api/source-access-contract-api.ts"],"names":[],"mappings":"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"}

package/out/api/source-snippet-api.d.ts

@@ -0,0 +1,58 @@
+import { MultiDbManager } from '../core/multi-db-manager';
+import { ReasonCode } from '../models/reason-codes';
+import { Evidence } from '../models/evidence';
+/**
+ * Source code snippet with metadata.
+ */
+export interface SourceSnippet {
+    file_path: string;
+    start_line: number;
+    end_line: number;
+    core_start_line: number;
+    core_end_line: number;
+    snippet: string;
+    content_hash: string;
+    byte_size: number;
+    evidence: Evidence;
+}
+/**
+ * Source snippet error.
+ */
+export interface SourceSnippetError {
+    error: 'SOURCE_UNAVAILABLE' | 'SYMBOL_NOT_FOUND' | 'SNIPPET_TOO_LARGE' | 'FILE_NOT_FOUND' | 'HASH_MISMATCH';
+    reason_codes?: ReasonCode[];
+    symbol_id?: string;
+    requested_lines?: number;
+    max_allowed?: number;
+    file_path?: string;
+    resolved_path?: string;
+    expected_hash?: string;
+    computed_hash?: string;
+    evidence: Evidence;
+}
+/**
+ * API for fetching source code snippets.
+ * Provides gated access with size limits and hash verification.
+ */
+export declare class SourceSnippetApi {
+    private contractApi;
+    private dbManager;
+    constructor(dbManager: MultiDbManager);
+    /**
+     * Fetch source code snippet by symbol ID or file path + range.
+     * Gated access with size limits and hash verification.
+     */
+    fetchSnippet(args: {
+        symbol_id?: string;
+        file_path?: string;
+        start_line?: number;
+        end_line?: number;
+        content_hash?: string;
+        include_context?: boolean;
+        context_lines?: number;
+        verify_hash?: boolean;
+        pluginId: string;
+        workspaceRoot?: string;
+    }): Promise<SourceSnippet | SourceSnippetError>;
+}
+//# sourceMappingURL=source-snippet-api.d.ts.map

package/out/api/source-snippet-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-snippet-api.d.ts","sourceRoot":"","sources":["../../src/api/source-snippet-api.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG1D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAsB,MAAM,oBAAoB,CAAC;AAGlE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,KAAK,EAAE,oBAAoB,GAAG,kBAAkB,GAAG,mBAAmB,GAAG,gBAAgB,GAAG,eAAe,CAAC;IAC5G,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,QAAQ,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,SAAS,CAAiB;gBAEtB,SAAS,EAAE,cAAc;IAKrC;;;OAGG;IACG,YAAY,CAAC,IAAI,EAAE;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,CAAC,EAAE,MAAM,CAAC;KAC1B,GAAG,OAAO,CAAC,aAAa,GAAG,kBAAkB,CAAC;CAiJlD"}

package/out/api/source-snippet-api.js

@@ -0,0 +1,185 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SourceSnippetApi = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const source_access_contract_api_1 = require("./source-access-contract-api");
+const symbol_repository_1 = require("../repositories/symbol-repository");
+const evidence_1 = require("../models/evidence");
+const evidence_2 = require("../models/evidence");
+/**
+ * API for fetching source code snippets.
+ * Provides gated access with size limits and hash verification.
+ */
+class SourceSnippetApi {
+    constructor(dbManager) {
+        this.dbManager = dbManager;
+        this.contractApi = new source_access_contract_api_1.SourceAccessContractApi(dbManager);
+    }
+    /**
+     * Fetch source code snippet by symbol ID or file path + range.
+     * Gated access with size limits and hash verification.
+     */
+    async fetchSnippet(args) {
+        // 1. Get source access contract
+        const contract = await this.contractApi.getContract(args.workspaceRoot);
+        if (contract.status === 'UNAVAILABLE') {
+            return {
+                error: 'SOURCE_UNAVAILABLE',
+                reason_codes: contract.reason_codes,
+                evidence: (0, evidence_1.createFactEvidence)([
+                    (0, evidence_2.createEvidenceSource)('DB_QUERY', undefined, undefined, undefined, {
+                        table: 'source_access_config',
+                        status: contract.status
+                    })
+                ], `Source code unavailable: ${contract.reason_codes?.map(code => code.toString()).join(', ')}`)
+            };
+        }
+        // 2. Resolve symbol to span (if symbol_id provided)
+        let filePath = args.file_path;
+        let startLine = args.start_line;
+        let endLine = args.end_line;
+        if (args.symbol_id) {
+            const db = await this.dbManager.getDatabase('Y');
+            const repository = new symbol_repository_1.SymbolRepository(db);
+            // Try to find symbol by symbol_id
+            const symbol = await repository.getBySymbolId(args.symbol_id, args.pluginId);
+            if (!symbol) {
+                return {
+                    error: 'SYMBOL_NOT_FOUND',
+                    symbol_id: args.symbol_id,
+                    evidence: (0, evidence_1.createFactEvidence)([
+                        (0, evidence_2.createEvidenceSource)('DB_QUERY', args.symbol_id, undefined, undefined, {
+                            table: 'symbols',
+                            plugin_id: args.pluginId
+                        })
+                    ], `Symbol ${args.symbol_id} not found in database`)
+                };
+            }
+            if (!symbol.start_line || !symbol.end_line) {
+                return {
+                    error: 'SYMBOL_NOT_FOUND',
+                    symbol_id: args.symbol_id,
+                    evidence: (0, evidence_1.createFactEvidence)([
+                        (0, evidence_2.createEvidenceSource)('DB_QUERY', args.symbol_id, symbol.path, undefined, {
+                            table: 'symbols',
+                            note: 'Symbol found but missing span information'
+                        })
+                    ], `Symbol ${args.symbol_id} found but missing span information (start_line/end_line)`)
+                };
+            }
+            filePath = symbol.path;
+            startLine = symbol.start_line;
+            endLine = symbol.end_line;
+        }
+        if (!filePath || !startLine || !endLine) {
+            throw new Error('Either symbol_id OR (file_path + start_line + end_line) must be provided');
+        }
+        // 3. Size check (gating!)
+        const requestedLines = endLine - startLine + 1;
+        const contextLines = args.include_context ? (args.context_lines || 5) : 0;
+        const totalLines = requestedLines + (contextLines * 2);
+        if (contract.constraints && totalLines > contract.constraints.max_lines_per_request) {
+            return {
+                error: 'SNIPPET_TOO_LARGE',
+                requested_lines: totalLines,
+                max_allowed: contract.constraints.max_lines_per_request,
+                evidence: (0, evidence_1.createFactEvidence)([
+                    (0, evidence_2.createEvidenceSource)('DB_QUERY', undefined, undefined, undefined, {
+                        table: 'source_access_config',
+                        constraint: 'max_lines_per_request'
+                    })
+                ], `Requested ${totalLines} lines exceeds limit of ${contract.constraints.max_lines_per_request}`)
+            };
+        }
+        // 4. Fetch code from filesystem
+        const workspaceRoot = contract.workspace_root || args.workspaceRoot || process.cwd();
+        const fullPath = path.join(workspaceRoot, filePath);
+        if (!fs.existsSync(fullPath)) {
+            return {
+                error: 'FILE_NOT_FOUND',
+                file_path: filePath,
+                resolved_path: fullPath,
+                evidence: (0, evidence_1.createFactEvidence)([
+                    (0, evidence_2.createEvidenceSource)('STATUS_CHECK', undefined, fullPath, undefined, {
+                        check: 'file_exists'
+                    })
+                ], `File not found: ${fullPath}`)
+            };
+        }
+        const fileContent = fs.readFileSync(fullPath, 'utf-8');
+        const lines = fileContent.split('\n');
+        // 5. Extract snippet with optional context
+        const actualStart = Math.max(1, startLine - contextLines);
+        const actualEnd = Math.min(lines.length, endLine + contextLines);
+        const snippet = lines.slice(actualStart - 1, actualEnd).join('\n');
+        // 6. Hash verification (if requested)
+        const computedHash = crypto.createHash('sha256').update(snippet).digest('hex').substring(0, 16);
+        if (args.verify_hash && args.content_hash && computedHash !== args.content_hash) {
+            return {
+                error: 'HASH_MISMATCH',
+                expected_hash: args.content_hash,
+                computed_hash: computedHash,
+                evidence: (0, evidence_1.createFactEvidence)([
+                    (0, evidence_2.createEvidenceSource)('STATUS_CHECK', undefined, fullPath, computedHash, {
+                        check: 'hash_verification',
+                        expected: args.content_hash
+                    })
+                ], `Hash mismatch: expected ${args.content_hash}, got ${computedHash}. Code may have changed since scan.`)
+            };
+        }
+        // 7. Return snippet with provenance
+        return {
+            file_path: filePath,
+            start_line: actualStart,
+            end_line: actualEnd,
+            core_start_line: startLine,
+            core_end_line: endLine,
+            snippet: snippet,
+            content_hash: computedHash,
+            byte_size: Buffer.byteLength(snippet, 'utf-8'),
+            evidence: (0, evidence_1.createFactEvidence)([
+                (0, evidence_2.createEvidenceSource)('STATUS_CHECK', undefined, fullPath, computedHash, {
+                    check: 'filesystem_read',
+                    lines: `${actualStart}-${actualEnd}`
+                })
+            ], `Code snippet extracted from ${filePath} lines ${startLine}-${endLine} with ${contextLines} context lines`)
+        };
+    }
+}
+exports.SourceSnippetApi = SourceSnippetApi;
+//# sourceMappingURL=source-snippet-api.js.map

package/out/api/source-snippet-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-snippet-api.js","sourceRoot":"","sources":["../../src/api/source-snippet-api.ts"],"names":[],"mappings":"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"}

package/out/api/vector-backend-status-api.d.ts

@@ -0,0 +1,68 @@
+import { MultiDbManager } from '../core/multi-db-manager';
+import { ReasonCode } from '../models/reason-codes';
+import { ActionHint } from '../models/action-hint';
+/**
+ * Vector backend status information.
+ */
+export interface VectorBackendStatus {
+    /** Type of backend (chromadb, vss, or fallback) */
+    backend: 'chromadb' | 'vss' | 'fallback' | 'none';
+    /** Mode (expected backend for this platform) */
+    mode: 'chromadb' | 'vss' | 'fallback';
+    /** Whether the expected backend is available */
+    expected_available: boolean;
+    /** Whether the backend is reachable */
+    reachable: boolean;
+    /** Whether fallback is active */
+    fallback: boolean;
+    /** Reason code for the current status */
+    reason_code: ReasonCode;
+    /** Human-readable description */
+    description: string;
+    /** Action hints for resolving issues (if any) */
+    action_hints?: ActionHint[];
+    /** Platform information */
+    platform: string;
+}
+/**
+ * Vector backend healthcheck result.
+ */
+export interface VectorBackendHealthcheck {
+    /** Whether the healthcheck passed */
+    healthy: boolean;
+    /** Reason code */
+    reason_code: ReasonCode;
+    /** Latency in milliseconds (if measurable) */
+    latency_ms?: number;
+    /** Error code (if any) */
+    error_code?: string;
+    /** Human-readable description */
+    description: string;
+    /** Action hints for resolving issues (if any) */
+    action_hints?: ActionHint[];
+}
+/**
+ * API for checking vector backend status and health.
+ */
+export declare class VectorBackendStatusApi {
+    private dbManager;
+    constructor(dbManager: MultiDbManager);
+    /**
+     * Gets the current vector backend status.
+     *
+     * @returns Promise that resolves to vector backend status
+     */
+    getVectorBackendStatus(): Promise<VectorBackendStatus>;
+    /**
+     * Performs a healthcheck on the vector backend.
+     * Attempts to perform a simple query to verify the backend is responsive.
+     *
+     * @returns Promise that resolves to healthcheck result
+     */
+    healthcheckVectorBackend(): Promise<VectorBackendHealthcheck>;
+    /**
+     * Gets action hints for a specific reason code.
+     */
+    private getActionHintsForReason;
+}
+//# sourceMappingURL=vector-backend-status-api.d.ts.map

package/out/api/vector-backend-status-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-backend-status-api.d.ts","sourceRoot":"","sources":["../../src/api/vector-backend-status-api.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI1D,OAAO,EAAE,UAAU,EAA4B,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAoB,MAAM,uBAAuB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,mDAAmD;IACnD,OAAO,EAAE,UAAU,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,CAAC;IAElD,gDAAgD;IAChD,IAAI,EAAE,UAAU,GAAG,KAAK,GAAG,UAAU,CAAC;IAEtC,gDAAgD;IAChD,kBAAkB,EAAE,OAAO,CAAC;IAE5B,uCAAuC;IACvC,SAAS,EAAE,OAAO,CAAC;IAEnB,iCAAiC;IACjC,QAAQ,EAAE,OAAO,CAAC;IAElB,yCAAyC;IACzC,WAAW,EAAE,UAAU,CAAC;IAExB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IAEpB,iDAAiD;IACjD,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;IAE5B,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACrC,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IAEjB,kBAAkB;IAClB,WAAW,EAAE,UAAU,CAAC;IAExB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,0BAA0B;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IAEpB,iDAAiD;IACjD,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;CAC/B;AAED;;GAEG;AACH,qBAAa,sBAAsB;IAC/B,OAAO,CAAC,SAAS,CAAiB;gBAEtB,SAAS,EAAE,cAAc;IAIrC;;;;OAIG;IACG,sBAAsB,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAuF5D;;;;;OAKG;IACG,wBAAwB,IAAI,OAAO,CAAC,wBAAwB,CAAC;IAuEnE;;OAEG;IACH,OAAO,CAAC,uBAAuB;CAoElC"}

package/out/api/vector-backend-status-api.js

@@ -0,0 +1,241 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VectorBackendStatusApi = void 0;
+const os = __importStar(require("os"));
+const chromadb_vector_database_1 = require("../core/chromadb-vector-database");
+const vss_vector_database_1 = require("../core/vss-vector-database");
+const reason_codes_1 = require("../models/reason-codes");
+const action_hint_1 = require("../models/action-hint");
+/**
+ * API for checking vector backend status and health.
+ */
+class VectorBackendStatusApi {
+    constructor(dbManager) {
+        this.dbManager = dbManager;
+    }
+    /**
+     * Gets the current vector backend status.
+     *
+     * @returns Promise that resolves to vector backend status
+     */
+    async getVectorBackendStatus() {
+        const platform = os.platform();
+        const arch = os.arch();
+        // Determine expected mode based on platform
+        let expectedMode = 'fallback';
+        if (platform === 'win32') {
+            expectedMode = 'chromadb';
+        }
+        else if (platform === 'darwin' || platform === 'linux') {
+            expectedMode = 'vss';
+        }
+        // Get vector database instance
+        const vectorDb = this.dbManager.getVectorDatabase();
+        if (!vectorDb) {
+            // Vector database not initialized
+            return {
+                backend: 'none',
+                mode: expectedMode,
+                expected_available: false,
+                reachable: false,
+                fallback: true,
+                reason_code: reason_codes_1.ReasonCode.NOT_INSTALLED,
+                description: 'Vector database not initialized. V-dimension database may not be opened yet.',
+                platform: `${platform}/${arch}`,
+                action_hints: this.getActionHintsForReason(reason_codes_1.ReasonCode.NOT_INSTALLED, expectedMode, platform)
+            };
+        }
+        const isAvailable = vectorDb.isAvailable();
+        const isChromaDb = vectorDb instanceof chromadb_vector_database_1.ChromaDbVectorDatabase;
+        const isVss = vectorDb instanceof vss_vector_database_1.VssVectorDatabase;
+        // Determine actual backend
+        let actualBackend = 'none';
+        if (isChromaDb) {
+            actualBackend = 'chromadb';
+        }
+        else if (isVss) {
+            actualBackend = 'vss';
+        }
+        else {
+            actualBackend = 'fallback';
+        }
+        // Determine if fallback is active
+        const isFallback = (expectedMode === 'chromadb' && actualBackend !== 'chromadb') ||
+            (expectedMode === 'vss' && actualBackend !== 'vss');
+        // Determine reason code
+        let reasonCode = reason_codes_1.ReasonCode.OK;
+        let description = 'Vector backend is available and reachable.';
+        if (!isAvailable) {
+            if (expectedMode === 'chromadb' && actualBackend === 'chromadb') {
+                reasonCode = reason_codes_1.ReasonCode.VECTOR_BACKEND_UNREACHABLE;
+                description = 'ChromaDB backend is not reachable. Check if ChromaDB server is running on localhost:8000.';
+            }
+            else if (expectedMode === 'vss' && actualBackend === 'vss') {
+                reasonCode = reason_codes_1.ReasonCode.DEPENDENCY_MISSING;
+                description = 'VSS extension is not available. SQLite VSS extension may not be installed.';
+            }
+            else if (isFallback) {
+                reasonCode = reason_codes_1.ReasonCode.VECTOR_BACKEND_UNREACHABLE;
+                description = 'Expected vector backend is not available, using fallback.';
+            }
+            else {
+                reasonCode = reason_codes_1.ReasonCode.NOT_INSTALLED;
+                description = 'Vector backend is not available.';
+            }
+        }
+        const status = {
+            backend: actualBackend,
+            mode: expectedMode,
+            expected_available: isAvailable && !isFallback,
+            reachable: isAvailable,
+            fallback: isFallback,
+            reason_code: reasonCode,
+            description,
+            platform: `${platform}/${arch}`
+        };
+        // Add action hints if there are issues
+        if (reasonCode !== reason_codes_1.ReasonCode.OK) {
+            status.action_hints = this.getActionHintsForReason(reasonCode, expectedMode, platform);
+        }
+        return status;
+    }
+    /**
+     * Performs a healthcheck on the vector backend.
+     * Attempts to perform a simple query to verify the backend is responsive.
+     *
+     * @returns Promise that resolves to healthcheck result
+     */
+    async healthcheckVectorBackend() {
+        const startTime = Date.now();
+        const vectorDb = this.dbManager.getVectorDatabase();
+        if (!vectorDb) {
+            return {
+                healthy: false,
+                reason_code: reason_codes_1.ReasonCode.NOT_INSTALLED,
+                description: 'Vector database not initialized.',
+                action_hints: this.getActionHintsForReason(reason_codes_1.ReasonCode.NOT_INSTALLED, 'fallback', os.platform())
+            };
+        }
+        if (!vectorDb.isAvailable()) {
+            const platform = os.platform();
+            const expectedMode = platform === 'win32' ? 'chromadb' : (platform === 'darwin' || platform === 'linux' ? 'vss' : 'fallback');
+            return {
+                healthy: false,
+                reason_code: reason_codes_1.ReasonCode.VECTOR_BACKEND_UNREACHABLE,
+                description: 'Vector backend is not available.',
+                action_hints: this.getActionHintsForReason(reason_codes_1.ReasonCode.VECTOR_BACKEND_UNREACHABLE, expectedMode, platform)
+            };
+        }
+        // Try to perform a simple search query to verify backend is responsive
+        try {
+            // Use a zero vector for testing (will return empty results, but tests connectivity)
+            const testVector = new Array(1536).fill(0);
+            await vectorDb.search(testVector, 1);
+            const latencyMs = Date.now() - startTime;
+            return {
+                healthy: true,
+                reason_code: reason_codes_1.ReasonCode.OK,
+                latency_ms: latencyMs,
+                description: 'Vector backend is healthy and responsive.'
+            };
+        }
+        catch (error) {
+            const latencyMs = Date.now() - startTime;
+            const errorMsg = error?.message || String(error);
+            const platform = os.platform();
+            const expectedMode = platform === 'win32' ? 'chromadb' : (platform === 'darwin' || platform === 'linux' ? 'vss' : 'fallback');
+            // Determine error code
+            let errorCode = 'UNKNOWN_ERROR';
+            let reasonCode = reason_codes_1.ReasonCode.VECTOR_BACKEND_UNREACHABLE;
+            if (errorMsg.includes('ECONNREFUSED') || errorMsg.includes('connect')) {
+                errorCode = 'CONNECTION_REFUSED';
+                reasonCode = reason_codes_1.ReasonCode.VECTOR_BACKEND_UNREACHABLE;
+            }
+            else if (errorMsg.includes('timeout')) {
+                errorCode = 'TIMEOUT';
+                reasonCode = reason_codes_1.ReasonCode.TIMEOUT;
+            }
+            else if (errorMsg.includes('ENOTFOUND')) {
+                errorCode = 'DNS_ERROR';
+                reasonCode = reason_codes_1.ReasonCode.WRONG_PATH;
+            }
+            return {
+                healthy: false,
+                reason_code: reasonCode,
+                latency_ms: latencyMs,
+                error_code: errorCode,
+                description: `Healthcheck failed: ${errorMsg}`,
+                action_hints: this.getActionHintsForReason(reasonCode, expectedMode, platform)
+            };
+        }
+    }
+    /**
+     * Gets action hints for a specific reason code.
+     */
+    getActionHintsForReason(reasonCode, expectedMode, platform) {
+        const hints = [];
+        if (reasonCode === reason_codes_1.ReasonCode.VECTOR_BACKEND_UNREACHABLE && expectedMode === 'chromadb') {
+            // ChromaDB is not reachable
+            if (platform === 'win32') {
+                hints.push((0, action_hint_1.createActionHint)('windows', 'chroma run --host localhost --port 8000', ['ChromaDB must be installed (pip install chromadb)', 'Python must be in PATH'], ['Open browser to http://localhost:8000/api/v1/heartbeat', 'Check if process is running: Get-Process | Where-Object {$_.ProcessName -like "*chroma*"}'], 'Start ChromaDB server on localhost:8000'));
+            }
+            else if (platform === 'linux') {
+                hints.push((0, action_hint_1.createActionHint)('linux', 'chroma run --host localhost --port 8000', ['ChromaDB must be installed (pip install chromadb)', 'Python must be in PATH'], ['curl http://localhost:8000/api/v1/heartbeat', 'Check if process is running: ps aux | grep chroma'], 'Start ChromaDB server on localhost:8000'));
+            }
+            else if (platform === 'darwin') {
+                hints.push((0, action_hint_1.createActionHint)('mac', 'chroma run --host localhost --port 8000', ['ChromaDB must be installed (pip install chromadb)', 'Python must be in PATH'], ['curl http://localhost:8000/api/v1/heartbeat', 'Check if process is running: ps aux | grep chroma'], 'Start ChromaDB server on localhost:8000'));
+            }
+        }
+        else if (reasonCode === reason_codes_1.ReasonCode.DEPENDENCY_MISSING && expectedMode === 'vss') {
+            // VSS extension is missing
+            if (platform === 'linux') {
+                hints.push((0, action_hint_1.createActionHint)('linux', 'sudo apt-get install sqlite3-vss', ['SQLite3 must be installed', 'Package manager access (apt-get)'], ['sqlite3 :memory: "SELECT load_extension(\'vss0\');"', 'Check if extension loads without errors'], 'Install SQLite VSS extension'));
+            }
+            else if (platform === 'darwin') {
+                hints.push((0, action_hint_1.createActionHint)('mac', 'brew install sqlite-vss', ['Homebrew must be installed', 'SQLite3 must be installed'], ['sqlite3 :memory: "SELECT load_extension(\'vss0\');"', 'Check if extension loads without errors'], 'Install SQLite VSS extension via Homebrew'));
+            }
+        }
+        else if (reasonCode === reason_codes_1.ReasonCode.NOT_INSTALLED) {
+            // Component is not installed
+            if (platform === 'win32') {
+                hints.push((0, action_hint_1.createActionHint)('windows', 'npm install chromadb', ['Node.js and npm must be installed'], ['node -e "require(\'chromadb\')"', 'Check if chromadb package is available'], 'Install chromadb npm package'));
+            }
+        }
+        return hints;
+    }
+}
+exports.VectorBackendStatusApi = VectorBackendStatusApi;
+//# sourceMappingURL=vector-backend-status-api.js.map

package/out/api/vector-backend-status-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-backend-status-api.js","sourceRoot":"","sources":["../../src/api/vector-backend-status-api.ts"],"names":[],"mappings":"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"}

package/out/cli/debug-plugin-id.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Debug Tool: Plugin ID Verification
+ *
+ * Verifies plugin ID calculation and checks database for matching plugin IDs.
+ * Useful for debugging foreign system issues where plugin IDs don't match.
+ */
+export {};
+//# sourceMappingURL=debug-plugin-id.d.ts.map

package/out/cli/debug-plugin-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-plugin-id.d.ts","sourceRoot":"","sources":["../../src/cli/debug-plugin-id.ts"],"names":[],"mappings":";AAEA;;;;;GAKG"}