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

package/tools/code-intel/swift.js

@@ -0,0 +1,249 @@
+/**
+ * swift.js  -  sourcekit-lsp, and an honest account of what it can answer.
+ *
+ * CAPABILITY IS NOT CAPABILITY. `initialize` returns `referencesProvider: true`
+ * whether or not references will ever be non-empty. Measured on this machine:
+ * against a package root, `textDocument/references` answered `[]` at 694ms and
+ * `[3]` at 5.8s, with nothing changed in between except that the background
+ * index had finished. Against a real 658-file package with dependencies it was
+ * still `[]` at 70s, having spent that time resolving and fetching. So the
+ * useful question is never "does the server say it supports references" but
+ * "has the index for this root settled", and that is what `indexReport` answers
+ * and what the reference tools wait on.
+ *
+ * WORKSPACE ROOT decides everything else. sourcekit-lsp takes its compiler
+ * arguments from a build system, and which one it finds determines whether the
+ * answers are semantic or a guess. The resolution order below is by strength of
+ * evidence, and whichever one matched is returned in every result, because a
+ * caller reading "0 references" deserves to know it came from a fallback.
+ *
+ * @module tools/code-intel/swift
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, basename } from "node:path";
+import { homedir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+/** Directories a root walk must not climb into or count. */
+const SKIP_DIRS = new Set([".git", ".build", "build", "DerivedData", "Pods", "node_modules"]);
+
+let cachedBin;
+
+/**
+ * Where sourcekit-lsp is.
+ *
+ * PATH before `xcrun` on purpose: it is what lets a test put a fake server on
+ * PATH and have it used, and on a real machine `/usr/bin/sourcekit-lsp` is on
+ * PATH anyway. `SOURCEKIT_LSP_PATH` wins over both.
+ */
+export function resolveSwiftBin() {
+  if (cachedBin !== undefined) return cachedBin;
+  const explicit = process.env.SOURCEKIT_LSP_PATH;
+  if (explicit && existsSync(explicit)) return (cachedBin = explicit);
+  const onPath = which("sourcekit-lsp");
+  if (onPath) return (cachedBin = onPath);
+  try {
+    const found = execFileSync("xcrun", ["--find", "sourcekit-lsp"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 10000,
+    }).trim();
+    if (found && existsSync(found)) return (cachedBin = found);
+  } catch {
+    /* no Xcode */
+  }
+  return (cachedBin = null);
+}
+
+function which(cmd) {
+  try {
+    const p = execFileSync("/usr/bin/which", [cmd], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    }).trim();
+    return p && existsSync(p) ? p : null;
+  } catch {
+    return null;
+  }
+}
+
+/** For tests, which change PATH between cases. */
+export function resetSwiftBinCache() {
+  cachedBin = undefined;
+}
+
+/**
+ * The strongest build-settings source at or above `file`.
+ *
+ * @returns {{root: string, source: string}}
+ */
+export function resolveWorkspaceRoot(file, explicitRoot) {
+  if (explicitRoot) return { root: explicitRoot, source: classify(explicitRoot) };
+  let dir = statSafe(file)?.isDirectory() ? file : dirname(file);
+  const seen = [];
+  for (let i = 0; i < 40 && dir && dir !== "/"; i++) {
+    seen.push(dir);
+    const s = classify(dir);
+    if (s !== "none") return { root: dir, source: s };
+    dir = dirname(dir);
+  }
+  const git = gitRoot(file);
+  if (git) return { root: git, source: "fallback" };
+  return { root: seen[0] || dirname(file), source: "fallback" };
+}
+
+function classify(dir) {
+  if (existsSync(join(dir, "buildServer.json"))) return "buildServer";
+  if (existsSync(join(dir, "Package.swift"))) return "swiftpm";
+  if (existsSync(join(dir, "compile_commands.json"))) return "compilationDatabase";
+  if (existsSync(join(dir, "compile_flags.txt"))) return "compilationDatabase";
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return "none";
+  }
+  if (entries.some((e) => e.endsWith(".xcworkspace") || e.endsWith(".xcodeproj"))) return "xcode";
+  return "none";
+}
+
+function statSafe(p) {
+  try {
+    return statSync(p);
+  } catch {
+    return null;
+  }
+}
+
+function gitRoot(file) {
+  try {
+    return execFileSync("git", ["-C", dirname(file), "rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What an answer from this root is worth, before any question is asked.
+ *
+ * `semantic` is the headline: true when cross-file answers can be trusted,
+ * false when the server will still reply but from fallback arguments. Nothing
+ * here starts a server - it is the tool a caller runs BECAUSE something is
+ * missing, so it must never be the thing that fails.
+ */
+export function indexReport(root, source) {
+  const spm = [
+    join(root, ".build", "index-build"),
+    join(root, ".build", "index-store"),
+  ].filter(existsSync);
+  const derived = derivedDataStore(root);
+  const built = spm.length > 0 || Boolean(derived);
+
+  const semantic = source === "swiftpm" || source === "buildServer" || source === "compilationDatabase";
+  const report = {
+    root,
+    buildSettingsSource: source,
+    semantic,
+    indexStore: derived || spm[0] || null,
+    indexBuilt: built,
+    remedy: [],
+  };
+  if (derived) {
+    const units = countUnits(join(derived, "v5", "units"));
+    if (units) {
+      report.unitCount = units.count;
+      report.newestUnit = new Date(units.newest).toISOString();
+    }
+  }
+  if (source === "xcode") {
+    report.remedy.push(
+      "This root is an Xcode project with no buildServer.json, so sourcekit-lsp falls back to default compiler arguments: cross-module answers and diagnostics will be wrong rather than missing. `brew install xcode-build-server && xcode-build-server config -project <X>.xcodeproj -scheme <S>` fixes it. Nothing here writes that file for you.",
+    );
+  }
+  if (source === "fallback") {
+    report.remedy.push(
+      "No build system was found at or above this file. Point --workspace_root at the package or project root.",
+    );
+  }
+  if (semantic && !built) {
+    report.remedy.push(
+      "No index on disk yet. The first cross-file question builds one in the background; on a package with dependencies that is minutes, not seconds.",
+    );
+  }
+  return report;
+}
+
+/**
+ * Xcode writes its index under DerivedData, in `<name>-<hash>`.
+ *
+ * `<name>` is the PROJECT's name, not the directory's, and the two differ often
+ * enough that assuming they match is the failure mode this whole file exists to
+ * avoid. Measured on a checkout whose directory name and `.xcodeproj` name had
+ * nothing in common: reported as having no index at all, while an 18,205-unit
+ * store sat under the project's name, and the remedy printed underneath told
+ * the caller to build one. So the candidate names come from the project and
+ * workspace files in the root, with the directory name last.
+ *
+ * Several folders can share a prefix - the same project checked out twice. The
+ * newest store wins, because the question being asked is about freshness.
+ */
+function derivedDataStore(root) {
+  const dd = join(homedir(), "Library", "Developer", "Xcode", "DerivedData");
+  let entries;
+  try {
+    entries = readdirSync(dd);
+  } catch {
+    return null;
+  }
+  const names = new Set([basename(root)]);
+  try {
+    for (const e of readdirSync(root)) {
+      const m = /^(.+)\.(xcodeproj|xcworkspace)$/.exec(e);
+      if (m) names.add(m[1]);
+    }
+  } catch {
+    /* unreadable root: the directory name is still a candidate */
+  }
+  let best = null;
+  for (const c of entries) {
+    const dash = c.lastIndexOf("-");
+    if (dash <= 0 || !names.has(c.slice(0, dash))) continue;
+    const store = join(dd, c, "Index.noindex", "DataStore");
+    if (!existsSync(store)) continue;
+    const s = statSafe(join(store, "v5", "units")) || statSafe(store);
+    const at = s ? s.mtimeMs : 0;
+    if (!best || at > best.at) best = { store, at };
+  }
+  return best ? best.store : null;
+}
+
+/**
+ * How many index units there are, and when one was last written.
+ *
+ * Freshness is taken from the DIRECTORY's mtime, not from a sample of the files
+ * in it. A store here holds 34,380 units: stat-ing all of them costs 1.8s, and
+ * stat-ing the first 200 of a readdir costs nothing but answers about an
+ * arbitrary 200 - directory order is a hash, not a timeline, so the number it
+ * produces is the newest of whichever units happened to come first. It was
+ * correct on the measured store by luck and nothing made that visible. A unit
+ * is written as a new file, which bumps the directory, so one syscall answers
+ * exactly: measured at 2ms from the true maximum over all 34,380.
+ */
+function countUnits(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const s = statSafe(dir);
+  return { count: entries.length, newest: s ? s.mtimeMs : Date.now() };
+}
+
+export { SKIP_DIRS };

package/tools/pass-kit/index.js

@@ -0,0 +1,432 @@
+/**
+ * pass-kit  -  build, sign, validate and inspect Apple Wallet passes.
+ *
+ * GENERIC BY CONSTRUCTION. No airline, no brand, no project appears anywhere in
+ * this directory. All five of Apple's styles are first-class, the asset
+ * contract is a table per style, and every identifier - pass type, team,
+ * organization, colours, copy - is caller input. The only thing that is not
+ * input is the specification itself.
+ *
+ * NO SECRETS. A literal passphrase is not an accepted parameter. The caller
+ * names an environment variable or a keychain entry, and the value reaches
+ * openssl through `-passin env:` so it never appears in `ps`, never lands in a
+ * log, and is scrubbed out of any error text on the way back.
+ *
+ * OFFLINE. Nothing here contacts Apple or anything else.
+ *
+ * @module tools/pass-kit
+ */
+
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { tmpdir } from "node:os";
+import { validatePass } from "./validate.js";
+import { STYLES, ASSETS, SCALES } from "./spec.js";
+import {
+  ERROR_PREFIX,
+  listPassFiles,
+  buildManifest,
+  writeManifest,
+  resolvePassphrase,
+  inspectCertificate,
+  signManifest,
+  verifySignature,
+  archive,
+  unpack,
+} from "./sign.js";
+
+const CERT_ARGS = {
+  certificate: { type: "string", description: "Pass Type ID certificate, PEM" },
+  private_key: { type: "string", description: "Private key for that certificate, PEM" },
+  wwdr_certificate: { type: "string", description: "Apple WWDR intermediate certificate, PEM" },
+  passphrase_env: {
+    type: "string",
+    description:
+      "NAME of an environment variable holding the private-key passphrase. Not the passphrase itself - a literal is deliberately not accepted",
+  },
+  keychain_account: {
+    type: "string",
+    description: "Keychain account to read the passphrase from, instead of passphrase_env",
+  },
+  keychain_service: { type: "string", description: 'Keychain service (default "pkpass")' },
+};
+
+export const PASS_TOOLS = [
+  {
+    name: "pass_validate",
+    description:
+      "Check a pass against Apple's rules without building or signing anything: required keys, the one style dictionary, field shapes, colours, barcodes, the per-style image contract, localization consistency, and semantic tags. Grades findings by consequence - an error is a pass Wallet refuses, a warning is a pass Wallet accepts while quietly doing less than intended. One unknown PKPassengerCapability value is the canonical example: no error anywhere, and the enhanced layout silently falls back.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pass_json: { type: "string", description: "Path to a pass.json" },
+        pass_dir: { type: "string", description: "Path to a .pass directory - checks its images and localizations too" },
+        pkpass: { type: "string", description: "Path to a built .pkpass - unpacked and checked, signature included" },
+      },
+    },
+  },
+  {
+    name: "pass_build",
+    description:
+      "Assemble, sign and archive a .pkpass. Takes a pass.json and an asset directory, writes the manifest (SHA-1 per file, as Apple specifies), signs it with openssl into a detached PKCS#7 signature, and zips the result. Validates first and refuses on an error-grade finding unless told otherwise. Offline, deterministic, and never accepts a literal passphrase.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pass_json: { type: "string", description: "Path to the pass.json to build from" },
+        assets_dir: { type: "string", description: "Directory holding the images and any xx.lproj folders" },
+        output: { type: "string", description: "Path to write the .pkpass to" },
+        ...CERT_ARGS,
+        overrides: {
+          type: "object",
+          description:
+            "Top-level keys to merge into pass.json before building - serialNumber, relevantDate, barcodes and so on. The file on disk is not modified",
+        },
+        allow_errors: {
+          type: "boolean",
+          description: "Build even when validation reports errors (default false)",
+        },
+      },
+      required: ["pass_json", "assets_dir", "output"],
+    },
+  },
+  {
+    name: "pass_inspect",
+    description:
+      "Open an existing .pkpass and report what is actually in it: style, top-level keys, semantic tags, images and their scales, localizations, whether the manifest matches the files, and the certificate chain that signed it. Read-only, and it never needs the private key.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pkpass: { type: "string", description: "Path to the .pkpass to open" },
+        show_pass_json: { type: "boolean", description: "Include the full pass.json in the result" },
+      },
+      required: ["pkpass"],
+    },
+  },
+  {
+    name: "pass_certificates",
+    description:
+      "Report the signing material: which certificate this is, its pass type and team identifier, when it expires and whether it already has. An expired Pass Type ID certificate still builds, still signs and still verifies - Wallet is the first thing that refuses it, and it does not say why. Never reads or reports key material.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        certificate: { type: "string", description: "Pass Type ID certificate, PEM" },
+        wwdr_certificate: { type: "string", description: "Apple WWDR intermediate certificate, PEM" },
+        passphrase_env: { type: "string", description: "Name of an env var to check is set (its value is never read out)" },
+        keychain_account: { type: "string", description: "Keychain account to check exists" },
+        keychain_service: { type: "string", description: 'Keychain service (default "pkpass")' },
+      },
+      required: ["certificate"],
+    },
+  },
+];
+
+export const PASS_READ_ONLY = ["pass_validate", "pass_inspect", "pass_certificates"];
+
+export const PASS_OUTPUT_SCHEMAS = {
+  pass_validate: {
+    type: "object",
+    properties: {
+      style: { type: "string" },
+      ok: { type: "boolean" },
+      errors: { type: "array", items: { type: "object" } },
+      warnings: { type: "array", items: { type: "object" } },
+      notes: { type: "array", items: { type: "object" } },
+      checked: { type: "object" },
+    },
+    required: ["ok", "errors", "warnings", "notes"],
+  },
+  pass_certificates: {
+    type: "object",
+    properties: {
+      certificate: { type: "object" },
+      wwdr: { type: "object" },
+      passphrase: { type: "object" },
+      usable: { type: "boolean" },
+    },
+    required: ["certificate", "usable"],
+  },
+};
+
+function requireAbs(p, label) {
+  if (!p) return `${label} is required`;
+  if (!isAbsolute(p)) return `${label} must be an absolute path, got "${p}"`;
+  if (!existsSync(p)) return `no such ${label}: ${p}`;
+  return null;
+}
+
+function readJson(p) {
+  try {
+    return { value: JSON.parse(readFileSync(p, "utf8")) };
+  } catch (e) {
+    return { error: `${ERROR_PREFIX}${p} is not readable JSON: ${e.message}` };
+  }
+}
+
+function validateTool(args) {
+  if (args.pkpass) {
+    const bad = requireAbs(args.pkpass, "pkpass");
+    if (bad) return `${ERROR_PREFIX}${bad}`;
+    const un = unpack(args.pkpass);
+    if (un.error) return un.error;
+    try {
+      const passPath = join(un.dir, "pass.json");
+      if (!existsSync(passPath)) return `${ERROR_PREFIX}${args.pkpass} contains no pass.json`;
+      const doc = readJson(passPath);
+      if (doc.error) return doc.error;
+      const files = listPassFiles(un.dir);
+      const report = validatePass(doc.value, files);
+      const sig = existsSync(join(un.dir, "signature"))
+        ? verifySignature({
+            signaturePath: join(un.dir, "signature"),
+            manifestPath: join(un.dir, "manifest.json"),
+          })
+        : { valid: false, reason: "no signature file" };
+      const manifestCheck = checkManifest(un.dir, files);
+      return {
+        ...report,
+        checked: { source: args.pkpass, files: files.length, signature: sig, manifest: manifestCheck },
+      };
+    } finally {
+      rmSync(un.dir, { recursive: true, force: true });
+    }
+  }
+
+  const dir = args.pass_dir;
+  if (dir) {
+    const bad = requireAbs(dir, "pass_dir");
+    if (bad) return `${ERROR_PREFIX}${bad}`;
+    const passPath = join(dir, "pass.json");
+    if (!existsSync(passPath)) return `${ERROR_PREFIX}${dir} contains no pass.json`;
+    const doc = readJson(passPath);
+    if (doc.error) return doc.error;
+    const files = listPassFiles(dir);
+    return { ...validatePass(doc.value, files), checked: { source: dir, files: files.length } };
+  }
+
+  const p = args.pass_json;
+  const bad = requireAbs(p, "pass_json");
+  if (bad) return `${ERROR_PREFIX}${bad}`;
+  const doc = readJson(p);
+  if (doc.error) return doc.error;
+  const report = validatePass(doc.value, []);
+  // Asset findings against an empty file list would be noise, not findings.
+  return {
+    ...report,
+    errors: report.errors.filter((e) => e.kind !== "asset"),
+    checked: { source: p, files: 0, note: "pass.json only - give pass_dir or pkpass to check images too" },
+  };
+}
+
+function checkManifest(dir, files) {
+  const manifestPath = join(dir, "manifest.json");
+  if (!existsSync(manifestPath)) return { present: false };
+  const doc = readJson(manifestPath);
+  if (doc.error) return { present: true, valid: false, reason: "unreadable" };
+  const expected = buildManifest(dir, files);
+  const missing = Object.keys(expected).filter((f) => !(f in doc.value));
+  const extra = Object.keys(doc.value).filter((f) => !(f in expected));
+  const mismatched = Object.keys(expected).filter((f) => f in doc.value && doc.value[f] !== expected[f]);
+  return {
+    present: true,
+    valid: missing.length === 0 && extra.length === 0 && mismatched.length === 0,
+    entries: Object.keys(doc.value).length,
+    ...(missing.length ? { missing } : {}),
+    ...(extra.length ? { extra } : {}),
+    ...(mismatched.length ? { mismatched } : {}),
+  };
+}
+
+function buildTool(args) {
+  for (const [p, label] of [
+    [args.pass_json, "pass_json"],
+    [args.assets_dir, "assets_dir"],
+    [args.certificate, "certificate"],
+    [args.private_key, "private_key"],
+    [args.wwdr_certificate, "wwdr_certificate"],
+  ]) {
+    const bad = requireAbs(p, label);
+    if (bad) return `${ERROR_PREFIX}${bad}`;
+  }
+  if (!args.output || !isAbsolute(args.output)) {
+    return `${ERROR_PREFIX}output must be an absolute path`;
+  }
+
+  const pass = readJson(args.pass_json);
+  if (pass.error) return pass.error;
+  const doc = { ...pass.value, ...(args.overrides || {}) };
+
+  const cert = inspectCertificate(args.certificate);
+  if (cert.expired) {
+    return `${ERROR_PREFIX}the Pass Type ID certificate expired on ${cert.notAfter}. A pass signed with it builds, signs and verifies, and Wallet then refuses it without saying why. Renew it before building.`;
+  }
+
+  const secret = resolvePassphrase(args);
+  if (secret.error) return secret.error;
+
+  const staging = mkdtempSync(join(tmpdir(), "pass-build-"));
+  try {
+    cpSync(args.assets_dir, staging, { recursive: true });
+    rmSync(join(staging, "pass.json"), { force: true });
+    rmSync(join(staging, "manifest.json"), { force: true });
+    rmSync(join(staging, "signature"), { force: true });
+    writeFileSync(join(staging, "pass.json"), JSON.stringify(doc, null, 2));
+
+    const files = listPassFiles(staging);
+    const report = validatePass(doc, files);
+    if (!report.ok && !args.allow_errors) {
+      return {
+        built: false,
+        reason: "validation failed - pass allow_errors: true to build anyway",
+        ...report,
+      };
+    }
+
+    const manifest = buildManifest(staging, files);
+    const manifestPath = writeManifest(staging, manifest);
+    const signed = signManifest({
+      manifestPath,
+      signaturePath: join(staging, "signature"),
+      certificate: args.certificate,
+      privateKey: args.private_key,
+      wwdr: args.wwdr_certificate,
+      passphrase: secret.value,
+    });
+    if (signed.error) return signed.error;
+
+    mkdirSync(dirname(args.output), { recursive: true });
+    rmSync(args.output, { force: true });
+    const zipped = archive(staging, args.output);
+    if (zipped.error) return zipped.error;
+
+    return {
+      built: true,
+      output: args.output,
+      bytes: zipped.bytes,
+      style: report.style,
+      files: files.length + 2,
+      manifestEntries: Object.keys(manifest).length,
+      passphraseSource: secret.source,
+      certificate: { passTypeIdentifier: cert.passTypeIdentifier, teamIdentifier: cert.teamIdentifier, notAfter: cert.notAfter, daysLeft: cert.daysLeft },
+      warnings: report.warnings,
+      notes: report.notes,
+      ...(report.ok ? {} : { errors: report.errors, builtWithErrors: true }),
+    };
+  } catch (e) {
+    return `${ERROR_PREFIX}build failed: ${e.message}`;
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+function inspectTool(args) {
+  const bad = requireAbs(args.pkpass, "pkpass");
+  if (bad) return `${ERROR_PREFIX}${bad}`;
+  const un = unpack(args.pkpass);
+  if (un.error) return un.error;
+  try {
+    const passPath = join(un.dir, "pass.json");
+    if (!existsSync(passPath)) return `${ERROR_PREFIX}${args.pkpass} contains no pass.json`;
+    const doc = readJson(passPath);
+    if (doc.error) return doc.error;
+    const pass = doc.value;
+    const files = listPassFiles(un.dir);
+    const style = STYLES.find((s) => pass[s] !== undefined) || null;
+
+    const images = {};
+    for (const f of files) {
+      const m = /^([a-zA-Z]+)(@2x|@3x)?\.png$/.exec(f.split("/").pop() || "");
+      if (!m) continue;
+      images[m[1]] = images[m[1]] || [];
+      images[m[1]].push(m[2] || "1x");
+    }
+    const localizations = [
+      ...new Set(files.filter((f) => f.includes(".lproj/")).map((f) => f.split(".lproj/")[0].split("/").pop())),
+    ];
+
+    const sig = existsSync(join(un.dir, "signature"))
+      ? verifySignature({ signaturePath: join(un.dir, "signature"), manifestPath: join(un.dir, "manifest.json") })
+      : { valid: false, reason: "no signature file" };
+
+    return {
+      pkpass: args.pkpass,
+      bytes: statSync(args.pkpass).size,
+      style,
+      passTypeIdentifier: pass.passTypeIdentifier,
+      teamIdentifier: pass.teamIdentifier,
+      organizationName: pass.organizationName,
+      serialNumber: pass.serialNumber,
+      formatVersion: pass.formatVersion,
+      topLevelKeys: Object.keys(pass).sort(),
+      semanticTags: Object.keys(pass.semantics || {}).sort(),
+      barcodes: (pass.barcodes || []).map((b) => b.format),
+      updates: pass.webServiceURL ? { webServiceURL: pass.webServiceURL, hasAuthenticationToken: Boolean(pass.authenticationToken) } : null,
+      images,
+      localizations,
+      files: files.length,
+      manifest: checkManifest(un.dir, files),
+      signature: sig,
+      ...(args.show_pass_json ? { passJson: pass } : {}),
+    };
+  } finally {
+    rmSync(un.dir, { recursive: true, force: true });
+  }
+}
+
+function certificatesTool(args) {
+  const bad = requireAbs(args.certificate, "certificate");
+  if (bad) return `${ERROR_PREFIX}${bad}`;
+  const cert = inspectCertificate(args.certificate);
+  const wwdr = args.wwdr_certificate ? inspectCertificate(args.wwdr_certificate) : null;
+
+  let passphrase = { configured: false, note: "give passphrase_env or keychain_account to check one" };
+  if (args.passphrase_env || args.keychain_account) {
+    const r = resolvePassphrase(args);
+    // The VALUE is never reported, only whether one was found.
+    passphrase = r.error
+      ? { configured: false, reason: r.error.replace(ERROR_PREFIX, "") }
+      : { configured: true, source: r.source };
+  }
+
+  const usable = Boolean(cert && !cert.error && cert.expired === false);
+  const advice = [];
+  if (cert.expired) {
+    advice.push(
+      `The certificate expired on ${cert.notAfter}. A pass signed with it builds, signs and verifies; Wallet refuses it and says nothing. Renew it at developer.apple.com.`,
+    );
+  } else if (cert.daysLeft !== null && cert.daysLeft < 30) {
+    advice.push(`The certificate expires in ${cert.daysLeft} day(s).`);
+  }
+  if (!wwdr) advice.push("Give wwdr_certificate to check the intermediate too; signing needs it.");
+  if (!passphrase.configured) {
+    advice.push(
+      "No passphrase source configured. Name an environment variable (passphrase_env) or store one in the keychain; a literal passphrase is deliberately not an accepted input.",
+    );
+  }
+
+  return { certificate: cert, wwdr, passphrase, usable, advice };
+}
+
+/**
+ * @param {string} name
+ * @param {object} args
+ */
+export async function handlePass(name, args = {}) {
+  try {
+    switch (name) {
+      case "pass_validate":
+        return validateTool(args);
+      case "pass_build":
+        return buildTool(args);
+      case "pass_inspect":
+        return inspectTool(args);
+      case "pass_certificates":
+        return certificatesTool(args);
+      default:
+        return null;
+    }
+  } catch (e) {
+    return `${ERROR_PREFIX}${name}: ${e?.message || String(e)}`;
+  }
+}
+
+export { STYLES, ASSETS, SCALES };