@mmerterden/multi-agent-toolkit-mcp 3.11.0 → 3.12.0

package/CHANGELOG.md

@@ -15,6 +15,76 @@ Releases before this file exists are recorded in the git tags and commit history
 
 ---
 
+## Unreleased
+
+---
+
+## 3.12.0
+
+The CI matrix had been red for five runs. Every fix below is something the red
+leg was pointing at; three of them are defects a green local run could not see,
+because the thing that broke was the assumption that the host is a Mac.
+
+### Fixed
+
+- **`ios_app_store_audit` answered PASS on an archive it never read.** Plist
+  parsing went entirely through `plutil`, a macOS binary. Off macOS every read
+  returned `null`, all 18 rules saw an empty archive, found nothing, and the
+  verdict came back clean - on a fixture built to be non-compliant. There are
+  now three answers instead of two: `plutil` when it is there, a small XML plist
+  reader when it is not, and an explicit record of what could be read by
+  neither. An audit with a non-empty `unreadablePlists` reports
+  `measurable: false` and an `archive-readable` error, so it can no longer
+  return PASS. An unreadable archive and a compliant one now look different.
+- **Argument rules were unreachable on a host without Xcode.** `handleIOS`
+  refused everything with "Xcode not installed" before any handler ran, so the
+  checks that answer from the arguments alone - `extra_args` shell
+  metacharacters, `project` XOR `workspace`, `mode=diff` without
+  `baseline_graph`, `ios_leaks` with neither `pid` nor `bundle_id`,
+  `ios_testflight_validate` with neither `ipa_path` nor `list_providers` - never
+  ran there, and the tests that prove them could not run either. They are
+  evaluated before the capability gate now, so a malformed call is named as
+  malformed on any host. The `extra_args` character class is additionally
+  declared as `pattern` on the tool schema, where a host can enforce it too.
+- **`build-stack-plugins.mjs`-style "works on the author's machine" in the
+  test harness.** Gate 10 printed a bare exit code when a suite failed, so a red
+  CI leg said which file failed and nothing about why. It now prints the failing
+  assertions, matching both reporter shapes `node:test` uses (TAP when piped,
+  spec on a terminal).
+
+### Changed
+
+- **`validateArgs` enforces the whole schema, not three keywords of it.** It
+  checked `type`, `required` and `enum`; `pattern`, `minimum`, `maximum`,
+  `minLength`, `maxLength`, `minItems`, `maxItems` and `items` were declarable
+  and unenforced. A schema the server does not keep is worse than no schema,
+  because the host shows the caller a contract that is not real. Array `items`
+  are validated element by element, including nested `required` and property
+  types. No existing tool declared any of the newly-enforced keywords, so
+  nothing that used to be accepted is now refused.
+- **`design-check` tests are `node:test` cases.** 1002 lines and 143 assertions
+  ran inside a hand-rolled tally that ended in `process.exit(1)`: the runner saw
+  one opaque suite, coverage could not attribute a line, and a failure named the
+  file rather than the check. Same assertions, now 143 reported cases. The two
+  that need `ripgrep` register as skips with a reason instead of printing a
+  warning nobody reads.
+- **Dependency advisories closed by upgrade, not by allowlist.** `fast-uri`,
+  `hono` and `qs` reach this tree only through `@modelcontextprotocol/sdk`;
+  bounded `overrides` resolve all three. `scripts/audit-allowlist.mjs` now has
+  an empty accepted list, and its stdio-only assertion runs on every invocation
+  rather than only when an advisory happens to be open.
+- **Repo tooling only, nothing in the published package.** A `PostToolUse` hook
+  (`.claude/settings.json` -> `scripts/hooks/stdout-hygiene.sh`) greps the file
+  that was just edited for `console.log` under `index.js` and `tools/`, and
+  fails the edit back to the author when it finds one. stdout is this server's
+  JSON-RPC channel, so a stray log corrupts the protocol stream and the client
+  reports only a closed connection. Gate 5 in `scripts/gates.sh` remains the
+  authority - it decides whether the package ships; the hook only moves the
+  catch from ship-day to edit-second, and gate 5 now also asserts that the hook
+  exists, parses and is wired.
+
+---
+
 ## 3.11.0
 
 ### Added

package/index.js

