@codragraph/cli 1.6.3 → 2.0.0

package/hooks/claude/codragraph-hook.cjs

@@ -12,8 +12,27 @@
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
-const { spawnSync } = require('child_process');
+const { spawnSync, spawn } = require('child_process');
+
+/**
+ * Decide whether background auto-reindex is opted in. Two equivalent signals:
+ *   1. CODRAGRAPH_AUTO_REINDEX=1 in env (good for shells, CI)
+ *   2. `{ "autoReindex": true }` in ~/.codragraph/config.json (good for GUI
+ *      editor launches on Windows, where shell env doesn't propagate to
+ *      hook child processes reliably)
+ */
+function isAutoReindexEnabled() {
+  if (process.env.CODRAGRAPH_AUTO_REINDEX === '1') return true;
+  try {
+    const configPath = path.join(os.homedir(), '.codragraph', 'config.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    return config && config.autoReindex === true;
+  } catch {
+    return false;
+  }
+}
 
 /**
  * Read JSON input from stdin synchronously.
@@ -133,8 +152,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,11 +268,85 @@ 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' : ''}`;
+
+  // Opt-in background auto-reindex.
+  // Default stays as notification-only because spawning analyze while an MCP
+  // server holds LadybugDB will fail with a database-busy error — the
+  // notification path lets the agent reindex at a quiet moment instead.
+  // Power users who run MCP outside Claude Code's lifecycle can opt in via
+  // CODRAGRAPH_AUTO_REINDEX=1 or `{ "autoReindex": true }` in
+  // ~/.codragraph/config.json.
+  if (isAutoReindexEnabled()) {
+    // The "coalesce" file is a single-process gate: it exists only while a
+    // reindex is in flight. The spawned analyze removes it on exit (success or
+    // failure) via CODRAGRAPH_REINDEX_LOCK_PATH; the 10-min mtime fallback
+    // catches the rare crash that bypasses analyze's exit handler.
+    const coalescePath = path.join(gitNexusDir, '.reindex.coalesce');
+    const crashSafetyTtlMs = 10 * 60 * 1000;
+    let inFlight = false;
+    try {
+      const stat = fs.statSync(coalescePath);
+      if (Date.now() - stat.mtimeMs < crashSafetyTtlMs) inFlight = true;
+    } catch {
+      /* no coalesce file — no reindex in flight */
+    }
+
+    if (!inFlight) {
+      try {
+        fs.writeFileSync(coalescePath, String(process.pid));
+      } catch {
+        /* best-effort — gate is for coalescing, not correctness */
+      }
+
+      const cliPath = resolveCliPath();
+      const reindexArgs = hadEmbeddings
+        ? ['analyze', '--embeddings', '--no-setup']
+        : ['analyze', '--no-setup'];
+      const spawnEnv = { ...process.env, CODRAGRAPH_REINDEX_LOCK_PATH: coalescePath };
+      const spawnOpts = {
+        cwd,
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+        env: spawnEnv,
+      };
+      try {
+        let child;
+        if (cliPath) {
+          child = spawn(process.execPath, [cliPath, ...reindexArgs], spawnOpts);
+        } else if (process.platform === 'win32') {
+          child = spawn('cmd', ['/c', 'npx', '-y', '@codragraph/cli', ...reindexArgs], spawnOpts);
+        } else {
+          child = spawn('npx', ['-y', '@codragraph/cli', ...reindexArgs], spawnOpts);
+        }
+        child.unref();
+      } catch {
+        /* spawn failed — fall through to notification */
+      }
+
+      sendHookResponse(
+        'PostToolUse',
+        `CodraGraph: auto-reindex started in background ` +
+          `(HEAD ${lastCommit ? lastCommit.slice(0, 7) : 'never'} → ${currentHead.slice(0, 7)}). ` +
+          `If an MCP server is currently holding the database, the reindex will fail silently — ` +
+          `run \`${analyzeCmd}\` manually after closing the agent session.`,
+      );
+      return;
+    }
+
+    sendHookResponse(
+      'PostToolUse',
+      `CodraGraph: auto-reindex coalesced — another reindex is in flight (will pick up your latest commit when it finishes).`,
+    );
+    return;
+  }
+
   sendHookResponse(
     'PostToolUse',
     `CodraGraph index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +
-      `Run \`${analyzeCmd}\` to update the knowledge graph.`,
+      `Run \`${analyzeCmd}\` to update the knowledge graph. ` +
+      `Set CODRAGRAPH_AUTO_REINDEX=1 (or autoReindex: true in ~/.codragraph/config.json) for background auto-reindex.`,
   );
 }
 

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": "2.0.0",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": {
     "name": "Anit Chaudhary",
@@ -56,10 +56,10 @@
     "prepack": "node scripts/build.js"
   },
   "dependencies": {
+    "@codragraph/graphstore": "^1.0.0",
     "@huggingface/transformers": "^4.1.0",
-    "@ladybugdb/core": "^0.15.2",
+    "@ladybugdb/core": "^0.16.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@codragraph/graphstore": "*",
     "@scarf/scarf": "^1.4.0",
     "cli-progress": "^3.12.0",
     "commander": "^14.0.3",
@@ -99,6 +99,7 @@
     "tree-sitter-swift": "^0.6.0"
   },
   "devDependencies": {
+    "@codragraph/shared": "file:../codragraph-shared",
     "@types/cli-progress": "^3.11.6",
     "@types/cors": "^2.8.17",
     "@types/express": "^4.17.21",
@@ -106,7 +107,6 @@
     "@types/node": "^25.6.0",
     "@types/uuid": "^11.0.0",
     "@vitest/coverage-v8": "^4.0.18",
-    "@codragraph/shared": "file:../codragraph-shared",
     "tsx": "^4.0.0",
     "typescript": "^5.4.5",
     "vitest": "^4.0.18"

package/scripts/build-tree-sitter-proto.cjs

@@ -34,14 +34,26 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
-const protoDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-proto');
+// Resolve tree-sitter-proto from BOTH the codragraph package itself AND any
+// monorepo root that hoisted the dep. npm workspaces hoist optional deps to
+// the workspace root, so the package-local path doesn't exist on a workspace
+// install. Same trap as patch-tree-sitter-swift.cjs — see that file for the
+// full failure mode.
+const protoCandidates = [
+  path.join(__dirname, '..', 'node_modules', 'tree-sitter-proto'),
+  path.join(__dirname, '..', '..', 'node_modules', 'tree-sitter-proto'),
+];
+const protoDir = protoCandidates.find((d) => fs.existsSync(path.join(d, 'binding.gyp')));
+if (!protoDir) {
+  // tree-sitter-proto is an optionalDependency; absent when install
+  // skipped optional deps or the file: dep was not resolved.
+  process.exit(0);
+}
 const bindingGyp = path.join(protoDir, 'binding.gyp');
 const bindingNode = path.join(protoDir, 'build', 'Release', 'tree_sitter_proto_binding.node');
 
 try {
   if (!fs.existsSync(bindingGyp)) {
-    // tree-sitter-proto is an optionalDependency; absent when install
-    // skipped optional deps or the file: dep was not resolved.
     process.exit(0);
   }
 

package/scripts/patch-tree-sitter-swift.cjs

@@ -29,13 +29,26 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
-const swiftDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-swift');
+// Resolve tree-sitter-swift from BOTH the codragraph package itself AND any
+// monorepo root that hoisted the dep. npm workspaces hoist optional deps to
+// the workspace root, so `codragraph/node_modules/tree-sitter-swift` doesn't
+// exist when this script runs as the codragraph postinstall — checking only
+// that path silently no-ops, which is exactly the failure that left
+// Windows Node 22.14 users without a Swift parser.
+//
+// Order matters: the package-local dir takes precedence (standalone install),
+// then the parent monorepo root (workspace install).
+const candidateDirs = [
+  path.join(__dirname, '..', 'node_modules', 'tree-sitter-swift'),
+  path.join(__dirname, '..', '..', 'node_modules', 'tree-sitter-swift'),
+];
+const swiftDir = candidateDirs.find((d) => fs.existsSync(path.join(d, 'binding.gyp')));
+if (!swiftDir) {
+  process.exit(0);
+}
 const bindingPath = path.join(swiftDir, 'binding.gyp');
 
 try {
-  if (!fs.existsSync(bindingPath)) {
-    process.exit(0);
-  }
 
   const content = fs.readFileSync(bindingPath, 'utf8');
   let needsRebuild = false;

package/skills/codragraph-api-surface.md

@@ -0,0 +1,110 @@
+---
+name: codragraph-api-surface
+description: "Use when the user wants to enumerate the public API of a package or codebase, understand what's exported, audit breaking change risk, or compare API shapes across versions. Examples: \"what's our public API\", \"list exports\", \"API surface\", \"what would break if I remove X\", \"document the public interface\""
+---
+
+# API Surface Audit with CodraGraph
+
+## When to Use
+
+- "What's the public API of this package?"
+- "List every exported function / class / type"
+- "What would break if I remove or rename `<symbol>`?"
+- Pre-release API freeze audit
+- Generating API documentation from the graph
+- Comparing API surface across versions (with `codragraph diff --semantic`)
+
+## Why CodraGraph helps here
+
+Reading every `index.ts` / `__init__.py` / `mod.rs` by hand misses re-exports
+and framework-magic exports (Next.js page routes, decorators, registered
+plugins). CodraGraph's `isExported` property is computed by language-aware
+export detection — covers default exports, named re-exports, `__all__`,
+`pub use`, etc., consistently across all 16 supported languages.
+
+## Workflow
+
+```
+1. codragraph_cypher({query: `
+     MATCH (n) WHERE n.isExported = true
+     RETURN labels(n)[0] AS table, n.name, n.filePath, n.id
+     ORDER BY table, n.filePath, n.name
+   `})
+   → every exported symbol, grouped by table
+
+2. For each high-traffic export:
+   codragraph_impact({target: "<name>", direction: "upstream"})
+   → who depends on it (within this repo)
+
+3. For cross-repo audits (multi-repo group):
+   codragraph_impact({repo: "@<group>", target: "<name>", direction: "upstream"})
+   → blast radius across every group member
+
+4. Compare across versions:
+   codragraph diff <baseline> <head> --semantic --json
+   → addedAPIs / removedAPIs / classifiedModifications
+   → produces a versioned changelog of what your public surface gained / lost
+```
+
+> Pair with `codragraph-pr-review` skill when reviewing a PR that touches
+> exported symbols — the impact-across-group check is the difference between
+> "breaks our consumers" and "internal refactor."
+
+## Checklist
+
+```
+- [ ] Cypher query for n.isExported = true
+- [ ] Group by file or by community (Leiden cluster)
+- [ ] For each non-trivial export, run impact upstream
+- [ ] If the package is in a group, run impact with repo: "@group" too
+- [ ] Compare with previous release: codragraph diff <prev-tag> HEAD --semantic
+- [ ] Flag exports with no documented consumers — candidates for visibility
+      reduction (export → internal)
+```
+
+## Example: "What's our public API?"
+
+```
+1. codragraph_cypher({
+     query: `MATCH (n) WHERE n.isExported = true
+              RETURN labels(n)[0] AS table, n.name, n.filePath`
+   })
+   → 47 exports: 22 Function, 12 Class, 8 Interface, 5 Constant
+
+2. Top-level functions:
+   - createClient (src/index.ts) ← 14 callers
+   - fetchUser (src/api.ts)      ← 6 callers
+   - validate (src/utils.ts)     ← 1 internal caller only ⚠ over-exported
+
+3. codragraph_impact({target: "validate", direction: "upstream"})
+   → d=1: only formatPayload (same package). No external consumers.
+   → Recommend: drop the `export` keyword. Internal-only.
+
+4. Compare with v1.5.3 release:
+   codragraph diff v1.5.3 HEAD --semantic
+   → +3 added APIs, -1 removed API (mappings.toCamelCase), ~2 modified
+   → Removed API is a SemVer major bump.
+```
+
+## Output Format
+
+```markdown
+## API Surface: <package>
+
+### Exports (47 total)
+| Symbol | Table | File | Callers (internal) | Notes |
+|--------|-------|------|-------------------:|-------|
+| createClient | Function | src/index.ts | 14 | core entry |
+| validate | Function | src/utils.ts | 1 | over-exported, suggest internal |
+| ...
+
+### Diff vs <previous-tag>
+- **Added (3):** `subscribe`, `unsubscribe`, `EventBus`
+- **Removed (1):** `toCamelCase` ⚠ SemVer major
+- **Modified (2):** `createClient` (param 3→4), `fetchUser` (return type)
+
+### Recommendations
+- Reduce visibility on 4 over-exported internals
+- Document the 3 new APIs in the release notes
+- The removed `toCamelCase` requires a major version bump
+```

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-config-audit.md

@@ -0,0 +1,146 @@
+---
+name: codragraph-config-audit
+description: "Use to audit how environment variables, config files, and feature flags are read and used across the codebase — find unused config, missing defaults, undocumented env vars, secrets read into logs. Examples: \"audit env vars\", \"unused config\", \"who reads FOO_BAR env\", \"feature flag usage\", \"config sprawl\""
+---
+
+# Configuration Audit with CodraGraph
+
+## When to Use
+
+- "Which env vars do we actually read?"
+- "Which env vars are read but never set in deploy configs?"
+- "Find the unused feature flags I can delete."
+- "Who reads `STRIPE_SECRET_KEY`?"
+- "Is `<config>` ever logged or sent to telemetry?"
+- "Audit config sprawl before consolidating."
+
+## Why CodraGraph helps here
+
+Configuration enters your code through a small set of helpers:
+`process.env.X`, `os.getenv("X")`, `config.get("foo.bar")`,
+`featureFlags.isEnabled("flag")`. CodraGraph indexes the calls to those
+helpers and the literal arguments — so a `query` for the helper plus a
+`context` of each call site produces a complete picture of which keys
+are read where.
+
+## Workflow
+
+```
+1. Identify the config helpers (per-language patterns):
+   codragraph_query({query: "process.env getenv ConfigService featureFlags"})
+   → list of config-read helpers
+
+2. For each helper, find every call site and its key argument:
+   codragraph_cypher({query: `
+     MATCH (caller)-[:CALLS]->(helper {name: 'getenv'})
+     RETURN caller.name, caller.filePath
+   `})
+   → For richer key-extraction, read the bodies via context:
+   codragraph_context({name: "<caller>", content: true})
+   → look for the literal string passed to getenv()
+
+3. Cross-check with deploy configs:
+   - Read .env / .env.example / docker-compose.yml / k8s ConfigMaps
+   - Build the SET of keys actually defined
+   - For each key your code reads but isn't defined: undocumented env var
+   - For each key defined but no code reads: dead config — delete
+
+4. Feature-flag specific audit:
+   codragraph_query({query: "featureFlags.isEnabled flag.evaluate"})
+   → For each flag-read site: codragraph_impact upstream
+   → Flags with no callers can be removed
+   → Flags with one branch always returning true / false are stale
+
+5. Secret-leakage check:
+   codragraph_query({query: "STRIPE_SECRET DATABASE_URL API_KEY"})
+   → For each match: codragraph_context to confirm the value is not
+     piped to logger / tracer / metrics
+```
+
+## Audit dimensions
+
+| Dimension | Question | CodraGraph approach |
+|---|---|---|
+| **Used** | Is this env var read anywhere? | `query` for the literal key |
+| **Documented** | Is the key in `.env.example` / docs? | grep deploy files; subtract from used set |
+| **Defaulted** | Does the read have a default? | `context` shows the surrounding code |
+| **Validated** | Is the value parsed / type-checked? | `context` for `parseInt` / `URL` / Zod schema in the caller |
+| **Logged** | Does the value flow to telemetry? | `impact` downstream from the read site → check telemetry helpers |
+| **Stale flag** | Is the flag still toggled in production? | combine with deploy-config check |
+
+## Feature flag lifecycle audit
+
+```
+codragraph_cypher({query: `
+  MATCH (caller)-[:CALLS]->(ff {name: 'isEnabled'})
+  RETURN caller.name, caller.filePath, count(*) AS uses
+  ORDER BY uses DESC
+`})
+→ for each call site, codragraph_context to extract the flag NAME literal
+
+# Then:
+- Flag name read by 0 callers → remove
+- Flag name with both branches identical → stale (always-true or always-false)
+- Flag still wired in code, but config has it pinned `true` for >90 days → graduate
+```
+
+## Checklist
+
+```
+- [ ] Listed config helpers (env / config / featureFlag readers)
+- [ ] Built the read-set: { key: [ call sites ] }
+- [ ] Built the defined-set from deploy configs
+- [ ] Diff: undocumented (in code, not in config) + dead (in config, not in code)
+- [ ] Spot-check defaults / validation / secret leakage on critical keys
+- [ ] Feature-flag staleness check
+- [ ] Output: read map + recommended deletions / required deploy changes
+```
+
+## Example: "Audit our feature flags"
+
+```
+1. codragraph_query({query: "featureFlags.isEnabled"})
+   → 47 call sites in 23 files
+
+2. For each call site, extract the flag string (codragraph_context):
+   - 'new_checkout' (12 sites)
+   - 'experimental_search' (4 sites)
+   - 'use_new_pricing' (8 sites)
+   - 'kill_legacy_admin' (1 site)
+   - 'canary_v3' (0 sites — defined in code dead)
+
+3. Cross-check deploys:
+   - 'new_checkout' set to TRUE for 100%% prod since 2026-01 (graduate it)
+   - 'experimental_search' set to TRUE for 5%% prod (active experiment, keep)
+   - 'use_new_pricing' set to TRUE for 100%% prod since 2026-03 (graduate)
+   - 'kill_legacy_admin' set to TRUE for 100%% prod since 2026-02 (graduate)
+   - 'canary_v3' not configured anywhere (truly dead)
+
+4. Findings:
+   - DELETE: 'canary_v3' (dead code, no callers, no config)
+   - GRADUATE: 'new_checkout', 'use_new_pricing', 'kill_legacy_admin' →
+     remove the flag check; keep the new behavior unconditionally
+   - KEEP: 'experimental_search'
+   - Codebase loses: 21 call sites, 1 unused flag definition
+```
+
+## Output Format
+
+```markdown
+## Config Audit: <scope>
+
+### Env vars / config keys
+| Key | Read sites | Defined? | Default? | Validated? | Notes |
+|---|--:|---|---|---|---|
+| DATABASE_URL | 4 | ✓ | ✗ | ✗ | add Zod parse |
+| EXPERIMENTAL_FOO | 1 | ✗ | ✓ ('false') | ✓ | undocumented; either document or delete |
+| ... | ... | ... | ... | ... | ... |
+
+### Feature flags
+- DELETE (no callers): canary_v3, legacy_dashboard_b
+- GRADUATE (100%% production for >90 days): new_checkout, kill_legacy_admin
+- KEEP (active experiment): experimental_search, ai_summarize_v2
+
+### Secret-leak check
+- 0 paths from secret reads to logger/metrics/tracer found ✓
+```