memtrace 0.3.41 → 0.3.42

package/bin/memtrace.js

@@ -10,6 +10,7 @@ const { getBinaryPath } = require("../install.js");
 const { platformBinary, spawnOptionsForPlatform } = require("../lib/spawn-helper");
 const { shouldPromptForUpgrade, isPromptDisabled } = require("../lib/update-prompt");
 const { fetchLatestVersion, readCachedVersion } = require("../lib/update-check");
+const rtkIntegration = require("../lib/rtk-integration");
 
 // ── Handle `memtrace uninstall` before delegating to the Rust binary ────────
 // npm v7+ does NOT fire preuninstall hooks for global packages (npm/cli#3042).
@@ -17,6 +18,105 @@ const { fetchLatestVersion, readCachedVersion } = require("../lib/update-check")
 
 const args = process.argv.slice(2);
 
+// ── RTK opt-in flow ─────────────────────────────────────────────────────────
+//
+// After a fresh `memtrace install` (or as a standalone `memtrace install-rtk`),
+// offer to install RTK alongside. RTK is a separate token-savings tool
+// covering shell-output filtering — non-overlapping with Memtrace's
+// graph-aware code lookups. Strictly opt-in.
+//
+// Routing matrix (from lib/rtk-integration.effectiveRtkAction):
+//   already-installed → skip silently with "RTK already installed"
+//   NO_RTK_PROMPT=1   → skip silently
+//   AUTO_INSTALL_RTK=1 → install without prompting (CI / scripted setups)
+//   interactive TTY    → prompt with default-yes
+//   no TTY             → print one-line hint pointing at `memtrace install-rtk`
+
+async function runRtkOptInFlow({ source }) {
+  const isTty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const alreadyInstalled = rtkIntegration.detectRtk();
+  const decision = rtkIntegration.effectiveRtkAction({
+    isTty,
+    alreadyInstalled,
+    env: process.env,
+  });
+
+  switch (decision.action) {
+    case "skip":
+      if (decision.reason === "already-installed") {
+        process.stdout.write("memtrace: RTK already installed — skipping prompt.\n");
+      }
+      // suppressed / invalid-input → silent
+      return { action: decision.action, reason: decision.reason };
+
+    case "hint":
+      process.stdout.write(`\n[memtrace] ${rtkIntegration.rtkHintLine()}\n\n`);
+      return { action: decision.action, reason: decision.reason };
+
+    case "install":
+      process.stdout.write("\n[memtrace] Installing RTK (MEMTRACE_AUTO_INSTALL_RTK)…\n");
+      return runRtkInstall();
+
+    case "prompt": {
+      const accepted = await promptForRtk({ source });
+      if (!accepted) {
+        process.stdout.write(
+          "[memtrace] OK, skipping RTK. " +
+          "Install later with: memtrace install-rtk\n",
+        );
+        return { action: "skip", reason: "user-declined" };
+      }
+      return runRtkInstall();
+    }
+
+    default:
+      return { action: "skip", reason: "unknown" };
+  }
+}
+
+async function promptForRtk({ source }) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const answer = await new Promise((resolve) => {
+    rl.question(rtkIntegration.rtkPromptText({ source }), resolve);
+  });
+  rl.close();
+  return rtkIntegration.parseRtkAnswer(answer);
+}
+
+function runRtkInstall() {
+  const result = rtkIntegration.installRtk();
+  if (result.ok) {
+    process.stdout.write(
+      `[memtrace] RTK installed via ${result.method}. ` +
+      `Run \`rtk gain\` to see your shell-savings ledger.\n`,
+    );
+    return { action: "install", reason: "ok" };
+  }
+  process.stderr.write(
+    `[memtrace] RTK install failed (${result.method}): ${result.error}\n` +
+    `[memtrace] Memtrace itself is fine. Install RTK manually:\n` +
+    `             curl -fsSL ${rtkIntegration.RTK_INSTALL_URL} | sh\n`,
+  );
+  return { action: "install", reason: "failed", error: result.error };
+}
+
+// ── Handle `memtrace install-rtk` — standalone RTK install entry point ──────
+
+if (args[0] === "install-rtk") {
+  // Run the opt-in flow standalone. Always exits 0 — RTK install
+  // failure is non-fatal (memtrace itself is unaffected).
+  runRtkOptInFlow({ source: "install-rtk" })
+    .then(() => process.exit(0))
+    .catch((e) => {
+      console.error(`memtrace install-rtk: ${e.message}`);
+      process.exit(0);
+    });
+  return; // (top-level await guard — see below for module-level return shim)
+}
+
 // ── Handle `memtrace install` — always pull latest, then run remaining args ──
 //
 // `npm install -g memtrace` fetches latest from the registry on a fresh
