memtrace 0.3.33 → 0.3.35

package/bin/memtrace.js

@@ -6,6 +6,7 @@ const path = require("path");
 const fs   = require("fs");
 const { spawnSync, spawn } = require("child_process");
 const { getBinaryPath } = require("../install.js");
+const { platformBinary, spawnOptionsForPlatform } = require("../lib/spawn-helper");
 
 // ── Handle `memtrace uninstall` before delegating to the Rust binary ────────
 // npm v7+ does NOT fire preuninstall hooks for global packages (npm/cli#3042).
@@ -27,14 +28,20 @@ const args = process.argv.slice(2);
 // which now resolves to the freshly-installed shim, not this old one.
 
 if (args[0] === "install" || args[0] === "update" || args[0] === "upgrade") {
-  const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
-  const memtraceCmd = process.platform === "win32" ? "memtrace.cmd" : "memtrace";
+  // `npm.cmd` on win32 needs `shell: true` since the CVE-2024-27980
+  // mitigation in Node 18.20+ / 20.12+ / 21.7+. The helpers in
+  // `lib/spawn-helper.js` are unit + property tested.
+  const npmCmd = platformBinary("npm", process.platform);
+  const memtraceCmd = platformBinary("memtrace", process.platform);
 
   process.stdout.write("memtrace: fetching latest from npm registry…\n");
   const installResult = spawnSync(
     npmCmd,
     ["install", "-g", "memtrace@latest"],
-    { stdio: "inherit", env: process.env }
+    spawnOptionsForPlatform(process.platform, {
+      stdio: "inherit",
+      env: process.env,
+    })
   );
 
   if (installResult.error) {
@@ -60,10 +67,15 @@ if (args[0] === "install" || args[0] === "update" || args[0] === "upgrade") {
   process.stdout.write(
     `memtrace: upgrade complete — running 'memtrace ${rest.join(" ")}'\n`
   );
-  const runResult = spawnSync(memtraceCmd, rest, {
-    stdio: "inherit",
-    env: process.env,
-  });
+  // memtrace.cmd on Windows needs the same shell:true handling.
+  const runResult = spawnSync(
+    memtraceCmd,
+    rest,
+    spawnOptionsForPlatform(process.platform, {
+      stdio: "inherit",
+      env: process.env,
+    })
+  );
   if (runResult.error) {
     console.error(`memtrace: failed to chain command — ${runResult.error.message}`);
     process.exit(1);
@@ -80,7 +92,13 @@ if (args[0] === "uninstall" || args[0] === "cleanup") {
   let ran = false;
   for (const p of candidates) {
     try {
-      require(p);
+      // Spawn the uninstall script as its own process so its top-level
+      // `if (require.main === module)` block fires. We deliberately
+      // avoid `require(p)` here: tests for the cleanup helpers
+      // import uninstall.js for its exports and would trigger the
+      // uninstall pipeline at import time if we relied on side effect.
+      const result = spawnSync(process.execPath, [p], { stdio: "inherit" });
+      if (result.error) continue;
       ran = true;
       break;
     } catch (e) {

package/hooks/posttool-mcp-telemetry.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+#
+# Memtrace PostToolUse hook for Claude Code — adoption telemetry.
+#
+# Fires after every tool call that matched the registered matcher
+# (`mcp__memtrace__.*`). Logs the call locally to
+# `~/.memtrace/adoption.jsonl` so we can measure whether v0.3.35's
+# enforcement layers actually moved Memtrace tool-invocation rates.
+#
+# This is LOCAL adoption tracking — the file lives in the user's
+# home directory, never leaves the machine. Aggregate counts may be
+# included in opt-in telemetry pings if the user has enabled them
+# (see PRIVACY.md).
+#
+# Hook never blocks. Always exit 0.
+#
+# Override:
+#   MEMTRACE_ADOPTION_LOG=off → unconditional no-op
+#
+set -euo pipefail
+
+[[ "${MEMTRACE_ADOPTION_LOG:-on}" == "off" ]] && exit 0
+
+# Read PostToolUse input from stdin. Shape:
+#   { "session_id", "cwd", "hook_event_name", "tool_name", "tool_input", ... }
+input="$(cat)"
+
+# Cheap exit if the JSON is malformed.
+[[ -z "$input" ]] && exit 0
+
+log_dir="${MEMTRACE_ADOPTION_DIR:-$HOME/.memtrace}"
+log_file="$log_dir/adoption.jsonl"
+mkdir -p "$log_dir" 2>/dev/null || exit 0
+
+# Append a single-line JSON record. We strip `tool_input` because it
+# can be large and may contain sensitive arguments. We keep the
+# tool name + a high-resolution timestamp + session id only.
+python3 - "$input" "$log_file" <<'PY' 2>/dev/null || true
+import json, sys, os, time
+input_str = sys.argv[1]
+log_path = sys.argv[2]
+try:
+    obj = json.loads(input_str)
+except Exception:
+    sys.exit(0)
+record = {
+    "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    "session_id": obj.get("session_id", ""),
+    "tool_name": obj.get("tool_name", ""),
+    "hook_event_name": obj.get("hook_event_name", ""),
+}
+with open(log_path, "a", encoding="utf-8") as f:
+    f.write(json.dumps(record) + "\n")
+PY
+
+exit 0

package/hooks/userprompt-claude.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+#
+# Memtrace UserPromptSubmit hook for Claude Code.
+#
+# Fires once per user turn (NOT per tool call). Reads the user's
+# prompt; if it looks like a code-discovery question and the
+# Memtrace daemon is reachable, injects an `additionalContext`
+# nudge so Claude considers Memtrace MCP tools BEFORE falling back
+# to Read/Grep/Glob.
+#
+# Why UserPromptSubmit instead of PreToolUse-on-Read|Grep|Glob:
+#   - fires once per turn, not per tool call → no per-Read latency
+#   - gets the user's actual prompt → can decide based on intent,
+#     not on which file the model chose to grep
+#   - non-blocking → just adds context, never denies a tool call
+#
+# Exit codes:
+#   0  : success (stdout is parsed for hook output)
+#   2  : would block the prompt (we never want this)
+#
+# Hook output JSON shape (per code.claude.com/docs/en/hooks-guide.md):
+#   { "decision": "continue", "additionalContext": "..." }
+#
+# Override:
+#   MEMTRACE_HOOK_MODE=off    → unconditional no-op
+#   MEMTRACE_HEALTH_URL=...   → custom health endpoint (default 3030)
+#
+set -euo pipefail
+
+mode="${MEMTRACE_HOOK_MODE:-advisory}"
+[[ "$mode" == "off" ]] && exit 0
+
+# ── Daemon liveness (portable: works on macOS/Linux/Windows-WSL) ──
+#
+# We use the Memtrace UI's status endpoint instead of `pgrep` so
+# Windows + restricted-shell environments work the same way.
+# 1-second timeout — must not slow Claude down.
+health_url="${MEMTRACE_HEALTH_URL:-http://localhost:3030/api/health}"
+if ! curl -sf --max-time 1 "$health_url" >/dev/null 2>&1; then
+    # Daemon unreachable: silent no-op. We never inject memtrace
+    # nudges when memtrace itself isn't running.
+    exit 0
+fi
+
+# ── Read prompt from stdin ──────────────────────────────────────────
+input="$(cat)"
+
+# Use python3 for JSON parsing — every macOS/Linux/Windows-with-Python
+# has it; jq is more concise but less universal.
+prompt="$(printf '%s' "$input" | python3 -c '
+import json, sys
+try:
+    obj = json.load(sys.stdin)
+    print(obj.get("prompt", ""), end="")
+except Exception:
+    pass
+' 2>/dev/null || true)"
+
+# If the prompt is empty or unparseable, no-op.
+[[ -z "$prompt" ]] && exit 0
+
+# ── Match code-discovery intent ─────────────────────────────────────
+#
+# The match list is intentionally generous on the "ask Memtrace" side
+# and is anchored against directive verbs and possessive phrases that
+# a real user prompt looks like. The agent's planner also uses these
+# (e.g. "trace through", "find the function that") so this catches
+# both human-typed and agent-internal phrasings.
+shopt -s nocasematch
+should_nudge=0
+case "$prompt" in
+    *"where is"*|*"where's"*|*"how does"*|*"how is"*) should_nudge=1 ;;
+    *"what calls"*|*"who calls"*|*"callers of"*|*"callees of"*) should_nudge=1 ;;
+    *"why does"*|*"why is"*|*"why was"*) should_nudge=1 ;;
+    *"find the function"*|*"find the class"*|*"find the type"*) should_nudge=1 ;;
+    *"trace through"*|*"trace this"*|*"trace the"*) should_nudge=1 ;;
+    *"investigate"*|*"debug"*|*"diagnose"*) should_nudge=1 ;;
+    *"explain this"*|*"explain the code"*|*"understand this"*) should_nudge=1 ;;
+    *"audit"*|*"review"*|*"refactor"*) should_nudge=1 ;;
+    *"fix bug"*|*"fix the bug"*|*"broken"*|*"failing"*) should_nudge=1 ;;
+    *"impact of"*|*"what breaks if"*|*"safe to remove"*|*"safe to rename"*) should_nudge=1 ;;
+    *"locate"*|*"look up"*|*"search for "*) should_nudge=1 ;;
+    *"recent changes"*|*"what changed"*|*"evolution of"*) should_nudge=1 ;;
+    *"call graph"*|*"dependency"*|*"depend on"*|*"dependencies of"*) should_nudge=1 ;;
+esac
+shopt -u nocasematch
+
+[[ "$should_nudge" -eq 0 ]] && exit 0
+
+# ── Emit the nudge ──────────────────────────────────────────────────
+#
+# Per Anthropic's hook docs, UserPromptSubmit accepts a top-level
+# `decision: continue` (don't block) plus `additionalContext` (which
+# is injected as a system-style reminder Claude reads alongside the
+# user's prompt). The wording is concise on purpose — this is added
+# to context for every matching prompt, so token cost is real.
+cat <<'EOF'
+{
+  "decision": "continue",
+  "additionalContext": "Memtrace is active for this repository. For this code-discovery question, prefer the Memtrace MCP tools FIRST — `mcp__memtrace__find_code` for natural-language search, `mcp__memtrace__find_symbol` for exact lookup, `mcp__memtrace__get_symbol_context` for callers/callees, `mcp__memtrace__get_impact` for blast radius. They return exact file:start_line:end_line in one round-trip. Fall back to Read/Grep/Glob only for: (a) config files (.env, package.json, README, raw JSON/YAML/TOML), (b) file inventory questions, (c) paths confirmed outside any indexed repo, (d) reading exact lines you already have from a Memtrace result."
+}
+EOF

