gitnexus 1.4.7 → 1.4.9

package/dist/core/lbug/csv-generator.js

@@ -208,6 +208,12 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
     const codeElemWriter = new BufferedCSVWriter(path.join(csvDir, 'codeelement.csv'), codeElementHeader);
     const communityWriter = new BufferedCSVWriter(path.join(csvDir, 'community.csv'), 'id,label,heuristicLabel,keywords,description,enrichedBy,cohesion,symbolCount');
     const processWriter = new BufferedCSVWriter(path.join(csvDir, 'process.csv'), 'id,label,heuristicLabel,processType,stepCount,communities,entryPointId,terminalId');
+    // Section nodes have an extra 'level' column
+    const sectionWriter = new BufferedCSVWriter(path.join(csvDir, 'section.csv'), 'id,name,filePath,startLine,endLine,level,content,description');
+    // Route nodes for API endpoint mapping
+    const routeWriter = new BufferedCSVWriter(path.join(csvDir, 'route.csv'), 'id,name,filePath,responseKeys,errorKeys,middleware');
+    // Tool nodes for MCP tool definitions
+    const toolWriter = new BufferedCSVWriter(path.join(csvDir, 'tool.csv'), 'id,name,filePath,description');
     // Multi-language node types share the same CSV shape (no isExported column)
     const multiLangHeader = 'id,name,filePath,startLine,endLine,content,description';
     const MULTI_LANG_TYPES = ['Struct', 'Enum', 'Macro', 'Typedef', 'Union', 'Namespace', 'Trait', 'Impl',
@@ -292,6 +298,47 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
                 ].join(','));
                 break;
             }
+            case 'Section': {
+                const content = await extractContent(node, contentCache);
+                await sectionWriter.addRow([
+                    escapeCSVField(node.id),
+                    escapeCSVField(node.properties.name || ''),
+                    escapeCSVField(node.properties.filePath || ''),
+                    escapeCSVNumber(node.properties.startLine, -1),
+                    escapeCSVNumber(node.properties.endLine, -1),
+                    escapeCSVNumber(node.properties.level, 1),
+                    escapeCSVField(content),
+                    escapeCSVField(node.properties.description || ''),
+                ].join(','));
+                break;
+            }
+            case 'Route': {
+                const responseKeys = node.properties.responseKeys || [];
+                // LadybugDB array literal inside a quoted CSV field: escapeCSVField wraps in "..."
+                // and the array uses single-quoted elements
+                const keysStr = `[${responseKeys.map((k) => `'${k.replace(/'/g, "''")}'`).join(',')}]`;
+                const errorKeys = node.properties.errorKeys || [];
+                const errorKeysStr = `[${errorKeys.map((k) => `'${k.replace(/'/g, "''")}'`).join(',')}]`;
+                const middleware = node.properties.middleware || [];
+                const middlewareStr = `[${middleware.map((m) => `'${m.replace(/'/g, "''")}'`).join(',')}]`;
+                await routeWriter.addRow([
+                    escapeCSVField(node.id),
+                    escapeCSVField(node.properties.name || ''),
+                    escapeCSVField(node.properties.filePath || ''),
+                    escapeCSVField(keysStr),
+                    escapeCSVField(errorKeysStr),
+                    escapeCSVField(middlewareStr),
+                ].join(','));
+                break;
+            }
+            case 'Tool':
+                await toolWriter.addRow([
+                    escapeCSVField(node.id),
+                    escapeCSVField(node.properties.name || ''),
+                    escapeCSVField(node.properties.filePath || ''),
+                    escapeCSVField(node.properties.description || ''),
+                ].join(','));
+                break;
             default: {
                 // Code element nodes (Function, Class, Interface, CodeElement)
                 const writer = codeWriterMap[node.label];
@@ -329,7 +376,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
         }
     }
     // Finish all node writers
-    const allWriters = [fileWriter, folderWriter, functionWriter, classWriter, interfaceWriter, methodWriter, codeElemWriter, communityWriter, processWriter, ...multiLangWriters.values()];
+    const allWriters = [fileWriter, folderWriter, functionWriter, classWriter, interfaceWriter, methodWriter, codeElemWriter, communityWriter, processWriter, sectionWriter, routeWriter, toolWriter, ...multiLangWriters.values()];
     await Promise.all(allWriters.map(w => w.finish()));
     // --- Stream relationship CSV ---
     const relCsvPath = path.join(csvDir, 'relations.csv');
@@ -353,6 +400,9 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
         ['Interface', interfaceWriter], ['Method', methodWriter],
         ['CodeElement', codeElemWriter],
         ['Community', communityWriter], ['Process', processWriter],
