gitnexushub 0.4.5 → 0.6.0

package/hooks/gitnexus-enterprise-hook.cjs

@@ -368,7 +368,51 @@ function writeMetaCache(repoId, meta) {
   }
 }
 
+/**
+ * Edit-closure capture. After Edit/Write/MultiEdit succeeds in the agent,
+ * fire a fire-and-forget POST telling the hub which file was edited. The
+ * hub correlates against recent MCP result_symbols to record whether
+ * GitNexus drove this edit (the strongest possible quality signal).
+ *
+ * Best-effort: never blocks the editor, never re-tries, swallows errors.
+ */
+async function handleEditObservation(input, config, entry) {
+  const tool = input.tool_name;
+  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;
+
+  const filePath = (input.tool_input && input.tool_input.file_path) || '';
+  if (!filePath || typeof filePath !== 'string') return;
+
+  // Best-effort line extraction. Edit tool input often carries a `line`
+  // hint; MultiEdit usually doesn't.
+  const line = Number.isInteger(input.tool_input && input.tool_input.line)
+    ? Number(input.tool_input.line)
+    : null;
+
+  await httpPostJson(`${config.hubUrl}/api/activity/edit-observed`, authHeaders(config), {
+    sessionId: input.session_id || null,
+    repoId: entry.hubRepoId,
+    filePath,
+    line,
+    tool,
+    agentName: 'claude-code',
+  });
+}
+
 async function handlePostToolUse(input, config, entry) {
+  // Fan out: edit observations are independent of the git-staleness check.
+  // Both run on PostToolUse; we don't want one to block the other.
+  if (input.tool_name === 'Edit' || input.tool_name === 'Write' || input.tool_name === 'MultiEdit') {
+    await handleEditObservation(input, config, entry);
+    return;
+  }
+
   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;
@@ -411,6 +455,89 @@ async function handlePostToolUse(input, config, entry) {
   );
 }
 