package/install.js

@@ -5,6 +5,8 @@ const os = require("os");
 const path = require("path");
 const fs = require("fs");
 const { spawnSync } = require("child_process");
+const { platformBinary, spawnOptionsForPlatform } = require("./lib/spawn-helper");
+const { installToFs } = require("./lib/claude-integration");
 
 // ── Platform binary resolution (preserved from legacy) ───────────────────────
 
@@ -68,10 +70,20 @@ function selfHealPlatformPackage() {
     `memtrace: optional platform dep ${pkg} was not installed; ` +
     `running 'npm install ${versioned}' to fetch it…`
   );
+  // On Windows, Node.js 18.20+ / 20.12+ / 21.7+ refuse to spawn `.cmd`
+  // and `.bat` files without `shell: true` as part of the
+  // CVE-2024-27980 mitigation. The platform-aware helpers in
+  // `lib/spawn-helper.js` are unit + property tested so the shell
+  // flag is set IFF process.platform === "win32" — see
+  // `test/spawn-helper.test.js` for the full regression coverage.
   const result = spawnSync(
-    process.platform === "win32" ? "npm.cmd" : "npm",
+    platformBinary("npm", process.platform),
     ["install", "--no-save", versioned],
-    { cwd: __dirname, stdio: "inherit", env: process.env }
+    spawnOptionsForPlatform(process.platform, {
+      cwd: __dirname,
+      stdio: "inherit",
+      env: process.env,
+    })
   );
   if (result.status !== 0) {
     console.warn(
@@ -117,7 +129,40 @@ if (require.main === module) {
     console.warn("memtrace: run 'memtrace install' manually after the package is built.");
   }
 
-  // 3. Persist uninstall script to ~/.memtrace/ (survives `npm uninstall -g`)
+  // 3. Claude Code adoption layer (v0.3.35+):
+  //    - write ~/.claude/MEMTRACE.md (sidecar directive we own)
+  //    - add a breadcrumb block to ~/.claude/CLAUDE.md if it exists
+  //    - register UserPromptSubmit + PostToolUse hooks in
+  //      ~/.claude/settings.json under `_managed_by: "memtrace"`
+  //
+  //    This layer is what makes Claude Code consistently reach for
+  //    Memtrace MCP tools FIRST instead of falling back to Read/Grep
+  //    on indexed repos. Heuristic skill auto-invocation is too soft
+  //    on its own — see lib/claude-integration.js for the why.
+  try {
+    const hooksDir = path.join(__dirname, "hooks");
+    // Make hook scripts executable on Unix (npm tarballs lose +x on
+    // some pack/unpack paths; doing this defensively).
+    if (os.platform() !== "win32" && fs.existsSync(hooksDir)) {
+      for (const entry of fs.readdirSync(hooksDir)) {
+        if (entry.endsWith(".sh")) {
+          try { fs.chmodSync(path.join(hooksDir, entry), 0o755); }
+          catch { /* best-effort */ }
+        }
+      }
+    }
+    const claudeDir = path.join(os.homedir(), ".claude");
+    const summary = installToFs({ claudeDir, hooksDir });
+    if (summary.wrote.length > 0) {
+      console.log(
+        `memtrace: configured Claude Code integration (${summary.wrote.length} file(s) updated)`
+      );
+    }
+  } catch (e) {
+    console.warn(`memtrace: Claude Code integration setup skipped: ${e.message}`);
+  }
+
+  // 4. Persist uninstall script to ~/.memtrace/ (survives `npm uninstall -g`)
   try {
     const memtraceDir = path.join(os.homedir(), ".memtrace");
     fs.mkdirSync(memtraceDir, { recursive: true });