@codragraph/cli 1.6.3 → 1.6.4

package/README.md

@@ -18,12 +18,12 @@ AI coding tools don't understand your codebase structure. They edit a function w
 
 ```bash
 # Index your repo (run from repo root)
-npx codragraph analyze
+npx @codragraph/cli analyze
 ```
 
 That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command.
 
-To configure MCP for your editor, run `npx codragraph setup` once — or set it up manually below.
+To configure MCP for your editor, run `npx @codragraph/cli setup` once — or set it up manually below.
 
 `codragraph setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
 
@@ -53,16 +53,16 @@ If you prefer to configure manually instead of using `codragraph setup`:
 
 ```bash
 # macOS / Linux
-claude mcp add codragraph -- npx -y codragraph@latest mcp
+claude mcp add codragraph -- npx -y @codragraph/cli@latest mcp
 
 # Windows
-claude mcp add codragraph -- cmd /c npx -y codragraph@latest mcp
+claude mcp add codragraph -- cmd /c npx -y @codragraph/cli@latest mcp
 ```
 
 ### Codex (full support — MCP + skills)
 
 ```bash
-codex mcp add codragraph -- npx -y codragraph@latest mcp
+codex mcp add codragraph -- npx -y @codragraph/cli@latest mcp
 ```
 
 ### Cursor / Windsurf
@@ -74,7 +74,7 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
   "mcpServers": {
     "codragraph": {
       "command": "npx",
-      "args": ["-y", "codragraph@latest", "mcp"]
+      "args": ["-y", "@codragraph/cli@latest", "mcp"]
     }
   }
 }
@@ -89,7 +89,7 @@ Add to `~/.config/opencode/config.json`:
   "mcp": {
     "codragraph": {
       "command": "npx",
-      "args": ["-y", "codragraph@latest", "mcp"]
+      "args": ["-y", "@codragraph/cli@latest", "mcp"]
     }
   }
 }
@@ -244,9 +244,9 @@ merges are skipped.)
 
 ```bash
 # Try the latest release candidate (pre-stable — may change at any time)
-npm install -g codragraph@rc
+npm install -g @codragraph/cli@rc
 # — or —
-npx codragraph@rc analyze
+npx @codragraph/cli@rc analyze
 ```
 
 Release-candidate versions follow the standard semver prerelease format
@@ -265,9 +265,9 @@ certain npm/arborist versions ([npm/cli#8126](https://github.com/npm/cli/issues/
 It is fixed in **codragraph v1.6.2+**. Upgrade to the latest version:
 
 ```bash
-npx codragraph@latest analyze          # always uses the newest release
+npx @codragraph/cli@latest analyze          # always uses the newest release
 # — or —
-npm install -g codragraph@latest       # upgrade a global install
+npm install -g @codragraph/cli@latest       # upgrade a global install
 ```
 
 If you still hit npm install issues after upgrading, these generic workarounds
@@ -282,7 +282,7 @@ npm cache clean --force              # clear a possibly corrupt cache
 
 Some optional language grammars (Dart, Kotlin, Swift) require native compilation. If they fail, CodraGraph still works — those languages will be skipped.
 
-If `npm install -g codragraph` fails on native modules:
+If `npm install -g @codragraph/cli` fails on native modules:
 
 ```bash
 # Ensure build tools are available (Linux/macOS)
@@ -290,7 +290,7 @@ If `npm install -g codragraph` fails on native modules:
 # macOS: xcode-select --install
 
 # Retry installation
-npm install -g codragraph
+npm install -g @codragraph/cli
 ```
 
 ### Analysis runs out of memory
@@ -299,7 +299,7 @@ For very large repositories:
 
 ```bash
 # Increase Node.js heap size
-NODE_OPTIONS="--max-old-space-size=16384" npx codragraph analyze
+NODE_OPTIONS="--max-old-space-size=16384" npx @codragraph/cli analyze
 
 # Exclude large directories
 echo "vendor/" >> .codragraphignore
