@mmerterden/multi-agent-toolkit-mcp 3.7.0 → 3.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-toolkit-mcp",
-  "version": "3.7.0",
+  "version": "3.9.0",
   "description": "MCP server for iOS Simulator, Android Emulator and headless web control. 87 tools: device automation (tap/swipe/type), accessibility audits, visual diff, crash logs, App Store / Play Store pre-submission compliance. Runs standalone over stdio with any MCP client.",
   "type": "module",
   "main": "index.js",

package/tools/design-check/index.js

@@ -128,7 +128,7 @@ function safeArg(x, label) {
   return x;
 }
 
-// ctx: { run, iosDevice, adbFlag, dumperScript }
+// ctx: { run, iosDevice, adbFlag, dumperScript, dumperCommand }
 export async function handleDesign(name, args, ctx) {
   switch (name) {
     case "design_mock_detect":
@@ -172,7 +172,8 @@ export async function handleDesign(name, args, ctx) {
           }
         }
         const depth = Number(args.max_depth) || 12;
-        const raw = ctx.run(`swift ${shq(ctx.dumperScript)} ${depth}`, { timeout: 15000 });
+        const dumper = ctx.dumperCommand ? ctx.dumperCommand() : `swift ${shq(ctx.dumperScript)}`;
+        const raw = ctx.run(`${dumper} ${depth}`, { timeout: 15000 });
         let tree; try { tree = JSON.parse(raw); } catch { return `ERROR: idb unavailable and AX dumper failed: ${String(raw).slice(0, 200)}`; }
         const elements = flattenIosAxTree(tree);
         const rf = tree.frame || {};

package/tools/design-check/report.js

@@ -541,6 +541,19 @@ ${variants.map((v, i) => variantSection(v, i, fileKey, L)).join("")}
 </body></html>`;
 }
 
+// The browser is closed on every path: a failed setContent/pdf used to leave a
+// headless Chromium running for the life of the server.
+export async function renderPdf({ html, pdfPath, chromium }) {
+  const browser = await chromium.launch();
+  try {
+    const page = await browser.newPage();
+    await page.setContent(html, { waitUntil: "networkidle" });
+    await page.pdf({ path: pdfPath, format: "A4", printBackground: true, margin: { top: "12mm", bottom: "12mm", left: "10mm", right: "10mm" } });
+  } finally {
+    await browser.close();
+  }
+}
+
 export async function writeReport({ report, outDir, formats = ["html"] }) {
   const html = renderHtml(report);
   const out = {};
@@ -571,11 +584,8 @@ export async function writeReport({ report, outDir, formats = ["html"] }) {
     let ok = false, err = "";
     try {
       const { chromium } = await import("playwright");
-      const browser = await chromium.launch();
-      const page = await browser.newPage();
-      await page.setContent(html, { waitUntil: "networkidle" });
-      await page.pdf({ path: pdfPath, format: "A4", printBackground: true, margin: { top: "12mm", bottom: "12mm", left: "10mm", right: "10mm" } });
-      await browser.close(); ok = true;
+      await renderPdf({ html, pdfPath, chromium });
+      ok = true;
     } catch (e) {
       err = e.message;
       // Fallback: use the chrome-headless-shell binary directly (no `playwright` package).

package/tools/ios-app-store-audit/index.js

@@ -67,8 +67,18 @@ const RULE_GROUPS = {
 function resolveRuleSelection(rules) {
   if (!rules || rules === "all" || rules === "deep") return RULE_GROUPS.all();
   if (rules === "core") return RULE_GROUPS.core();
-  // Comma-separated explicit list.
-  return rules.split(",").map((s) => s.trim()).filter(Boolean);
+  // Comma-separated explicit list. An unknown id used to select nothing, and
+  // nothing selected audited nothing and reported PASS.
+  const known = RULE_REGISTRY.map((r) => r.id);
+  const asked = String(rules).split(",").map((s) => s.trim()).filter(Boolean);
+  const unknown = asked.filter((id) => !known.includes(id));
+  if (unknown.length > 0) {
+    throw new Error(`unknown rule id(s): ${unknown.join(", ")}. Valid values: all, core, deep, or a comma-separated subset of ${known.join(", ")}`);
+  }
+  if (asked.length === 0) {
+    throw new Error(`no rules selected from "${rules}". Valid values: all, core, deep, or a comma-separated subset of ${known.join(", ")}`);
+  }
+  return asked;
 }
 
 // ---------- Public entry ---------------------------------------------------
@@ -87,6 +97,7 @@ export async function runAudit({ archivePath, rules = "all", options = {} } = {}
 
   const selectedIDs = new Set(resolveRuleSelection(rules));
   const toRun = RULE_REGISTRY.filter((r) => selectedIDs.has(r.id));
+  if (toRun.length === 0) throw new Error("no rules selected; an audit that runs nothing cannot pass");
 
   const violations = [];
   const ranIDs = [];
@@ -135,6 +146,9 @@ export async function runAudit({ archivePath, rules = "all", options = {} } = {}
     info: violations.filter((v) => v.severity === "info").length,
     total: violations.length,
   };
+  if (ranIDs.length === 0) {
+    throw new Error(`no rule ran: ${skippedIDs.map((s) => `${s.id} (${s.reason})`).join("; ")}`);
+  }
   const verdict = summary.error > 0 ? "FAIL" : summary.warning > 0 ? "WARN" : "PASS";
 
   return {

package/tools/ios-testflight/index.js

@@ -24,7 +24,7 @@
  */
 
 import { execFile } from "child_process";
-import { existsSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "fs";
+import { existsSync, mkdtempSync, readdirSync, rmSync, statSync, writeFileSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
 
@@ -227,6 +227,15 @@ export function resolveAuth(opts = {}) {
  * @param {string} [opts.signingStyle]    "automatic" | "manual"
  * @returns {string} plist XML
  */
+export function xmlEscape(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
 export function buildExportOptionsPlist(opts) {
   const {
     method = "app-store-connect",
@@ -236,17 +245,17 @@ export function buildExportOptionsPlist(opts) {
     signingStyle,
   } = opts;
 
-  const entries = [`    <key>method</key>\n    <string>${method}</string>`];
+  const entries = [`    <key>method</key>\n    <string>${xmlEscape(method)}</string>`];
   entries.push(
     `    <key>uploadSymbols</key>\n    <${uploadSymbols ? "true" : "false"}/>`,
   );
-  if (teamId) entries.push(`    <key>teamID</key>\n    <string>${teamId}</string>`);
+  if (teamId) entries.push(`    <key>teamID</key>\n    <string>${xmlEscape(teamId)}</string>`);
   if (signingStyle) {
-    entries.push(`    <key>signingStyle</key>\n    <string>${signingStyle}</string>`);
+    entries.push(`    <key>signingStyle</key>\n    <string>${xmlEscape(signingStyle)}</string>`);
   }
   if (provisioningProfiles && Object.keys(provisioningProfiles).length > 0) {
     const rows = Object.entries(provisioningProfiles)
-      .map(([bundleId, profile]) => `      <key>${bundleId}</key>\n      <string>${profile}</string>`)
+      .map(([bundleId, profile]) => `      <key>${xmlEscape(bundleId)}</key>\n      <string>${xmlEscape(profile)}</string>`)
       .join("\n");
     entries.push(`    <key>provisioningProfiles</key>\n    <dict>\n${rows}\n    </dict>`);
   }
@@ -263,6 +272,36 @@ export function buildExportOptionsPlist(opts) {
   ].join("\n");
 }
 
+/**
+ * The .ipa this export wrote: the newest one in output_dir, and only if it was
+ * written after the export started. An older .ipa left by a previous run was
+ * reported as this run's result.
+ *
+ * @param {string} outputDir
+ * @param {number} notBefore - epoch ms; files modified earlier are stale
+ * @returns {{ipaPath: string|null, stale: string[]}}
+ */
+export function pickExportedIpa(outputDir, notBefore) {
+  if (!outputDir || !existsSync(outputDir)) return { ipaPath: null, stale: [] };
+  const candidates = readdirSync(outputDir)
+    .filter((f) => f.endsWith(".ipa"))
+    .map((f) => {
+      const full = join(outputDir, f);
+      try {
+        return { full, mtime: statSync(full).mtimeMs };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.mtime - a.mtime);
+  const fresh = candidates.find((c) => c.mtime >= notBefore);
+  return {
+    ipaPath: fresh ? fresh.full : null,
+    stale: candidates.filter((c) => c.mtime < notBefore).map((c) => c.full),
+  };
+}
+
 /**
  * Export a .xcarchive to a signed .ipa.
  *
@@ -305,6 +344,8 @@ export async function exportIpa(opts) {
   // want that.
   if (allowProvisioningUpdates) argv.push("-allowProvisioningUpdates");
 
+  // 2s of slack for filesystems with coarse mtime granularity.
+  const startedAt = Date.now() - 2000;
   const { err, stdout, stderr } = await execFileAsync("xcodebuild", argv, {
     encoding: "utf-8",
     timeout: timeoutSec * 1000,
@@ -317,13 +358,15 @@ export async function exportIpa(opts) {
     : stdout;
 
   const errors = (log.match(/^.*error:.*$/gim) || []).map((l) => l.trim());
-  let ipaPath;
-  if (existsSync(outputDir)) {
-    const ipa = readdirSync(outputDir).find((f) => f.endsWith(".ipa"));
-    if (ipa) ipaPath = join(outputDir, ipa);
-  }
+  const picked = pickExportedIpa(outputDir, startedAt);
+  const ipaPath = picked.ipaPath || undefined;
   // xcodebuild can exit 0 and still produce nothing useful.
-  if (!ipaPath) ok = false;
+  if (!ipaPath) {
+    ok = false;
+    if (picked.stale.length > 0) {
+      errors.push(`error: no .ipa was written by this export; ${picked.stale.join(", ")} in output_dir predates this run`);
+    }
+  }
 
   // The plist is consumed by the time xcodebuild returns. Leaving the temp dir
   // behind would accumulate one per export for the life of the machine; the path

package/tools/memory/index.js

@@ -85,11 +85,12 @@ const MEMINFO_ROWS = [
  * snapshots of the same flow is the shape a leak takes, where a single
  * absolute number says almost nothing.
  *
- * NOT VERIFIED ON A DEVICE. Written against the documented output shape on a
- * machine with adb installed but no device or emulator to run it against,
- * unlike the leaks parser above, which was
- * checked against live output. The tests below pin the shape this expects; the
- * first real run is the measurement.
+ * Verified against a real device: an Android 35 Pixel emulator, after the parser
+ * had first been written from documentation alone. That first version returned
+ * null for the swap total on every real device, because the documented shape
+ * says "TOTAL SWAP (KB):" and the device prints "TOTAL SWAP PSS:". Both are
+ * accepted now. It is the clearest argument in this file for running a parser
+ * against the thing it parses.
  *
  * @param {string} raw
  * @returns {{measurable: boolean, reason: string|null, pss: object, totalPssKb: number|null,
@@ -118,7 +119,11 @@ export function parseMeminfoOutput(raw) {
   };
   const totalPssKb = num(/TOTAL PSS:\s*(\d+)/i);
   const totalRssKb = num(/TOTAL RSS:\s*(\d+)/i);
-  const totalSwapKb = num(/TOTAL SWAP \(KB\):\s*(\d+)/i);
+  // Two spellings in the wild: "TOTAL SWAP (KB):" in the documented shape and
+  // "TOTAL SWAP PSS:" on a real Android 35 device, which is what a Pixel
+  // emulator actually printed. The first regex, written from documentation,
+  // returned null against every real device.
+  const totalSwapKb = num(/TOTAL SWAP(?: \(KB\)| PSS)?:\s*(\d+)/i);
 
   if (found === 0 && totalPssKb === null) {
     return { measurable: false, reason: "no App Summary block in the dumpsys output", pss: {}, totalPssKb: null, totalRssKb: null, totalSwapKb: null };
@@ -127,17 +132,32 @@ export function parseMeminfoOutput(raw) {
   return { measurable: true, reason: null, pss, totalPssKb, totalRssKb, totalSwapKb };
 }
 
+/**
+ * Accept both snapshot shapes: the parser's (pss, totalPssKb) and the one the
+ * android_meminfo tool emits and hands back as baseline_json (pss_kb,
+ * total_pss_kb). The diff read only the parser shape while the tool emitted
+ * the other, so mode=diff never compared anything.
+ */
+function normalizeSnapshot(s) {
+  if (!s || typeof s !== "object") return null;
+  const pss = s.pss && typeof s.pss === "object" ? s.pss : s.pss_kb && typeof s.pss_kb === "object" ? s.pss_kb : {};
+  const totalPssKb = typeof s.totalPssKb === "number" ? s.totalPssKb : typeof s.total_pss_kb === "number" ? s.total_pss_kb : null;
+  return { measurable: s.measurable === true, pss, totalPssKb };
+}
+
 /**
  * Difference between two meminfo snapshots, in KB.
  *
  * Only keys present in both are compared; a key missing from either side is
  * absent from the result rather than counted as zero growth.
  *
- * @param {object} before - parseMeminfoOutput result
- * @param {object} after - parseMeminfoOutput result
+ * @param {object} before - parseMeminfoOutput result, or the android_meminfo snapshot payload
+ * @param {object} after - parseMeminfoOutput result, or the android_meminfo snapshot payload
  * @returns {{comparable: boolean, reason: string|null, deltaKb: object, totalPssDeltaKb: number|null}}
  */
-export function diffMeminfo(before, after) {
+export function diffMeminfo(beforeRaw, afterRaw) {
+  const before = normalizeSnapshot(beforeRaw);
+  const after = normalizeSnapshot(afterRaw);
   if (!before?.measurable || !after?.measurable) {
     return { comparable: false, reason: "one of the snapshots was not measurable", deltaKb: {}, totalPssDeltaKb: null };
   }

package/tools/offload/index.js

@@ -15,7 +15,7 @@
 // outputSchema answers with JSON the host parses as structuredContent, and
 // replacing that with a summary would break the parse.
 
-import { writeFileSync, readFileSync, mkdirSync, existsSync, readdirSync, statSync, unlinkSync } from "fs";
+import { writeFileSync, readFileSync, mkdirSync, existsSync, readdirSync, statSync, rmSync } from "fs";
 import { join, resolve, sep } from "path";
 import { homedir } from "os";
 
@@ -31,20 +31,24 @@ const TAIL_LINES = 20;
 export const OFFLOAD_KEEP_FILES = 50;
 export const OFFLOAD_KEEP_DAYS = 7;
 
-// `keep` is the file the caller just wrote. It is never deleted, whatever the
-// retention numbers say: the returned text promises that path to the caller, and
-// this module exists precisely because losing the payload is the failure mode. A
-// keepFiles of 0 must bound the directory, not break the answer.
-export function pruneOffloadDir(dir, opts = {}) {
-  const keepFiles = opts.keepFiles ?? OFFLOAD_KEEP_FILES;
-  const keepDays = opts.keepDays ?? OFFLOAD_KEEP_DAYS;
-  const now = opts.now ?? Date.now();
-  const keep = typeof opts.keep === "string" ? resolve(opts.keep) : null;
+// The server's own scratch directory (screenshots, UI dumps, push payloads,
+// build logs, .xcresult bundles) gets the same treatment with a wider count,
+// since a single design audit writes 100+ captures.
+export const WORK_KEEP_ENTRIES = 200;
+export const WORK_KEEP_DAYS = 7;
+
+// `keep` names the file(s) the caller was just promised. They are never deleted,
+// whatever the retention numbers say: the returned text promises that path to
+// the caller, and this module exists precisely because losing the payload is the
+// failure mode. A keepFiles of 0 must bound the directory, not break the answer.
+function pruneEntries(dir, { keepFiles, keepDays, now, keep, match }) {
+  const keepList = Array.isArray(keep) ? keep : keep ? [keep] : [];
+  const keepSet = new Set(keepList.filter((k) => typeof k === "string").map((k) => resolve(k)));
   const cutoff = now - keepDays * 24 * 60 * 60 * 1000;
   let removed = 0;
   try {
     const entries = readdirSync(dir)
-      .filter((n) => n.endsWith(".txt"))
+      .filter(match)
       .map((n) => {
         const full = join(dir, n);
         try {
@@ -57,12 +61,12 @@ export function pruneOffloadDir(dir, opts = {}) {
       .sort((a, b) => b.mtime - a.mtime);
 
     for (let i = 0; i < entries.length; i++) {
-      if (keep && resolve(entries[i].full) === keep) continue;
+      if (keepSet.has(resolve(entries[i].full))) continue;
       const tooOld = entries[i].mtime < cutoff;
       const tooMany = i >= keepFiles;
       if (!tooOld && !tooMany) continue;
       try {
-        unlinkSync(entries[i].full);
+        rmSync(entries[i].full, { recursive: true, force: true });
         removed++;
       } catch {
         // A file another process holds open is skipped, not fatal.
@@ -74,6 +78,28 @@ export function pruneOffloadDir(dir, opts = {}) {
   return removed;
 }
 
+export function pruneOffloadDir(dir, opts = {}) {
+  return pruneEntries(dir, {
+    keepFiles: opts.keepFiles ?? OFFLOAD_KEEP_FILES,
+    keepDays: opts.keepDays ?? OFFLOAD_KEEP_DAYS,
+    now: opts.now ?? Date.now(),
+    keep: opts.keep,
+    match: (n) => n.endsWith(".txt"),
+  });
+}
+
+// Every entry counts here, directories included: an .xcresult bundle is a
+// directory and was the largest thing nothing ever removed.
+export function pruneWorkDir(dir, opts = {}) {
+  return pruneEntries(dir, {
+    keepFiles: opts.keepFiles ?? WORK_KEEP_ENTRIES,
+    keepDays: opts.keepDays ?? WORK_KEEP_DAYS,
+    now: opts.now ?? Date.now(),
+    keep: opts.keep,
+    match: () => true,
+  });
+}
+
 let lastOffload = null;
 
 export function lastOffloadRecord() {