memorydetective 1.8.1 → 1.10.0

package/dist/runtime/leakReport.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Self-contained HTML rendering for `detectLeaksInXCTest` and
+ * `detectLeaksInXCUITest`.
+ *
+ * The rendered file embeds inline CSS (no external assets) so it renders the
+ * same way in:
+ *
+ *   - GitHub's file preview after upload-artifact + download
+ *   - PR-comment bots that link to the artifact URL
+ *   - A local `open report.html` from a CI failure investigation
+ *
+ * The template lives at `src/templates/leak-report.html` and is substituted
+ * with three placeholders: `{{TITLE}}`, `{{VERSION}}`, `{{TIMESTAMP}}`,
+ * `{{BODY}}`. The body fragment is generated per-call and represents the
+ * per-test sections (totals, new-cycles table, embedded steps log).
+ *
+ * Inputs are intentionally narrowed to the result shapes the two detect
+ * tools share, so the renderer can be called from either tool without
+ * conditional branches.
+ */
+export interface LeakReportSection {
+    /** Short label that goes at the top of the section (e.g. test identifier). */
+    title: string;
+    /** True when the section passed all checks (green verdict pill). */
+    passed: boolean;
+    /** Free-text reason rendered next to the pill when `passed` is false. */
+    failureReason?: string;
+    /** Absolute path to the baseline `.memgraph` (rendered as a `<code>` line). */
+    baselineMemgraph?: string;
+    /** Absolute path to the after `.memgraph`. */
+    afterMemgraph?: string;
+    totals: {
+        baselineLeaks: number;
+        afterLeaks: number;
+        leakDelta: number;
+    };
+    newCycles: Array<{
+        rootClass: string;
+        chainLength: number;
+        allowlisted: boolean;
+    }>;
+    /** Step-by-step log, rendered inside a collapsed `<details>` block. */
+    steps?: string[];
+}
+export interface RenderLeakReportInput {
+    title: string;
+    /** Optional context line (e.g. scheme, destination) rendered under the H1. */
+    subtitle?: string;
+    sections: LeakReportSection[];
+}
+export declare function renderLeakReportHtml(input: RenderLeakReportInput): string;
+/**
+ * Render and persist the HTML report. Returns the absolute path it was
+ * written to. The caller is responsible for choosing the path (so the same
+ * helper drives both the XCTest and XCUITest tools without each tool having
+ * to know about path conventions).
+ */
+export declare function writeLeakReportHtml(outputPath: string, input: RenderLeakReportInput): string;
+export declare function _resetTemplateCacheForTests(): void;
+export declare function _templatePathForTests(): string;
+export declare const LEAK_REPORT_TEMPLATE_PATH: string;
+export type { LeakReportSection as LeakReportSectionType };

package/dist/runtime/leakReport.js