@@ -62,7 +162,16 @@ if (args[0] === "install" || args[0] === "update" || args[0] === "upgrade") {
   const rest = args.slice(1);
   if (rest.length === 0) {
     process.stdout.write("memtrace: latest installed.\n");
-    process.exit(0);
+    // Offer RTK alongside (interactive default-yes). Awaits the flow
+    // so the prompt blocks before the process exits. Failure of the
+    // RTK install does NOT fail the memtrace install.
+    runRtkOptInFlow({ source: "install" })
+      .then(() => process.exit(0))
+      .catch((e) => {
+        console.error(`memtrace: RTK opt-in flow errored (non-fatal): ${e.message}`);
+        process.exit(0);
+      });
+    return;
   }
 
   // Chain into the upgraded binary. PATH now resolves `memtrace` to the

package/install.js

@@ -162,7 +162,9 @@ if (require.main === module) {
     console.warn(`memtrace: Claude Code integration setup skipped: ${e.message}`);
   }
 
-  // 4. Persist uninstall script to ~/.memtrace/ (survives `npm uninstall -g`)
+  // 5. Persist uninstall script to ~/.memtrace/ (survives `npm uninstall -g`)
+  //    Done BEFORE the RTK opt-in below so the uninstall script lands
+  //    even if the RTK prompt errors / blocks / takes a long time.
   try {
     const memtraceDir = path.join(os.homedir(), ".memtrace");
     fs.mkdirSync(memtraceDir, { recursive: true });
@@ -174,6 +176,96 @@ if (require.main === module) {
   } catch (e) {
     console.warn(`memtrace: failed to persist uninstall script: ${e.message}`);
   }
+
+  // 6. RTK opt-in flow.
+  //
+  //    npm postinstall pipes stdin away — process.stdin.isTTY is false
+  //    even when the user is sitting at a terminal. To still ask the
+  //    user during a fresh `npm install -g memtrace`, we open /dev/tty
+  //    directly (same trick create-react-app, playwright, prisma use).
+  //
+  //    Routing:
+  //      - Already-installed → skip silently
+  //      - MEMTRACE_NO_RTK_PROMPT=1 → skip silently
+  //      - MEMTRACE_AUTO_INSTALL_RTK=1 → install no-prompt
+  //      - /dev/tty opens → prompt with default-yes, install on yes
+  //      - /dev/tty refused (Docker, CI, win32) → print one-line hint
+  //
+  //    Wrapped in async-IIFE because readline is async; we await it so
+  //    npm sees a clean exit code only after the user has answered.
+  (async () => {
+    const readline = require("readline");
+    const rtk = require("./lib/rtk-integration");
+
+    let alreadyInstalled = false;
+    try { alreadyInstalled = rtk.detectRtk(); } catch (_) { /* skip */ }
+
+    if (alreadyInstalled) return; // RTK is here, no prompt
+    if (rtk.isRtkPromptDisabled({ env: process.env })) return; // user opted out
+
+    if (rtk.isRtkAutoInstall({ env: process.env })) {
+      console.log("\nmemtrace: installing RTK (MEMTRACE_AUTO_INSTALL_RTK)…");
+      const r = rtk.installRtk();
+      if (r.ok) console.log(`memtrace: RTK installed via ${r.method}`);
+      else console.warn(`memtrace: RTK install failed: ${r.error}`);
+      return;
+    }
+
+    // Try /dev/tty for an interactive prompt. Falls back to hint if
+    // the controlling terminal is unavailable.
+    const ttyStreams = rtk.openTtyStreams();
+    if (!ttyStreams) {
+      console.log("");
+      console.log(rtk.rtkHintLine());
+      return;
+    }
+
+    let answered = false;
+    try {
+      const rl = readline.createInterface({
+        input: ttyStreams.input,
+        output: ttyStreams.output,
+        terminal: true,
+      });
+      const answer = await new Promise((resolve) => {
+        rl.question(rtk.rtkPromptText({ source: "postinstall" }), resolve);
+      });
+      rl.close();
+      answered = true;
+
+      if (!rtk.parseRtkAnswer(answer)) {
+        ttyStreams.output.write(
+          "memtrace: OK, skipping RTK. Install later: memtrace install-rtk\n",
+        );
+        return;
+      }
+
+      ttyStreams.output.write("memtrace: installing RTK…\n");
+      const r = rtk.installRtk();
+      if (r.ok) {
+        ttyStreams.output.write(
+          `memtrace: RTK installed via ${r.method}. Run 'rtk gain' for the savings ledger.\n`,
+        );
+      } else {
+        ttyStreams.output.write(
+          `memtrace: RTK install failed (${r.method}): ${r.error}\n` +
+          `memtrace: Memtrace itself is fine. Manual install:\n` +
+          `             curl -fsSL ${rtk.RTK_INSTALL_URL} | sh\n`,
+        );
+      }
+    } catch (e) {
+      // Any error in the prompt path is non-fatal for memtrace itself.
+      if (!answered) {
+        console.log(rtk.rtkHintLine());
+      } else {
+        console.warn(`memtrace: RTK install errored: ${e.message}`);
+      }
+    } finally {
+      ttyStreams.close();
+    }
+  })().catch((e) => {
+    console.warn(`memtrace: RTK opt-in flow errored: ${e.message}`);
+  });
 }
 
 module.exports = { getBinaryPath };

package/lib/rtk-integration.js

@@ -0,0 +1,357 @@
+"use strict";
+
+// Opt-in install of RTK ("Rust Token Killer", https://github.com/rtk-ai/rtk)
+// alongside Memtrace.
+//
+// Why:
+//   Memtrace eliminates token waste from code-discovery operations
+//   (find_symbol, find_code, get_symbol_context). RTK is a parallel,
+//   complementary system that proxies shell commands and filters their
+//   output before it reaches the agent — claims 60-90% reduction on
+//   dev operations like git/ls/cat output, build logs, etc.
+//
+//   The two are non-overlapping in scope (graph-aware code lookups vs
+//   shell-output filtering), share no runtime dependencies, and
+//   already have a coexistence contract on CLAUDE.md / settings.json
+//   sentinel blocks (see test/uninstall-cleanliness.test.js).
+//
+//   Bundling them as "want both?" at install time gives users
+//   maximum savings without forcing a separate discovery + install
+//   cycle. Strictly opt-in.
+//
+// Module shape mirrors lib/update-prompt.js:
+//   - Pure decision helpers below (testable without IO)
+//   - Side-effecting prompt + install runner separated so callers can
+//     unit-test the routing without spawning subprocesses
+
+// ── Env-var parsing helpers ─────────────────────────────────────────
+
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+
+function isTruthyEnv(value) {
+    if (typeof value !== "string") return false;
+    return TRUTHY.has(value.trim().toLowerCase());
+}
+
+/**
+ * @param {object} input
+ * @param {object} [input.env] defaults to process.env
+ * @returns {boolean}
+ */
+function isRtkPromptDisabled(input = {}) {
+    const env = input.env || {};
+    return isTruthyEnv(env.MEMTRACE_NO_RTK_PROMPT);
+}
+
+/**
+ * @param {object} input
+ * @param {object} [input.env] defaults to process.env
+ * @returns {boolean}
+ */
+function isRtkAutoInstall(input = {}) {
+    const env = input.env || {};
+    return isTruthyEnv(env.MEMTRACE_AUTO_INSTALL_RTK);
+}
+
+// ── Decision helpers ────────────────────────────────────────────────
+
+/**
+ * Should the caller PROMPT the user for RTK install? Pure: no IO.
+ *
+ * @param {object} input
+ * @param {boolean} input.isTty
+ * @param {boolean} input.alreadyInstalled
+ * @param {object} [input.env]
+ * @returns {boolean}
+ */
+function shouldPromptForRtk(input) {
+    if (!input || typeof input !== "object") return false;
+    if (!input.isTty) return false;
+    if (input.alreadyInstalled) return false;
+    if (isRtkPromptDisabled(input)) return false;
+    if (isRtkAutoInstall(input)) return false; // auto bypasses prompt → install path
+    return true;
+}
+
+/**
+ * Compute the routing decision for the RTK opt-in flow. Returns
+ *   { action: "install" | "prompt" | "skip" | "hint", reason: string }
+ * so callers can both act and produce a consistent log line.
+ *
+ * Decision precedence (top wins):
+ *   1. already-installed → skip (RTK is here, nothing to do)
+ *   2. NO_RTK_PROMPT     → skip (user explicitly opted out)
+ *   3. AUTO_INSTALL_RTK  → install (user explicitly opted in)
+ *   4. interactive TTY   → prompt (default-yes interactive flow)
+ *   5. otherwise         → hint (no TTY, no env signal — print one-line hint, skip install)
+ */
+function effectiveRtkAction(input) {
+    if (!input || typeof input !== "object") {
+        return { action: "skip", reason: "invalid-input" };
+    }
+    if (input.alreadyInstalled) {
+        return { action: "skip", reason: "already-installed" };
+    }
+    if (isRtkPromptDisabled(input)) {
+        return { action: "skip", reason: "suppressed" };
+    }
+    if (isRtkAutoInstall(input)) {
+        return { action: "install", reason: "auto-env" };
+    }
+    if (input.isTty) {
+        return { action: "prompt", reason: "interactive" };
+    }
+    return { action: "hint", reason: "no-tty" };
+}
+
+// ── Install-strategy helper ────────────────────────────────────────
+
+const RTK_INSTALL_URL =
+    "https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh";
+
+/**
+ * Pick the right install method for the host platform. Pure.
+ *
+ * Returns:
+ *   { method: "brew" | "curl" | "unsupported",
+ *     command: string[]     // argv to spawnSync (empty for unsupported)
+ *     reason?: string }     // for unsupported, why
+ */
+function chooseInstallStrategy(input) {
+    const platform = (input && input.platform) || "linux";
+    const hasBrew = Boolean(input && input.hasBrew);
+
+    if (platform === "win32") {
+        return {
+            method: "unsupported",
+            command: [],
+            reason: "RTK does not ship a Windows installer; install WSL or skip RTK.",
+        };
+    }
+
+    if (platform === "darwin" && hasBrew) {
+        return {
+            method: "brew",
+            command: ["brew", "install", "rtk"],
+        };
+    }
+
+    // Linux + macOS-without-brew → official curl|sh installer.
+    return {
+        method: "curl",
+        command: [
+            "sh",
+            "-c",
+            `set -e; curl -fsSL ${RTK_INSTALL_URL} | sh`,
+        ],
+    };
+}
+
+// ── Side-effecting helpers (thin shells; the real work is in argv) ─
+
+/**
+ * Detect whether RTK is already installed AND is the correct one (rtk-ai
+ * version, not the Rust Type Kit collision). Returns true only when
+ * `rtk gain` succeeds — per RTK's own README, that's the canonical
+ * verification because `rtk --version` also passes for the wrong RTK.
+ *
+ * Synchronous so it composes with the npm postinstall flow.
+ *
+ * @param {{spawnSync?: function}} [opts]
+ * @returns {boolean}
+ */
+function detectRtk(opts = {}) {
+    const spawnSync = opts.spawnSync || require("child_process").spawnSync;
+    // `rtk gain --help` is a fast no-op that proves we have the
+    // rtk-ai binary. We don't actually need to run `rtk gain` itself
+    // (which would hit network / read history) — `--help` parsing is
+    // enough to fail loudly on the wrong binary.
+    const r = spawnSync("rtk", ["gain", "--help"], {
+        stdio: "ignore",
+        timeout: 5000,
+    });
+    return r.status === 0;
+}
+
+/**
+ * Detect whether Homebrew is on PATH. Used to pick install strategy
+ * on macOS.
+ */
+function detectHomebrew(opts = {}) {
+    const spawnSync = opts.spawnSync || require("child_process").spawnSync;
+    const r = spawnSync("brew", ["--version"], {
+        stdio: "ignore",
+        timeout: 3000,
+    });
+    return r.status === 0;
+}
+
+/**
+ * Side-effecting RTK installer. Spawns the chosen install command,
+ * inheriting stdio so the user sees progress. Returns
+ *   { ok: boolean, method: string, error?: string }
+ */
+function installRtk(opts = {}) {
+    const spawnSync = opts.spawnSync || require("child_process").spawnSync;
+    const platform = opts.platform || process.platform;
+    const hasBrew = opts.hasBrew !== undefined
+        ? opts.hasBrew
+        : (platform === "darwin" && detectHomebrew({ spawnSync }));
+
+    const strategy = chooseInstallStrategy({ platform, hasBrew });
+
+    if (strategy.method === "unsupported") {
+        return { ok: false, method: strategy.method, error: strategy.reason };
+    }
+
+    const [cmd, ...args] = strategy.command;
+    const r = spawnSync(cmd, args, {
+        stdio: "inherit",
+        timeout: 120000, // 2 min cap; brew/curl install should be well under this
+    });
+    if (r.status !== 0) {
+        return {
+            ok: false,
+            method: strategy.method,
+            error: `${cmd} exited with status ${r.status}`,
+        };
+    }
+
+    // Verify the right RTK landed.
+    if (!detectRtk({ spawnSync })) {
+        return {
+            ok: false,
+            method: strategy.method,
+            error:
+                "rtk install reported success but `rtk gain --help` did not work. " +
+                "You may have hit the Rust-Type-Kit name collision — see " +
+                "https://github.com/rtk-ai/rtk/blob/master/INSTALL.md",
+        };
+    }
+
+    return { ok: true, method: strategy.method };
+}
+
+/**
+ * Print the one-line hint for the no-TTY path. Separated so callers
+ * can route output to wherever (stderr, log file, etc.).
+ */
+function rtkHintLine() {
+    return (
+        "memtrace: RTK (rtk-ai/rtk) is a complementary token-savings tool. " +
+        "Install alongside with: memtrace install-rtk"
+    );
+}
+
+// ── /dev/tty prompting (for npm postinstall, where stdin is piped) ──
+//
+// npm postinstall runs with stdin piped to npm — process.stdin.isTTY
+// is false even when the user is sitting at a terminal. Plenty of
+// well-known npm installers (create-react-app, playwright, prisma)
+// work around this by opening /dev/tty directly. We do the same.
+//
+// On Windows there is no /dev/tty. We return null and the caller
+// falls back to the hint path.
+
+/**
+ * Open read+write streams on the controlling terminal.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.platform] defaults to process.platform
+ * @param {object} [opts.fs]       defaults to require("fs")
+ * @param {object} [opts.tty]      defaults to require("tty")
+ * @returns {{input: ReadStream, output: WriteStream, close: function}|null}
+ *          null if /dev/tty cannot be opened (Win32, Docker without
+ *          tty, sandboxed environments).
+ */
+function openTtyStreams(opts = {}) {
+    const platform = opts.platform || process.platform;
+    if (platform === "win32") {
+        // Windows has CONIN$/CONOUT$ but the stream wrappers don't
+        // round-trip cleanly through readline. Fall back to hint.
+        return null;
+    }
+
+    const fs = opts.fs || require("fs");
+    const tty = opts.tty || require("tty");
+
+    let fd;
+    try {
+        fd = fs.openSync("/dev/tty", "r+");
+    } catch (_) {
+        return null; // no controlling tty (Docker, CI, etc.)
+    }
+
+    let input, output;
+    try {
+        input = new tty.ReadStream(fd);
+        output = new tty.WriteStream(fd);
+    } catch (e) {
+        try { fs.closeSync(fd); } catch (_) { /* best-effort */ }
+        return null;
+    }
+
+    return {
+        input,
+        output,
+        close() {
+            try { input.destroy(); } catch (_) { /* best-effort */ }
+            try { output.destroy(); } catch (_) { /* best-effort */ }
+        },
+    };
+}
+
+/**
+ * Pure parser: did the user accept the [Y/n] prompt?
+ *
+ * Default-yes: empty input (just Enter), unrecognised input → true.
+ * Only explicit "n" / "no" (case-insensitive, trimmed) → false.
+ */
+function parseRtkAnswer(answer) {
+    if (typeof answer !== "string") return true; // default-yes
+    const trimmed = answer.trim().toLowerCase();
+    if (trimmed === "") return true;
+    if (trimmed === "n" || trimmed === "no") return false;
+    return true;
+}
+
+/**
+ * Build the prompt text. Pure so we can keep the IO wrapper thin.
+ */
+function rtkPromptText({ source } = {}) {
+    const heading =
+        source === "install"
+            ? "Memtrace is installed. One more thing —"
+            : source === "postinstall"
+                ? "Memtrace is installed. One more thing —"
+                : "Add RTK to your toolchain?";
+    return (
+        `\n[memtrace] ${heading}\n` +
+        `\n` +
+        `RTK (Rust Token Killer, https://rtk-ai.app) is a separate CLI proxy\n` +
+        `that filters shell-command output before it reaches your AI assistant.\n` +
+        `Memtrace eliminates token waste from code lookups; RTK does the same\n` +
+        `for shell output. They're complementary.\n` +
+        `\n` +
+        `Install RTK alongside Memtrace? [Y/n] `
+    );
+}
+
+module.exports = {
+    // Pure helpers
+    isRtkPromptDisabled,
+    isRtkAutoInstall,
+    shouldPromptForRtk,
+    effectiveRtkAction,
+    chooseInstallStrategy,
+    rtkHintLine,
+    parseRtkAnswer,
+    rtkPromptText,
+    // IO helpers (injectable spawnSync / fs / tty for tests)
+    detectRtk,
+    detectHomebrew,
+    installRtk,
+    openTtyStreams,
+    // Constants
+    RTK_INSTALL_URL,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace",
-  "version": "0.3.41",
+  "version": "0.3.42",
   "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
   "keywords": [
     "mcp",
@@ -39,9 +39,9 @@
     "fs-extra": "^11.0.0"
   },
   "optionalDependencies": {
-    "@memtrace/darwin-arm64": "0.3.41",
-    "@memtrace/linux-x64": "0.3.41",
-    "@memtrace/win32-x64": "0.3.41"
+    "@memtrace/darwin-arm64": "0.3.42",
+    "@memtrace/linux-x64": "0.3.42",
+    "@memtrace/win32-x64": "0.3.42"
   },
   "engines": {
     "node": ">=18"