@@ -484,7 +484,7 @@ const IOS_TOOLS = [
   { name: "ios_export_ipa", description: "Export a .xcarchive to a signed .ipa via xcodebuild -exportArchive. Generates the exportOptions.plist from the arguments (method defaults to app-store-connect), so callers do not have to hand-maintain one. Returns the .ipa path plus parsed errors; a run that exits 0 without producing an .ipa is reported as a failure. Pair with ios_testflight_validate for the pre-submission gate.", inputSchema: { type: "object", properties: { archive_path: { type: "string", description: "Absolute path to the .xcarchive" }, output_dir: { type: "string", description: "Directory to write the .ipa into" }, method: { type: "string", description: "Export method: app-store-connect (default) | release-testing | enterprise | development" }, team_id: { type: "string", description: "Apple Developer team ID" }, provisioning_profiles: { type: "object", description: "Map of bundleId -> provisioning profile name (manual signing)" }, signing_style: { type: "string", description: "automatic | manual" }, upload_symbols: { type: "boolean", description: "Include symbols (default true)" }, allow_provisioning_updates: { type: "boolean", description: "Off by default. Lets xcodebuild register devices and create/modify provisioning profiles in the developer account - a change on Apple's side, so it is opt-in" }, timeout_sec: { type: "number", description: "Default 900" } }, required: ["archive_path", "output_dir"] } },
   { name: "ios_testflight_validate", description: "Run Apple's own pre-submission validation on an .ipa via `xcrun altool --validate-app`, then map returned ITMS error codes onto the App Store rule each one implies. This is the authoritative gate: unlike the static ios_app_store_audit it can catch an unregistered bundle ID, a profile that does not match the App Store Connect app record, a version+build pair already used, and entitlements not provisioned for the app ID. Auth is a 3-tier chain: ASC API key (api_key_id + api_issuer_id), else Apple ID + app-specific password referenced indirectly through a keychain item or env var (never passed by value), else the gate returns verdict SKIPPED with a reason. SKIPPED is not a pass - it means Apple was never asked. Set list_providers=true for a pre-flight that reports which teams the credentials can deliver for (needed when a corporate Apple ID belongs to several).", inputSchema: { type: "object", properties: { ipa_path: { type: "string", description: "Absolute path to the .ipa" }, platform: { type: "string", description: "ios (default) | appletvos | visionos | macos" }, api_key_id: { type: "string", description: "App Store Connect API key ID (tier 1)" }, api_issuer_id: { type: "string", description: "App Store Connect issuer ID (tier 1)" }, p8_path: { type: "string", description: "Explicit path to AuthKey_<id>.p8; otherwise altool's search dirs are used" }, apple_id: { type: "string", description: "Apple ID (tier 2)" }, keychain_item: { type: "string", description: "Keychain item holding the app-specific password (tier 2, preferred)" }, password_env_var: { type: "string", description: "Env var holding the app-specific password (tier 2 fallback)" }, provider_public_id: { type: "string", description: "Required when the account belongs to multiple providers" }, list_providers: { type: "boolean", description: "Pre-flight only: list deliverable providers and return" }, timeout_sec: { type: "number", description: "Default 900" } }, required: [] } },
   { name: "ios_app_store_audit", description: "Deep App Store Review compliance audit for .xcarchive bundles. 18-rule catalog covering privacy manifest, code signing, embedded SDKs, entitlements, asset hygiene, IPv6 compliance, debug-tool leak detection, Swift ABI compatibility, SDK floor (ITMS-90725), and more. Returns structured JSON with severity-ranked violations and ITMS error code mappings. Replaces ios_archive_audit (deprecated). Pass rules='core' for the 6 baseline checks (code-signing, entitlements, info-plist, privacy-manifest, binary-size, sdk-floor); 'all'|'deep' for the full 18-rule scan; CSV like 'binary-size,ipv6-compliance' for an explicit subset.", inputSchema: { type: "object", properties: { archive_path: { type: "string", description: "Absolute path to the .xcarchive bundle" }, rules: { type: "string", description: "'all' (default) | 'core' | 'deep' | comma-separated ruleIDs" } }, required: ["archive_path"] } },
-  { name: "ios_xcodebuild", description: "Build / test / clean an Xcode project with progressive disclosure. Returns one-line summary plus xcresult ID; drill in via ios_xcresult. Token-efficient - full log stays out of context unless requested.", inputSchema: { type: "object", properties: { project: { type: "string", description: "Path to .xcodeproj (mutually exclusive with workspace)" }, workspace: { type: "string", description: "Path to .xcworkspace (mutually exclusive with project)" }, scheme: { type: "string" }, configuration: { type: "string", description: "Debug / Release (default: Release)" }, destination: { type: "string", description: "Xcode destination string. Default: generic iOS Simulator; for action test, the booted simulator (xcodebuild refuses a generic destination for test)" }, action: { type: "string", enum: ["build", "test", "clean", "archive", "clean-build"], description: "Default: build" }, derived_data_path: { type: "string" }, extra_args: { type: "string", description: "Additional raw xcodebuild args appended verbatim" }, timeout_sec: { type: "number", description: "Build timeout in seconds (default 600)" } }, required: ["scheme"] } },
+  { name: "ios_xcodebuild", description: "Build / test / clean an Xcode project with progressive disclosure. Returns one-line summary plus xcresult ID; drill in via ios_xcresult. Token-efficient - full log stays out of context unless requested.", inputSchema: { type: "object", properties: { project: { type: "string", description: "Path to .xcodeproj (mutually exclusive with workspace)" }, workspace: { type: "string", description: "Path to .xcworkspace (mutually exclusive with project)" }, scheme: { type: "string" }, configuration: { type: "string", description: "Debug / Release (default: Release)" }, destination: { type: "string", description: "Xcode destination string. Default: generic iOS Simulator; for action test, the booted simulator (xcodebuild refuses a generic destination for test)" }, action: { type: "string", enum: ["build", "test", "clean", "archive", "clean-build"], description: "Default: build" }, derived_data_path: { type: "string" }, extra_args: { type: "string", description: "Additional raw xcodebuild args appended verbatim. Plain flags and values only - shell metacharacters are refused.", pattern: "^[^;&|`$(){}<>\\\\\\n]*$", patternHint: "may contain only plain flags and values (no shell metacharacters ; & | ` $ ( ) { } < > \\\\)" }, timeout_sec: { type: "number", description: "Build timeout in seconds (default 600)" } }, required: ["scheme"] } },
   { name: "ios_xcresult", description: "Drill into a previous ios_xcodebuild result by xcresult ID. Modes: summary (counts), errors (file:line + message), warnings, log (last N lines), tests (failed), metrics (XCTMetric performance results as JSON). Use this instead of dumping the whole build log into context.", inputSchema: { type: "object", properties: { id: { type: "string", description: "xcresult ID returned by ios_xcodebuild" }, mode: { type: "string", enum: ["summary", "errors", "warnings", "log", "tests", "metrics"], description: "Default: summary" }, log_lines: { type: "number", description: "Lines of raw log to return when mode=log (default 200)" }, test_id: { type: "string", description: "mode=metrics only: scope to one test case or suite instead of every measured test" } }, required: ["id"] } },
   { name: "ios_visual_diff", description: "Compare two PNG screenshots. Returns JSON with diff_pct, pass/fail vs threshold, and an optional diff image. Use for snapshot regression checks across light/dark, locale, dynamic type variants.", inputSchema: { type: "object", properties: { baseline: { type: "string", description: "Path to baseline PNG" }, current: { type: "string", description: "Path to current PNG" }, threshold: { type: "number", description: "Per-pixel color threshold 0..1 (default 0.1, lower = stricter)" }, max_diff_pct: { type: "number", description: "Fail if diff exceeds this percent (default 1.0)" }, output: { type: "string", description: "Path to write diff PNG (optional)" } }, required: ["baseline", "current"] } },
   { name: "ios_leaks", description: "Look for leaked memory in a running simulator (or host) process with /usr/bin/leaks. mode=snapshot reports the current leak count and bytes; mode=diff reports only leaks new since a saved memory graph, which is the shape a regression gate wants. Reports measurable:false when the target lacks get-task-allow rather than reporting it as clean - leaks exits 0 in that case, so an unmeasurable target and a clean one are indistinguishable by exit status. Debug builds are debuggable; Apple-signed apps are not.", inputSchema: { type: "object", properties: { pid: { type: "number", description: "Process id. Either this or bundle_id." }, bundle_id: { type: "string", description: "Bundle id of an app running on the booted simulator; its pid is resolved for you." }, device_id: { type: "string" }, mode: { type: "string", enum: ["snapshot", "diff"], description: "Default: snapshot" }, baseline_graph: { type: "string", description: "mode=diff: path to the memory graph saved by an earlier call" }, output_graph: { type: "string", description: "Save a memory graph here to use as a later baseline" } }, required: [] } },
@@ -496,7 +496,38 @@ const IOS_TOOLS = [
 // reports needs no simulator, so a missing Xcode must not refuse them.
 const IOS_TOOLS_WITHOUT_XCRUN = new Set(["ios_visual_diff", "ios_list_crashes", "ios_xcresult"]);
 
+// Argument rules a JSON Schema cannot state, because they relate two fields
+// rather than constrain one. They ran inside each handler, which put them
+// BEHIND the "Xcode not installed" gate: on a host without Xcode every
+// malformed call got the same answer as a well-formed one, and the tests that
+// prove these rules could not run there at all. That is how the Linux CI leg
+// found them. They answer from the arguments alone, so they belong in front of
+// the capability gate - a caller learns their call is wrong whether or not this
+// machine could have run it.
+const IOS_ARG_RULES = {
+  ios_leaks: (a) => {
+    if (!a.pid && !a.bundle_id) return "pass pid or bundle_id";
+    if ((a.mode || "snapshot") === "diff" && !a.baseline_graph) {
+      return "mode=diff needs baseline_graph, the memory graph saved by an earlier call";
+    }
+    return null;
+  },
+  ios_xcodebuild: (a) => {
+    if (!a.project && !a.workspace) return "project or workspace required";
+    if (a.project && a.workspace) return "pass project OR workspace, not both";
+    return null;
+  },
+  ios_accessibility_audit_deep: (a) => (!a.project && !a.workspace ? "pass project or workspace" : null),
+  ios_testflight_validate: (a) =>
+    !a.list_providers && !a.ipa_path ? "ipa_path is required (or pass list_providers=true)" : null,
+};
+
 async function handleIOS(name, args, ctx = {}) {
+  const argRule = IOS_ARG_RULES[name];
+  if (argRule) {
+    const bad = argRule(args);
+    if (bad) return `${ERROR_PREFIX}${bad}`;
+  }
   if (!HAS_XCRUN && !IOS_TOOLS_WITHOUT_XCRUN.has(name)) return `${ERROR_PREFIX}Xcode not installed - iOS tools unavailable. Install Xcode and run: xcode-select --install`;
   const did = (n) => { try { return iosDevice(n); } catch (e) { return null; } };
 
@@ -798,7 +829,6 @@ async function handleIOS(name, args, ctx = {}) {
         const res = await listProviders(auth, ctx.signal);
         return JSON.stringify({ authTier: auth.tier, authMethod: auth.method, ...res }, null, 2);
       }
-      if (!args.ipa_path) return "ERROR: ipa_path is required (or pass list_providers=true)";
       // Same finally rationale as ios_export_ipa: never leak the heartbeat.
       const stopHeartbeat = startHeartbeat(ctx, "altool --validate-app");
       let res;
@@ -831,8 +861,6 @@ async function handleIOS(name, args, ctx = {}) {
     }
     case "ios_xcodebuild": {
       if (!HAS_XCRUN) return "ERROR: xcrun not available - Xcode Command Line Tools required";
-      if (!args.project && !args.workspace) return "ERROR: project or workspace required";
-      if (args.project && args.workspace) return "ERROR: pass project OR workspace, not both";
       const action = args.action || "build";
       const config = args.configuration || "Release";
       let dest = args.destination;
@@ -852,9 +880,13 @@ async function handleIOS(name, args, ctx = {}) {
       const derivedFlag = args.derived_data_path ? `-derivedDataPath ${shq(args.derived_data_path)}` : "";
       const actionMap = { "clean-build": "clean build", build: "build", test: "test", clean: "clean", archive: "archive" };
       // extra_args is appended verbatim (multiple flags, so it can't be a single
-      // shq'd token), which makes it a shell passthrough. Reject the metacharacters
-      // that enable command chaining or substitution so it stays "extra xcodebuild
-      // flags" and cannot become an arbitrary-command tool.
+      // shq'd token), which makes it a shell passthrough. The same character class
+      // is declared as `pattern` on the tool schema, so the CallTool boundary
+      // refuses the payload before dispatch; this is the second line, kept because
+      // the string is one concatenation away from a shell. It lived only here
+      // until the Linux CI run showed why that was not enough: handleIOS returns
+      // "Xcode not installed" first, so on any host without Xcode the guard was
+      // never reached and the test that proves it works could not run.
       const extra = args.extra_args || "";
       if (/[;&|`$(){}<>\n\\]/.test(extra)) {
         return "ERROR: extra_args may contain only plain flags and values (no shell metacharacters ; & | ` $ ( ) { } < > \\).";
@@ -980,7 +1012,6 @@ async function handleIOS(name, args, ctx = {}) {
       const mode = args.mode || "snapshot";
       const graphOut = args.output_graph ? ` --outputGraph=${shq(args.output_graph)}` : "";
       if (mode === "diff") {
-        if (!args.baseline_graph) return "ERROR: mode=diff needs baseline_graph, the memory graph saved by an earlier call";
         if (!existsSync(args.baseline_graph)) return `ERROR: baseline graph not found at ${args.baseline_graph}`;
       }
       const diffArg = mode === "diff" ? ` --diffFrom=${shq(args.baseline_graph)}` : "";
@@ -1007,7 +1038,6 @@ async function handleIOS(name, args, ctx = {}) {
       }, null, 2);
     }
     case "ios_accessibility_audit_deep": {
-      if (!args.project && !args.workspace) return "ERROR: pass project or workspace";
       const container = args.workspace ? `-workspace ${shq(args.workspace)}` : `-project ${shq(args.project)}`;
       const d = iosDevice(args.device_id);
       const bundle = join(SCREENSHOT_DIR, `a11ydeep_${Date.now()}.xcresult`);
@@ -1354,17 +1384,29 @@ async function handleAndroid(name, args, ctx = {}) {
       }
       // 2. Signing check. apksigner exits 1 on a failed verification with the
       // verdict on stdout, so the output is captured whatever the status.
+      //
+      // "signed" needs positive evidence - apksigner's own `Verifies` line or a
+      // printed certificate. The branch used to be the else of three negative
+      // tests, so ANY output it did not recognise became "APK is signed": on a
+      // host with apksigner installed, 1KB of zero bytes audited as a correctly
+      // signed APK. It read as correct on a Mac only because apksigner is not
+      // there, and "command not found" is one of the strings it did recognise.
       const signingInfo = runCapture(`apksigner verify --print-certs ${shq(p)} 2>&1`);
+      const verifies = /^Verifies\b/m.test(signingInfo) || /Signer #\d+ certificate DN:/.test(signingInfo);
       if (/DOES NOT VERIFY/.test(signingInfo)) {
         findings.push({ check: "signing", status: "critical", detail: signingInfo.slice(0, 500) });
       } else if (isFailure(signingInfo) || /command not found|No such file or directory/i.test(signingInfo)) {
         findings.push({ check: "signing", status: "warning", detail: "apksigner not found - install Android SDK Build-Tools to verify the signature" });
-      } else if (/^(ERROR|Exception)/m.test(signingInfo)) {
-        findings.push({ check: "signing", status: "warning", detail: signingInfo.slice(0, 500) });
-      } else {
+      } else if (verifies) {
         const hasV2 = signingInfo.includes("v2 scheme") || (runOrNull(`apksigner verify -v ${shq(p)} 2>&1`) || "").includes("Verified using v2");
         findings.push({ check: "signing", status: "pass", detail: "APK is signed" });
         findings.push({ check: "signing_v2", status: hasV2 ? "pass" : "warning", detail: hasV2 ? "v2+ signature present" : "Only v1 signature - consider v2+ for tamper protection" });
+      } else {
+        findings.push({
+          check: "signing",
+          status: "warning",
+          detail: `apksigner did not report a verified signature; treat this as unverified, not as signed: ${signingInfo.slice(0, 400) || "(no output)"}`,
+        });
       }
       // 3. File size
       try {
@@ -1701,6 +1743,74 @@ function schemaTypeOk(value, type) {
   }
 }
 
+// Constraint keywords beyond type/required/enum. A schema that declares
+// `pattern` or `maximum` and has nobody enforcing it is worse than one that
+// declares nothing: the host shows the caller a contract the server does not
+// keep. Everything a tool literal is allowed to write is checked here.
+//
+// `patternHint` is ours, not JSON Schema. A regex in an error message tells a
+// human nothing; the hint says what the rule is in words. Hosts ignore unknown
+// keywords, so it rides along in inputSchema harmlessly.
+function checkConstraints(key, value, spec) {
+  if (spec.type && !schemaTypeOk(value, spec.type)) {
+    return `argument '${key}' must be ${spec.type}, got ${Array.isArray(value) ? "array" : typeof value}`;
+  }
+  if (Array.isArray(spec.enum) && !spec.enum.includes(value)) {
+    return `argument '${key}' must be one of ${JSON.stringify(spec.enum)}`;
+  }
+  if (typeof spec.pattern === "string" && !new RegExp(spec.pattern).test(String(value))) {
+    return spec.patternHint
+      ? `argument '${key}' ${spec.patternHint}`
+      : `argument '${key}' must match ${spec.pattern}`;
+  }
+  if (typeof value === "string" || typeof value === "number") {
+    const str = String(value);
+    if (Number.isFinite(spec.minLength) && str.length < spec.minLength) {
+      return `argument '${key}' must be at least ${spec.minLength} characters`;
+    }
+    if (Number.isFinite(spec.maxLength) && str.length > spec.maxLength) {
+      return `argument '${key}' must be at most ${spec.maxLength} characters`;
+    }
+  }
+  if (spec.type === "number" || spec.type === "integer") {
+    const num = Number(value);
+    if (Number.isFinite(spec.minimum) && num < spec.minimum) {
+      return `argument '${key}' must be >= ${spec.minimum}`;
+    }
+    if (Number.isFinite(spec.maximum) && num > spec.maximum) {
+      return `argument '${key}' must be <= ${spec.maximum}`;
+    }
+  }
+  if (Array.isArray(value)) {
+    if (Number.isFinite(spec.minItems) && value.length < spec.minItems) {
+      return `argument '${key}' must have at least ${spec.minItems} item(s)`;
+    }
+    if (Number.isFinite(spec.maxItems) && value.length > spec.maxItems) {
+      return `argument '${key}' must have at most ${spec.maxItems} item(s)`;
+    }
+    if (spec.items) {
+      for (let i = 0; i < value.length; i++) {
+        const err = checkConstraints(`${key}[${i}]`, value[i], spec.items);
+        if (err) return err;
+        for (const req of spec.items.required || []) {
+          const el = value[i];
+          if (el === null || typeof el !== "object" || el[req] === undefined || el[req] === null) {
+            return `argument '${key}[${i}]' is missing required field: ${req}`;
+          }
+        }
+        for (const [k, sub] of Object.entries(spec.items.properties || {})) {
+          const el = value[i];
+          if (el === null || typeof el !== "object") continue;
+          if (el[k] === undefined || el[k] === null) continue;
+          const subErr = checkConstraints(`${key}[${i}].${k}`, el[k], sub);
+          if (subErr) return subErr;
+        }
+      }
+    }
+  }
+  return null;
+}
+
 function validateArgs(name, args) {
   const schema = TOOL_SCHEMAS.get(name);
   if (!schema || schema.type !== "object") return null;
@@ -1712,12 +1822,8 @@ function validateArgs(name, args) {
   }
   for (const [key, spec] of Object.entries(props)) {
     if (args[key] === undefined || args[key] === null) continue;
-    if (spec.type && !schemaTypeOk(args[key], spec.type)) {
-      return `argument '${key}' must be ${spec.type}, got ${Array.isArray(args[key]) ? "array" : typeof args[key]}`;
-    }
-    if (Array.isArray(spec.enum) && !spec.enum.includes(args[key])) {
-      return `argument '${key}' must be one of ${JSON.stringify(spec.enum)}`;
-    }
+    const err = checkConstraints(key, args[key], spec);
+    if (err) return err;
   }
   return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-toolkit-mcp",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "MCP server for iOS Simulator, Android Emulator and headless web control. 99 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",
@@ -73,6 +73,12 @@
     "CHANGELOG.md",
     "LICENSE"
   ],
+  "_overridesReadme": "Three advisories reach this tree only through @modelcontextprotocol/sdk, and all three are fixed inside the major their consumer already depends on. The upper bound on fast-uri is load-bearing: ajv@8 declares ^3, and an unbounded >=3.1.6 resolves to 4.x, which is a different major under a dependency that never asked for it.",
+  "overrides": {
+    "fast-uri": ">=3.1.6 <4",
+    "hono": ">=4.13.5 <5",
+    "qs": ">=6.16.0 <7"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "pixelmatch": "^7.2.0",

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

@@ -3,14 +3,22 @@
  * 18 rules consume. Direct port of XCArchiveParser.swift +
  * InfoPlistParser.swift + PrivacyManifestParser.swift + EntitlementParser.swift.
  *
- * Plist parsing is delegated to `plutil -convert json` (system binary on
- * macOS, ships with the OS) - more reliable than any Node `plist` package
- * across the long tail of Apple plist quirks (binary plists, XML-with-DTD,
- * mixed array/dict roots).
+ * Plist parsing prefers `plutil -convert json` (system binary on macOS, ships
+ * with the OS) - more reliable than any Node `plist` package across the long
+ * tail of Apple plist quirks (binary plists, XML-with-DTD, mixed array/dict
+ * roots).
+ *
+ * When plutil is absent it falls back to a small XML reader, and when even that
+ * cannot apply - a binary plist off macOS - it records the miss rather than
+ * returning an empty object. That distinction is the whole point: every rule
+ * reads `infoPlist`, so a silent `{}` makes an unreadable archive audit exactly
+ * like a compliant one, and the tool answers PASS because it saw nothing. It
+ * shipped that way; a run with no plutil on PATH reported zero violations on a
+ * deliberately non-compliant fixture.
  */
 
 import { execSync } from "child_process";
-import { existsSync, readdirSync, statSync } from "fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
 import { shq } from "./models.js";
 import { join, basename } from "path";
 
@@ -23,16 +31,159 @@ function run(cmd) {
   }
 }
 
-/** Parse a binary or XML plist file into a JS object via `plutil`. */
+/** True when the `plutil` binary is on PATH. Probed once. */
+let _hasPlutil = null;
+export function hasPlutil() {
+  if (_hasPlutil === null) _hasPlutil = run("command -v plutil") !== "";
+  return _hasPlutil;
+}
+
+/**
+ * Plists this process could not read, as absolute paths. A rule that finds
+ * nothing in an unread plist is not evidence of compliance, and runAudit turns
+ * a non-empty list into a finding rather than letting the verdict stand.
+ */
+export const unreadablePlists = new Set();
+
+/**
+ * Empty the record. runAudit calls this before it parses anything, so the set
+ * describes the run being reported and not every run this process has done.
+ */
+export function resetUnreadablePlists() {
+  unreadablePlists.clear();
+}
+
+/** Decode the XML entities a plist can carry. */
+function unescapeXml(s) {
+  return s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_, d) => String.fromCharCode(Number(d)))
+    .replace(/&amp;/g, "&");
+}
+
+/**
+ * Minimal XML-plist reader for hosts without plutil.
+ *
+ * Deliberately small: it handles the element set an Info.plist, an entitlements
+ * file and a PrivacyInfo.xcprivacy actually use. It is not a general plist
+ * implementation and makes no attempt at binary plists - those return null and
+ * are recorded as unreadable, which is the honest answer.
+ *
+ * @param {string} xml
+ * @returns {object|Array|null}
+ */
+export function parseXmlPlist(xml) {
+  // <!DOCTYPE ...> and <?xml ...?> carry nothing we need and complicate the scan.
+  const body = xml.replace(/<\?xml[^>]*\?>/g, "").replace(/<!DOCTYPE[^>]*>/g, "");
+  const tokens = body.match(/<\/?[A-Za-z]+(?:\s[^>]*)?\/?>|[^<]+/g);
+  if (!tokens) return null;
+  let i = 0;
+
+  const next = () => tokens[i++];
+  const peek = () => tokens[i];
+
+  function readValue(tag) {
+    switch (tag) {
+      case "dict": {
+        const out = {};
+        for (;;) {
+          const t = peek();
+          if (t === undefined || t === "</dict>") {
+            next();
+            return out;
+          }
+          if (t === "<key>") {
+            next();
+            const k = unescapeXml(String(next() ?? "").trim());
+            next(); // </key>
+            const vt = String(next() ?? "").trim();
+            out[k] = readValue(vt.replace(/^<|\/?>$/g, "").split(/\s/)[0]);
+          } else {
+            next();
+          }
+        }
+      }
+      case "array": {
+        const out = [];
+        for (;;) {
+          const t = peek();
+          if (t === undefined || t === "</array>") {
+            next();
+            return out;
+          }
+          const vt = String(next() ?? "").trim();
+          if (!vt.startsWith("<")) continue;
+          out.push(readValue(vt.replace(/^<|\/?>$/g, "").split(/\s/)[0]));
+        }
+      }
+      case "string":
+      case "data":
+      case "date": {
+        const raw = peek() !== undefined && !String(peek()).startsWith("<") ? String(next()) : "";
+        if (String(peek() ?? "").startsWith("</")) next();
+        return unescapeXml(raw);
+      }
+      case "integer":
+      case "real": {
+        const raw = peek() !== undefined && !String(peek()).startsWith("<") ? String(next()) : "0";
+        if (String(peek() ?? "").startsWith("</")) next();
+        return Number(raw.trim());
+      }
+      case "true":
+        return true;
+      case "false":
+        return false;
+      default:
+        return null;
+    }
+  }
+
+  for (;;) {
+    const t = next();
+    if (t === undefined) return null;
+    const s = String(t).trim();
+    if (!s.startsWith("<plist")) continue;
+    for (;;) {
+      const u = next();
+      if (u === undefined) return null;
+      const v = String(u).trim();
+      if (!v.startsWith("<")) continue;
+      return readValue(v.replace(/^<|\/?>$/g, "").split(/\s/)[0]);
+    }
+  }
+}
+
+/** Parse a binary or XML plist file into a JS object. */
 export function parsePlist(plistPath) {
   if (!existsSync(plistPath)) return null;
-  const json = run(`plutil -convert json -o - ${shq(plistPath)} 2>/dev/null`);
-  if (!json) return null;
+  if (hasPlutil()) {
+    const json = run(`plutil -convert json -o - ${shq(plistPath)} 2>/dev/null`);
+    if (json) {
+      try {
+        return JSON.parse(json);
+      } catch {
+        /* fall through to the XML reader */
+      }
+    }
+  }
+  let raw;
   try {
-    return JSON.parse(json);
+    raw = readFileSync(plistPath, "utf-8");
   } catch {
+    unreadablePlists.add(plistPath);
+    return null;
+  }
+  // A binary plist starts with the magic "bplist"; there is no reading it here.
+  if (raw.startsWith("bplist")) {
+    unreadablePlists.add(plistPath);
     return null;
   }
+  const parsed = parseXmlPlist(raw);
+  if (parsed === null) unreadablePlists.add(plistPath);
+  return parsed;
 }
 
 /** Recursively measure total size of a directory in bytes. */

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

@@ -21,7 +21,7 @@
  * the rest of the scan.
  */
 
-import { parseArchive } from "./context.js";
+import { hasPlutil, parseArchive, resetUnreadablePlists, unreadablePlists } from "./context.js";
 import { compareSeverity } from "./models.js";
 
 // ---------- Rule registry --------------------------------------------------
@@ -93,6 +93,7 @@ function resolveRuleSelection(rules) {
  * @returns {Promise<object>} structured audit report
  */
 export async function runAudit({ archivePath, rules = "all", options = {} } = {}) {
+  resetUnreadablePlists();
   const ctx = parseArchive(archivePath);
 
   const selectedIDs = new Set(resolveRuleSelection(rules));
@@ -134,6 +135,25 @@ export async function runAudit({ archivePath, rules = "all", options = {} } = {}
     }
   }
 
+  // A rule that found nothing in a plist nobody could read has not measured
+  // anything, and the audit must not let that reach the caller as compliance.
+  // Every rule reads infoPlist, so one unread plist can silence all eighteen:
+  // the tool answered PASS on a deliberately non-compliant fixture the first
+  // time it ran on a host without plutil. Reported as an error so the verdict
+  // is not PASS, with the cause named - this is the tool's reach, not the
+  // archive's fault.
+  const unreadable = [...unreadablePlists].sort();
+  if (unreadable.length > 0) {
+    violations.push({
+      ruleID: "archive-readable",
+      severity: "error",
+      message: `${unreadable.length} plist(s) could not be read, so the rules below them measured nothing: ${unreadable.join(", ")}`,
+      suggestion: hasPlutil()
+        ? "The files are present but neither plutil nor the XML reader could parse them. Re-export the archive, or open an issue with one of the files attached."
+        : "Binary plists need `plutil`, which ships with macOS. Run this audit on macOS, or convert the archive's plists to XML first (`plutil -convert xml1`).",
+    });
+  }
+
   // Sort: error → warning → info, then by ruleID alphabetically inside each.
   violations.sort((a, b) => {
     const c = compareSeverity(b.severity, a.severity);
@@ -156,6 +176,9 @@ export async function runAudit({ archivePath, rules = "all", options = {} } = {}
     app: ctx.appName,
     rulesRun: ranIDs,
     rulesSkipped: skippedIDs,
+    // Explicit, so a caller can tell "clean" from "could not look".
+    measurable: unreadable.length === 0,
+    unreadablePlists: unreadable,
     summary,
     verdict,
     violations,

package/tools/offload/index.js

@@ -58,15 +58,35 @@ function pruneEntries(dir, { keepFiles, keepDays, now, keep, match }) {
         }
       })
       .filter(Boolean)
-      .sort((a, b) => b.mtime - a.mtime);
-
-    for (let i = 0; i < entries.length; i++) {
-      if (keepSet.has(resolve(entries[i].full))) continue;
-      const tooOld = entries[i].mtime < cutoff;
-      const tooMany = i >= keepFiles;
-      if (!tooOld && !tooMany) continue;
+      // Name as the tie-break, because mtime ties are not a corner case. APFS
+      // records nanoseconds, so five files written in a loop have five distinct
+      // stamps; ext4 on a CI runner records one, so they have the same stamp and
+      // "the newest" is whatever order readdir happened to return. Without this
+      // the retained set differs per filesystem.
+      .sort((a, b) => b.mtime - a.mtime || (a.full < b.full ? 1 : a.full > b.full ? -1 : 0));
+
+    // keepFiles is the size of the directory after the prune, not the size of
+    // the part of it retention got to decide. A promised file is one of the
+    // survivors, so it takes one of the slots - reserved up front rather than
+    // counted as the loop reaches it, because otherwise the answer depends on
+    // where that file happens to sort. It used to be neither: a keepSet entry
+    // was skipped without consuming anything, so keepFiles: 1 plus one promised
+    // file left TWO files behind. On APFS the promised file is genuinely the
+    // newest and sorted first, which hid it; on a filesystem whose mtimes tie it
+    // sorted anywhere and the directory kept a stale file forever.
+    const reserved = entries.filter((e) => keepSet.has(resolve(e.full))).length;
+    const budget = Math.max(0, keepFiles - reserved);
+    let kept = 0;
+    for (const entry of entries) {
+      if (keepSet.has(resolve(entry.full))) continue;
+      const tooOld = entry.mtime < cutoff;
+      const tooMany = kept >= budget;
+      if (!tooOld && !tooMany) {
+        kept++;
+        continue;
+      }
       try {
-        rmSync(entries[i].full, { recursive: true, force: true });
+        rmSync(entry.full, { recursive: true, force: true });
         removed++;
       } catch {
         // A file another process holds open is skipped, not fatal.