@@ -0,0 +1,138 @@
+/**
+ * Self-contained HTML rendering for `detectLeaksInXCTest` and
+ * `detectLeaksInXCUITest`.
+ *
+ * The rendered file embeds inline CSS (no external assets) so it renders the
+ * same way in:
+ *
+ *   - GitHub's file preview after upload-artifact + download
+ *   - PR-comment bots that link to the artifact URL
+ *   - A local `open report.html` from a CI failure investigation
+ *
+ * The template lives at `src/templates/leak-report.html` and is substituted
+ * with three placeholders: `{{TITLE}}`, `{{VERSION}}`, `{{TIMESTAMP}}`,
+ * `{{BODY}}`. The body fragment is generated per-call and represents the
+ * per-test sections (totals, new-cycles table, embedded steps log).
+ *
+ * Inputs are intentionally narrowed to the result shapes the two detect
+ * tools share, so the renderer can be called from either tool without
+ * conditional branches.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { VERSION } from "../version.js";
+const here = dirname(fileURLToPath(import.meta.url));
+// `dist/runtime/leakReport.js` -> `dist/templates/leak-report.html`
+// (matches the `tsconfig.json` layout where src and dist are parallel).
+const TEMPLATE_PATH = resolvePath(here, "..", "templates", "leak-report.html");
+let cachedTemplate = null;
+function loadTemplate() {
+    if (cachedTemplate == null) {
+        cachedTemplate = readFileSync(TEMPLATE_PATH, "utf8");
+    }
+    return cachedTemplate;
+}
+function escapeHtml(s) {
+    return s
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function renderSection(section) {
+    const verdict = section.passed
+        ? '<span class="verdict pass">PASS</span>'
+        : '<span class="verdict fail">FAIL</span>';
+    const failReason = section.failureReason
+        ? `<p style="margin-top:.5rem;color:#ff3b30">${escapeHtml(section.failureReason)}</p>`
+        : "";
+    const baseline = section.baselineMemgraph
+        ? `<div><span class="label">Baseline:</span> <code>${escapeHtml(section.baselineMemgraph)}</code></div>`
+        : "";
+    const after = section.afterMemgraph
+        ? `<div><span class="label">After:</span> <code>${escapeHtml(section.afterMemgraph)}</code></div>`
+        : "";
+    const stats = `
+    <div style="margin:.75rem 0">
+      <div class="stat"><div class="n">${section.totals.baselineLeaks}</div><div class="label">Baseline</div></div>
+      <div class="stat"><div class="n">${section.totals.afterLeaks}</div><div class="label">After</div></div>
+      <div class="stat"><div class="n">${section.totals.leakDelta >= 0 ? "+" : ""}${section.totals.leakDelta}</div><div class="label">Delta</div></div>
+    </div>`;
+    const cyclesTable = section.newCycles.length === 0
+        ? '<p style="opacity:.65;margin:.5rem 0">No new ROOT CYCLEs after the test.</p>'
+        : `
+    <table>
+      <thead><tr><th>Root class</th><th>Chain length</th><th>Status</th></tr></thead>
+      <tbody>${section.newCycles
+            .map((c) => `
+        <tr>
+          <td><code>${escapeHtml(c.rootClass)}</code></td>
+          <td>${c.chainLength}</td>
+          <td>${c.allowlisted
+            ? '<span class="badge allow">allowlisted</span>'
+            : '<span class="badge fail">new leak</span>'}</td>
+        </tr>`)
+            .join("")}
+      </tbody>
+    </table>`;
+    const stepsBlock = section.steps && section.steps.length > 0
+        ? `<details><summary>Run log (${section.steps.length} step${section.steps.length === 1 ? "" : "s"})</summary><div class="steps">${section.steps.map(escapeHtml).join("\n")}</div></details>`
+        : "";
+    return `
+  <section class="card">
+    <h2 style="margin:0">${escapeHtml(section.title)} ${verdict}</h2>
+    ${failReason}
+    ${baseline}
+    ${after}
+    ${stats}
+    ${cyclesTable}
+    ${stepsBlock}
+  </section>`;
+}
+export function renderLeakReportHtml(input) {
+    const template = loadTemplate();
+    const body = (input.subtitle
+        ? `<div class="meta" style="margin-top:-1rem;margin-bottom:1.25rem">${escapeHtml(input.subtitle)}</div>`
+        : "") + input.sections.map(renderSection).join("\n");
+    return template
+        .replace(/\{\{TITLE\}\}/g, escapeHtml(input.title))
+        .replace(/\{\{VERSION\}\}/g, escapeHtml(VERSION))
+        .replace(/\{\{TIMESTAMP\}\}/g, escapeHtml(new Date().toISOString()))
+        .replace(/\{\{BODY\}\}/g, body);
+}
+/**
+ * Render and persist the HTML report. Returns the absolute path it was
+ * written to. The caller is responsible for choosing the path (so the same
+ * helper drives both the XCTest and XCUITest tools without each tool having
+ * to know about path conventions).
+ */
+export function writeLeakReportHtml(outputPath, input) {
+    const absolute = resolvePath(outputPath);
+    writeFileSync(absolute, renderLeakReportHtml(input), "utf8");
+    return absolute;
+}
+// Exposed for tests so the cached template can be reset between cases.
+export function _resetTemplateCacheForTests() {
+    cachedTemplate = null;
+}
+export function _templatePathForTests() {
+    return TEMPLATE_PATH;
+}
+// Build-time pin so `npm pack` ships the template alongside `dist/`. The
+// `package.json` `files` field needs to include `src/templates/**` AND
+// `dist/templates/**` after the build copies them. Verified in tests by
+// reading `loadTemplate()` synchronously: if the template is missing, the
+// first leak-report render throws an obvious ENOENT.
+//
+// Why pin the path instead of bundling the HTML as a string constant?
+// Keeping the template as a real HTML file lets contributors preview it in
+// a browser without going through a TS rebuild, and keeps the CSS-heavy
+// section out of TypeScript's diagnostics.
+const _BUILD_NOTE = "see comment block";
+void _BUILD_NOTE;
+// Re-export so other build steps can locate the template path without
+// importing the private helper.
+export const LEAK_REPORT_TEMPLATE_PATH = TEMPLATE_PATH;
+//# sourceMappingURL=leakReport.js.map

