gitnexushub 0.3.0 → 0.4.0

package/hooks/gitnexus-enterprise-hook.cjs

@@ -0,0 +1,415 @@
+#!/usr/bin/env node
+/**
+ * GitNexus Enterprise Hook
+ *
+ * PreToolUse  - POST /api/repos/:id/augment, prepend text to tool result
+ * PostToolUse - after git mutations, compare local HEAD vs hub last_commit,
+ *               emit staleness hint to nudge the agent toward `gnx sync`
+ *
+ * Resolves cwd -> hub_repo_id via ~/.gitnexus/connect-registry.json.
+ * Reads auth from ~/.gitnexus/config.json (written by `gnx connect`).
+ *
+ * Hard 1500ms timeout on all HTTP calls. Silent failure on error so the
+ * original tool runs unchanged. GITNEXUS_NO_AUGMENT=1 disables entirely.
+ *
+ * CJS, runs as `node gitnexus-enterprise-hook.cjs` without a build step.
+ * Dependencies: Node stdlib only (fs, path, os, http, https, child_process,
+ * url).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const http = require('http');
+const https = require('https');
+const { spawnSync } = require('child_process');
+const { URL } = require('url');
+
+const HOOK_TIMEOUT_MS = 1500;
+const CONFIG_PATH = path.join(os.homedir(), '.gitnexus', 'config.json');
+const REGISTRY_PATH = path.join(os.homedir(), '.gitnexus', 'connect-registry.json');
+const META_CACHE_DIR = path.join(os.homedir(), '.gitnexus', 'meta-cache');
+const META_CACHE_TTL_MS = 30_000;
+
+/**
+ * Read the hook event JSON from stdin (file descriptor 0). Claude Code /
+ * Cursor / OpenCode all send the event payload as a single blob on stdin.
+ * Any parse failure returns an empty object so downstream code can fall
+ * through to the silent-failure path.
+ */
+function readInput() {
+  try {
+    return JSON.parse(fs.readFileSync(0, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function readRegistry() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf-8'));
+    return Array.isArray(parsed.entries) ? parsed.entries : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve the editor's current working directory to the best-matching
+ * registry entry.
+ *
+ * Mirrors the semantics of gitnexus-connect/src/registry.ts
+ * resolveCwdToRepo (longest-path match + symlink normalization +
+ * path-separator boundary) but reimplemented here with sync fs APIs so
+ * the hook has no runtime dependency on the compiled connect bundle.
+ * Windows paths are lowercased before comparison so D:\foo and d:\foo
+ * match.
+ */
+function resolveCwdToRepo(cwd, entries) {
+  if (!entries.length) return null;
+
+  let resolved;
+  try {
+    resolved = fs.realpathSync(path.resolve(cwd));
+  } catch {
+    resolved = path.resolve(cwd);
+  }
+
+  const isWin = process.platform === 'win32';
+  const norm = isWin ? resolved.toLowerCase() : resolved;
+  const sep = path.sep;
+
+  let best = null;
+  let bestLen = 0;
+
+  for (const entry of entries) {
+    if (!entry || !entry.localPath || !entry.hubRepoId) continue;
+    let ep;
+    try {
+      ep = fs.realpathSync(path.resolve(entry.localPath));
+    } catch {
+      ep = path.resolve(entry.localPath);
+    }
+    const nep = isWin ? ep.toLowerCase() : ep;
+    const matched = norm === nep || norm.startsWith(nep + sep);
+    if (matched && nep.length > bestLen) {
+      best = entry;
+      bestLen = nep.length;
+    }
+  }
+
+  return best;
+}
+
+/**
+ * Extract a usable search pattern from the tool input, or null if the
+ * tool is not one we augment. Mirrors the OSS engine's best-effort
+ * extraction:
+ *   - Grep: direct pattern field
+ *   - Glob: first word-like token after a slash or star
+ *   - Bash: rg/grep command — skip flags and flag values, first bare
+ *     token wins
+ */
+function extractPattern(toolName, toolInput) {
+  if (toolName === 'Grep') {
+    return (toolInput && toolInput.pattern) || null;
+  }
+
+  if (toolName === 'Glob') {
+    const raw = (toolInput && toolInput.pattern) || '';
+    const m = raw.match(/[*\/]([a-zA-Z][a-zA-Z0-9_-]{2,})/);
+    return m ? m[1] : null;
+  }
+
+  if (toolName === 'Bash') {
+    const cmd = (toolInput && toolInput.command) || '';
+    if (!/\brg\b|\bgrep\b/.test(cmd)) return null;
+
+    const tokens = cmd.split(/\s+/);
+    let foundCmd = false;
+    let skipNext = false;
+    const flagsWithValues = new Set([
+      '-e',
+      '-f',
+      '-m',
+      '-A',
+      '-B',
+      '-C',
+      '-g',
+      '--glob',
+      '-t',
+      '--type',
+      '--include',
+      '--exclude',
+    ]);
+
+    for (const token of tokens) {
+      if (skipNext) {
+        skipNext = false;
+        continue;
+      }
+      if (!foundCmd) {
+        if (/\brg$|\bgrep$/.test(token)) foundCmd = true;
+        continue;
+      }
+      if (token.startsWith('-')) {
+        if (flagsWithValues.has(token)) skipNext = true;
+        continue;
+      }
+      const cleaned = token.replace(/['"]/g, '');
+      return cleaned.length >= 3 ? cleaned : null;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * POST JSON with a hard 1500ms timeout. Resolves to
+ *   {status: number, body: any}   on success
+ *   null                           on any error / timeout / non-JSON
+ *
+ * Never throws so callers can use the short-circuit pattern
+ *   const res = await httpPostJson(...); if (!res) return;
+ * and rely on silent-failure semantics.
+ */
+function httpPostJson(urlStr, headers, body) {
+  return new Promise((resolve) => {
+    try {
+      const u = new URL(urlStr);
+      const mod = u.protocol === 'https:' ? https : http;
+      const payload = JSON.stringify(body);
+      const req = mod.request(
+        {
+          method: 'POST',
+          hostname: u.hostname,
+          port: u.port || (u.protocol === 'https:' ? 443 : 80),
+          path: u.pathname + u.search,
+          headers: Object.assign(
+            {
+              'Content-Type': 'application/json',
+              'Content-Length': Buffer.byteLength(payload),
+            },
+            headers || {},
+          ),
+          timeout: HOOK_TIMEOUT_MS,
+        },
+        (res) => {
+          let data = '';
+          res.on('data', (c) => (data += c));
+          res.on('end', () => {
+            try {
+              resolve({ status: res.statusCode, body: JSON.parse(data) });
+            } catch {
+              resolve({ status: res.statusCode, body: null });
+            }
+          });
+        },
+      );
+      req.on('error', () => resolve(null));
+      req.on('timeout', () => {
+        try {
+          req.destroy();
+        } catch {
+          /* ignore */
+        }
+        resolve(null);
+      });
+      req.write(payload);
+      req.end();
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+/**
+ * GET JSON with a hard 1500ms timeout. Same contract as httpPostJson.
+ */
+function httpGetJson(urlStr, headers) {
+  return new Promise((resolve) => {
+    try {
+      const u = new URL(urlStr);
+      const mod = u.protocol === 'https:' ? https : http;
+      const req = mod.request(
+        {
+          method: 'GET',
+          hostname: u.hostname,
+          port: u.port || (u.protocol === 'https:' ? 443 : 80),
+          path: u.pathname + u.search,
+          headers: headers || {},
+          timeout: HOOK_TIMEOUT_MS,
+        },
+        (res) => {
+          let data = '';
+          res.on('data', (c) => (data += c));
+          res.on('end', () => {
+            try {
+              resolve({ status: res.statusCode, body: JSON.parse(data) });
+            } catch {
+              resolve(null);
+            }
+          });
+        },
+      );
+      req.on('error', () => resolve(null));
+      req.on('timeout', () => {
+        try {
+          req.destroy();
+        } catch {
+          /* ignore */
+        }
+        resolve(null);
+      });
+      req.end();
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+/**
+ * Emit the Claude Code / Cursor / OpenCode hookSpecificOutput envelope.
+ * The editor will prepend `message` to the tool's output before handing
+ * control back to the model.
+ */
+function sendResponse(event, message) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: event, additionalContext: message },
+    }) + '\n',
+  );
+}
+
+async function handlePreToolUse(input, config, entry) {
+  const toolName = 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`,
+    { Authorization: `Bearer ${config.hubToken}` },
+    { pattern },
+  );
+  if (!res || res.status !== 200 || !res.body || !res.body.text) return;
+
+  const text = String(res.body.text).trim();
+  if (!text) return;
+  sendResponse('PreToolUse', text);
+}
+
+/**
+ * Read the meta cache for a given repo, returning null if absent or
+ * older than META_CACHE_TTL_MS. The cache keeps the hook from hammering
+ * /meta on every git commit in a batch — editors can fire multiple
+ * PostToolUse events in quick succession.
+ */
+function readMetaCache(repoId) {
+  try {
+    const p = path.join(META_CACHE_DIR, `${repoId}.json`);
+    const stat = fs.statSync(p);
+    if (Date.now() - stat.mtimeMs > META_CACHE_TTL_MS) return null;
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeMetaCache(repoId, meta) {
+  try {
+    fs.mkdirSync(META_CACHE_DIR, { recursive: true });
+    fs.writeFileSync(path.join(META_CACHE_DIR, `${repoId}.json`), JSON.stringify(meta));
+  } catch {
+    /* ignore — cache is best-effort */
+  }
+}
+
+async function handlePostToolUse(input, config, entry) {
+  if (input.tool_name !== 'Bash') return;
+  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;
+
+  let localHead = '';
+  try {
+    const r = spawnSync('git', ['rev-parse', 'HEAD'], {
+      cwd: input.cwd || process.cwd(),
+      encoding: 'utf-8',
+      timeout: 2000,
+    });
+    localHead = (r.stdout || '').trim();
+  } catch {
+    return;
+  }
+  if (!localHead) return;
+
+  let meta = readMetaCache(entry.hubRepoId);
+  if (!meta) {
+    const res = await httpGetJson(`${config.hubUrl}/api/repos/${entry.hubRepoId}/meta`, {
+      Authorization: `Bearer ${config.hubToken}`,
+    });
+    if (!res || res.status !== 200 || !res.body) return;
+    meta = res.body;
+    writeMetaCache(entry.hubRepoId, meta);
+  }
+
+  if (meta.last_commit === localHead) return;
+  const shortOld = meta.last_commit ? String(meta.last_commit).slice(0, 7) : 'none';
+  sendResponse(
+    'PostToolUse',
+    `GitNexus index is stale (last indexed: ${shortOld}). Run \`gnx sync\` to update.`,
+  );
+}
+
+async function main() {
+  if (process.env.GITNEXUS_NO_AUGMENT === '1') return;
+
+  const input = readInput();
+  const event = input.hook_event_name;
+  if (event !== 'PreToolUse' && event !== 'PostToolUse') return;
+
+  const config = readConfig();
+  if (!config || !config.hubToken || !config.hubUrl) return;
+
+  const entries = readRegistry();
+  const cwd = input.cwd || process.cwd();
+  const entry = resolveCwdToRepo(cwd, entries);
+  if (!entry) return;
+
+  try {
+    if (event === 'PreToolUse') {
+      await handlePreToolUse(input, config, entry);
+    } else {
+      await handlePostToolUse(input, config, entry);
+    }
+  } catch (err) {
+    if (process.env.GITNEXUS_DEBUG) {
+      process.stderr.write(
+        `gitnexus hook error: ${(err && err.message ? err.message : String(err)).slice(0, 300)}\n`,
+      );
+    }
+  }
+}
+
+main().catch((err) => {
+  if (process.env.GITNEXUS_DEBUG) {
+    process.stderr.write(
+      `gitnexus hook fatal: ${(err && err.message ? err.message : String(err)).slice(0, 300)}\n`,
+    );
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexushub",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Connect your editor to GitNexus Hub — one command MCP setup + project context",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -36,10 +36,12 @@
   },
   "dependencies": {
     "commander": "^12.0.0",
-    "picocolors": "^1.1.1"
+    "picocolors": "^1.1.1",
+    "tar-stream": "^3.1.8"
   },
   "devDependencies": {
     "@types/node": "^20.19.37",
+    "@types/tar-stream": "^3.1.4",
     "tsx": "^4.0.0",
     "typescript": "^5.4.5",
     "vitest": "^4.1.4"
@@ -49,6 +51,7 @@
   },
   "files": [
     "dist",
+    "hooks",
     "skills"
   ],
   "publishConfig": {}

package/skills/gitnexus-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 gitnexus analyze` in the terminal first.
+> If step 1 warns the index is stale, run `gnx sync` in the terminal first.
 
 ## Skills
 

package/skills/gitnexus-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 gitnexus analyze` in terminal.
+> If "Index is stale" → run `gnx sync` in terminal.
 
 ## Checklists