@mmerterden/dev-toolkit-mcp 2.24.1

package/tools/ios-testflight/index.js

@@ -0,0 +1,479 @@
+/**
+ * TestFlight / App Store pre-submission validation.
+ *
+ * Two capabilities, both thin wrappers over Apple's own tooling:
+ *
+ *   exportIpa()     xcodebuild -exportArchive  (.xcarchive -> .ipa)
+ *   validateApp()   xcrun altool --validate-app (.ipa -> Apple's verdict)
+ *
+ * Why this exists next to `ios_app_store_audit`: that tool is a STATIC scanner.
+ * It reads the archive on disk and can only find what is visible there. It
+ * cannot know whether the bundle ID is registered, whether the profile matches
+ * the App Store Connect app record, whether this version+build pair was already
+ * used, or whether an entitlement is actually provisioned for the app ID. Only
+ * Apple's server can answer those, and `altool --validate-app` is how you ask.
+ * The two are complementary, not alternatives - run the static scan first
+ * because it is free, then this.
+ *
+ * Secret handling: altool accepts `-p @keychain:<item>` and `-p @env:<VAR>`
+ * indirections. This module uses ONLY those. A password is never placed in an
+ * argv element, so it cannot leak through the process list, a crash dump, or an
+ * error message that echoes the failing command.
+ *
+ * @module tools/ios-testflight
+ */
+
+import { execFileSync } from "child_process";
+import { existsSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+/**
+ * ITMS error code -> the App Store rule it maps onto.
+ *
+ * Deliberately partial. Only codes whose guideline mapping is unambiguous are
+ * listed; everything else passes Apple's own message through verbatim rather
+ * than guessing, because a confidently wrong guideline reference sends the
+ * developer to the wrong fix.
+ */
+export const ITMS_GUIDELINE_MAP = Object.freeze({
+  "ITMS-90683": {
+    guideline: "5.1.1 Data Collection and Storage",
+    hint: "Info.plist is missing a purpose string for a privacy-sensitive API. Every NS*UsageDescription must state why the app needs that data, in user-facing language.",
+  },
+  "ITMS-91053": {
+    guideline: "5.1.1 / Privacy manifest requirement",
+    hint: "PrivacyInfo.xcprivacy is missing a required-reason entry for an API in the required-reason list. Declare the reason code, do not remove the declaration.",
+  },
+  "ITMS-91061": {
+    guideline: "Privacy manifest requirement (third-party SDK)",
+    hint: "A bundled SDK on Apple's commonly-used list ships no signature or privacy manifest. Update to a version that includes one.",
+  },
+  "ITMS-91065": {
+    guideline: "Privacy manifest requirement (SDK signature)",
+    hint: "A bundled SDK is missing a valid code signature. Update the dependency; you cannot sign someone else's binary for them.",
+  },
+  "ITMS-90725": {
+    guideline: "Minimum SDK requirement",
+    hint: "Built against an SDK older than the App Store floor. Rebuild with a current Xcode.",
+  },
+  "ITMS-90022": {
+    guideline: "2.3 Accurate Metadata / asset completeness",
+    hint: "A required icon size is missing from the asset catalog.",
+  },
+  "ITMS-90023": {
+    guideline: "2.3 Accurate Metadata / asset completeness",
+    hint: "A required icon set is missing from the asset catalog.",
+  },
+  "ITMS-90717": {
+    guideline: "Asset requirements",
+    hint: "The App Store icon has an alpha channel. Flatten it: App Store icons must be fully opaque.",
+  },
+  "ITMS-90174": {
+    guideline: "Signing and provisioning",
+    hint: "No provisioning profile is embedded. Export with an App Store distribution profile.",
+  },
+  "ITMS-90283": {
+    guideline: "Signing and provisioning",
+    hint: "The embedded provisioning profile is invalid for App Store distribution.",
+  },
+  "ITMS-90046": {
+    guideline: "Signing and provisioning",
+    hint: "An entitlement in the binary is not permitted by the provisioning profile. Align the entitlements file with what the App ID is provisioned for.",
+  },
+  "ITMS-90034": {
+    guideline: "Signing and provisioning",
+    hint: "The binary is not signed, or the signature is invalid.",
+  },
+  "ITMS-90035": {
+    guideline: "Signing and provisioning",
+    hint: "Invalid signature. Re-sign with a valid Apple Distribution identity.",
+  },
+  "ITMS-90809": {
+    guideline: "2.5.1 Software Requirements (deprecated API)",
+    hint: "The binary references a removed API. Migrate off it; this is a hard rejection, not a warning.",
+  },
+});
+
+/** Where altool searches for `AuthKey_<keyId>.p8` when `--api-key` is used. */
+export const P8_SEARCH_DIRS = Object.freeze([
+  "./private_keys",
+  "~/private_keys",
+  "~/.private_keys",
+  "~/.appstoreconnect/private_keys",
+  "$API_PRIVATE_KEYS_DIR",
+]);
+
+/**
+ * Resolve which authentication tier is usable, without touching any secret.
+ *
+ * Tier 1 - App Store Connect API key (`--api-key` + `--api-issuer`). Preferred:
+ *          no 2FA, no interactive prompt, works unattended. Creating one needs
+ *          an Admin or App Manager role in App Store Connect, which many
+ *          developers on a corporate team do not have.
+ * Tier 2 - Apple ID + app-specific password. Any Apple ID holder can generate
+ *          one at appleid.apple.com with no elevated role, which makes this the
+ *          realistic path on a locked-down corporate account. The secret is
+ *          referenced indirectly (`@keychain:` / `@env:`), never passed by value.
+ * Tier 3 - Nothing available. Returns tier `null`. Callers MUST surface this as
+ *          a skipped gate, never as a pass: "Apple did not object" and "Apple
+ *          was never asked" are different results.
+ *
+ * @param {object} opts
+ * @param {string} [opts.apiKeyId]       ASC API key id (the `<keyId>` in AuthKey_<keyId>.p8)
+ * @param {string} [opts.apiIssuerId]    ASC issuer id
+ * @param {string} [opts.p8Path]         explicit path to the .p8, bypassing the search dirs
+ * @param {string} [opts.appleId]        Apple ID for tier 2
+ * @param {string} [opts.keychainItem]   keychain item holding the app-specific password
+ * @param {string} [opts.passwordEnvVar] env var holding the app-specific password
+ * @param {string} [opts.providerPublicId] required when the account has multiple providers
+ * @returns {{tier: 1|2|null, method: string, argv: string[], reason?: string, requiresEnv?: string}}
+ */
+export function resolveAuth(opts = {}) {
+  const {
+    apiKeyId,
+    apiIssuerId,
+    p8Path,
+    appleId,
+    keychainItem,
+    passwordEnvVar,
+    providerPublicId,
+  } = opts;
+
+  const provider = providerPublicId ? ["--provider-public-id", providerPublicId] : [];
+
+  if (apiKeyId && apiIssuerId) {
+    const argv = ["--api-key", apiKeyId, "--api-issuer", apiIssuerId];
+    if (p8Path) argv.push("--p8-file-path", p8Path);
+    return {
+      tier: 1,
+      method: "asc-api-key",
+      argv: [...argv, ...provider],
+    };
+  }
+
+  if (appleId && (keychainItem || passwordEnvVar)) {
+    // Indirection only. `-p <literal>` would put the password in argv.
+    const secretRef = keychainItem ? `@keychain:${keychainItem}` : `@env:${passwordEnvVar}`;
+    if (passwordEnvVar && !keychainItem && !process.env[passwordEnvVar]) {
+      // Caught here rather than left to altool: `-p @env:MISSING` fails deep
+      // inside delivery with an authentication error that reads like a wrong
+      // password, sending the caller to rotate a credential that was fine.
+      return {
+        tier: null,
+        method: "none",
+        argv: [],
+        reason: `password_env_var "${passwordEnvVar}" is not set in this process, so altool would read an empty password`,
+      };
+    }
+    return {
+      tier: 2,
+      method: keychainItem ? "apple-id-keychain" : "apple-id-env",
+      argv: ["-u", appleId, "-p", secretRef, ...provider],
+      requiresEnv: keychainItem ? undefined : passwordEnvVar,
+    };
+  }
+
+  // A literal password is refused rather than used. Accepting one would put the
+  // secret in argv, where it leaks through the process list and through any error
+  // that echoes the failing command - and doing it silently is worse, because the
+  // caller would have no signal that their credential was exposed.
+  if (opts.password) {
+    return {
+      tier: null,
+      method: "none",
+      argv: [],
+      reason:
+        "a literal password was supplied; pass it by reference instead (keychain_item, or password_env_var) so it never reaches the process list. `altool --store-password-in-keychain-item <name> -u <apple-id> -p <password>` creates the keychain item once.",
+    };
+  }
+
+  return {
+    tier: null,
+    method: "none",
+    argv: [],
+    reason:
+      apiKeyId || apiIssuerId
+        ? "incomplete API key credentials: both --api-key and --api-issuer are required"
+        : appleId
+          ? "an Apple ID was supplied with no password reference (keychain item or env var)"
+          : "no App Store Connect credentials configured",
+  };
+}
+
+/**
+ * Build the `exportOptions.plist` xcodebuild needs to turn an archive into a
+ * distributable .ipa.
+ *
+ * @param {object} opts
+ * @param {string} opts.method            e.g. "app-store-connect"
+ * @param {string} [opts.teamId]
+ * @param {Record<string,string>} [opts.provisioningProfiles] bundleId -> profile name
+ * @param {boolean} [opts.uploadSymbols]
+ * @param {string} [opts.signingStyle]    "automatic" | "manual"
+ * @returns {string} plist XML
+ */
+export function buildExportOptionsPlist(opts) {
+  const {
+    method = "app-store-connect",
+    teamId,
+    provisioningProfiles,
+    uploadSymbols = true,
+    signingStyle,
+  } = opts;
+
+  const entries = [`    <key>method</key>\n    <string>${method}</string>`];
+  entries.push(
+    `    <key>uploadSymbols</key>\n    <${uploadSymbols ? "true" : "false"}/>`,
+  );
+  if (teamId) entries.push(`    <key>teamID</key>\n    <string>${teamId}</string>`);
+  if (signingStyle) {
+    entries.push(`    <key>signingStyle</key>\n    <string>${signingStyle}</string>`);
+  }
+  if (provisioningProfiles && Object.keys(provisioningProfiles).length > 0) {
+    const rows = Object.entries(provisioningProfiles)
+      .map(([bundleId, profile]) => `      <key>${bundleId}</key>\n      <string>${profile}</string>`)
+      .join("\n");
+    entries.push(`    <key>provisioningProfiles</key>\n    <dict>\n${rows}\n    </dict>`);
+  }
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    "  <dict>",
+    entries.join("\n"),
+    "  </dict>",
+    "</plist>",
+    "",
+  ].join("\n");
+}
+
+/**
+ * Export a .xcarchive to a signed .ipa.
+ *
+ * @param {object} opts
+ * @param {string} opts.archivePath
+ * @param {string} opts.outputDir
+ * @param {string} [opts.method]
+ * @param {string} [opts.teamId]
+ * @param {Record<string,string>} [opts.provisioningProfiles]
+ * @param {string} [opts.signingStyle]
+ * @param {boolean} [opts.uploadSymbols]
+ * @param {number} [opts.timeoutSec]
+ * @returns {{ok: boolean, ipaPath?: string, exportOptionsPath: string, errors: string[], log: string}}
+ */
+export function exportIpa(opts) {
+  const { archivePath, outputDir, timeoutSec = 900, allowProvisioningUpdates = false } = opts;
+  if (!archivePath || !existsSync(archivePath)) {
+    return { ok: false, errors: [`archive not found: ${archivePath}`], log: "", exportOptionsPath: "" };
+  }
+
+  const plist = buildExportOptionsPlist(opts);
+  const workDir = mkdtempSync(join(tmpdir(), "tf-export-"));
+  const exportOptionsPath = join(workDir, "exportOptions.plist");
+  writeFileSync(exportOptionsPath, plist);
+
+  const argv = [
+    "-exportArchive",
+    "-archivePath",
+    archivePath,
+    "-exportPath",
+    outputDir,
+    "-exportOptionsPlist",
+    exportOptionsPath,
+  ];
+  // Off by default, and that is deliberate. `-allowProvisioningUpdates` lets
+  // xcodebuild register devices and create or modify provisioning profiles in the
+  // developer account - a change on Apple's side, made by a tool whose job is to
+  // check a build rather than to alter the account it belongs to. Opt in when you
+  // want that.
+  if (allowProvisioningUpdates) argv.push("-allowProvisioningUpdates");
+
+  let log = "";
+  let ok = true;
+  try {
+    log = execFileSync("xcodebuild", argv, {
+      encoding: "utf-8",
+      timeout: timeoutSec * 1000,
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch (e) {
+    ok = false;
+    log = `${e.stdout || ""}\n${e.stderr || ""}${e.signal === "SIGTERM" ? "\n[TIMEOUT]" : ""}`;
+  }
+
+  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);
+  }
+  // xcodebuild can exit 0 and still produce nothing useful.
+  if (!ipaPath) ok = false;
+
+  // 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
+  // is still reported for a failed run so the caller can inspect what was sent.
+  let exportOptions = exportOptionsPath;
+  if (ok) {
+    try {
+      rmSync(workDir, { recursive: true, force: true });
+      exportOptions = null;
+    } catch {
+      /* leaving a temp dir behind is not worth failing an otherwise good export */
+    }
+  }
+
+  return { ok, ipaPath, exportOptionsPath: exportOptions, errors, log };
+}
+
+/**
+ * Parse altool's JSON output into a flat issue list.
+ *
+ * altool nests findings differently across versions and error classes
+ * (`product-errors`, `errors`, `warnings`), so every known shape is walked and
+ * anything unrecognised is preserved as a raw message rather than dropped - a
+ * validator that silently loses Apple's objection is worse than no validator.
+ *
+ * @param {string} stdout
+ * @returns {{issues: Array<{code: string|null, message: string, severity: string}>, parsed: boolean}}
+ */
+export function parseAltoolOutput(stdout) {
+  const issues = [];
+  let parsed = false;
+
+  const pushRaw = (message, severity) => {
+    if (!message) return;
+    const code = (message.match(/ITMS-\d+/) || [null])[0];
+    issues.push({ code, message: String(message).trim(), severity });
+  };
+
+  try {
+    const json = JSON.parse(stdout);
+    parsed = true;
+    for (const key of ["product-errors", "errors"]) {
+      for (const e of json[key] || []) {
+        pushRaw(e.message || JSON.stringify(e), "error");
+      }
+    }
+    for (const w of json.warnings || []) {
+      pushRaw(w.message || JSON.stringify(w), "warning");
+    }
+  } catch {
+    // Not JSON (older altool, or a transport-level failure printed as text).
+    for (const line of stdout.split("\n")) {
+      if (/ITMS-\d+|error:/i.test(line)) pushRaw(line, "error");
+    }
+  }
+
+  return { issues, parsed };
+}
+
+/**
+ * Ask Apple to validate an .ipa for App Store / TestFlight delivery.
+ *
+ * @param {object} opts
+ * @param {string} opts.ipaPath
+ * @param {string} [opts.platform] ios | appletvos | visionos | macos
+ * @param {object} opts.auth        result of resolveAuth()
+ * @param {number} [opts.timeoutSec]
+ * @returns {object} structured verdict; `verdict: "SKIPPED"` when unauthenticated
+ */
+export function validateApp(opts) {
+  const { ipaPath, platform = "ios", auth, timeoutSec = 900 } = opts;
+
+  if (!ipaPath || !existsSync(ipaPath)) {
+    return { verdict: "ERROR", error: `ipa not found: ${ipaPath}` };
+  }
+  if (!auth || auth.tier === null) {
+    // Explicitly not a pass. The caller must render this as an unrun gate.
+    return {
+      tool: "altool --validate-app",
+      ipa: ipaPath,
+      platform,
+      authTier: null,
+      authMethod: "none",
+      verdict: "SKIPPED",
+      skippedReason:
+        auth?.reason || "no App Store Connect credentials configured; Apple was never asked",
+      issues: [],
+    };
+  }
+
+  const argv = [
+    "altool",
+    "--validate-app",
+    ipaPath,
+    "-t",
+    platform,
+    "--output-format",
+    "json",
+    ...auth.argv,
+  ];
+
+  const started = Date.now();
+  let stdout = "";
+  let failed = false;
+  try {
+    stdout = execFileSync("xcrun", argv, {
+      encoding: "utf-8",
+      timeout: timeoutSec * 1000,
+      maxBuffer: 32 * 1024 * 1024,
+    });
+  } catch (e) {
+    failed = true;
+    stdout = `${e.stdout || ""}\n${e.stderr || ""}${e.signal === "SIGTERM" ? "\n[TIMEOUT]" : ""}`;
+  }
+
+  const { issues, parsed } = parseAltoolOutput(stdout);
+  const enriched = issues.map((i) => ({
+    ...i,
+    ...(i.code && ITMS_GUIDELINE_MAP[i.code] ? ITMS_GUIDELINE_MAP[i.code] : {}),
+  }));
+  const errors = enriched.filter((i) => i.severity === "error");
+
+  return {
+    tool: "altool --validate-app",
+    ipa: ipaPath,
+    platform,
+    authTier: auth.tier,
+    authMethod: auth.method,
+    // A non-zero exit with no parsed issue is still a failure: the run did not
+    // produce Apple's approval, and treating "unparseable" as success is how a
+    // broken gate reports green.
+    verdict: failed || errors.length > 0 ? "FAIL" : "PASS",
+    outputParsed: parsed,
+    durationMs: Date.now() - started,
+    summary: {
+      errors: errors.length,
+      warnings: enriched.length - errors.length,
+      mappedToGuideline: enriched.filter((i) => i.guideline).length,
+    },
+    issues: enriched,
+    rawOutput: stdout.slice(-8000),
+  };
+}
+
+/**
+ * List the providers (teams) the credentials can deliver for.
+ *
+ * Useful as a pre-flight: a corporate Apple ID that belongs to several teams
+ * needs `--provider-public-id`, and altool's failure without it is opaque.
+ *
+ * @param {object} auth result of resolveAuth()
+ * @returns {{ok: boolean, output: string}}
+ */
+export function listProviders(auth) {
+  if (!auth || auth.tier === null) return { ok: false, output: "no credentials configured" };
+  try {
+    const out = execFileSync(
+      "xcrun",
+      ["altool", "--list-providers", "--output-format", "json", ...auth.argv],
+      { encoding: "utf-8", timeout: 120000 },
+    );
+    return { ok: true, output: out };
+  } catch (e) {
+    return { ok: false, output: `${e.stdout || ""}\n${e.stderr || ""}`.trim() };
+  }
+}

package/ui-tree-dumper.swift

@@ -0,0 +1,122 @@
+#!/usr/bin/swift
+// ui-tree-dumper.swift
+// Reads the iOS Simulator accessibility tree via macOS AX APIs (host-side)
+// Usage: swift ui-tree-dumper.swift [max-depth]
+// Output: JSON array of accessibility elements
+
+import Cocoa
+import Foundation
+
+struct AXNode: Codable {
+    let role: String
+    let title: String?
+    let value: String?
+    let description: String?
+    let identifier: String?
+    let frame: [String: Double]
+    let enabled: Bool
+    let focused: Bool
+    let children: [AXNode]
+}
+
+func getAXValue(_ element: AXUIElement, _ attr: String) -> AnyObject? {
+    var value: AnyObject?
+    AXUIElementCopyAttributeValue(element, attr as CFString, &value)
+    return value
+}
+
+func getString(_ element: AXUIElement, _ attr: String) -> String? {
+    return getAXValue(element, attr) as? String
+}
+
+func getBool(_ element: AXUIElement, _ attr: String) -> Bool {
+    return (getAXValue(element, attr) as? Bool) ?? false
+}
+
+func getFrame(_ element: AXUIElement) -> [String: Double] {
+    var pos = CGPoint.zero
+    var size = CGSize.zero
+    var posValue: AnyObject?
+    var sizeValue: AnyObject?
+    AXUIElementCopyAttributeValue(element, kAXPositionAttribute as CFString, &posValue)
+    AXUIElementCopyAttributeValue(element, kAXSizeAttribute as CFString, &sizeValue)
+    if let pv = posValue { AXValueGetValue(pv as! AXValue, .cgPoint, &pos) }
+    if let sv = sizeValue { AXValueGetValue(sv as! AXValue, .cgSize, &size) }
+    return ["x": Double(pos.x), "y": Double(pos.y), "w": Double(size.width), "h": Double(size.height)]
+}
+
+func dumpElement(_ element: AXUIElement, depth: Int, maxDepth: Int) -> AXNode? {
+    guard depth < maxDepth else { return nil }
+
+    let role = getString(element, kAXRoleAttribute) ?? "unknown"
+    let title = getString(element, kAXTitleAttribute)
+    let value = getString(element, kAXValueAttribute)
+    let desc = getString(element, kAXDescriptionAttribute)
+    let identifier = getString(element, kAXIdentifierAttribute)
+    let enabled = getBool(element, kAXEnabledAttribute)
+    let focused = getBool(element, kAXFocusedAttribute)
+    let frame = getFrame(element)
+
+    var children: [AXNode] = []
+    var childrenRef: AnyObject?
+    AXUIElementCopyAttributeValue(element, kAXChildrenAttribute as CFString, &childrenRef)
+    if let kids = childrenRef as? [AXUIElement] {
+        for kid in kids {
+            if let child = dumpElement(kid, depth: depth + 1, maxDepth: maxDepth) {
+                children.append(child)
+            }
+        }
+    }
+
+    // Skip empty nodes with no useful info
+    if title == nil && value == nil && desc == nil && identifier == nil && children.isEmpty && role == "AXGroup" {
+        return nil
+    }
+
+    return AXNode(
+        role: role,
+        title: title,
+        value: value,
+        description: desc,
+        identifier: identifier,
+        frame: frame,
+        enabled: enabled,
+        focused: focused,
+        children: children
+    )
+}
+
+func findSimulatorWindow() -> AXUIElement? {
+    let apps = NSWorkspace.shared.runningApplications
+    for app in apps {
+        if app.bundleIdentifier == "com.apple.iphonesimulator" {
+            let axApp = AXUIElementCreateApplication(app.processIdentifier)
+            var windows: AnyObject?
+            AXUIElementCopyAttributeValue(axApp, kAXWindowsAttribute as CFString, &windows)
+            if let wins = windows as? [AXUIElement], let first = wins.first {
+                return first
+            }
+        }
+    }
+    return nil
+}
+
+// Main
+let maxDepth = CommandLine.arguments.count > 1 ? Int(CommandLine.arguments[1]) ?? 10 : 10
+
+guard let simWindow = findSimulatorWindow() else {
+    let error = ["error": "Simulator not running or no window found"]
+    let data = try! JSONSerialization.data(withJSONObject: error)
+    FileHandle.standardOutput.write(data)
+    exit(1)
+}
+
+if let tree = dumpElement(simWindow, depth: 0, maxDepth: maxDepth) {
+    let encoder = JSONEncoder()
+    encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+    if let data = try? encoder.encode(tree) {
+        FileHandle.standardOutput.write(data)
+    }
+} else {
+    print("{\"error\": \"Could not parse accessibility tree\"}")
+}