package/dist/runtime/leakReport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"leakReport.js","sourceRoot":"","sources":["../../src/runtime/leakReport.ts"],"names":[],"mappings":"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"}

package/dist/runtime/platformCheck.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Platform-specific advisories surfaced before capture-class tool calls.
+ *
+ * Today this only handles the macOS 26.x `task_for_pid` regression that
+ * blocks `leaks --outputGraph`, `heap`, and `xctrace --template Allocations`
+ * against iOS simulator processes regardless of `MallocStackLogging`.
+ * Surfaced from the notelet investigation 2026-05-12, where three CLI
+ * memory-introspection paths all failed with `Failed to get DYLD info for
+ * task` / minimal-corpse, and even Xcode's "View Memory Graph Hierarchy"
+ * failed unless Malloc Stack Logging was enabled in the scheme.
+ *
+ * The advisory is informational and idempotent: emitted once per server
+ * instance via {@link maybeLogPlatformAdvisoryOnce} (stderr), and returned
+ * as a structured `platformAdvisory` field on capture-class tool responses
+ * via {@link getPlatformAdvisory} so agents can surface it to the user
+ * before any tool work.
+ */
+export type PlatformAdvisory = {
+    issue: "macos-26-task-for-pid-broken";
+    message: string;
+    recommendedActions: string[];
+};
+/**
+ * Pure: returns the structured platform advisory for the current host,
+ * or `null` when no advisory applies.
+ *
+ * The advisory is suppressed when:
+ *   - Host is not macOS.
+ *   - Host is macOS but not in the 26.x range (Darwin kernel 25.x).
+ *   - `MEMORYDETECTIVE_SUPPRESS_PLATFORM_ADVISORY=1` is set in the environment.
+ *
+ * Conservative: when the Darwin major cannot be parsed, returns `null`
+ * (no advisory) rather than emitting a false positive. The macOS 27.x case
+ * (Darwin 26.x) is also `null` pending verification of whether Apple
+ * shipped a kernel fix; reopen this helper when 27.x lands.
+ *
+ * @param env - Environment lookup (defaults to `process.env`).
+ *              Threaded as a parameter for testability.
+ * @param osPlatform - `os.platform()` value (defaults to live).
+ * @param osRelease - `os.release()` value (defaults to live).
+ */
+export declare function getPlatformAdvisory(env?: Readonly<Record<string, string | undefined>>, osPlatform?: () => NodeJS.Platform, osRelease?: () => string): PlatformAdvisory | null;
+/**
+ * Side-effecting: emits the platform advisory to stderr on the FIRST call
+ * per server instance, then no-ops on subsequent calls. Safe to call at
+ * the top of every capture-class tool.
+ *
+ * The once-per-instance flag is module-level so it survives across tool
+ * calls within the same server process. Tests can reset via
+ * {@link resetPlatformAdvisoryFlagForTests}.
+ */
+export declare function maybeLogPlatformAdvisoryOnce(advisory: PlatformAdvisory | null, writer?: (line: string) => void): void;
+/** Test-only: reset the once-per-instance flag. */
+export declare function resetPlatformAdvisoryFlagForTests(): void;

package/dist/runtime/platformCheck.js

