memorydetective 1.7.0 → 1.8.1

package/dist/tools/replayScenario.js

@@ -0,0 +1,187 @@
+/**
+ * Drive the iOS Simulator through a sequence of UI actions to amplify a
+ * suspected leak before capturing a memgraph. Tied to the leak/perf workflow:
+ * the only reason this tool exists is to make verify-fix loops reproducible
+ * (same scenario before/after a fix) and to surface leaks that only manifest
+ * after N iterations of a flow.
+ *
+ * Soft dependency on `axe` (https://github.com/cameroncooke/AXe). When axe is
+ * not on PATH, this tool returns ok:false with a structured workaroundNotice
+ * pointing the caller at the install instructions, instead of throwing.
+ */
+import { z } from "zod";
+import { existsSync, mkdirSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { checkAxeAvailable, describeUI, swipe, tap, typeText, } from "../runtime/axe.js";
+const tapActionSchema = z.object({
+    type: z.literal("tap"),
+    label: z
+        .string()
+        .optional()
+        .describe("Match an element by its accessibility label or identifier. Mutually exclusive with `coords` and `elementId`."),
+    elementId: z
+        .string()
+        .optional()
+        .describe("Match an element by its accessibility identifier. Mutually exclusive with `label` and `coords`."),
+    coords: z
+        .tuple([z.number(), z.number()])
+        .optional()
+        .describe("Tap at explicit [x, y] coordinates. Mutually exclusive with `label` and `elementId`."),
+});
+const swipeActionSchema = z.object({
+    type: z.literal("swipe"),
+    from: z.tuple([z.number(), z.number()]),
+    to: z.tuple([z.number(), z.number()]),
+    durationMs: z.number().int().positive().max(5000).default(250),
+});
+const waitActionSchema = z.object({
+    type: z.literal("wait"),
+    seconds: z.number().nonnegative().max(60),
+});
+const typeActionSchema = z.object({
+    type: z.literal("type"),
+    text: z.string(),
+});
+const actionSchema = z.discriminatedUnion("type", [
+    tapActionSchema,
+    swipeActionSchema,
+    waitActionSchema,
+    typeActionSchema,
+]);
+export const replayScenarioShape = {
+    simulatorUDID: z
+        .string()
+        .min(1)
+        .describe("UDID of the booted simulator. Use listTraceDevices to find one."),
+    actions: z
+        .array(actionSchema)
+        .min(1)
+        .describe("Ordered list of UI actions: { type: 'tap', label|elementId|coords }, { type: 'swipe', from, to }, { type: 'wait', seconds }, or { type: 'type', text }."),
+    repeat: z
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .default(1)
+        .describe("Run the entire actions sequence this many times. Default 1. Use 5-10 to amplify subtle leaks that accumulate per repetition."),
+    settleBetweenActionsMs: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(10_000)
+        .default(500)
+        .describe("Pause between consecutive actions in milliseconds. Default 500. Increase for animation-heavy flows."),
+    finalUITreePath: z
+        .string()
+        .optional()
+        .describe("When provided, after the scenario completes the final UI tree is written here as JSON for the caller to verify the app ended in the expected state."),
+};
+export const replayScenarioSchema = z.object(replayScenarioShape);
+export async function replayScenario(input) {
+    const availability = await checkAxeAvailable();
+    if (!availability.available) {
+        return {
+            ok: false,
+            executedSteps: 0,
+            failures: [],
+            totalDurationMs: 0,
+            workaroundNotice: {
+                issue: "axe-not-found",
+                message: availability.installHint ??
+                    "axe CLI not found. Required for replayScenario.",
+            },
+        };
+    }
+    const start = Date.now();
+    const failures = [];
+    let executedSteps = 0;
+    for (let iteration = 0; iteration < input.repeat; iteration++) {
+        for (let i = 0; i < input.actions.length; i++) {
+            const action = input.actions[i];
+            try {
+                await executeAction(input.simulatorUDID, action);
+                executedSteps++;
+            }
+            catch (err) {
+                failures.push({
+                    iteration,
+                    stepIndex: i,
+                    reason: err.message,
+                });
+                // Continue with remaining actions in this iteration so the agent
+                // gets the full picture instead of one early failure masking the rest.
+            }
+            if (input.settleBetweenActionsMs > 0) {
+                await sleep(input.settleBetweenActionsMs);
+            }
+        }
+    }
+    let finalUITreePath;
+    if (input.finalUITreePath) {
+        try {
+            const tree = await describeUI(input.simulatorUDID);
+            ensureParentDir(input.finalUITreePath);
+            await writeFile(input.finalUITreePath, JSON.stringify(tree, null, 2), "utf8");
+            finalUITreePath = input.finalUITreePath;
+        }
+        catch (err) {
+            failures.push({
+                iteration: input.repeat,
+                stepIndex: input.actions.length,
+                reason: `Failed to capture final UI tree: ${err.message}`,
+            });
+        }
+    }
+    return {
+        ok: failures.length === 0,
+        executedSteps,
+        failures,
+        totalDurationMs: Date.now() - start,
+        ...(finalUITreePath ? { finalUITreePath } : {}),
+    };
+}
+async function executeAction(udid, action) {
+    switch (action.type) {
+        case "tap": {
+            const target = resolveTapTarget(action);
+            await tap(udid, target);
+            return;
+        }
+        case "swipe":
+            await swipe(udid, { x: action.from[0], y: action.from[1] }, { x: action.to[0], y: action.to[1] }, action.durationMs);
+            return;
+        case "wait":
+            await sleep(action.seconds * 1000);
+            return;
+        case "type":
+            await typeText(udid, action.text);
+            return;
+    }
+}
+/** Pure: convert a tap-action input shape into the runtime TapTarget union. Exposed for tests. */
+export function resolveTapTarget(action) {
+    const provided = [action.label, action.elementId, action.coords].filter((v) => v !== undefined).length;
+    if (provided !== 1) {
+        throw new Error("tap action must provide exactly one of: label, elementId, coords.");
+    }
+    if (action.coords) {
+        return { kind: "coords", x: action.coords[0], y: action.coords[1] };
+    }
+    if (action.label) {
+        return { kind: "label", value: action.label };
+    }
+    return { kind: "elementId", value: action.elementId };
+}
+function ensureParentDir(filePath) {
+    const slash = filePath.lastIndexOf("/");
+    if (slash === -1)
+        return;
+    const dir = filePath.slice(0, slash);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=replayScenario.js.map

package/dist/tools/replayScenario.js.map

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

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "memorydetective",
-  "version": "1.7.0",
-  "description": "MCP server for iOS leak hunting and performance investigation. Reads .memgraph + .trace files, captures new ones via xctrace and leaks(1), classifies retain cycles.",
+  "version": "1.8.1",
+  "mcpName": "io.github.carloshpdoc/memorydetective",
+  "description": "MCP server for iOS leak hunting and performance investigation. 31 tools across .memgraph and .trace files, 34-pattern retain-cycle classifier with Swift fixTemplate snippets, single-call build+boot+launch with MallocStackLogging for macOS 26.x leaks --outputGraph regression, replayScenario + captureScenarioState for verify-fix loops, compareTracesByPattern for CI gating on hangs/animation-hitches/app-launch regressions, SourceKit-LSP source bridging. macOS only (depends on leaks(1) and xctrace).",
   "type": "module",
   "bin": {
     "memorydetective": "dist/index.js"