+// ─── Soft-nudge upgrade flow ──────────────────────────────────────────────
+//
+// Hook version is read from the bundled package.json. Once per local day
+// we hit /api/activity/hook-version and compare. If the published latest
+// is ahead of ours, we print a single stderr line — never blocks editing.
+// State is held in ~/.gitnexus/hook-version-check.json so we don't spam
+// the hub on every PreToolUse.
+
+const VERSION_CHECK_FILE = path.join(os.homedir(), '.gitnexus', 'hook-version-check.json');
+const VERSION_CHECK_TTL_MS = 24 * 60 * 60 * 1000; // once per day
+
+function readPackageVersion() {
+  try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version || null;
+  } catch {
+    return null;
+  }
+}
+
+function readVersionCheckState() {
+  try {
+    const stat = fs.statSync(VERSION_CHECK_FILE);
+    if (Date.now() - stat.mtimeMs > VERSION_CHECK_TTL_MS) return null;
+    return JSON.parse(fs.readFileSync(VERSION_CHECK_FILE, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeVersionCheckState(state) {
+  try {
+    fs.mkdirSync(path.dirname(VERSION_CHECK_FILE), { recursive: true });
+    fs.writeFileSync(VERSION_CHECK_FILE, JSON.stringify(state));
+  } catch {
+    /* ignore — best effort */
+  }
+}
+
+/**
+ * Compare two semver strings (major.minor.patch only — pre-releases ignored).
+ * Returns -1 if a < b, 0 if equal, 1 if a > b. Defensive against malformed.
+ */
+function compareSemver(a, b) {
+  const pa = String(a || '0.0.0')
+    .split('.')
+    .map((n) => parseInt(n, 10) || 0);
+  const pb = String(b || '0.0.0')
+    .split('.')
+    .map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+async function maybeNudgeUpgrade(config) {
+  const local = readPackageVersion();
+  if (!local) return;
+
+  const cached = readVersionCheckState();
+  if (cached && compareSemver(local, cached.latestVersion) >= 0) return;
+
+  const res = await httpGetJson(`${config.hubUrl}/api/activity/hook-version`, authHeaders(config));
+  if (!res || res.status !== 200 || !res.body) return;
+
+  const latest = res.body.latestVersion;
+  if (!latest) return;
+
+  writeVersionCheckState({ latestVersion: latest, checkedAt: Date.now() });
+
+  if (compareSemver(local, latest) < 0) {
+    const note = res.body.notes ? ` — ${res.body.notes}` : '';
+    process.stderr.write(
+      `[gitnexus] connect hook ${local} → update available (${latest})${note}. ` +
+        `Run: npm update -g gitnexushub\n`,
+    );
+  }
+}
+
 async function main() {
   if (process.env.GITNEXUS_NO_AUGMENT === '1') return;
 
@@ -421,6 +548,13 @@ async function main() {
   const config = readConfig();
   if (!config || !config.hubToken || !config.hubUrl) return;
 
+  // Once-per-day soft-nudge if we're behind. Best-effort, won't block.
+  // Skipped entirely on PostToolUse so the editor's response path stays
+  // hot — PreToolUse fires more often, so the check still happens daily.
+  if (event === 'PreToolUse') {
+    maybeNudgeUpgrade(config).catch(() => {});
+  }
+
   const entries = readRegistry();
   const cwd = input.cwd || process.cwd();
   const entry = resolveCwdToRepo(cwd, entries);

package/package.json

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

package/skills/gitnexus-debugging.md

@@ -1,89 +1,89 @@
----
-name: gitnexus-debugging
-description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
----
-
-# Debugging with GitNexus
-
-## When to Use
-
-- "Why is this function failing?"
-- "Trace where this error comes from"
-- "Who calls this method?"
-- "This endpoint returns 500"
-- Investigating bugs, errors, or unexpected behavior
-
-## Workflow
-
-```
-1. gitnexus_query({query: "<error or symptom>"})            → Find related execution flows
-2. gitnexus_context({name: "<suspect>"})                    → See callers/callees/processes
-3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
-4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
-```
-
-> If "Index is stale" → trigger re-indexing from the Hub dashboard.
-
-## Checklist
-
-```
-- [ ] Understand the symptom (error message, unexpected behavior)
-- [ ] gitnexus_query for error text or related code
-- [ ] Identify the suspect function from returned processes
-- [ ] gitnexus_context to see callers and callees
-- [ ] Trace execution flow via process resource if applicable
-- [ ] gitnexus_cypher for custom call chain traces if needed
-- [ ] Read source files to confirm root cause
-```
-
-## Debugging Patterns
-
-| Symptom              | GitNexus Approach                                          |
-| -------------------- | ---------------------------------------------------------- |
-| Error message        | `gitnexus_query` for error text → `context` on throw sites |
-| Wrong return value   | `context` on the function → trace callees for data flow    |
-| Intermittent failure | `context` → look for external calls, async deps            |
-| Performance issue    | `context` → find symbols with many callers (hot paths)     |
-| Recent regression    | `impact` on changed functions → check what callers broke   |
-
-## Tools
-
-**gitnexus_query** — find code related to error:
-
-```
-gitnexus_query({query: "payment validation error"})
-→ Processes: CheckoutFlow, ErrorHandling
-→ Symbols: validatePayment, handlePaymentError, PaymentException
-```
-
-**gitnexus_context** — full context for a suspect:
-
-```
-gitnexus_context({name: "validatePayment"})
-→ Incoming calls: processCheckout, webhookHandler
-→ Outgoing calls: verifyCard, fetchRates (external API!)
-→ Processes: CheckoutFlow (step 3/7)
-```
-
-**gitnexus_cypher** — custom call chain traces:
-
-```cypher
-MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
-RETURN [n IN nodes(path) | n.name] AS chain
-```
-
-## Example: "Payment endpoint returns 500 intermittently"
-
-```
-1. gitnexus_query({query: "payment error handling"})
-   → Processes: CheckoutFlow, ErrorHandling
-   → Symbols: validatePayment, handlePaymentError
-
-2. gitnexus_context({name: "validatePayment"})
-   → Outgoing calls: verifyCard, fetchRates (external API!)
-
-3. READ gitnexus://repo/my-app/process/CheckoutFlow
-   → Step 3: validatePayment → calls fetchRates (external)
-
-4. Root cause: fetchRates calls external API without proper timeout
-```
+---
+name: gitnexus-debugging
+description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
+---
+
+# Debugging with GitNexus
+
+## When to Use
+
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "Who calls this method?"
+- "This endpoint returns 500"
+- Investigating bugs, errors, or unexpected behavior
+
+## Workflow
+
+```
+1. gitnexus_query({query: "<error or symptom>"})            → Find related execution flows
+2. gitnexus_context({name: "<suspect>"})                    → See callers/callees/processes
+3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
+4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
+```
+
+> If "Index is stale" → trigger re-indexing from the Hub dashboard.
+
+## Checklist
+
+```
+- [ ] Understand the symptom (error message, unexpected behavior)
+- [ ] gitnexus_query for error text or related code
+- [ ] Identify the suspect function from returned processes
+- [ ] gitnexus_context to see callers and callees
+- [ ] Trace execution flow via process resource if applicable
+- [ ] gitnexus_cypher for custom call chain traces if needed
+- [ ] Read source files to confirm root cause
+```
+
+## Debugging Patterns
+
+| Symptom              | GitNexus Approach                                          |
+| -------------------- | ---------------------------------------------------------- |
+| Error message        | `gitnexus_query` for error text → `context` on throw sites |
+| Wrong return value   | `context` on the function → trace callees for data flow    |
+| Intermittent failure | `context` → look for external calls, async deps            |
+| Performance issue    | `context` → find symbols with many callers (hot paths)     |
+| Recent regression    | `impact` on changed functions → check what callers broke   |
+
+## Tools
+
+**gitnexus_query** — find code related to error:
+
+```
+gitnexus_query({query: "payment validation error"})
+→ Processes: CheckoutFlow, ErrorHandling
+→ Symbols: validatePayment, handlePaymentError, PaymentException
+```
+
+**gitnexus_context** — full context for a suspect:
+
+```
+gitnexus_context({name: "validatePayment"})
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates (external API!)
+→ Processes: CheckoutFlow (step 3/7)
+```
+
+**gitnexus_cypher** — custom call chain traces:
+
+```cypher
+MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
+RETURN [n IN nodes(path) | n.name] AS chain
+```
+
+## Example: "Payment endpoint returns 500 intermittently"
+
+```
+1. gitnexus_query({query: "payment error handling"})
+   → Processes: CheckoutFlow, ErrorHandling
+   → Symbols: validatePayment, handlePaymentError
+
+2. gitnexus_context({name: "validatePayment"})
+   → Outgoing calls: verifyCard, fetchRates (external API!)
+
+3. READ gitnexus://repo/my-app/process/CheckoutFlow
+   → Step 3: validatePayment → calls fetchRates (external)
+
+4. Root cause: fetchRates calls external API without proper timeout
+```

package/skills/gitnexus-exploring.md

@@ -1,78 +1,78 @@
----
-name: gitnexus-exploring
-description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
----
-
-# Exploring Codebases with GitNexus
-
-## When to Use
-
-- "How does authentication work?"
-- "What's the project structure?"
-- "Show me the main components"
-- "Where is the database logic?"
-- Understanding code you haven't seen before
-
-## Workflow
-
-```
-1. READ gitnexus://repos                          → Discover indexed repos
-2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
-3. gitnexus_query({query: "<what you want to understand>"})  → Find related execution flows
-4. gitnexus_context({name: "<symbol>"})            → Deep dive on specific symbol
-5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
-```
-
-> If step 2 says "Index is stale" → trigger re-indexing from the Hub dashboard.
-
-## Checklist
-
-```
-- [ ] READ gitnexus://repo/{name}/context
-- [ ] gitnexus_query for the concept you want to understand
-- [ ] Review returned processes (execution flows)
-- [ ] gitnexus_context on key symbols for callers/callees
-- [ ] READ process resource for full execution traces
-- [ ] Read source files for implementation details
-```
-
-## Resources
-
-| Resource                                | What you get                                            |
-| --------------------------------------- | ------------------------------------------------------- |
-| `gitnexus://repo/{name}/context`        | Stats, staleness warning (~150 tokens)                  |
-| `gitnexus://repo/{name}/clusters`       | All functional areas with cohesion scores (~300 tokens) |
-| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens)              |
-| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens)              |
-
-## Tools
-
-**gitnexus_query** — find execution flows related to a concept:
-
-```
-gitnexus_query({query: "payment processing"})
-→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
-→ Symbols grouped by flow with file locations
-```
-
-**gitnexus_context** — 360-degree view of a symbol:
-
-```
-gitnexus_context({name: "validateUser"})
-→ Incoming calls: loginHandler, apiMiddleware
-→ Outgoing calls: checkToken, getUserById
-→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
-```
-
-## Example: "How does payment processing work?"
-
-```
-1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
-2. gitnexus_query({query: "payment processing"})
-   → CheckoutFlow: processPayment → validateCard → chargeStripe
-   → RefundFlow: initiateRefund → calculateRefund → processRefund
-3. gitnexus_context({name: "processPayment"})
-   → Incoming: checkoutHandler, webhookHandler
-   → Outgoing: validateCard, chargeStripe, saveTransaction
-4. Read src/payments/processor.ts for implementation details
-```
+---
+name: gitnexus-exploring
+description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
+---
+
+# Exploring Codebases with GitNexus
+
+## When to Use
+
+- "How does authentication work?"
+- "What's the project structure?"
+- "Show me the main components"
+- "Where is the database logic?"
+- Understanding code you haven't seen before
+
+## Workflow
+
+```
+1. READ gitnexus://repos                          → Discover indexed repos
+2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
+3. gitnexus_query({query: "<what you want to understand>"})  → Find related execution flows
+4. gitnexus_context({name: "<symbol>"})            → Deep dive on specific symbol
+5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
+```
+
+> If step 2 says "Index is stale" → trigger re-indexing from the Hub dashboard.
+
+## Checklist
+
+```
+- [ ] READ gitnexus://repo/{name}/context
+- [ ] gitnexus_query for the concept you want to understand
+- [ ] Review returned processes (execution flows)
+- [ ] gitnexus_context on key symbols for callers/callees
+- [ ] READ process resource for full execution traces
+- [ ] Read source files for implementation details
+```
+
+## Resources
+
+| Resource                                | What you get                                            |
+| --------------------------------------- | ------------------------------------------------------- |
+| `gitnexus://repo/{name}/context`        | Stats, staleness warning (~150 tokens)                  |
+| `gitnexus://repo/{name}/clusters`       | All functional areas with cohesion scores (~300 tokens) |
+| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens)              |
+| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens)              |
+
+## Tools
+
+**gitnexus_query** — find execution flows related to a concept:
+
+```
+gitnexus_query({query: "payment processing"})
+→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
+→ Symbols grouped by flow with file locations
+```
+
+**gitnexus_context** — 360-degree view of a symbol:
+
+```
+gitnexus_context({name: "validateUser"})
+→ Incoming calls: loginHandler, apiMiddleware
+→ Outgoing calls: checkToken, getUserById
+→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
+```
+
+## Example: "How does payment processing work?"
+
+```
+1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
+2. gitnexus_query({query: "payment processing"})
+   → CheckoutFlow: processPayment → validateCard → chargeStripe
+   → RefundFlow: initiateRefund → calculateRefund → processRefund
+3. gitnexus_context({name: "processPayment"})
+   → Incoming: checkoutHandler, webhookHandler
+   → Outgoing: validateCard, chargeStripe, saveTransaction
+4. Read src/payments/processor.ts for implementation details
+```