@@ -0,0 +1,94 @@
+/**
+ * Platform-specific advisories surfaced before capture-class tool calls.
+ *
+ * Today this only handles the macOS 26.x `task_for_pid` regression that
+ * blocks `leaks --outputGraph`, `heap`, and `xctrace --template Allocations`
+ * against iOS simulator processes regardless of `MallocStackLogging`.
+ * Surfaced from the notelet investigation 2026-05-12, where three CLI
+ * memory-introspection paths all failed with `Failed to get DYLD info for
+ * task` / minimal-corpse, and even Xcode's "View Memory Graph Hierarchy"
+ * failed unless Malloc Stack Logging was enabled in the scheme.
+ *
+ * The advisory is informational and idempotent: emitted once per server
+ * instance via {@link maybeLogPlatformAdvisoryOnce} (stderr), and returned
+ * as a structured `platformAdvisory` field on capture-class tool responses
+ * via {@link getPlatformAdvisory} so agents can surface it to the user
+ * before any tool work.
+ */
+import os from "node:os";
+const ADVISORY_MESSAGE = "macOS 26.x has an Apple-side kernel regression in `task_for_pid` against simulator processes. " +
+    "`leaks --outputGraph`, `heap`, and `xctrace --template Allocations` all abort with " +
+    "`Failed to get DYLD info for task` / minimal-corpse, even with `MallocStackLogging=1` " +
+    "applied at launch. memorydetective surfaces this via `workaroundNotice` when capture " +
+    "is attempted. The most reliable workaround today is to use an iOS 18 simulator runtime, " +
+    "which is pre-regression. Set `MEMORYDETECTIVE_SUPPRESS_PLATFORM_ADVISORY=1` to silence " +
+    "this notice.";
+const ADVISORY_ACTIONS = [
+    "Install an iOS 18 simulator runtime via Xcode > Settings > Platforms > +iOS 18.x.",
+    "When capturing a `.memgraph`, target the iOS 18 simulator rather than a macOS 26.x sim.",
+    "If iOS 18 is not feasible, fall back to manual Xcode `Debug > View Memory Graph Hierarchy` with Malloc Stack Logging enabled in the scheme's Diagnostics tab.",
+    "Set `MEMORYDETECTIVE_SUPPRESS_PLATFORM_ADVISORY=1` in the environment to silence this notice.",
+];
+/**
+ * Pure: returns the structured platform advisory for the current host,
+ * or `null` when no advisory applies.
+ *
+ * The advisory is suppressed when:
+ *   - Host is not macOS.
+ *   - Host is macOS but not in the 26.x range (Darwin kernel 25.x).
+ *   - `MEMORYDETECTIVE_SUPPRESS_PLATFORM_ADVISORY=1` is set in the environment.
+ *
+ * Conservative: when the Darwin major cannot be parsed, returns `null`
+ * (no advisory) rather than emitting a false positive. The macOS 27.x case
+ * (Darwin 26.x) is also `null` pending verification of whether Apple
+ * shipped a kernel fix; reopen this helper when 27.x lands.
+ *
+ * @param env - Environment lookup (defaults to `process.env`).
+ *              Threaded as a parameter for testability.
+ * @param osPlatform - `os.platform()` value (defaults to live).
+ * @param osRelease - `os.release()` value (defaults to live).
+ */
+export function getPlatformAdvisory(env = process.env, osPlatform = os.platform, osRelease = os.release) {
+    if (env.MEMORYDETECTIVE_SUPPRESS_PLATFORM_ADVISORY === "1")
+        return null;
+    if (osPlatform() !== "darwin")
+        return null;
+    const release = osRelease();
+    const majorStr = release.split(".")[0];
+    const major = Number.parseInt(majorStr, 10);
+    if (!Number.isFinite(major))
+        return null;
+    // Darwin 25.x kernel ships with macOS 26.x. Darwin 24.x = macOS 25 / Sequoia
+    // (no regression). Darwin 26.x = macOS 27 (verification pending; no advisory
+    // until confirmed).
+    if (major !== 25)
+        return null;
+    return {
+        issue: "macos-26-task-for-pid-broken",
+        message: ADVISORY_MESSAGE,
+        recommendedActions: ADVISORY_ACTIONS,
+    };
+}
+let advisoryLoggedThisInstance = false;
+/**
+ * Side-effecting: emits the platform advisory to stderr on the FIRST call
+ * per server instance, then no-ops on subsequent calls. Safe to call at
+ * the top of every capture-class tool.
+ *
+ * The once-per-instance flag is module-level so it survives across tool
+ * calls within the same server process. Tests can reset via
+ * {@link resetPlatformAdvisoryFlagForTests}.
+ */
+export function maybeLogPlatformAdvisoryOnce(advisory, writer = (line) => process.stderr.write(line)) {
+    if (advisoryLoggedThisInstance)
+        return;
+    if (advisory == null)
+        return;
+    writer(`[memorydetective] platform advisory: ${advisory.message}\n`);
+    advisoryLoggedThisInstance = true;
+}
+/** Test-only: reset the once-per-instance flag. */
+export function resetPlatformAdvisoryFlagForTests() {
+    advisoryLoggedThisInstance = false;
+}
+//# sourceMappingURL=platformCheck.js.map