+        ['Section', sectionWriter],
+        ['Route', routeWriter],
+        ['Tool', toolWriter],
         ...Array.from(multiLangWriters.entries()).map(([name, w]) => [name, w]),
     ];
     for (const [name, writer] of tableMap) {

package/dist/core/lbug/lbug-adapter.d.ts

@@ -2,6 +2,12 @@ import lbug from '@ladybugdb/core';
 import { KnowledgeGraph } from '../graph/types.js';
 /** Expose the current Database for pool adapter reuse in tests. */
 export declare const getDatabase: () => lbug.Database | null;
+/**
+ * Return true when the error message indicates that another process holds
+ * an exclusive lock on the LadybugDB file (e.g. `gitnexus analyze` or
+ * `gitnexus serve` running at the same time).
+ */
+export declare const isDbBusyError: (err: unknown) => boolean;
 export declare const initLbug: (dbPath: string) => Promise<{
     db: lbug.Database;
     conn: lbug.Connection;
@@ -9,6 +15,10 @@ export declare const initLbug: (dbPath: string) => Promise<{
 /**
  * Execute multiple queries against one repo DB atomically.
  * While the callback runs, no other request can switch the active DB.
+ *
+ * Automatically retries up to DB_LOCK_RETRY_ATTEMPTS times when the
+ * database is busy (e.g. `gitnexus analyze` holds the write lock).
+ * Each retry waits DB_LOCK_RETRY_DELAY_MS * attempt milliseconds.
  */
 export declare const withLbugDb: <T>(dbPath: string, operation: () => Promise<T>) => Promise<T>;
 export type LbugProgressCallback = (message: string) => void;

package/dist/core/lbug/lbug-adapter.js

@@ -14,6 +14,22 @@ export const getDatabase = () => db;
 // Global session lock for operations that touch module-level lbug globals.
 // This guarantees no DB switch can happen while an operation is running.
 let sessionLock = Promise.resolve();
+/** Number of times to retry on a BUSY / lock-held error before giving up. */
+const DB_LOCK_RETRY_ATTEMPTS = 3;
+/** Base back-off in ms between BUSY retries (multiplied by attempt number). */
+const DB_LOCK_RETRY_DELAY_MS = 500;
+/**
+ * Return true when the error message indicates that another process holds
+ * an exclusive lock on the LadybugDB file (e.g. `gitnexus analyze` or
+ * `gitnexus serve` running at the same time).
+ */
+export const isDbBusyError = (err) => {
+    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return (msg.includes('busy')
+        || msg.includes('lock')
+        || msg.includes('already in use')
+        || msg.includes('could not set lock'));
+};
 const runWithSessionLock = async (operation) => {
     const previous = sessionLock;
     let release = null;
@@ -35,12 +51,50 @@ export const initLbug = async (dbPath) => {
 /**
  * Execute multiple queries against one repo DB atomically.
  * While the callback runs, no other request can switch the active DB.
+ *
+ * Automatically retries up to DB_LOCK_RETRY_ATTEMPTS times when the
+ * database is busy (e.g. `gitnexus analyze` holds the write lock).
+ * Each retry waits DB_LOCK_RETRY_DELAY_MS * attempt milliseconds.
  */
 export const withLbugDb = async (dbPath, operation) => {
-    return runWithSessionLock(async () => {
-        await ensureLbugInitialized(dbPath);
-        return operation();
-    });
+    let lastError;
+    for (let attempt = 1; attempt <= DB_LOCK_RETRY_ATTEMPTS; attempt++) {
+        try {
+            return await runWithSessionLock(async () => {
+                await ensureLbugInitialized(dbPath);
+                return operation();
+            });
+        }
+        catch (err) {
+            lastError = err;
+            if (!isDbBusyError(err) || attempt === DB_LOCK_RETRY_ATTEMPTS) {
+                throw err;
+            }
+            // Close stale connection inside the session lock to prevent race conditions
+            // with concurrent operations that might acquire the lock between cleanup steps
+            await runWithSessionLock(async () => {
+                try {
+                    if (conn)
+                        await conn.close();
+                }
+                catch { /* best-effort */ }
+                try {
+                    if (db)
+                        await db.close();
+                }
+                catch { /* best-effort */ }
+                conn = null;
+                db = null;
+                currentDbPath = null;
+                ftsLoaded = false;
+            });
+            // Sleep outside the lock — no need to block others while waiting
+            await new Promise(resolve => setTimeout(resolve, DB_LOCK_RETRY_DELAY_MS * attempt));
+        }
+    }
+    // This line is unreachable — the loop either returns or throws inside,
+    // but TypeScript needs an explicit throw to satisfy the return type.
+    throw lastError;
 };
 const ensureLbugInitialized = async (dbPath) => {
     if (conn && currentDbPath === dbPath) {
@@ -323,6 +377,15 @@ const getCopyQuery = (table, filePath) => {
     if (table === 'Process') {
         return `COPY ${t}(id, label, heuristicLabel, processType, stepCount, communities, entryPointId, terminalId) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
+    if (table === 'Section') {
+        return `COPY ${t}(id, name, filePath, startLine, endLine, level, content, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+    }
+    if (table === 'Route') {
+        return `COPY ${t}(id, name, filePath, responseKeys, errorKeys, middleware) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+    }
+    if (table === 'Tool') {
+        return `COPY ${t}(id, name, filePath, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+    }
     if (table === 'Method') {
         return `COPY ${t}(id, name, filePath, startLine, endLine, isExported, content, description, parameterCount, returnType) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
@@ -363,6 +426,10 @@ export const insertNodeToLbug = async (label, properties, dbPath) => {
         else if (label === 'Folder') {
             query = `CREATE (n:Folder {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}})`;
         }
+        else if (label === 'Section') {
+            const descPart = properties.description ? `, description: ${escapeValue(properties.description)}` : '';
+            query = `CREATE (n:Section {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, level: ${properties.level || 1}, content: ${escapeValue(properties.content || '')}${descPart}})`;
+        }
         else if (TABLES_WITH_EXPORTED.has(label)) {
             const descPart = properties.description ? `, description: ${escapeValue(properties.description)}` : '';
             query = `CREATE (n:${t} {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, isExported: ${!!properties.isExported}, content: ${escapeValue(properties.content || '')}${descPart}})`;
@@ -438,6 +505,10 @@ export const batchInsertNodesToLbug = async (nodes, dbPath) => {
                 else if (label === 'Folder') {
                     query = `MERGE (n:Folder {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}`;
                 }
+                else if (label === 'Section') {
+                    const descPart = properties.description ? `, n.description = ${escapeValue(properties.description)}` : '';
+                    query = `MERGE (n:Section {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.level = ${properties.level || 1}, n.content = ${escapeValue(properties.content || '')}${descPart}`;
+                }
                 else if (TABLES_WITH_EXPORTED.has(label)) {
                     const descPart = properties.description ? `, n.description = ${escapeValue(properties.description)}` : '';
                     query = `MERGE (n:${t} {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.isExported = ${!!properties.isExported}, n.content = ${escapeValue(properties.content || '')}${descPart}`;

package/dist/core/lbug/schema.d.ts

@@ -8,10 +8,10 @@
  * This allows LLMs to write natural Cypher queries like:
  *   MATCH (f:Function)-[r:CodeRelation {type: 'CALLS'}]->(g:Function) RETURN f, g
  */
-export declare const NODE_TABLES: readonly ["File", "Folder", "Function", "Class", "Interface", "Method", "CodeElement", "Community", "Process", "Struct", "Enum", "Macro", "Typedef", "Union", "Namespace", "Trait", "Impl", "TypeAlias", "Const", "Static", "Property", "Record", "Delegate", "Annotation", "Constructor", "Template", "Module"];
+export declare const NODE_TABLES: readonly ["File", "Folder", "Function", "Class", "Interface", "Method", "CodeElement", "Community", "Process", "Section", "Struct", "Enum", "Macro", "Typedef", "Union", "Namespace", "Trait", "Impl", "TypeAlias", "Const", "Static", "Property", "Record", "Delegate", "Annotation", "Constructor", "Template", "Module", "Route", "Tool"];
 export type NodeTableName = typeof NODE_TABLES[number];
 export declare const REL_TABLE_NAME = "CodeRelation";
-export declare const REL_TYPES: readonly ["CONTAINS", "DEFINES", "IMPORTS", "CALLS", "EXTENDS", "IMPLEMENTS", "HAS_METHOD", "HAS_PROPERTY", "ACCESSES", "OVERRIDES", "MEMBER_OF", "STEP_IN_PROCESS"];
+export declare const REL_TYPES: readonly ["CONTAINS", "DEFINES", "IMPORTS", "CALLS", "EXTENDS", "IMPLEMENTS", "HAS_METHOD", "HAS_PROPERTY", "ACCESSES", "OVERRIDES", "MEMBER_OF", "STEP_IN_PROCESS", "HANDLES_ROUTE", "FETCHES", "HANDLES_TOOL", "ENTRY_POINT_OF", "WRAPS", "QUERIES"];
 export type RelType = typeof REL_TYPES[number];
 export declare const EMBEDDING_TABLE_NAME = "CodeEmbedding";
 export declare const FILE_SCHEMA = "\nCREATE NODE TABLE File (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  content STRING,\n  PRIMARY KEY (id)\n)";
@@ -41,8 +41,12 @@ export declare const ANNOTATION_SCHEMA: string;
 export declare const CONSTRUCTOR_SCHEMA: string;
 export declare const TEMPLATE_SCHEMA: string;
 export declare const MODULE_SCHEMA: string;
-export declare const RELATION_SCHEMA = "\nCREATE REL TABLE CodeRelation (\n  FROM File TO File,\n  FROM File TO Folder,\n  FROM File TO Function,\n  FROM File TO Class,\n  FROM File TO Interface,\n  FROM File TO Method,\n  FROM File TO CodeElement,\n  FROM File TO `Struct`,\n  FROM File TO `Enum`,\n  FROM File TO `Macro`,\n  FROM File TO `Typedef`,\n  FROM File TO `Union`,\n  FROM File TO `Namespace`,\n  FROM File TO `Trait`,\n  FROM File TO `Impl`,\n  FROM File TO `TypeAlias`,\n  FROM File TO `Const`,\n  FROM File TO `Static`,\n  FROM File TO `Property`,\n  FROM File TO `Record`,\n  FROM File TO `Delegate`,\n  FROM File TO `Annotation`,\n  FROM File TO `Constructor`,\n  FROM File TO `Template`,\n  FROM File TO `Module`,\n  FROM Folder TO Folder,\n  FROM Folder TO File,\n  FROM Function TO Function,\n  FROM Function TO Method,\n  FROM Function TO Class,\n  FROM Function TO Community,\n  FROM Function TO `Macro`,\n  FROM Function TO `Struct`,\n  FROM Function TO `Template`,\n  FROM Function TO `Enum`,\n  FROM Function TO `Namespace`,\n  FROM Function TO `TypeAlias`,\n  FROM Function TO `Module`,\n  FROM Function TO `Impl`,\n  FROM Function TO Interface,\n  FROM Function TO `Constructor`,\n  FROM Function TO `Const`,\n  FROM Function TO `Typedef`,\n  FROM Function TO `Union`,\n  FROM Function TO `Property`,\n  FROM Class TO Method,\n  FROM Class TO Function,\n  FROM Class TO Class,\n  FROM Class TO Interface,\n  FROM Class TO Community,\n  FROM Class TO `Template`,\n  FROM Class TO `TypeAlias`,\n  FROM Class TO `Struct`,\n  FROM Class TO `Enum`,\n  FROM Class TO `Annotation`,\n  FROM Class TO `Constructor`,\n  FROM Class TO `Trait`,\n  FROM Class TO `Macro`,\n  FROM Class TO `Impl`,\n  FROM Class TO `Union`,\n  FROM Class TO `Namespace`,\n  FROM Class TO `Typedef`,\n  FROM Class TO `Property`,\n  FROM Method TO Function,\n  FROM Method TO Method,\n  FROM Method TO Class,\n  FROM Method TO Community,\n  FROM Method TO `Template`,\n  FROM Method TO `Struct`,\n  FROM Method TO `TypeAlias`,\n  FROM Method TO `Enum`,\n  FROM Method TO `Macro`,\n  FROM Method TO `Namespace`,\n  FROM Method TO `Module`,\n  FROM Method TO `Impl`,\n  FROM Method TO Interface,\n  FROM Method TO `Constructor`,\n  FROM Method TO `Property`,\n  FROM `Template` TO `Template`,\n  FROM `Template` TO Function,\n  FROM `Template` TO Method,\n  FROM `Template` TO Class,\n  FROM `Template` TO `Struct`,\n  FROM `Template` TO `TypeAlias`,\n  FROM `Template` TO `Enum`,\n  FROM `Template` TO `Macro`,\n  FROM `Template` TO Interface,\n  FROM `Template` TO `Constructor`,\n  FROM `Module` TO `Module`,\n  FROM CodeElement TO Community,\n  FROM Interface TO Community,\n  FROM Interface TO Function,\n  FROM Interface TO Method,\n  FROM Interface TO Class,\n  FROM Interface TO Interface,\n  FROM Interface TO `TypeAlias`,\n  FROM Interface TO `Struct`,\n  FROM Interface TO `Constructor`,\n  FROM Interface TO `Property`,\n  FROM `Struct` TO Community,\n  FROM `Struct` TO `Trait`,\n  FROM `Struct` TO `Struct`,\n  FROM `Struct` TO Class,\n  FROM `Struct` TO `Enum`,\n  FROM `Struct` TO Function,\n  FROM `Struct` TO Method,\n  FROM `Struct` TO Interface,\n  FROM `Struct` TO `Constructor`,\n  FROM `Struct` TO `Property`,\n  FROM `Enum` TO `Enum`,\n  FROM `Enum` TO Community,\n  FROM `Enum` TO Class,\n  FROM `Enum` TO Interface,\n  FROM `Macro` TO Community,\n  FROM `Macro` TO Function,\n  FROM `Macro` TO Method,\n  FROM `Module` TO Function,\n  FROM `Module` TO Method,\n  FROM `Typedef` TO Community,\n  FROM `Union` TO Community,\n  FROM `Namespace` TO Community,\n  FROM `Namespace` TO `Struct`,\n  FROM `Trait` TO Method,\n  FROM `Trait` TO `Constructor`,\n  FROM `Trait` TO `Property`,\n  FROM `Trait` TO Community,\n  FROM `Impl` TO Method,\n  FROM `Impl` TO `Constructor`,\n  FROM `Impl` TO `Property`,\n  FROM `Impl` TO Community,\n  FROM `Impl` TO `Trait`,\n  FROM `Impl` TO `Struct`,\n  FROM `Impl` TO `Impl`,\n  FROM `TypeAlias` TO Community,\n  FROM `TypeAlias` TO `Trait`,\n  FROM `TypeAlias` TO Class,\n  FROM `Const` TO Community,\n  FROM `Static` TO Community,\n  FROM `Property` TO Community,\n  FROM `Record` TO Method,\n  FROM `Record` TO `Constructor`,\n  FROM `Record` TO `Property`,\n  FROM `Record` TO Community,\n  FROM `Delegate` TO Community,\n  FROM `Annotation` TO Community,\n  FROM `Constructor` TO Community,\n  FROM `Constructor` TO Interface,\n  FROM `Constructor` TO Class,\n  FROM `Constructor` TO Method,\n  FROM `Constructor` TO Function,\n  FROM `Constructor` TO `Constructor`,\n  FROM `Constructor` TO `Struct`,\n  FROM `Constructor` TO `Macro`,\n  FROM `Constructor` TO `Template`,\n  FROM `Constructor` TO `TypeAlias`,\n  FROM `Constructor` TO `Enum`,\n  FROM `Constructor` TO `Annotation`,\n  FROM `Constructor` TO `Impl`,\n  FROM `Constructor` TO `Namespace`,\n  FROM `Constructor` TO `Module`,\n  FROM `Constructor` TO `Property`,\n  FROM `Constructor` TO `Typedef`,\n  FROM `Template` TO Community,\n  FROM `Module` TO Community,\n  FROM Function TO Process,\n  FROM Method TO Process,\n  FROM Class TO Process,\n  FROM Interface TO Process,\n  FROM `Struct` TO Process,\n  FROM `Constructor` TO Process,\n  FROM `Module` TO Process,\n  FROM `Macro` TO Process,\n  FROM `Impl` TO Process,\n  FROM `Typedef` TO Process,\n  FROM `TypeAlias` TO Process,\n  FROM `Enum` TO Process,\n  FROM `Union` TO Process,\n  FROM `Namespace` TO Process,\n  FROM `Trait` TO Process,\n  FROM `Const` TO Process,\n  FROM `Static` TO Process,\n  FROM `Property` TO Process,\n  FROM `Record` TO Process,\n  FROM `Delegate` TO Process,\n  FROM `Annotation` TO Process,\n  FROM `Template` TO Process,\n  FROM CodeElement TO Process,\n  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\n)";
-export declare const EMBEDDING_SCHEMA = "\nCREATE NODE TABLE CodeEmbedding (\n  nodeId STRING,\n  embedding FLOAT[384],\n  PRIMARY KEY (nodeId)\n)";
+export declare const ROUTE_SCHEMA = "\nCREATE NODE TABLE Route (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  responseKeys STRING[],\n  errorKeys STRING[],\n  middleware STRING[],\n  PRIMARY KEY (id)\n)";
+export declare const TOOL_SCHEMA = "\nCREATE NODE TABLE Tool (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
+export declare const SECTION_SCHEMA = "\nCREATE NODE TABLE Section (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  level INT64,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
+export declare const RELATION_SCHEMA = "\nCREATE REL TABLE CodeRelation (\n  FROM File TO File,\n  FROM File TO Folder,\n  FROM File TO Function,\n  FROM File TO Class,\n  FROM File TO Interface,\n  FROM File TO Method,\n  FROM File TO CodeElement,\n  FROM File TO `Struct`,\n  FROM File TO `Enum`,\n  FROM File TO `Macro`,\n  FROM File TO `Typedef`,\n  FROM File TO `Union`,\n  FROM File TO `Namespace`,\n  FROM File TO `Trait`,\n  FROM File TO `Impl`,\n  FROM File TO `TypeAlias`,\n  FROM File TO `Const`,\n  FROM File TO `Static`,\n  FROM File TO `Property`,\n  FROM File TO `Record`,\n  FROM File TO `Delegate`,\n  FROM File TO `Annotation`,\n  FROM File TO `Constructor`,\n  FROM File TO `Template`,\n  FROM File TO `Module`,\n  FROM File TO Section,\n  FROM Folder TO Folder,\n  FROM Folder TO File,\n  FROM Function TO Function,\n  FROM Function TO Method,\n  FROM Function TO Class,\n  FROM Function TO Community,\n  FROM Function TO `Macro`,\n  FROM Function TO `Struct`,\n  FROM Function TO `Template`,\n  FROM Function TO `Enum`,\n  FROM Function TO `Namespace`,\n  FROM Function TO `TypeAlias`,\n  FROM Function TO `Module`,\n  FROM Function TO `Impl`,\n  FROM Function TO Interface,\n  FROM Function TO `Constructor`,\n  FROM Function TO `Const`,\n  FROM Function TO `Typedef`,\n  FROM Function TO `Union`,\n  FROM Function TO `Property`,\n  FROM Function TO CodeElement,\n  FROM Class TO Method,\n  FROM Class TO Function,\n  FROM Class TO Class,\n  FROM Class TO Interface,\n  FROM Class TO Community,\n  FROM Class TO `Template`,\n  FROM Class TO `TypeAlias`,\n  FROM Class TO `Struct`,\n  FROM Class TO `Enum`,\n  FROM Class TO `Annotation`,\n  FROM Class TO `Constructor`,\n  FROM Class TO `Trait`,\n  FROM Class TO `Macro`,\n  FROM Class TO `Impl`,\n  FROM Class TO `Union`,\n  FROM Class TO `Namespace`,\n  FROM Class TO `Typedef`,\n  FROM Class TO `Property`,\n  FROM Method TO Function,\n  FROM Method TO Method,\n  FROM Method TO Class,\n  FROM Method TO Community,\n  FROM Method TO `Template`,\n  FROM Method TO `Struct`,\n  FROM Method TO `TypeAlias`,\n  FROM Method TO `Enum`,\n  FROM Method TO `Macro`,\n  FROM Method TO `Namespace`,\n  FROM Method TO `Module`,\n  FROM Method TO `Impl`,\n  FROM Method TO Interface,\n  FROM Method TO `Constructor`,\n  FROM Method TO `Property`,\n  FROM Method TO CodeElement,\n  FROM `Template` TO `Template`,\n  FROM `Template` TO Function,\n  FROM `Template` TO Method,\n  FROM `Template` TO Class,\n  FROM `Template` TO `Struct`,\n  FROM `Template` TO `TypeAlias`,\n  FROM `Template` TO `Enum`,\n  FROM `Template` TO `Macro`,\n  FROM `Template` TO Interface,\n  FROM `Template` TO `Constructor`,\n  FROM `Module` TO `Module`,\n  FROM Section TO Section,\n  FROM Section TO File,\n  FROM File TO Route,\n  FROM Function TO Route,\n  FROM Method TO Route,\n  FROM File TO Tool,\n  FROM Function TO Tool,\n  FROM Method TO Tool,\n  FROM CodeElement TO Community,\n  FROM Interface TO Community,\n  FROM Interface TO Function,\n  FROM Interface TO Method,\n  FROM Interface TO Class,\n  FROM Interface TO Interface,\n  FROM Interface TO `TypeAlias`,\n  FROM Interface TO `Struct`,\n  FROM Interface TO `Constructor`,\n  FROM Interface TO `Property`,\n  FROM `Struct` TO Community,\n  FROM `Struct` TO `Trait`,\n  FROM `Struct` TO `Struct`,\n  FROM `Struct` TO Class,\n  FROM `Struct` TO `Enum`,\n  FROM `Struct` TO Function,\n  FROM `Struct` TO Method,\n  FROM `Struct` TO Interface,\n  FROM `Struct` TO `Constructor`,\n  FROM `Struct` TO `Property`,\n  FROM `Enum` TO `Enum`,\n  FROM `Enum` TO Community,\n  FROM `Enum` TO Class,\n  FROM `Enum` TO Interface,\n  FROM `Macro` TO Community,\n  FROM `Macro` TO Function,\n  FROM `Macro` TO Method,\n  FROM `Module` TO Function,\n  FROM `Module` TO Method,\n  FROM `Typedef` TO Community,\n  FROM `Union` TO Community,\n  FROM `Namespace` TO Community,\n  FROM `Namespace` TO `Struct`,\n  FROM `Trait` TO Method,\n  FROM `Trait` TO `Constructor`,\n  FROM `Trait` TO `Property`,\n  FROM `Trait` TO Community,\n  FROM `Impl` TO Method,\n  FROM `Impl` TO `Constructor`,\n  FROM `Impl` TO `Property`,\n  FROM `Impl` TO Community,\n  FROM `Impl` TO `Trait`,\n  FROM `Impl` TO `Struct`,\n  FROM `Impl` TO `Impl`,\n  FROM `TypeAlias` TO Community,\n  FROM `TypeAlias` TO `Trait`,\n  FROM `TypeAlias` TO Class,\n  FROM `Const` TO Community,\n  FROM `Static` TO Community,\n  FROM `Property` TO Community,\n  FROM `Record` TO Method,\n  FROM `Record` TO `Constructor`,\n  FROM `Record` TO `Property`,\n  FROM `Record` TO Community,\n  FROM `Delegate` TO Community,\n  FROM `Annotation` TO Community,\n  FROM `Constructor` TO Community,\n  FROM `Constructor` TO Interface,\n  FROM `Constructor` TO Class,\n  FROM `Constructor` TO Method,\n  FROM `Constructor` TO Function,\n  FROM `Constructor` TO `Constructor`,\n  FROM `Constructor` TO `Struct`,\n  FROM `Constructor` TO `Macro`,\n  FROM `Constructor` TO `Template`,\n  FROM `Constructor` TO `TypeAlias`,\n  FROM `Constructor` TO `Enum`,\n  FROM `Constructor` TO `Annotation`,\n  FROM `Constructor` TO `Impl`,\n  FROM `Constructor` TO `Namespace`,\n  FROM `Constructor` TO `Module`,\n  FROM `Constructor` TO `Property`,\n  FROM `Constructor` TO `Typedef`,\n  FROM `Template` TO Community,\n  FROM `Module` TO Community,\n  FROM Function TO Process,\n  FROM Method TO Process,\n  FROM Class TO Process,\n  FROM Interface TO Process,\n  FROM `Struct` TO Process,\n  FROM `Constructor` TO Process,\n  FROM `Module` TO Process,\n  FROM `Macro` TO Process,\n  FROM `Impl` TO Process,\n  FROM `Typedef` TO Process,\n  FROM `TypeAlias` TO Process,\n  FROM `Enum` TO Process,\n  FROM `Union` TO Process,\n  FROM `Namespace` TO Process,\n  FROM `Trait` TO Process,\n  FROM `Const` TO Process,\n  FROM `Static` TO Process,\n  FROM `Property` TO Process,\n  FROM `Record` TO Process,\n  FROM `Delegate` TO Process,\n  FROM `Annotation` TO Process,\n  FROM `Template` TO Process,\n  FROM CodeElement TO Process,\n  FROM Route TO Process,\n  FROM Tool TO Process,\n  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\n)";
+export declare const EMBEDDING_DIMS: number;
+export declare const EMBEDDING_SCHEMA: string;
 /**
  * Create vector index for semantic search
  * Uses HNSW (Hierarchical Navigable Small World) algorithm with cosine similarity

package/dist/core/lbug/schema.js

@@ -12,17 +12,20 @@
 // NODE TABLE NAMES
 // ============================================================================
 export const NODE_TABLES = [
-    'File', 'Folder', 'Function', 'Class', 'Interface', 'Method', 'CodeElement', 'Community', 'Process',
+    'File', 'Folder', 'Function', 'Class', 'Interface', 'Method', 'CodeElement', 'Community', 'Process', 'Section',
     // Multi-language support
     'Struct', 'Enum', 'Macro', 'Typedef', 'Union', 'Namespace', 'Trait', 'Impl',
-    'TypeAlias', 'Const', 'Static', 'Property', 'Record', 'Delegate', 'Annotation', 'Constructor', 'Template', 'Module'
+    'TypeAlias', 'Const', 'Static', 'Property', 'Record', 'Delegate', 'Annotation', 'Constructor', 'Template', 'Module',
+    'Route',
+    'Tool'
 ];
 // ============================================================================
 // RELATION TABLE
 // ============================================================================
 export const REL_TABLE_NAME = 'CodeRelation';
 // Valid relation types
-export const REL_TYPES = ['CONTAINS', 'DEFINES', 'IMPORTS', 'CALLS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'HAS_PROPERTY', 'ACCESSES', 'OVERRIDES', 'MEMBER_OF', 'STEP_IN_PROCESS'];
+// Note: WRAPS is reserved for future middleware graph traversal (not yet emitted)
+export const REL_TYPES = ['CONTAINS', 'DEFINES', 'IMPORTS', 'CALLS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'HAS_PROPERTY', 'ACCESSES', 'OVERRIDES', 'MEMBER_OF', 'STEP_IN_PROCESS', 'HANDLES_ROUTE', 'FETCHES', 'HANDLES_TOOL', 'ENTRY_POINT_OF', 'WRAPS', 'QUERIES'];
 // ============================================================================
 // EMBEDDING TABLE
 // ============================================================================
@@ -171,6 +174,39 @@ export const ANNOTATION_SCHEMA = CODE_ELEMENT_BASE('Annotation');
 export const CONSTRUCTOR_SCHEMA = CODE_ELEMENT_BASE('Constructor');
 export const TEMPLATE_SCHEMA = CODE_ELEMENT_BASE('Template');
 export const MODULE_SCHEMA = CODE_ELEMENT_BASE('Module');
+// API route endpoints (Next.js, Express, etc.)
+export const ROUTE_SCHEMA = `
+CREATE NODE TABLE Route (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  responseKeys STRING[],
+  errorKeys STRING[],
+  middleware STRING[],
+  PRIMARY KEY (id)
+)`;
+// MCP tool definitions
+export const TOOL_SCHEMA = `
+CREATE NODE TABLE Tool (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  description STRING,
+  PRIMARY KEY (id)
+)`;
+// Markdown heading sections
+export const SECTION_SCHEMA = `
+CREATE NODE TABLE Section (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  startLine INT64,
+  endLine INT64,
+  level INT64,
+  content STRING,
+  description STRING,
+  PRIMARY KEY (id)
+)`;
 // ============================================================================
 // RELATION TABLE SCHEMA
 // Single table with 'type' property - connects all node tables
@@ -202,6 +238,7 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM File TO \`Constructor\`,
   FROM File TO \`Template\`,
   FROM File TO \`Module\`,
+  FROM File TO Section,
   FROM Folder TO Folder,
   FROM Folder TO File,
   FROM Function TO Function,
@@ -222,6 +259,7 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM Function TO \`Typedef\`,
   FROM Function TO \`Union\`,
   FROM Function TO \`Property\`,
+  FROM Function TO CodeElement,
   FROM Class TO Method,
   FROM Class TO Function,
   FROM Class TO Class,
@@ -255,6 +293,7 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM Method TO Interface,
   FROM Method TO \`Constructor\`,
   FROM Method TO \`Property\`,
+  FROM Method TO CodeElement,
   FROM \`Template\` TO \`Template\`,
   FROM \`Template\` TO Function,
   FROM \`Template\` TO Method,
@@ -266,6 +305,14 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM \`Template\` TO Interface,
   FROM \`Template\` TO \`Constructor\`,
   FROM \`Module\` TO \`Module\`,
+  FROM Section TO Section,
+  FROM Section TO File,
+  FROM File TO Route,
+  FROM Function TO Route,
+  FROM Method TO Route,
+  FROM File TO Tool,
+  FROM Function TO Tool,
+  FROM Method TO Tool,
   FROM CodeElement TO Community,
   FROM Interface TO Community,
   FROM Interface TO Function,
@@ -364,6 +411,8 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM \`Annotation\` TO Process,
   FROM \`Template\` TO Process,
   FROM CodeElement TO Process,
+  FROM Route TO Process,
+  FROM Tool TO Process,
   type STRING,
   confidence DOUBLE,
   reason STRING,
@@ -373,10 +422,16 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
 // EMBEDDING TABLE SCHEMA
 // Separate table for vector storage to avoid copy-on-write overhead
 // ============================================================================
+/** Embedding vector dimensions. Default 384 (snowflake-arctic-embed-xs). */
+const _rawDims = parseInt(process.env.GITNEXUS_EMBEDDING_DIMS ?? '384', 10);
+if (Number.isNaN(_rawDims) || _rawDims <= 0) {
+    throw new Error(`GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${process.env.GITNEXUS_EMBEDDING_DIMS}"`);
+}
+export const EMBEDDING_DIMS = _rawDims;
 export const EMBEDDING_SCHEMA = `
 CREATE NODE TABLE ${EMBEDDING_TABLE_NAME} (
   nodeId STRING,
-  embedding FLOAT[384],
+  embedding FLOAT[${EMBEDDING_DIMS}],
   PRIMARY KEY (nodeId)
 )`;
 /**
@@ -419,6 +474,12 @@ export const NODE_SCHEMA_QUERIES = [
     CONSTRUCTOR_SCHEMA,
     TEMPLATE_SCHEMA,
     MODULE_SCHEMA,
+    // Markdown support
+    SECTION_SCHEMA,
+    // API routes
+    ROUTE_SCHEMA,
+    // MCP tools
+    TOOL_SCHEMA,
 ];
 export const REL_SCHEMA_QUERIES = [
     RELATION_SCHEMA,

package/dist/core/tree-sitter/parser-loader.js

@@ -12,13 +12,18 @@ import PHP from 'tree-sitter-php';
 import Ruby from 'tree-sitter-ruby';
 import { createRequire } from 'node:module';
 import { SupportedLanguages } from '../../config/supported-languages.js';
-// tree-sitter-swift is an optionalDependency — may not be installed
+// tree-sitter-swift and tree-sitter-dart are optionalDependencies — may not be installed
 const _require = createRequire(import.meta.url);
 let Swift = null;
 try {
     Swift = _require('tree-sitter-swift');
 }
 catch { }
+let Dart = null;
+try {
+    Dart = _require('tree-sitter-dart');
+}
+catch { }
 // tree-sitter-kotlin is an optionalDependency — may not be installed
 let Kotlin = null;
 try {
@@ -40,6 +45,7 @@ const languageMap = {
     ...(Kotlin ? { [SupportedLanguages.Kotlin]: Kotlin } : {}),
     [SupportedLanguages.PHP]: PHP.php_only,
     [SupportedLanguages.Ruby]: Ruby,
+    ...(Dart ? { [SupportedLanguages.Dart]: Dart } : {}),
     ...(Swift ? { [SupportedLanguages.Swift]: Swift } : {}),
 };
 export const isLanguageAvailable = (language) => language in languageMap;

package/dist/core/wiki/cursor-client.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Cursor CLI Client for Wiki Generation
+ *
+ * Wrapper for the Cursor headless CLI (`agent` command).
+ * Uses print mode for non-interactive LLM calls.
+ *
+ * Docs: https://cursor.com/docs/cli/headless
+ */
+import type { LLMResponse, CallLLMOptions } from './llm-client.js';
+export interface CursorConfig {
+    model?: string;
+    workingDirectory?: string;
+}
+/**
+ * Detect if Cursor CLI is available in PATH.
+ * Returns the binary name if found ('agent'), null otherwise.
+ * Result is cached after the first call.
+ */
+export declare function detectCursorCLI(): string | null;
+/**
+ * Resolve Cursor CLI configuration.
+ * Model is optional - if not provided, Cursor CLI uses its default (auto).
+ */
+export declare function resolveCursorConfig(overrides?: Partial<CursorConfig>): CursorConfig;
+/**
+ * Call the Cursor CLI in print mode.
+ *
+ * Uses `agent -p --output-format text` for clean non-streaming output.
+ * The prompt is passed as the final CLI argument.
+ */
+export declare function callCursorLLM(prompt: string, config: CursorConfig, systemPrompt?: string, options?: CallLLMOptions): Promise<LLMResponse>;

package/dist/core/wiki/cursor-client.js

@@ -0,0 +1,127 @@
+/**
+ * Cursor CLI Client for Wiki Generation
+ *
+ * Wrapper for the Cursor headless CLI (`agent` command).
+ * Uses print mode for non-interactive LLM calls.
+ *
+ * Docs: https://cursor.com/docs/cli/headless
+ */
+import { spawn, execSync } from 'child_process';
+function isVerbose() {
+    return process.env.GITNEXUS_VERBOSE === '1';
+}
+function verboseLog(...args) {
+    if (isVerbose()) {
+        console.log('[cursor-cli]', ...args);
+    }
+}
+let cachedCursorBin;
+/**
+ * Detect if Cursor CLI is available in PATH.
+ * Returns the binary name if found ('agent'), null otherwise.
+ * Result is cached after the first call.
+ */
+export function detectCursorCLI() {
+    if (cachedCursorBin !== undefined)
+        return cachedCursorBin;
+    try {
+        execSync('agent --version', { stdio: 'ignore' });
+        cachedCursorBin = 'agent';
+    }
+    catch {
+        cachedCursorBin = null;
+    }
+    return cachedCursorBin;
+}
+/**
+ * Resolve Cursor CLI configuration.
+ * Model is optional - if not provided, Cursor CLI uses its default (auto).
+ */
+export function resolveCursorConfig(overrides) {
+    return {
+        model: overrides?.model,
+        workingDirectory: overrides?.workingDirectory,
+    };
+}
+/**
+ * Call the Cursor CLI in print mode.
+ *
+ * Uses `agent -p --output-format text` for clean non-streaming output.
+ * The prompt is passed as the final CLI argument.
+ */
+export async function callCursorLLM(prompt, config, systemPrompt, options) {
+    const cursorBin = detectCursorCLI();
+    if (!cursorBin) {
+        throw new Error('Cursor CLI not found. Install it from https://cursor.com/docs/cli/installation');
+    }
+    // Always use text format to get clean output without agent narration/thinking.
+    // stream-json captures assistant messages which include "Let me explore..." narration
+    // that pollutes the actual content when using thinking models.
+    const fullPrompt = systemPrompt
+        ? `${systemPrompt}\n\n---\n\n${prompt}`
+        : prompt;
+    const args = [
+        '-p',
+        '--output-format', 'text',
+    ];
+    if (config.model) {
+        args.push('--model', config.model);
+    }
+    // Add the prompt as the final argument
+    args.push(fullPrompt);
+    verboseLog('Spawning:', cursorBin, args.slice(0, -1).join(' '), '[prompt length:', fullPrompt.length, 'chars]');
+    verboseLog('Working directory:', config.workingDirectory || process.cwd());
+    if (config.model) {
+        verboseLog('Model:', config.model);
+    }
+    else {
+        verboseLog('Model: auto (default)');
+    }
+    const startTime = Date.now();
+    return new Promise((resolve, reject) => {
+        const child = spawn(cursorBin, args, {
+            cwd: config.workingDirectory || process.cwd(),
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: {
+                ...process.env,
+                // Ensure non-interactive mode
+                CI: '1',
+            },
+        });
+        verboseLog('Process spawned with PID:', child.pid);
+        let stdout = '';
+        let stderr = '';
+        // Text mode - collect all output, report progress based on output size
+        child.stdout.on('data', (chunk) => {
+            const chunkStr = chunk.toString();
+            stdout += chunkStr;
+            verboseLog(`[stdout] received ${chunkStr.length} chars, total: ${stdout.length}`);
+            // Report progress if callback provided
+            if (options?.onChunk) {
+                options.onChunk(stdout.length);
+            }
+        });
+        child.on('close', (code) => {
+            const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+            verboseLog(`Process exited with code ${code} after ${elapsed}s`);
+            verboseLog(`stdout length: ${stdout.length} chars`);
+            if (code !== 0) {
+                verboseLog('stderr:', stderr);
+                reject(new Error(`Cursor CLI exited with code ${code}: ${stderr}`));
+                return;
+            }
+            resolve({ content: stdout.trim() });
+        });
+        child.stderr.on('data', (chunk) => {
+            const chunkStr = chunk.toString();
+            stderr += chunkStr;
+            verboseLog('[stderr]', chunkStr.trim());
+        });
+        child.on('error', (err) => {
+            verboseLog('Spawn error:', err.message);
+            reject(new Error(`Failed to spawn Cursor CLI: ${err.message}`));
+        });
+        // Close stdin immediately since we pass prompt as argument
+        child.stdin.end();
+    });
+}