gitnexushub 0.7.0 → 0.7.1

package/dist/hooks-installer.d.ts

@@ -10,6 +10,22 @@ export interface InstallOptions {
     homeDir?: string;
     /** Absolute path to the shipped hook script. */
     hookScriptPath: string;
+    /**
+     * Absolute path to the `node` binary that should run the hook
+     * script. Defaults to `process.execPath` — the node binary
+     * currently running the installer, which is the safest cross-
+     * platform guarantee that the hook spawn will find an interpreter.
+     *
+     * Why this matters: GUI editor processes (Cursor.app on macOS, Kiro
+     * launched from Dock) inherit a minimal `PATH` that often excludes
+     * `~/.local/node/bin`, `/opt/homebrew/bin`, etc. — wherever the
+     * user installed node. A hook command of `node "..."` then fails
+     * to spawn (`/bin/sh: node: command not found`) and the editor
+     * silently marks the hook as failed (Cursor renders this as a
+     * cosmetic red X in the Hooks tab; the hook never runs). Embedding
+     * the absolute path sidesteps PATH entirely. Tests can override.
+     */
+    nodePath?: string;
 }
 /**
  * Install the Claude Code PreToolUse + PostToolUse hooks.
@@ -38,19 +54,34 @@ export declare function installClaudeCodeHook(opts: InstallOptions): Promise<str
  */
 export declare function installCursorHook(opts: InstallOptions): Promise<string>;
 /**
- * Install the Kiro graph-context + staleness hooks.
- * Returns the absolute paths to both written hook files.
+ * Install Kiro hooks — graph-tools nudge (askAgent) + edit-closure
+ * capture (runCommand). Returns the absolute paths to both files.
  *
- * Kiro hooks (kiro.dev/docs/hooks/types) live as one JSON file per
- * hook under `.kiro/hooks/<name>.kiro.hook`. Trigger names are kebab-
- * case ("pre-tool-use" / "post-tool-use"), matching the Claude Code
- * PreToolUse/PostToolUse semantics. The gitnexus hook script handles
- * both — it normalises the kebab-case event name back to PascalCase
- * internally so a single script serves Kiro + Claude Code + Cursor +
- * OpenCode.
+ * Kiro's actual hook schema (verified against a Kiro-UI-generated
+ * file, kiro.dev/docs/hooks notwithstanding) differs in three places
+ * from what 0.7.0 shipped:
  *
- * We register two hook files because Kiro's hook spec is one trigger
- * per file; bundling both into a single file would silently lose one.
+ *   1. Top-level shape is `{when, then, version, name, enabled}` —
+ *      not the `{trigger, actions[]}` shape we were writing.
+ *   2. Trigger type values are camelCase (`postToolUse`) — not the
+ *      kebab-case (`post-tool-use`) we emitted.
+ *   3. Action type for shell commands is `runCommand` — not `shell`.
+ *
+ * Plus three runtime constraints Kiro disclosed when asked directly:
+ *
+ *   - `runCommand` actions get NO stdin payload, NO env vars for
+ *     tool metadata, and NO `${variable}` substitution. So unlike
+ *     Claude Code / Cursor, the script can't read the just-edited
+ *     file path off stdin — we have to scan the working tree
+ *     ourselves (see runKiroEditCapture in the hook script).
+ *   - `runCommand` stdout is NOT fed back to the agent. Staleness
+ *     nudges and graph-context augmentation are invisible via this
+ *     channel — only `askAgent` actions can inject prompt text.
+ *   - The graph-tools nudge therefore uses `askAgent`; capture uses
+ *     `runCommand` plus the `--kiro-edit-capture` flag.
+ *
+ * `~/.kiro/hooks/` (user-level) IS loaded by Kiro despite some docs
+ * suggesting workspace-only — verified empirically in this session.
  */
 export declare function installKiroHook(opts: InstallOptions): Promise<string[]>;
 /**

package/dist/hooks-installer.js

@@ -11,6 +11,9 @@ import os from 'os';
 function getHome(opts) {
     return opts.homeDir ?? os.homedir();
 }
+function getNode(opts) {
+    return opts.nodePath ?? process.execPath;
+}
 async function writeJsonIdempotent(filePath, obj) {
     await fs.mkdir(path.dirname(filePath), { recursive: true });
     const body = JSON.stringify(obj, null, 2) + '\n';
@@ -61,7 +64,7 @@ export async function installClaudeCodeHook(opts) {
     // script which editor it's running under so /api/activity captures
     // get the right agentName (the stdin payload alone can't
     // distinguish editors that share the PascalCase MCP event names).
-    const command = `node ${shellQuote(opts.hookScriptPath)} --agent=claude-code`;
+    const command = `${shellQuote(getNode(opts))} ${shellQuote(opts.hookScriptPath)} --agent=claude-code`;
     const config = {
         hooks: {
             PreToolUse: [
@@ -116,7 +119,7 @@ export async function installClaudeCodeHook(opts) {
 export async function installCursorHook(opts) {
     const home = getHome(opts);
     const hooksJsonPath = path.join(home, '.cursor', 'hooks.json');
-    const command = `node ${shellQuote(opts.hookScriptPath)} --agent=cursor`;
+    const command = `${shellQuote(getNode(opts))} ${shellQuote(opts.hookScriptPath)} --agent=cursor`;
     // Merge into the user's existing ~/.cursor/hooks.json instead of
     // clobbering it — that file is the GLOBAL Cursor hooks config and
     // may already carry the user's own audit / lint hooks. Idempotent:
@@ -143,42 +146,70 @@ export async function installCursorHook(opts) {
     return hooksJsonPath;
 }
 /**
- * Install the Kiro graph-context + staleness hooks.
- * Returns the absolute paths to both written hook files.
+ * Install Kiro hooks — graph-tools nudge (askAgent) + edit-closure
+ * capture (runCommand). Returns the absolute paths to both files.
+ *
+ * Kiro's actual hook schema (verified against a Kiro-UI-generated
+ * file, kiro.dev/docs/hooks notwithstanding) differs in three places
+ * from what 0.7.0 shipped:
+ *
+ *   1. Top-level shape is `{when, then, version, name, enabled}` —
+ *      not the `{trigger, actions[]}` shape we were writing.
+ *   2. Trigger type values are camelCase (`postToolUse`) — not the
+ *      kebab-case (`post-tool-use`) we emitted.
+ *   3. Action type for shell commands is `runCommand` — not `shell`.
  *
- * Kiro hooks (kiro.dev/docs/hooks/types) live as one JSON file per
- * hook under `.kiro/hooks/<name>.kiro.hook`. Trigger names are kebab-
- * case ("pre-tool-use" / "post-tool-use"), matching the Claude Code
- * PreToolUse/PostToolUse semantics. The gitnexus hook script handles
- * both — it normalises the kebab-case event name back to PascalCase
- * internally so a single script serves Kiro + Claude Code + Cursor +
- * OpenCode.
+ * Plus three runtime constraints Kiro disclosed when asked directly:
  *
- * We register two hook files because Kiro's hook spec is one trigger
- * per file; bundling both into a single file would silently lose one.
+ *   - `runCommand` actions get NO stdin payload, NO env vars for
+ *     tool metadata, and NO `${variable}` substitution. So unlike
+ *     Claude Code / Cursor, the script can't read the just-edited
+ *     file path off stdin — we have to scan the working tree
+ *     ourselves (see runKiroEditCapture in the hook script).
+ *   - `runCommand` stdout is NOT fed back to the agent. Staleness
+ *     nudges and graph-context augmentation are invisible via this
+ *     channel — only `askAgent` actions can inject prompt text.
+ *   - The graph-tools nudge therefore uses `askAgent`; capture uses
+ *     `runCommand` plus the `--kiro-edit-capture` flag.
+ *
+ * `~/.kiro/hooks/` (user-level) IS loaded by Kiro despite some docs
+ * suggesting workspace-only — verified empirically in this session.
  */
 export async function installKiroHook(opts) {
     const home = getHome(opts);
     const hooksDir = path.join(home, '.kiro', 'hooks');
-    // `--agent=kiro` tags /api/activity captures so distillation can
-    // split rows by editor — Kiro's kebab-case events would also let
-    // detectAgent infer "kiro", but explicit > inferred.
-    const cmd = `node ${shellQuote(opts.hookScriptPath)} --agent=kiro`;
-    const preHookPath = path.join(hooksDir, 'gitnexus-graph-context.kiro.hook');
-    const postHookPath = path.join(hooksDir, 'gitnexus-staleness-check.kiro.hook');
-    await writeJsonIdempotent(preHookPath, {
-        name: 'gitnexus-graph-context',
-        description: 'Inject GitNexus graph context (callers, callees, impact) before Grep/Glob/Bash tool calls',
-        trigger: { type: 'pre-tool-use' },
-        actions: [{ type: 'shell', command: cmd }],
+    const editCaptureCmd = `${shellQuote(getNode(opts))} ${shellQuote(opts.hookScriptPath)} --agent=kiro --kiro-edit-capture`;
+    const preferGraphHookPath = path.join(hooksDir, 'gitnexus-prefer-graph-tools.kiro.hook');
+    const editCaptureHookPath = path.join(hooksDir, 'gitnexus-edit-capture.kiro.hook');
+    // 1. Steer the agent toward graph tools before shell searches.
+    // askAgent is the only Kiro action whose prompt actually reaches
+    // the agent context; runCommand stdout is discarded.
+    await writeJsonIdempotent(preferGraphHookPath, {
+        name: 'gitnexus-prefer-graph-tools',
+        version: '1',
+        enabled: true,
+        description: 'Before running shell searches (grep/find/rg), prefer GitNexus graph tools for richer code context',
+        when: { type: 'preToolUse', toolTypes: ['shell'] },
+        then: {
+            type: 'askAgent',
+            prompt: "Before running this shell command: if it's a search (grep, find, glob, rg), prefer the GitNexus MCP tools instead — `gitnexus_query` for concept search, `gitnexus_context` for symbol lookup, `gitnexus_cypher` for structural queries. Only fall back to shell search if GitNexus can't answer it.",
+        },
     });
-    await writeJsonIdempotent(postHookPath, {
-        name: 'gitnexus-staleness-check',
-        description: 'Capture file edits (edit-closure) and nudge to gnx sync after git commit/merge/rebase',
-        trigger: { type: 'post-tool-use' },
-        actions: [{ type: 'shell', command: cmd }],
+    // 2. Edit-closure capture. Fires after every write tool. Hook
+    // script runs `git status --porcelain` in the workspace root,
+    // posts each dirty file to /api/activity/edit-observed. Coarser
+    // than Claude Code / Cursor (catches all dirty files, not just
+    // the one the agent just touched) — but it's the only signal
+    // Kiro's hook plumbing exposes.
+    await writeJsonIdempotent(editCaptureHookPath, {
+        name: 'gitnexus-edit-capture',
+        version: '1',
+        enabled: true,
+        description: 'Capture file edits for distillation by scanning the working tree after write tool calls',
+        when: { type: 'postToolUse', toolTypes: ['write'] },
+        then: { type: 'runCommand', command: editCaptureCmd, timeout: 5 },
     });
-    return [preHookPath, postHookPath];
+    return [preferGraphHookPath, editCaptureHookPath];
 }
 /**
  * Install the OpenCode plugin stub.

package/hooks/gitnexus-enterprise-hook.cjs

@@ -389,23 +389,67 @@ function normaliseToolName(raw) {
 }
 
 /**
- * Emit the response in the format the source editor expects. Three
+ * Parse a `tool_output` field that may be either an object (Claude
+ * Code / Kiro / OpenCode native shape) or a JSON-stringified blob
+ * (Cursor wraps the result as a string per cursor.com/docs/hooks).
+ * Returns the parsed object, or the original value if it isn't a
+ * string we can decode. Caller still has to check for null.
+ */
+function parseToolOutput(out) {
+  if (typeof out === 'string') {
+    try {
+      return JSON.parse(out);
+    } catch {
+      return null;
+    }
+  }
+  return out;
+}
+
+/**
+ * Get the exit code from a normalised tool_output, accepting either
+ * `exit_code` (Claude Code / snake_case) or `exitCode` (Cursor /
+ * camelCase). Returns null when neither is present so callers can
+ * treat that as "succeeded" (some editors omit exit info entirely).
+ */
+function readExitCode(out) {
+  if (!out || typeof out !== 'object') return null;
+  if (typeof out.exit_code === 'number') return out.exit_code;
+  if (typeof out.exitCode === 'number') return out.exitCode;
+  return null;
+}
+
+/**
+ * Emit the response in the format the source editor expects. Four
  * envelopes today, one script:
  *
  *   Claude Code / OpenCode → `hookSpecificOutput` envelope
  *     ({ hookSpecificOutput: { hookEventName, additionalContext } })
- *   Cursor 2.4+            → `additional_context` (snake_case top-level)
- *     ({ additional_context: "..." })  see cursor.com/docs/hooks
- *   Kiro IDE               → plain stdout (kiro.dev/docs/hooks/actions
- *     "the stdout output of the command is added to the agent's context")
+ *   Cursor 2.4+ preToolUse → `permission` field is REQUIRED (cursor.com/docs/hooks)
+ *     plus optional `additional_context` for prompt injection
+ *   Cursor 2.4+ postToolUse → `additional_context` only
+ *   Kiro IDE               → plain stdout (kiro.dev/docs/hooks/actions —
+ *     except `runCommand` actions are fire-and-forget; stdout is NOT
+ *     fed back into agent context per Kiro's own clarification)
  */
 function sendResponse(event, agentName, message) {
   if (agentName === 'kiro') {
+    // Kiro `runCommand` action discards stdout. Writing it is harmless
+    // — it just doesn't reach the agent. We still emit so manual
+    // testing / log inspection has something to read.
     process.stdout.write(message + '\n');
     return;
   }
   if (agentName === 'cursor') {
-    process.stdout.write(JSON.stringify({ additional_context: message }) + '\n');
+    // Cursor preToolUse rejects entries that don't include `permission`
+    // — without it the Hooks tab logs the call as failed (cosmetic red
+    // X) even when our capture POST succeeded behind the scenes. We
+    // always allow; gating tool calls isn't gitnexus's job.
+    const envelope =
+      event === 'PreToolUse'
+        ? { permission: 'allow', additional_context: message }
+        : { additional_context: message };
+    process.stdout.write(JSON.stringify(envelope) + '\n');
     return;
   }
   process.stdout.write(
@@ -415,23 +459,48 @@ function sendResponse(event, agentName, message) {
   );
 }
 
+/**
+ * Cursor preToolUse with no augmentation message still has to return
+ * `permission: "allow"` or the IDE logs the call as failed. Use this
+ * when the script's other handlers decide not to inject context but
+ * we still need to clear the permission gate.
+ */
+function sendCursorAllow() {
+  process.stdout.write(JSON.stringify({ permission: 'allow' }) + '\n');
+}
+
 async function handlePreToolUse(input, config, entry, agentName) {
   const toolName = normaliseToolName(input.tool_name);
-  if (toolName !== 'Grep' && toolName !== 'Glob' && toolName !== 'Bash') return;
 
-  const pattern = extractPattern(toolName, input.tool_input || {});
-  if (!pattern || pattern.length < 3) return;
-
-  const res = await httpPostJson(
-    `${config.hubUrl}/api/repos/${entry.hubRepoId}/augment`,
-    authHeaders(config),
-    { pattern },
-  );
-  if (!res || res.status !== 200 || !res.body || !res.body.text) return;
+  // Cursor's preToolUse matcher includes Read + Write so the hook
+  // also fires for those, but our augment flow only handles search
+  // tools. Track whether we actually injected context so we can
+  // satisfy Cursor's permission contract on the no-augment path.
+  let injected = false;
+
+  if (toolName === 'Grep' || toolName === 'Glob' || toolName === 'Bash') {
+    const pattern = extractPattern(toolName, input.tool_input || {});
+    if (pattern && pattern.length >= 3) {
+      const res = await httpPostJson(
+        `${config.hubUrl}/api/repos/${entry.hubRepoId}/augment`,
+        authHeaders(config),
+        { pattern },
+      );
+      if (res && res.status === 200 && res.body && res.body.text) {
+        const text = String(res.body.text).trim();
+        if (text) {
+          sendResponse('PreToolUse', agentName, text);
+          injected = true;
+        }
+      }
+    }
+  }
 
-  const text = String(res.body.text).trim();
-  if (!text) return;
-  sendResponse('PreToolUse', agentName, text);
+  // Cursor preToolUse REQUIRES `permission` in the response; without
+  // it the Hooks tab marks every fire as failed (red X). Allow the
+  // tool unconditionally when we have nothing else to say — gating
+  // tool execution isn't gitnexus's responsibility.
+  if (!injected && agentName === 'cursor') sendCursorAllow();
 }
 
 /**
@@ -473,10 +542,15 @@ async function handleEditObservation(input, config, entry, agentName) {
   if (tool !== 'Edit' && tool !== 'Write' && tool !== 'MultiEdit') return;
 
   // Only fire when the edit succeeded. Some editors omit exit info; treat
-  // missing as success so we don't drop legitimate edits.
-  const out = input.tool_output;
-  if (out && out.exit_code !== undefined && out.exit_code !== 0) return;
-  if (out && out.error) return;
+  // missing as success so we don't drop legitimate edits. Cursor wraps
+  // tool_output as a JSON-stringified blob; everyone else passes an
+  // object — parseToolOutput normalises both. Cursor uses `exitCode`
+  // (camel) while Claude Code uses `exit_code` (snake) — readExitCode
+  // accepts either.
+  const out = parseToolOutput(input.tool_output);
+  const exitCode = readExitCode(out);
+  if (exitCode !== null && exitCode !== 0) return;
+  if (out && typeof out === 'object' && out.error) return;
 
   const filePath = (input.tool_input && input.tool_input.file_path) || '';
   if (!filePath || typeof filePath !== 'string') return;
@@ -511,11 +585,12 @@ async function handlePostToolUse(input, config, entry, agentName) {
   const cmd = (input.tool_input && input.tool_input.command) || '';
   if (!/\bgit\s+(commit|merge|rebase|cherry-pick|pull)(\s|$)/.test(cmd)) return;
 
-  // Only nudge when the git command actually succeeded. Some editors
-  // omit exit_code; treat missing as success so we don't silently
-  // skip legitimate mutations.
-  const exitCode = input.tool_output && input.tool_output.exit_code;
-  if (exitCode !== undefined && exitCode !== 0) return;
+  // Only nudge when the git command actually succeeded. Same parse
+  // shenanigans as handleEditObservation — Cursor stringifies and uses
+  // camelCase. Treat missing exit info as success.
+  const out = parseToolOutput(input.tool_output);
+  const exitCode = readExitCode(out);
+  if (exitCode !== null && exitCode !== 0) return;
 
   let localHead = '';
   try {
@@ -633,9 +708,95 @@ async function maybeNudgeUpgrade(config) {
   }
 }
 
+/**
+ * Kiro edit-capture mode. Kiro's `runCommand` action provides no stdin
+ * payload, no env vars for tool metadata, and no argument substitution
+ * — so we can't know which file the agent just edited. Instead, fire
+ * this on Kiro's `postToolUse` toolTypes:["write"] hook and scan the
+ * git working tree for changed files via `git status --porcelain`.
+ * Each dirty path POSTs to /api/activity/edit-observed so distillation
+ * gets per-file edit-closure data, even though the precision is
+ * coarser than Claude Code / Cursor (catches all dirty files in the
+ * tree, not just the one the agent just touched).
+ *
+ * cwd defaults to process.cwd() which Kiro sets to the workspace root.
+ * Resolving to a registry repo + reading the auth token mirrors the
+ * standard PostToolUse path.
+ */
+async function runKiroEditCapture(agentName) {
+  const config = readConfig();
+  if (!config || !config.hubToken || !config.hubUrl) return;
+
+  const entries = readRegistry();
+  const cwd = process.cwd();
+  const entry = resolveCwdToRepo(cwd, entries);
+  if (!entry) return;
+
+  // Two parallel git invocations: tracked-file modifications via
+  // `git diff --name-only HEAD` (catches modified + staged + deleted-
+  // tracked), and untracked files via `git ls-files --others
+  // --exclude-standard`. Both produce one absolute-relative path per
+  // line, no status-code prefix — far more robust than parsing
+  // `git status --porcelain` (whose XY field varies across git
+  // versions and edge cases).
+  const collected = new Set();
+  for (const args of [
+    ['diff', '--name-only', 'HEAD'],
+    ['ls-files', '--others', '--exclude-standard'],
+  ]) {
+    try {
+      const r = spawnSync('git', args, { cwd, encoding: 'utf-8', timeout: 2000 });
+      const out = (r.stdout || '').trim();
+      if (!out) continue;
+      for (const line of out.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed) collected.add(trimmed);
+      }
+    } catch {
+      // Best effort — proceed with whatever we got from prior args.
+    }
+  }
+  if (collected.size === 0) return;
+
+  // Cap at 20 files per fire so a big rewrite or a fresh branch
+  // pull doesn't hammer the hub with hundreds of edit-observed
+  // posts. The 20 cap is arbitrary but matches the per-call
+  // ladybugdb worker pool's typical session length.
+  let posted = 0;
+  for (const filePath of collected) {
+    if (posted >= 20) break;
+    const absPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+    await httpPostJson(`${config.hubUrl}/api/activity/edit-observed`, authHeaders(config), {
+      sessionId: null,
+      repoId: entry.hubRepoId,
+      filePath: absPath,
+      line: null,
+      tool: 'Write',
+      agentName,
+    });
+    posted++;
+  }
+}
+
 async function main() {
   if (process.env.GITNEXUS_NO_AUGMENT === '1') return;
 
+  // Kiro short-circuit: when invoked with --kiro-edit-capture, skip
+  // the standard stdin-driven flow entirely (Kiro's runCommand
+  // doesn't pipe stdin) and run the porcelain scan instead. The
+  // installer wires this flag onto Kiro's postToolUse:write hook.
+  if (process.argv.slice(2).includes('--kiro-edit-capture')) {
+    const agentName = parseAgentArg() || 'kiro';
+    try {
+      await runKiroEditCapture(agentName);
+    } catch (err) {
+      if (process.env.GITNEXUS_DEBUG) {
+        process.stderr.write(`kiro edit-capture: ${(err && err.message) || String(err)}\n`);
+      }
+    }
+    return;
+  }
+
   const input = readInput();
   const rawEvent = input.hook_event_name;
   const event = normaliseEvent(rawEvent);
@@ -654,9 +815,26 @@ async function main() {
   }
 
   const entries = readRegistry();
-  const cwd = input.cwd || process.cwd();
+  // Cursor 3.x spawns hooks from ~/.cursor (NOT the workspace) and
+  // sets `cwd: ""` in the stdin payload. The actual project root is
+  // in `workspace_roots[0]`. Without this fallback, resolveCwdToRepo
+  // looks for a registry entry at ~/.cursor → no match → script
+  // bails before posting /api/activity/edit-observed. Other editors
+  // (Claude Code, Kiro) set `cwd` themselves, so the fallback chain
+  // hits their value first.
+  const cwd =
+    (Array.isArray(input.workspace_roots) && input.workspace_roots[0]) ||
+    input.cwd ||
+    process.cwd();
   const entry = resolveCwdToRepo(cwd, entries);
-  if (!entry) return;
+  if (!entry) {
+    // Cursor preToolUse must still emit `permission: "allow"` even
+    // when we have nothing else to say — without it the IDE flags the
+    // hook entry as failed (cosmetic red X). All other paths exit
+    // silently as before.
+    if (event === 'PreToolUse' && agentName === 'cursor') sendCursorAllow();
+    return;
+  }
 
   try {
     if (event === 'PreToolUse') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexushub",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Connect your editor to GitNexus Hub — one command MCP setup + project context",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",