package/dist/runtime/platformCheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platformCheck.js","sourceRoot":"","sources":["../../src/runtime/platformCheck.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AAQzB,MAAM,gBAAgB,GACpB,gGAAgG;IAChG,qFAAqF;IACrF,wFAAwF;IACxF,uFAAuF;IACvF,0FAA0F;IAC1F,yFAAyF;IACzF,cAAc,CAAC;AAEjB,MAAM,gBAAgB,GAAG;IACvB,mFAAmF;IACnF,yFAAyF;IACzF,+JAA+J;IAC/J,+FAA+F;CAChG,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAoD,OAAO,CAAC,GAAG,EAC/D,aAAoC,EAAE,CAAC,QAAQ,EAC/C,YAA0B,EAAE,CAAC,OAAO;IAEpC,IAAI,GAAG,CAAC,0CAA0C,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACxE,IAAI,UAAU,EAAE,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,OAAO,GAAG,SAAS,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC5C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,6EAA6E;IAC7E,6EAA6E;IAC7E,oBAAoB;IACpB,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC9B,OAAO;QACL,KAAK,EAAE,8BAA8B;QACrC,OAAO,EAAE,gBAAgB;QACzB,kBAAkB,EAAE,gBAAgB;KACrC,CAAC;AACJ,CAAC;AAED,IAAI,0BAA0B,GAAG,KAAK,CAAC;AAEvC;;;;;;;;GAQG;AACH,MAAM,UAAU,4BAA4B,CAC1C,QAAiC,EACjC,SAAiC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;IAErE,IAAI,0BAA0B;QAAE,OAAO;IACvC,IAAI,QAAQ,IAAI,IAAI;QAAE,OAAO;IAC7B,MAAM,CAAC,wCAAwC,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;IACrE,0BAA0B,GAAG,IAAI,CAAC;AACpC,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,iCAAiC;IAC/C,0BAA0B,GAAG,KAAK,CAAC;AACrC,CAAC"}