@@ -312,11 +312,11 @@ By default the walker skips files larger than **512 KB** (see log line `Skipped
 
 ```bash
 # CLI flag (takes precedence over the env var)
-npx codragraph analyze --max-file-size 2048     # skip only files > 2 MB
+npx @codragraph/cli analyze --max-file-size 2048     # skip only files > 2 MB
 
 # Environment variable (persists across commands)
 export CODRAGRAPH_MAX_FILE_SIZE=2048
-npx codragraph analyze
+npx @codragraph/cli analyze
 ```
 
 Values above **32768 KB (32 MB)** are clamped to the tree-sitter parser ceiling; invalid values fall back to the 512 KB default with a one-time warning. When an override is active, `analyze` prints the effective threshold in its startup banner (e.g. `CODRAGRAPH_MAX_FILE_SIZE: effective threshold 2048KB (default 512KB)`).

package/dist/cli/ai-context.js

@@ -86,7 +86,7 @@ function generateCodraGraphContent(projectName, stats, generatedSkills, groupNam
 
 This project is indexed by CodraGraph as **${projectName}**${noStats ? '' : ` (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows)`}. Use the CodraGraph MCP tools to understand code, assess impact, and navigate safely.
 
-> If any CodraGraph tool warns the index is stale, run \`npx codragraph analyze\` in terminal first.
+> If any CodraGraph tool warns the index is stale, run \`npx @codragraph/cli analyze\` in terminal first.
 
 ## Always Do
 
@@ -115,7 +115,7 @@ This project is indexed by CodraGraph as **${projectName}**${noStats ? '' : ` ($
 ${groupNames && groupNames.length > 0
         ? `## Cross-Repo Groups
 
-This repository is listed under CodraGraph **group(s): ${groupNames.join(', ')}** (see \`~/.codragraph/groups/\`). For cross-repo analysis, use MCP tools \`impact\`, \`query\`, and \`context\` with \`repo\` set to \`@<groupName>\` or \`@<groupName>/<memberPath>\` (paths match keys in that group’s \`group.yaml\`). Use \`group_list\` / \`group_sync\` for membership and sync. From the terminal: \`npx codragraph group list\`, \`npx codragraph group sync <name>\`, \`npx codragraph group impact <name> --target <symbol> --repo <group-path>\`.
+This repository is listed under CodraGraph **group(s): ${groupNames.join(', ')}** (see \`~/.codragraph/groups/\`). For cross-repo analysis, use MCP tools \`impact\`, \`query\`, and \`context\` with \`repo\` set to \`@<groupName>\` or \`@<groupName>/<memberPath>\` (paths match keys in that group’s \`group.yaml\`). Use \`group_list\` / \`group_sync\` for membership and sync. From the terminal: \`npx @codragraph/cli group list\`, \`npx @codragraph/cli group sync <name>\`, \`npx @codragraph/cli group impact <name> --target <symbol> --repo <group-path>\`.
 
 `
         : ''}## CLI

package/dist/cli/analyze.js

@@ -289,8 +289,8 @@ export const analyzeCommand = async (inputPath, options) => {
             console.error('  Suggestions:');
             console.error('    1. Clear the npm cache:    npm cache clean --force');
             console.error('    2. Update npm:             npm install -g npm@latest');
-            console.error('    3. Reinstall codragraph:     npm install -g codragraph@latest');
-            console.error('    4. Or try npx directly:    npx codragraph@latest analyze');
+            console.error('    3. Reinstall codragraph:     npm install -g @codragraph/cli@latest');
+            console.error('    4. Or try npx directly:    npx @codragraph/cli@latest analyze');
             console.error('');
         }
         else if (msg.includes('MODULE_NOT_FOUND') ||
@@ -298,8 +298,8 @@ export const analyzeCommand = async (inputPath, options) => {
             msg.includes('ERR_MODULE_NOT_FOUND')) {
             console.error('  A required module could not be loaded. The installation may be corrupt.');
             console.error('  Suggestions:');
-            console.error('    1. Reinstall:   npm install -g codragraph@latest');
-            console.error('    2. Clear cache: npm cache clean --force && npx codragraph@latest analyze');
+            console.error('    1. Reinstall:   npm install -g @codragraph/cli@latest');
+            console.error('    2. Clear cache: npm cache clean --force && npx @codragraph/cli@latest analyze');
             console.error('');
         }
         process.exitCode = 1;

package/dist/cli/index.js

@@ -8,10 +8,7 @@ import { registerGroupCommands } from './group.js';
 const _require = createRequire(import.meta.url);
 const pkg = _require('../../package.json');
 const program = new Command();
-program
-    .name('codragraph')
-    .description('CodraGraph local CLI and MCP server')
-    .version(pkg.version);
+program.name('codragraph').description('CodraGraph local CLI and MCP server').version(pkg.version);
 program
     .command('setup')
     .description('One-time setup: configure MCP for Cursor, Claude Code, OpenCode, Codex')

package/dist/cli/setup.js

@@ -18,20 +18,38 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const execFileAsync = promisify(execFile);
 /**
- * Resolve the absolute path to the `@codragraph/cli` binary if it's installed
+ * Resolve the absolute path to the `codragraph` binary if it's installed
  * globally (or via npm -g / yarn global). Returns null when not found.
+ *
+ * Note: the npm package is `@codragraph/cli`, but the executable it installs
+ * is `codragraph` (see package.json `bin`). PATH lookup must use the bin name.
+ *
+ * Windows specifics: `where codragraph` returns every PATH entry, in order:
+ * the extensionless Unix shim npm creates first (a sh script — Node's
+ * spawn/execFile cannot launch it on Windows), then `codragraph.cmd`,
+ * then `codragraph.ps1`. We must pick the .cmd / .exe / .bat entry; writing
+ * the extensionless path into a downstream MCP config produces a launcher
+ * that fails on every spawn.
  */
 function resolveCodragraphBin() {
     try {
         const cmd = process.platform === 'win32' ? 'where' : 'which';
-        const resolved = execFileSync(cmd, ['@codragraph/cli'], {
+        const stdout = execFileSync(cmd, ['codragraph'], {
             encoding: 'utf-8',
             timeout: 5000,
             stdio: ['ignore', 'pipe', 'ignore'],
-        })
-            .split('\n')[0]
-            .trim();
-        return resolved || null;
+        });
+        const lines = stdout
+            .split('\n')
+            .map((l) => l.trim())
+            .filter(Boolean);
+        if (process.platform === 'win32') {
+            // Prefer a Windows-executable shim. If none is on PATH, return null so
+            // the caller falls through to the `cmd /c npx -y @codragraph/cli` path.
+            const exe = lines.find((l) => /\.(cmd|exe|bat)$/i.test(l));
+            return exe ?? null;
+        }
+        return lines[0] ?? null;
     }
     catch {
         return null;
@@ -40,28 +58,38 @@ function resolveCodragraphBin() {
 /**
  * The MCP server entry for all editors.
  *
- * Prefers the globally-installed `@codragraph/cli` binary (starts in ~1 s) over
- * `npx -y codragraph@latest` (cold-cache install of native deps can take
+ * Prefers the globally-installed `codragraph` binary (starts in ~1 s) over
+ * `npx -y @codragraph/cli@latest` (cold-cache install of native deps can take
  * >60 s, exceeding Claude Code's 30 s MCP connection timeout).
  *
  * Falls back to npx when the binary isn't on PATH — e.g. first-time
- * users who ran `npx codragraph analyze` but haven't done `npm i -g`.
+ * users who ran `npx @codragraph/cli analyze` but haven't done `npm i -g`.
+ *
+ * Windows note: even when the bin is on PATH, we launch via `cmd /c codragraph
+ * mcp` rather than writing the resolved path. Reason: `where codragraph`
+ * returns the extensionless Unix shim before `codragraph.cmd`, and Node's
+ * spawn/execFile cannot launch the extensionless shim on Windows. Letting
+ * cmd resolve via PATHEXT is the only reliable path that works for npm-,
+ * pnpm-, and yarn-installed shims alike.
  */
 function getMcpEntry() {
     const bin = resolveCodragraphBin();
     if (bin) {
+        if (process.platform === 'win32') {
+            return { command: 'cmd', args: ['/c', 'codragraph', 'mcp'] };
+        }
         return { command: bin, args: ['mcp'] };
     }
     // Fallback: npx (works without a global install, but slow cold-start)
     if (process.platform === 'win32') {
         return {
             command: 'cmd',
-            args: ['/c', 'npx', '-y', 'codragraph@latest', 'mcp'],
+            args: ['/c', 'npx', '-y', '@codragraph/cli@latest', 'mcp'],
         };
     }
     return {
         command: 'npx',
-        args: ['-y', 'codragraph@latest', 'mcp'],
+        args: ['-y', '@codragraph/cli@latest', 'mcp'],
     };
 }
 /**
@@ -71,12 +99,18 @@ function getMcpEntry() {
 function getOpenCodeMcpEntry() {
     const bin = resolveCodragraphBin();
     if (bin) {
+        if (process.platform === 'win32') {
+            return { type: 'local', command: ['cmd', '/c', 'codragraph', 'mcp'] };
+        }
         return { type: 'local', command: [bin, 'mcp'] };
     }
     if (process.platform === 'win32') {
-        return { type: 'local', command: ['cmd', '/c', 'npx', '-y', 'codragraph@latest', 'mcp'] };
+        return {
+            type: 'local',
+            command: ['cmd', '/c', 'npx', '-y', '@codragraph/cli@latest', 'mcp'],
+        };
     }
-    return { type: 'local', command: ['npx', '-y', 'codragraph@latest', 'mcp'] };
+    return { type: 'local', command: ['npx', '-y', '@codragraph/cli@latest', 'mcp'] };
 }
 /**
  * Merge codragraph entry into an existing MCP config JSON object.
@@ -239,7 +273,7 @@ async function installClaudeCodeHooks(result) {
     // Source hooks bundled within the codragraph package (hooks/claude/)
     const pluginHooksPath = path.join(__dirname, '..', '..', 'hooks', 'claude');
     // Copy unified hook script to ~/.claude/hooks/codragraph/
-    const destHooksDir = path.join(claudeDir, 'hooks', '@codragraph/cli');
+    const destHooksDir = path.join(claudeDir, 'hooks', 'codragraph');
     try {
         await fs.mkdir(destHooksDir, { recursive: true });
         const src = path.join(pluginHooksPath, 'codragraph-hook.cjs');
@@ -291,7 +325,7 @@ async function setupOpenCode(result) {
     }
     const configPath = path.join(opencodeDir, 'opencode.json');
     try {
-        const ok = await mergeJsoncFile(configPath, ['mcp', '@codragraph/cli'], getOpenCodeMcpEntry());
+        const ok = await mergeJsoncFile(configPath, ['mcp', 'codragraph'], getOpenCodeMcpEntry());
         if (ok) {
             result.configured.push('OpenCode');
         }
@@ -339,9 +373,10 @@ async function setupCodex(result) {
     }
     try {
         const entry = getMcpEntry();
-        await execFileAsync('codex', ['mcp', 'add', '@codragraph/cli', '--', entry.command, ...entry.args], {
-            shell: process.platform === 'win32',
-        });
+        // On Windows, npm-installed CLIs ship as .cmd shims that Node's execFile
+        // can only invoke when the file extension is explicit (no PATHEXT lookup).
+        const codexBin = process.platform === 'win32' ? 'codex.cmd' : 'codex';
+        await execFileAsync(codexBin, ['mcp', 'add', 'codragraph', '--', entry.command, ...entry.args]);
         result.configured.push('Codex');
         return;
     }

package/dist/cli/skill-gen.js

@@ -103,7 +103,7 @@ export const generateSkillFiles = async (repoPath, projectName, pipelineResult)
  * @param {string} repoPath - Repository root for path normalization
  * @returns {CommunityNode[]} Synthetic community nodes built from membership data
  */
-const buildCommunitiesFromMemberships = (memberships, graph, repoPath) => {
+const buildCommunitiesFromMemberships = (memberships, graph, _repoPath) => {
     // Group memberships by communityId
     const groups = new Map();
     for (const m of memberships) {

package/dist/config/ignore-service.js

@@ -285,7 +285,7 @@ export const shouldIgnorePath = (filePath) => {
     // Ignore hidden files (starting with .)
     if (fileName.startsWith('.') && fileName !== '.') {
         // But allow some important config files
-        const allowedDotFiles = ['.env', '.gitignore']; // Already in IGNORED_FILES, so this is redundant
+        const _allowedDotFiles = ['.env', '.gitignore']; // Already in IGNORED_FILES, so this is redundant
         // Actually, let's NOT ignore all dot files - many are important configs
         // Just rely on the explicit lists above
     }

package/dist/core/group/extractors/grpc-patterns/proto.js

@@ -31,7 +31,6 @@ if (ProtoGrammar) {
         // test runners (vitest forks) when SyntaxNode isn't fully initialized
         // yet. Catching that here ensures `PROTO_GRPC_PLUGIN` stays null and
         // the orchestrator falls back to the manual parser.
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const _Parser = _require('tree-sitter');
         // Smoke-test: parse + setLanguage to verify the grammar is
         // end-to-end compatible with this tree-sitter runtime.
@@ -72,24 +71,14 @@ if (ProtoGrammar) {
     }
 }
 function buildPlugin() {
-    if (!ProtoGrammar || !PACKAGE_PATTERNS || !SERVICE_PATTERNS)
+    if (!ProtoGrammar || !SERVICE_PATTERNS)
         return null;
-    const pkgPatterns = PACKAGE_PATTERNS;
     const svcPatterns = SERVICE_PATTERNS;
     return {
         name: 'proto-grpc',
         language: ProtoGrammar,
         scan(tree) {
             const out = [];
-            // Extract `package` declaration (first match wins).
-            let pkg = '';
-            for (const match of runCompiledPatterns(pkgPatterns, tree)) {
-                const pkgNode = match.captures.pkg;
-                if (pkgNode) {
-                    pkg = pkgNode.text;
-                    break;
-                }
-            }
             // Extract `service → rpc` pairs. The query returns one match per
             // (service, rpc) combination thanks to the nested structure.
             for (const match of runCompiledPatterns(svcPatterns, tree)) {

package/dist/core/ingestion/call-processor.js

@@ -616,7 +616,7 @@ importedRawReturnTypesMap, heritageMap, bindingAccumulator) => {
                     bufferSize: getTreeSitterBufferSize(file.content.length),
                 });
             }
-            catch (parseError) {
+            catch (_parseError) {
                 continue;
             }
             astCache.set(file.path, tree);
@@ -704,7 +704,7 @@ importedRawReturnTypesMap, heritageMap, bindingAccumulator) => {
     // loop above, so verifyConstructorBindings sees all provider bindings
     // regardless of file processing order.
     for (let i = 0; i < prepared.length; i++) {
-        const { file, language, provider, tree, matches, parentMap, typeEnv } = prepared[i];
+        const { file, language, provider, tree: _tree, matches, parentMap, typeEnv } = prepared[i];
         enclosingFnExtractCache.clear();
         onProgress?.(i + 1, files.length);
         if (i % 20 === 0)

package/dist/core/ingestion/cobol/cobol-preprocessor.js

@@ -1404,7 +1404,7 @@ export function extractCobolSymbolsWithRegex(content, _filePath) {
         if (anonRedefMatch) {
             // Check it's truly anonymous: the second capture is not a valid data name
             // followed by more clauses — it's the REDEFINES target directly after level
-            const level = parseInt(anonRedefMatch[1], 10);
+            const _level = parseInt(anonRedefMatch[1], 10);
             // Only skip if this is genuinely "NN REDEFINES target" with no name between
             // We detect this by checking the full data item regex does NOT match
             // (because RE_DATA_ITEM expects a name before any clauses)

package/dist/core/ingestion/cobol/jcl-parser.d.ts

@@ -65,4 +65,4 @@ export interface JclParseResults {
  * @param filePath - Path for diagnostics (not used in extraction)
  * @returns Parsed JCL results
  */
-export declare function parseJcl(content: string, filePath: string): JclParseResults;
+export declare function parseJcl(content: string, _filePath: string): JclParseResults;

package/dist/core/ingestion/cobol/jcl-parser.js

@@ -73,7 +73,7 @@ function extractDisp(params) {
  * @param filePath - Path for diagnostics (not used in extraction)
  * @returns Parsed JCL results
  */
-export function parseJcl(content, filePath) {
+export function parseJcl(content, _filePath) {
     const results = {
         jobs: [],
         steps: [],

package/dist/core/ingestion/cobol-processor.d.ts

@@ -50,5 +50,5 @@ export declare function isJclFile(filePath: string): boolean;
  * @param allPathSet - Set of all file paths in the repository
  * @returns Summary of what was extracted
  */
-export declare const processCobol: (graph: KnowledgeGraph, files: CobolFile[], allPathSet: ReadonlySet<string>) => CobolProcessResult;
+export declare const processCobol: (graph: KnowledgeGraph, files: CobolFile[], _allPathSet: ReadonlySet<string>) => CobolProcessResult;
 export {};

package/dist/core/ingestion/cobol-processor.js

@@ -47,7 +47,7 @@ function isCopybook(filePath) {
  * @param allPathSet - Set of all file paths in the repository
  * @returns Summary of what was extracted
  */
-export const processCobol = (graph, files, allPathSet) => {
+export const processCobol = (graph, files, _allPathSet) => {
     const result = {
         programs: 0,
         paragraphs: 0,

package/dist/core/ingestion/heritage-extractors/generic.js

@@ -12,7 +12,7 @@ export function createHeritageExtractor(config) {
     const callNameSet = actualConfig.callBasedHeritage?.callNames;
     return {
         language: actualConfig.language,
-        extract(captureMap, context) {
+        extract(captureMap, _context) {
             const classNode = captureMap['heritage.class'];
             if (!classNode)
                 return [];

package/dist/core/ingestion/heritage-processor.js

@@ -151,7 +151,7 @@ export const processHeritage = async (graph, files, astCache, ctx, onProgress) =
                     bufferSize: getTreeSitterBufferSize(file.content.length),
                 });
             }
-            catch (parseError) {
+            catch (_parseError) {
                 // Skip files that can't be parsed
                 continue;
             }

package/dist/core/ingestion/import-processor.js

@@ -245,7 +245,7 @@ export const processImports = async (graph, files, astCache, ctx, onProgress, re
                     bufferSize: getTreeSitterBufferSize(file.content.length),
                 });
             }
-            catch (parseError) {
+            catch (_parseError) {
                 continue;
             }
             wasReparsed = true;

package/dist/core/ingestion/mro-processor.js

@@ -316,7 +316,7 @@ function parameterTypesMatch(a, b, aParamCount, bParamCount) {
  */
 function emitMethodImplementsEdges(graph, parentMap, methodMap, parentEdgeType, ancestorsMap, edgeTypesMap) {
     let edgeCount = 0;
-    for (const [classId, parentIds] of parentMap) {
+    for (const [classId, _parentIds] of parentMap) {
         const classNode = graph.getNode(classId);
         if (!classNode)
             continue;

package/dist/core/ingestion/parsing-processor.js

@@ -273,7 +273,7 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, sco
                 bufferSize: getTreeSitterBufferSize(parseContent.length),
             });
         }
-        catch (parseError) {
+        catch (_parseError) {
             console.warn(`Skipping unparseable file: ${file.path}`);
             continue;
         }

package/dist/core/ingestion/type-extractors/c-cpp.js

@@ -479,7 +479,7 @@ const inferLiteralType = (node) => {
 };
 /** C++: detect constructor type from smart pointer factory calls (make_shared<Dog>()).
  *  Extracts the template type argument as the constructor type for virtual dispatch. */
-const detectCppConstructorType = (node, classNames) => {
+const detectCppConstructorType = (node, _classNames) => {
     // Navigate to the initializer value in the declaration
     const declarator = node.childForFieldName('declarator');
     const initDecl = declarator?.type === 'init_declarator' ? declarator : undefined;

package/dist/core/ingestion/type-extractors/python.js

@@ -149,7 +149,7 @@ const scanConstructorBinding = (node) => {
 };
 const FOR_LOOP_NODE_TYPES = new Set(['for_statement']);
 /** Python function/method node types that carry a parameters list. */
-const PY_FUNCTION_NODE_TYPES = new Set(['function_definition', 'decorated_definition']);
+const _PY_FUNCTION_NODE_TYPES = new Set(['function_definition', 'decorated_definition']);
 /**
  * Extract element type from a Python type annotation AST node.
  * Handles:

package/dist/core/ingestion/type-extractors/shared.js

@@ -564,16 +564,13 @@ export function extractElementTypeFromString(typeStr, pos = 'last') {
     const openAngle = typeStr.indexOf('<');
     const openSquare = typeStr.indexOf('[');
     let openIdx = -1;
-    let openChar = '';
     let closeChar = '';
     if (openAngle >= 0 && (openSquare < 0 || openAngle < openSquare)) {
         openIdx = openAngle;
-        openChar = '<';
         closeChar = '>';
     }
     else if (openSquare >= 0) {
         openIdx = openSquare;
-        openChar = '[';
         closeChar = ']';
     }
     if (openIdx < 0)

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

@@ -322,7 +322,7 @@ export const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress)
         try {
             await conn.query(copyQuery);
         }
-        catch (err) {
+        catch (_err) {
             try {
                 const retryQuery = copyQuery.replace('auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)');
                 await conn.query(retryQuery);
@@ -360,7 +360,7 @@ export const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress)
             try {
                 await conn.query(copyQuery);
             }
-            catch (err) {
+            catch (_err) {
                 try {
                     const retryQuery = copyQuery.replace('auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)');
                     await conn.query(retryQuery);
@@ -671,7 +671,7 @@ export const batchInsertNodesToLbug = async (nodes, dbPath) => {
                 await tempConn.query(query);
                 inserted++;
             }
-            catch (e) {
+            catch (_e) {
                 // Don't console.error here - it corrupts MCP JSON-RPC on stderr
                 failed++;
             }
@@ -991,7 +991,7 @@ export const deleteNodesForFile = async (filePath, dbPath) => {
                     deletedNodes += count;
                 }
             }
-            catch (e) {
+            catch (_e) {
                 // Some tables may not support this query, skip
             }
         }

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

@@ -280,29 +280,18 @@ async function doInitLbug(repoId, dbPath) {
     finally {
         preWarmActive = false;
     }
-    // Load FTS extension once per shared Database.
-    // Done BEFORE pool registration so no concurrent checkout can grab
-    // the connection while the async FTS load is in progress.
-    if (!shared.ftsLoaded) {
-        try {
-            await available[0].query('LOAD EXTENSION fts');
-            shared.ftsLoaded = true;
-        }
-        catch {
-            // Extension may not be installed — FTS queries will fail gracefully
-        }
-    }
-    // Load VECTOR extension once per shared Database for semantic search support.
-    if (!shared.vectorLoaded) {
-        try {
-            await available[0].query('INSTALL VECTOR');
-            await available[0].query('LOAD EXTENSION VECTOR');
-            shared.vectorLoaded = true;
-        }
-        catch {
-            // VECTOR extension may not be available
-        }
-    }
+    // Load FTS + VECTOR extensions on EVERY connection in the pool.
+    //
+    // CRITICAL: LadybugDB's extension state is per-connection on macOS (and
+    // possibly other platforms) — loading on `available[0]` does NOT propagate
+    // to the other connections. Since checkout pops from the end of the array,
+    // queries would otherwise hit unloaded connections and `QUERY_FTS_INDEX`
+    // would silently return 0 rows (catch in queryFTSViaExecutor swallows the
+    // "extension not loaded" error). That broke every search on macOS.
+    //
+    // Load on all connections concurrently, but BEFORE the pool is registered
+    // so no checkout can race the load.
+    await loadExtensionsOnConnections(available, shared);
     // Register pool entry only after all connections are pre-warmed and FTS is
     // loaded.  Concurrent executeQuery calls see either "not initialized"
     // (and throw cleanly) or a fully ready pool — never a half-built one.
@@ -317,6 +306,42 @@ async function doInitLbug(repoId, dbPath) {
     });
     ensureIdleTimer();
 }
+/**
+ * Load FTS + VECTOR extensions on every connection in the pool.
+ * Per-connection load is required because LadybugDB's extension state is
+ * not always shared across connections of the same Database (observed on
+ * macOS native bindings — silent FTS failures otherwise).
+ */
+async function loadExtensionsOnConnections(conns, shared) {
+    // FTS: every connection needs `LOAD EXTENSION fts` independently.
+    await Promise.all(conns.map(async (c) => {
+        try {
+            await c.query('LOAD EXTENSION fts');
+        }
+        catch {
+            // already-loaded / not-installed — FTS queries fail gracefully if missing
+        }
+    }));
+    shared.ftsLoaded = true;
+    // VECTOR: install once on the Database (idempotent), then LOAD on every
+    // connection. INSTALL is a no-op after the first call but we run it on
+    // conn[0] to guarantee the package is present before fanning out LOADs.
+    try {
+        await conns[0].query('INSTALL VECTOR');
+    }
+    catch {
+        /* not available — semantic search will be a no-op */
+    }
+    await Promise.all(conns.map(async (c) => {
+        try {
+            await c.query('LOAD EXTENSION VECTOR');
+        }
+        catch {
+            /* not available — semantic search will be a no-op */
+        }
+    }));
+    shared.vectorLoaded = true;
+}
 /**
  * Initialize a pool entry from a pre-existing Database object.
  *
@@ -354,27 +379,9 @@ export async function initLbugWithDb(repoId, existingDb, dbPath) {
     finally {
         preWarmActive = false;
     }
-    // Load FTS extension if not already loaded on this Database
-    if (!shared.ftsLoaded) {
-        try {
-            await available[0].query('LOAD EXTENSION fts');
-            shared.ftsLoaded = true;
-        }
-        catch {
-            // Extension may already be loaded or not installed
-        }
-    }
-    // Load VECTOR extension for semantic search support
-    if (!shared.vectorLoaded) {
-        try {
-            await available[0].query('INSTALL VECTOR');
-            await available[0].query('LOAD EXTENSION VECTOR');
-            shared.vectorLoaded = true;
-        }
-        catch {
-            // VECTOR extension may not be available
-        }
-    }
+    // Load FTS + VECTOR on every connection (see loadExtensionsOnConnections
+    // for why per-connection load is required on macOS native bindings).
+    await loadExtensionsOnConnections(available, shared);
     pool.set(repoId, {
         db: existingDb,
         available,

package/dist/core/search/bm25-index.js

@@ -10,7 +10,7 @@
  * small repos / CI runners) at the cost of paying that overhead on the
  * first `query`/`context` call in a session.
  */
-import { queryFTS, ensureFTSIndex } from '../lbug/lbug-adapter.js';
+import { queryFTS, ensureFTSIndex, executeQuery as executeCoreQuery, } from '../lbug/lbug-adapter.js';
 /**
  * FTS schema served by `searchFTSFromLbug`. Centralised so that both the
  * CLI/pipeline path and the MCP pool path use identical (table, index,
@@ -23,6 +23,13 @@ const FTS_INDEXES = [
     { table: 'Method', indexName: 'method_fts', properties: ['name', 'content'] },
     { table: 'Interface', indexName: 'interface_fts', properties: ['name', 'content'] },
 ];
+const FALLBACK_SCAN_LIMIT = 50_000;
+const BOOLEAN_QUERY_TOKENS = new Set(['and', 'or', 'not']);
+const FALLBACK_FIELD_WEIGHTS = {
+    name: 4,
+    content: 2,
+    description: 1,
+};
 /**
  * Per-process cache for the MCP pool path: tracks which `(repoId, table)`
  * pairs have been ensured. The CLI/pipeline path gets its own cache inside
@@ -122,6 +129,68 @@ async function queryFTSViaExecutor(executor, tableName, indexName, query, limit)
         return [];
     }
 }
+function searchTerms(query) {
+    const terms = query
+        .toLowerCase()
+        .match(/[\p{L}\p{N}_]+/gu)
+        ?.filter((term) => term.length > 1 && !BOOLEAN_QUERY_TOKENS.has(term));
+    return [...new Set(terms ?? [])];
+}
+function scoreFallbackNode(node, query, properties) {
+    const terms = searchTerms(query);
+    if (terms.length === 0)
+        return 0;
+    const phrase = query.trim().toLowerCase();
+    let score = 0;
+    for (const property of properties) {
+        const raw = node[property];
+        if (raw === null || raw === undefined)
+            continue;
+        const value = String(raw).toLowerCase();
+        if (!value)
+            continue;
+        const weight = FALLBACK_FIELD_WEIGHTS[property] ?? 1;
+        if (phrase.length > 1 && value.includes(phrase)) {
+            score += weight * (terms.length + 1);
+        }
+        for (const term of terms) {
+            if (value.includes(term))
+                score += weight;
+        }
+    }
+    return score;
+}
+async function queryFallbackViaExecutor(executor, tableName, properties, query, limit) {
+    try {
+        const rows = await executor(`
+      MATCH (node:${tableName})
+      RETURN node
+      LIMIT ${FALLBACK_SCAN_LIMIT}
+    `);
+        return rows
+            .map((row) => {
+            const node = row.node || row[0] || {};
+            return {
+                filePath: node.filePath || '',
+                score: scoreFallbackNode(node, query, properties),
+                nodeId: node.nodeId || node.id || '',
+            };
+        })
+            .filter((result) => result.filePath && result.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+    }
+    catch {
+        return [];
+    }
+}
+async function fallbackSearchAllTables(executor, query, limit) {
+    const results = [];
+    for (const { table, properties } of FTS_INDEXES) {
+        results.push(await queryFallbackViaExecutor(executor, table, properties, query, limit));
+    }
+    return results;
+}
 /**
  * Search using LadybugDB's built-in FTS (always fresh, reads from disk)
  *
@@ -134,6 +203,8 @@ async function queryFTSViaExecutor(executor, tableName, indexName, query, limit)
  * @returns Ranked search results from FTS indexes
  */
 export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
+    if (!query.trim() || limit <= 0)
+        return [];
     let fileResults, functionResults, classResults, methodResults, interfaceResults;
     if (repoId) {
         // Use MCP connection pool via dynamic import
@@ -157,6 +228,15 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         classResults = await queryFTSViaExecutor(executor, 'Class', 'class_fts', query, limit);
         methodResults = await queryFTSViaExecutor(executor, 'Method', 'method_fts', query, limit);
         interfaceResults = await queryFTSViaExecutor(executor, 'Interface', 'interface_fts', query, limit);
+        if (fileResults.length +
+            functionResults.length +
+            classResults.length +
+            methodResults.length +
+            interfaceResults.length ===
+            0) {
+            [fileResults, functionResults, classResults, methodResults, interfaceResults] =
+                await fallbackSearchAllTables(executor, query, limit);
+        }
     }
     else {
         // Use core lbug adapter (CLI / pipeline context) — also sequential for safety.
@@ -169,6 +249,15 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         classResults = await queryFTS('Class', 'class_fts', query, limit, false).catch(() => []);
         methodResults = await queryFTS('Method', 'method_fts', query, limit, false).catch(() => []);
         interfaceResults = await queryFTS('Interface', 'interface_fts', query, limit, false).catch(() => []);
+        if (fileResults.length +
+            functionResults.length +
+            classResults.length +
+            methodResults.length +
+            interfaceResults.length ===
+            0) {
+            [fileResults, functionResults, classResults, methodResults, interfaceResults] =
+                await fallbackSearchAllTables(executeCoreQuery, query, limit);
+        }
     }
     // Collect all node scores per filePath to track which nodes actually matched
     const fileNodeScores = new Map();

package/dist/core/wiki/generator.js

@@ -221,7 +221,7 @@ export class WikiGenerator {
                 reportProgress(node.name);
                 return 1;
             }
-            catch (err) {
+            catch (_err) {
                 this.failedModules.push(node.name);
                 reportProgress(`Failed: ${node.name}`);
                 return 0;
@@ -239,7 +239,7 @@ export class WikiGenerator {
                 pagesGenerated++;
                 reportProgress(node.name);
             }
-            catch (err) {
+            catch (_err) {
                 this.failedModules.push(node.name);
                 reportProgress(`Failed: ${node.name}`);
             }
@@ -607,7 +607,7 @@ export class WikiGenerator {
                 this.onProgress('incremental', percent, `${incProcessed}/${affectedNodes.length} — ${node.name}`);
                 return 1;
             }
-            catch (err) {
+            catch (_err) {
                 this.failedModules.push(node.name);
                 incProcessed++;
                 return 0;
@@ -807,7 +807,7 @@ export class WikiGenerator {
         let activeConcurrency = this.concurrency;
         let running = 0;
         let idx = 0;
-        return new Promise((resolve, reject) => {
+        return new Promise((resolve, _reject) => {
             const next = () => {
                 while (running < activeConcurrency && idx < items.length) {
                     const item = items[idx++];

package/dist/mcp/resources.js

@@ -318,7 +318,7 @@ async function getContextResource(backend, repoName) {
     lines.push('  - cypher: Raw graph queries');
     lines.push('  - list_repos: Discover all indexed repositories');
     lines.push('');
-    lines.push('re_index: Run `npx codragraph analyze` in terminal if data is stale');
+    lines.push('re_index: Run `npx @codragraph/cli analyze` in terminal if data is stale');
     lines.push('');
     lines.push('resources_available:');
     lines.push('  - codragraph://repos: All indexed repositories');
@@ -520,7 +520,7 @@ async function getProcessDetailResource(name, backend, repoName) {
 async function getSetupResource(backend) {
     const repos = await backend.listRepos();
     if (repos.length === 0) {
-        return '# CodraGraph\n\nNo repositories indexed. Run: `npx codragraph analyze` in a repository.';
+        return '# CodraGraph\n\nNo repositories indexed. Run: `npx @codragraph/cli analyze` in a repository.';
     }
     const sections = [];
     for (const repo of repos) {
@@ -625,7 +625,6 @@ async function getRecipesResource(backend, repoName, taskFamily) {
     let result;
     try {
         const harnessModuleId = '@codragraph/harness/mcp/handler';
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const mod = (await import(/* @vite-ignore */ harnessModuleId));
         result = await mod.handleHarnessRecipesList({
             task_family: taskFamily,

package/hooks/claude/codragraph-hook.cjs

@@ -133,8 +133,18 @@ function runCodraGraphCli(cliPath, args, cwd, timeout) {
       stdio: ['pipe', 'pipe', 'pipe'],
     });
   }
-  // On Windows, invoke npx.cmd directly (no shell needed)
-  return spawnSync(isWin ? 'npx.cmd' : 'npx', ['-y', '@codragraph/cli', ...args], {
+  // npx fallback: on Windows, Node 22's spawn refuses to launch `npx.cmd`
+  // directly (returns EINVAL), so route through `cmd /c` and let PATHEXT
+  // resolve the shim. POSIX direct-spawn is fine.
+  if (isWin) {
+    return spawnSync('cmd', ['/c', 'npx', '-y', '@codragraph/cli', ...args], {
+      encoding: 'utf-8',
+      timeout: timeout + 5000,
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  }
+  return spawnSync('npx', ['-y', '@codragraph/cli', ...args], {
     encoding: 'utf-8',
     timeout: timeout + 5000,
     cwd,
@@ -239,7 +249,7 @@ function handlePostToolUse(input) {
   // If HEAD matches last indexed commit, no reindex needed
   if (currentHead && currentHead === lastCommit) return;
 
-  const analyzeCmd = `npx codragraph analyze${hadEmbeddings ? ' --embeddings' : ''}`;
+  const analyzeCmd = `npx @codragraph/cli analyze${hadEmbeddings ? ' --embeddings' : ''}`;
   sendHookResponse(
     'PostToolUse',
     `CodraGraph index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +

package/hooks/claude/pre-tool-use.sh

@@ -64,7 +64,12 @@ fi
 
 # Run codragraph augment — must be fast (<500ms target)
 # augment writes to stderr (KuzuDB captures stdout at OS level), so capture stderr and discard stdout
-RESULT=$(cd "$CWD" && npx -y codragraph augment "$PATTERN" 2>&1 1>/dev/null)
+# Prefer the global bin if present; fall back to npx (npm package is @codragraph/cli, bin is `codragraph`)
+if command -v codragraph >/dev/null 2>&1; then
+  RESULT=$(cd "$CWD" && codragraph augment "$PATTERN" 2>&1 1>/dev/null)
+else
+  RESULT=$(cd "$CWD" && npx -y @codragraph/cli augment "$PATTERN" 2>&1 1>/dev/null)
+fi
 
 if [ -n "$RESULT" ]; then
   ESCAPED=$(echo "$RESULT" | jq -Rs .)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codragraph/cli",
-  "version": "1.6.3",
+  "version": "1.6.4",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": {
     "name": "Anit Chaudhary",
@@ -59,7 +59,7 @@
     "@huggingface/transformers": "^4.1.0",
     "@ladybugdb/core": "^0.15.2",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@codragraph/graphstore": "*",
+    "@codragraph/graphstore": "^0.1.1",
     "@scarf/scarf": "^1.4.0",
     "cli-progress": "^3.12.0",
     "commander": "^14.0.3",

package/skills/codragraph-cli.md

@@ -12,7 +12,7 @@ All commands work via `npx` — no global install required.
 ### analyze — Build or refresh the index
 
 ```bash
-npx codragraph analyze
+npx @codragraph/cli analyze
 ```
 
 Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.codragraph/`, and generates CLAUDE.md / AGENTS.md context files.
@@ -27,7 +27,7 @@ Run from the project root. This parses all source files, builds the knowledge gr
 ### status — Check index freshness
 
 ```bash
-npx codragraph status
+npx @codragraph/cli status
 ```
 
 Shows whether the current repo has a CodraGraph index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
@@ -35,7 +35,7 @@ Shows whether the current repo has a CodraGraph index, when it was last updated,
 ### clean — Delete the index
 
 ```bash
-npx codragraph clean
+npx @codragraph/cli clean
 ```
 
 Deletes the `.codragraph/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing CodraGraph from a project.
@@ -48,7 +48,7 @@ Deletes the `.codragraph/` directory and unregisters the repo from the global re
 ### wiki — Generate documentation from the graph
 
 ```bash
-npx codragraph wiki
+npx @codragraph/cli wiki
 ```
 
 Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.codragraph/config.json` on first use).
@@ -65,7 +65,7 @@ Generates repository documentation from the knowledge graph using an LLM. Requir
 ### list — Show all indexed repos
 
 ```bash
-npx codragraph list
+npx @codragraph/cli list
 ```
 
 Lists all repositories registered in `~/.codragraph/registry.json`. The MCP `list_repos` tool provides the same information.

package/skills/codragraph-debugging.md

@@ -22,7 +22,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 4. codragraph_cypher({query: "MATCH path..."})                 → Custom traces if needed
 ```
 
-> If "Index is stale" → run `npx codragraph analyze` in terminal.
+> If "Index is stale" → run `npx @codragraph/cli analyze` in terminal.
 
 ## Checklist
 

package/skills/codragraph-exploring.md

@@ -23,7 +23,7 @@ description: "Use when the user asks how code works, wants to understand archite
 5. READ codragraph://repo/{name}/process/{name}      → Trace full execution flow
 ```
 
-> If step 2 says "Index is stale" → run `npx codragraph analyze` in terminal.
+> If step 2 says "Index is stale" → run `npx @codragraph/cli analyze` in terminal.
 
 ## Checklist
 

package/skills/codragraph-guide.md

@@ -15,7 +15,7 @@ For any task involving code understanding, debugging, impact analysis, or refact
 2. **Match your task to a skill below** and **read that skill file**
 3. **Follow the skill's workflow and checklist**
 
-> If step 1 warns the index is stale, run `npx codragraph analyze` in the terminal first.
+> If step 1 warns the index is stale, run `npx @codragraph/cli analyze` in the terminal first.
 
 ## Skills
 

package/skills/codragraph-impact-analysis.md

@@ -23,7 +23,7 @@ description: "Use when the user wants to know what will break if they change som
 4. Assess risk and report to user
 ```
 
-> If "Index is stale" → run `npx codragraph analyze` in terminal.
+> If "Index is stale" → run `npx @codragraph/cli analyze` in terminal.
 
 ## Checklist
 

package/skills/codragraph-pr-review.md

@@ -26,7 +26,7 @@ description: "Use when the user wants to review a pull request, understand what
 6. Summarize findings with risk assessment
 ```
 
-> If "Index is stale" → run `npx codragraph analyze` in terminal before reviewing.
+> If "Index is stale" → run `npx @codragraph/cli analyze` in terminal before reviewing.
 
 ## Checklist
 

package/skills/codragraph-refactoring.md

@@ -22,7 +22,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 4. Plan update order: interfaces → implementations → callers → tests
 ```
 
-> If "Index is stale" → run `npx codragraph analyze` in terminal.
+> If "Index is stale" → run `npx @codragraph/cli analyze` in terminal.
 
 ## Checklists