package/dist/runtime/redact.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Redact sensitive substrings from tool responses before they leave the
+ * MCP boundary.
+ *
+ * Tool outputs frequently include filesystem paths (with the user's home
+ * directory in them), token-shaped strings, hostnames, IP addresses, and
+ * bundle identifiers. None of those are useful to an AI agent reasoning
+ * about an iOS leak, and all of them are footguns when the output ends
+ * up in a Slack message, a PR comment, or a screenshot. This module
+ * scrubs them at the formatter boundary so by-default outputs are safe
+ * to share without manual sweeping.
+ *
+ * Three modes are selected via the `MEMORYDETECTIVE_REDACTION` env var:
+ *
+ * - `balanced` (default): home-directory absolute paths become `~/...`,
+ *   common secret-shaped tokens (AWS keys, GitHub PATs, Stripe secrets,
+ *   Slack tokens, Bearer auth) are masked. Hostnames, IPs, bundle IDs,
+ *   process names, and class names are preserved (they are usually
+ *   useful for debugging).
+ *
+ * - `strict`: everything in `balanced`, plus hostnames, IPv4 addresses,
+ *   and bundle identifiers. Use when the output is going to be pasted
+ *   into a public artifact (issue tracker, blog post, social) and you
+ *   want a wide safety margin.
+ *
+ * - `off`: no redaction. Default behavior is preserved for legacy
+ *   workflows and for local-only debugging where the noise is genuinely
+ *   helpful. The startup banner logs the active mode so an operator
+ *   running `off` knows the responses are unfiltered.
+ *
+ * Redaction is structural: the value passed in keeps its shape (same
+ * object keys, same array lengths, same scalar types), only string
+ * leaves are rewritten. Numbers, booleans, null/undefined, and dates
+ * pass through unchanged.
+ */
+export type RedactionMode = "balanced" | "strict" | "off";
+/**
+ * Pure: read the active redaction mode from an env-like object.
+ * Defaults to `balanced` when unset or set to an unrecognized value.
+ *
+ * Threaded as a parameter for testability; production callers omit it
+ * and get `process.env`.
+ */
+export declare function getRedactionMode(env?: Readonly<Record<string, string | undefined>>): RedactionMode;
+/**
+ * Pure: scrub a single string per the active mode. `off` returns the
+ * input unchanged; the other modes apply the rules described in the
+ * module doc.
+ *
+ * Threaded `homeDir` for testability so unit tests can pass a fake
+ * `/Users/test/` without depending on the real home directory.
+ */
+export declare function redactString(input: string, mode: RedactionMode, homeDir?: string): string;
+/**
+ * Pure: recursively redact strings inside an arbitrary JSON-shaped
+ * value. Object key names are preserved unchanged (they are part of
+ * the schema, not data); only string VALUES and string ARRAY items
+ * are scrubbed.
+ *
+ * Non-string scalars (number, boolean, null) pass through. Functions,
+ * symbols, and other non-JSON values are returned as-is.
+ */
+export declare function redact(value: unknown, mode: RedactionMode, homeDir?: string): unknown;
+export declare function maybeLogRedactionModeOnce(mode: RedactionMode, writer?: (line: string) => void): void;
+/** Test-only: reset the once-per-instance log flag. */
+export declare function resetRedactionAdvisoryFlagForTests(): void;

package/dist/runtime/redact.js

@@ -0,0 +1,146 @@
+/**
+ * Redact sensitive substrings from tool responses before they leave the
+ * MCP boundary.
+ *
+ * Tool outputs frequently include filesystem paths (with the user's home
+ * directory in them), token-shaped strings, hostnames, IP addresses, and
+ * bundle identifiers. None of those are useful to an AI agent reasoning
+ * about an iOS leak, and all of them are footguns when the output ends
+ * up in a Slack message, a PR comment, or a screenshot. This module
+ * scrubs them at the formatter boundary so by-default outputs are safe
+ * to share without manual sweeping.
+ *
+ * Three modes are selected via the `MEMORYDETECTIVE_REDACTION` env var:
+ *
+ * - `balanced` (default): home-directory absolute paths become `~/...`,
+ *   common secret-shaped tokens (AWS keys, GitHub PATs, Stripe secrets,
+ *   Slack tokens, Bearer auth) are masked. Hostnames, IPs, bundle IDs,
+ *   process names, and class names are preserved (they are usually
+ *   useful for debugging).
+ *
+ * - `strict`: everything in `balanced`, plus hostnames, IPv4 addresses,
+ *   and bundle identifiers. Use when the output is going to be pasted
+ *   into a public artifact (issue tracker, blog post, social) and you
+ *   want a wide safety margin.
+ *
+ * - `off`: no redaction. Default behavior is preserved for legacy
+ *   workflows and for local-only debugging where the noise is genuinely
+ *   helpful. The startup banner logs the active mode so an operator
+ *   running `off` knows the responses are unfiltered.
+ *
+ * Redaction is structural: the value passed in keeps its shape (same
+ * object keys, same array lengths, same scalar types), only string
+ * leaves are rewritten. Numbers, booleans, null/undefined, and dates
+ * pass through unchanged.
+ */
+import os from "node:os";
+const TOKEN_PATTERNS = [
+    // AWS access key id (AKIA + 16 chars)
+    { re: /\bAKIA[0-9A-Z]{16}\b/g, keepPrefix: 4 },
+    // GitHub classic PAT
+    { re: /\bghp_[A-Za-z0-9]{36,}\b/g, keepPrefix: 4 },
+    // GitHub fine-grained PAT
+    { re: /\bgithub_pat_[A-Za-z0-9_]+\b/g, keepPrefix: 11 },
+    // Stripe live + test secret
+    { re: /\bsk_(?:live|test)_[A-Za-z0-9]{20,}\b/g, keepPrefix: 8 },
+    // Slack tokens
+    { re: /\bxox[bpoasr]-[A-Za-z0-9-]+\b/g, keepPrefix: 5 },
+    // Bearer auth tokens
+    { re: /\bBearer\s+[A-Za-z0-9._\-]{20,}\b/gi, keepPrefix: 7 },
+];
+// Hostnames: 1+ labels followed by a TLD (2+ alpha chars). Excludes the
+// .swift / .ts / .js / .json / .trace / .memgraph "extensions" we see in
+// paths, since those would false-positive otherwise.
+const HOST_PATTERN = /\b(?!(?:[A-Za-z0-9-]+)\.(?:swift|ts|js|json|trace|memgraph|md|yaml|yml|html|png|jpg|jpeg|gif|m4v|mp4|mov|css|sh|py|rb|go|rs|c|cpp|h|hpp|m|mm|plist|xcframework|xcconfig|xcassets)\b)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}\b/gi;
+const IP_PATTERN = /\b(?:\d{1,3}\.){3}\d{1,3}\b/g;
+const BUNDLE_ID_PATTERN = /\bcom\.[a-z0-9_-]+(?:\.[a-z0-9_-]+)+\b/gi;
+/**
+ * Pure: read the active redaction mode from an env-like object.
+ * Defaults to `balanced` when unset or set to an unrecognized value.
+ *
+ * Threaded as a parameter for testability; production callers omit it
+ * and get `process.env`.
+ */
+export function getRedactionMode(env = process.env) {
+    const raw = (env.MEMORYDETECTIVE_REDACTION ?? "balanced").toLowerCase();
+    if (raw === "off" || raw === "strict" || raw === "balanced") {
+        return raw;
+    }
+    return "balanced";
+}
+/**
+ * Pure: scrub a single string per the active mode. `off` returns the
+ * input unchanged; the other modes apply the rules described in the
+ * module doc.
+ *
+ * Threaded `homeDir` for testability so unit tests can pass a fake
+ * `/Users/test/` without depending on the real home directory.
+ */
+export function redactString(input, mode, homeDir = os.homedir()) {
+    if (mode === "off")
+        return input;
+    let result = input;
+    // Home dir collapse first so subsequent host/IP rules don't mistakenly
+    // grab parts of paths.
+    if (homeDir && homeDir.length > 1 && result.includes(homeDir)) {
+        result = result.split(homeDir).join("~");
+    }
+    // Always mask token-shaped secrets, even in `balanced`.
+    for (const { re, keepPrefix } of TOKEN_PATTERNS) {
+        result = result.replace(re, (match) => match.slice(0, keepPrefix) + "***REDACTED***");
+    }
+    if (mode === "strict") {
+        result = result.replace(BUNDLE_ID_PATTERN, "***BUNDLE_ID***");
+        result = result.replace(IP_PATTERN, "***IP***");
+        result = result.replace(HOST_PATTERN, "***HOST***");
+    }
+    return result;
+}
+/**
+ * Pure: recursively redact strings inside an arbitrary JSON-shaped
+ * value. Object key names are preserved unchanged (they are part of
+ * the schema, not data); only string VALUES and string ARRAY items
+ * are scrubbed.
+ *
+ * Non-string scalars (number, boolean, null) pass through. Functions,
+ * symbols, and other non-JSON values are returned as-is.
+ */
+export function redact(value, mode, homeDir = os.homedir()) {
+    if (mode === "off")
+        return value;
+    if (value == null)
+        return value;
+    if (typeof value === "string")
+        return redactString(value, mode, homeDir);
+    if (typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((v) => redact(v, mode, homeDir));
+    }
+    if (typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = redact(v, mode, homeDir);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Side-effecting: log the active redaction mode once per server
+ * startup so an operator running with `off` knows the responses
+ * are unfiltered.
+ */
+let advisoryLogged = false;
+export function maybeLogRedactionModeOnce(mode, writer = (line) => process.stderr.write(line)) {
+    if (advisoryLogged)
+        return;
+    writer(`[memorydetective] redaction mode: ${mode}. ` +
+        `Set MEMORYDETECTIVE_REDACTION to balanced (default), strict, or off.\n`);
+    advisoryLogged = true;
+}
+/** Test-only: reset the once-per-instance log flag. */
+export function resetRedactionAdvisoryFlagForTests() {
+    advisoryLogged = false;
+}
+//# sourceMappingURL=redact.js.map

package/dist/runtime/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/runtime/redact.ts"],"names":[],"mappings":"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"}

package/dist/runtime/responseFormatter.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared response formatter for MCP tool outputs.
+ *
+ * Tools can declare `outputFormat?: "markdown" | "json" | "both"` (defaults to
+ * `"json"`, preserving v1.8 behavior). When the caller asks for a different
+ * shape, the registration wrapper in `src/index.ts` calls
+ * {@link formatMcpResponse} to produce the actual response content.
+ *
+ * Two audiences are served at once:
+ *   - **AI agents** (the typical caller) want raw JSON they can parse and chain
+ *     into the next call without re-reasoning.
+ *   - **Humans reading the same response** (the typical second audience: the
+ *     dev pasting the result into a PR comment, a Slack thread, or a Jira
+ *     ticket) want a markdown view that highlights the key fields.
+ *
+ * `outputFormat: "both"` returns BOTH content items in a single response, so a
+ * client can display the markdown to the user AND parse the JSON for the
+ * agent loop without an extra round-trip.
+ */
+import { z } from "zod";
+export declare const outputFormatField: z.ZodOptional<z.ZodEnum<["markdown", "json", "both", "verify-fix-table"]>>;
+export type OutputFormat = z.infer<typeof outputFormatField>;
+export interface McpContentItem {
+    type: "text";
+    text: string;
+}
+/**
+ * Shape of the MCP tool response. Matches the SDK's expected type
+ * (which has an open index signature for arbitrary extension fields like
+ * `_meta`); we model it explicitly here so the formatter's return type
+ * can flow through `server.registerTool` without a cast.
+ */
+export interface McpResponse {
+    content: McpContentItem[];
+    [key: string]: unknown;
+}
+/**
+ * Pure: shape the MCP response based on the caller's `outputFormat`.
+ *
+ * For `json` and `both`, the JSON is `JSON.stringify(result, null, 2)`. For
+ * `markdown` and `both`, the markdown is rendered via {@link renderAsMarkdown}.
+ */
+export declare function formatMcpResponse(result: unknown, toolName: string, format: OutputFormat | undefined): McpResponse;
+/**
+ * Pure: render a verify-fix focused markdown table for tools that support
+ * it. Returns `null` if the tool's result does not match the expected
+ * verify-fix shape, signaling the caller to fall back to standard markdown.
+ *
+ * Supported tools:
+ *
+ * - `analyzeAbandonedMemory`: reads `actionableShrinkage[]` (the v1.10
+ *   verify-fix-default direction: classes that the fix freed) and
+ *   `actionableGrowth[]` (regressions the fix didn't address). Emits one
+ *   table for shrinkage and, when non-empty, a second smaller table for
+ *   growth. Threshold: |delta| >= 10 by default to filter cosmetic noise.
+ *
+ * - `diffMemgraphs`: reads `classCountChanges[]` (positive + negative).
+ *   Future expansion; for now returns null and falls back to standard
+ *   markdown.
+ *
+ * The 4-column layout is deliberately compact (Class | Before | After |
+ * Delta) so it renders cleanly in GitHub's markdown preview, dev.to, and
+ * agent chat contexts. A trailing `> Diagnosis: ...` blockquote carries
+ * the structured `diagnosis` field when present.
+ */
+export declare function renderVerifyFixTable(result: unknown, toolName: string): string | null;
+/**
+ * Pure: render an arbitrary JSON-shaped value as markdown.
+ *
+ * The rendering is intentionally generic: it does not have per-tool
+ * templates. A `# Tool name` header, a `## Key` for each top-level field, and
+ * smart formatting for arrays of objects (tables when the rows share a
+ * schema) and scalars. Per-tool overrides can land in v1.9.1+ if any
+ * specific tool's output deserves a more curated view.
+ *
+ * Exposed for tests.
+ */
+export declare function renderAsMarkdown(value: unknown, toolName: string): string;