@rightkit/release 0.2.174 → 0.4.0

package/install-app.mjs

@@ -271,15 +271,38 @@ const defaultIsAlive = (pid) => {
   try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
 };
 
-// Keep the bundle it replaced as `<installed>.previous` beside the fixed path (replacing any older one), by rename.
-// Rollback is renaming it back; nothing ever runs from it. It is never sent to the Trash: a Trash copy is a second
-// path macOS can resolve for the same bundle id.
-async function keepPreviousBundle(run, fsImpl, bundle, installed) {
-  const previous = previousPathOf(installed);
-  if (bundle === previous) return previous;
-  fsImpl.rmSync(previous, { recursive: true, force: true });
-  await moveAside(run, fsImpl, bundle, previous);
-  return previous;
+// Retire the replaced bundle after the new one verifies: NO `<installed>.previous` is retained (D01/#771).
+// Only the exact journaled park scope is cleaned: the old bundle at its staged/backup path and the stale
+// `<installed>.previous` an older RightKit left beside this fixed path. Nothing else in dest is touched.
+function retireOldBundle(fsImpl, bundle, installed) {
+  const rm = (p) => { if (p) { try { fsImpl.rmSync(p, { recursive: true, force: true }); } catch { /* best effort */ } } };
+  rm(bundle);
+  rm(previousPathOf(installed));
+}
+
+// Exclusive per-destination install lock: a lock file beside the installed apps, created O_EXCL. A lock whose pid is dead is
+// stale and taken over once. Held across recovery, staging, journal mutation and cleanup so two installers never share the
+// fixed staging/journal paths.
+const LOCK_NAME = ".rightkit-install.lock";
+// Locks this process currently holds. A lock naming our own pid that is not in this set was leaked (a simulated or
+// aborted install in this process), so it is stale exactly like a dead pid's.
+const heldLocks = new Set();
+function acquireInstallLock({ dest, fsImpl, pid, isAlive }) {
+  const lock = path.join(dest, LOCK_NAME);
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      fsImpl.writeFileSync(lock, JSON.stringify({ pid }), { flag: "wx" });
+      heldLocks.add(lock);
+      return () => { heldLocks.delete(lock); try { fsImpl.rmSync(lock, { force: true }); } catch { /* best effort */ } };
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw new InstallAppError("lock-failed", `cannot create install lock ${lock}: ${errText(error)}`);
+      let holder = null;
+      try { holder = JSON.parse(fsImpl.readFileSync(lock, "utf8")).pid; } catch { holder = null; }
+      if (Number.isInteger(holder) && isAlive(holder) && !(holder === pid && !heldLocks.has(lock))) throw new InstallAppError("install-locked", `another install holds ${lock} (pid ${holder})`);
+      try { fsImpl.rmSync(lock, { force: true }); } catch { /* retry decides */ }
+    }
+  }
+  throw new InstallAppError("install-locked", `could not take install lock ${lock}`);
 }
 
 // Deterministic roll-forward/back of any interrupted install journal in `dest`. Idempotent.
@@ -315,9 +338,8 @@ export async function recoverInstalls({ dest, appName = null, run, fsImpl, home,
           let ok = j.phase === "verified";
           if (!ok) { try { await verifyBundle(run, j.installed, { assess: !j.dev, staple: false }); ok = true; } catch { ok = false; } }
           if (ok) {
-            // A dev journal (from an older RightKit) never keeps the old bundle: the staged path is cleared below.
-            try { if (!j.dev) await keepPreviousBundle(run, fsImpl, j.staged, j.installed); action = "rolled-forward"; }
-            catch { action = "rolled-forward-previous-pending"; keepJournal = true; keepStaged = true; }
+            // Roll forward: the old bundle at the staged path is retired below, never kept as `.previous`.
+            action = "rolled-forward";
           } else {
             swapBack(swapPaths, fsImpl, j.staged, j.installed); // staged now holds the bad new bundle
             action = "rolled-back";
@@ -330,8 +352,8 @@ export async function recoverInstalls({ dest, appName = null, run, fsImpl, home,
         let ok = j.phase === "verified";
         if (!ok) { try { await verifyBundle(run, j.installed, { assess: !j.dev, staple: false }); ok = true; } catch { ok = false; } }
         if (ok) {
-          try { if (j.dev) rm(j.backup); else await keepPreviousBundle(run, fsImpl, j.backup, j.installed); action = "rolled-forward"; }
-          catch { action = "rolled-forward-previous-pending"; keepJournal = true; }
+          rm(j.backup); // validated journaled backup scope only; never retained as `.previous`
+          action = "rolled-forward";
         } else {
           rm(j.installed);
           fsImpl.renameSync(j.backup, j.installed);
@@ -343,6 +365,7 @@ export async function recoverInstalls({ dest, appName = null, run, fsImpl, home,
       continue; // leave the journal for the next run
     }
     if (!keepStaged) rm(j.staged);
+    if (j.installed) rm(previousPathOf(j.installed)); // no retained `.previous` survives recovery
     if (j.mount && has(j.mount)) {
       const out = await detachWithRetry({ mount: j.mount, log: (e) => event(e.event, e), sleep, detach: (args) => run("/usr/bin/hdiutil", args) });
       if (out.ok) rm(j.mountRoot);
@@ -357,7 +380,10 @@ export async function recoverInstalls({ dest, appName = null, run, fsImpl, home,
 export async function recoverApp(opts, deps = {}) {
   const { execFile = realExecFile, fsImpl = fs, home = os.homedir(), now = () => new Date(), sleep = (ms) => new Promise((r) => setTimeout(r, ms)), emit = () => {}, isAlive, platform = process.platform, env = process.env, swapPaths = createSwapPaths({ env }) } = deps;
   if (platform !== "darwin") throw new InstallAppError("unsupported", `install-app is not implemented on ${platform}`);
-  const results = await recoverInstalls({ dest: opts.dest, appName: opts.appName, run: (c, a) => execFile(c, a), fsImpl, home, now, event: (name, data = {}) => emit({ event: name, ...data }), sleep, isAlive, swapPaths });
+  const release = acquireInstallLock({ dest: opts.dest, fsImpl, pid: process.pid, isAlive: isAlive ?? defaultIsAlive });
+  let results;
+  try { results = await recoverInstalls({ dest: opts.dest, appName: opts.appName, run: (c, a) => execFile(c, a), fsImpl, home, now, event: (name, data = {}) => emit({ event: name, ...data }), sleep, isAlive, swapPaths }); }
+  finally { release(); }
   emit({ event: "recover-done", dest: opts.dest, recovered: results.length });
   return { ok: true, recovered: results };
 }
@@ -389,6 +415,7 @@ export async function installApp(opts, deps = {}) {
   let mountPoint = null;
   let failedStage = "start";
   let swap = null; // set once the journal exists; tracks which renames happened
+  let releaseLock = () => {};
   let devOldRemoved = false; // a dev install removed the old bundle; nothing can put it back
 
   const removeQuiet = (p) => { if (p) { try { fsImpl.rmSync(p, { recursive: true, force: true }); } catch { /* best effort */ } } };
@@ -401,7 +428,7 @@ export async function installApp(opts, deps = {}) {
       if (s.mode === "atomic") {
         // installed was never absent. Before the exchange only the staged copy needs removing; after it,
         // exchange back (installed = old again, staged = the new copy) and drop the new copy. Once final,
-        // staged holds the verified-old bundle awaiting retirement to .previous, so it must not be touched.
+        // staged holds the verified-old bundle awaiting retirement (deletion), so it must not be touched.
         if (!s.final) {
           if (s.swapped) swapBack(swapPaths, fsImpl, s.staged, s.installed);
           removeQuiet(s.staged);
@@ -428,6 +455,7 @@ export async function installApp(opts, deps = {}) {
         await detach();
         cleanupExtract();
       } catch { /* exiting anyway */ }
+      releaseLock();
       exit(128 + (os.constants.signals[sig] || 0));
     })();
   };
@@ -455,6 +483,7 @@ export async function installApp(opts, deps = {}) {
     if (!fsImpl.existsSync(inputPath)) throw new InstallAppError(`${inputKind}-missing`, `${inputKind.toUpperCase()} not found: ${inputPath}`);
     if (!fsImpl.existsSync(opts.dest)) throw new InstallAppError("dest-missing", `destination not found: ${opts.dest}`);
 
+    releaseLock = acquireInstallLock({ dest: opts.dest, fsImpl, pid, isAlive });
     await recoverInstalls({ dest: opts.dest, appName: opts.appName, run, fsImpl, home, now, event, sleep, isAlive, selfPid: pid, swapPaths });
 
     let sourceApp = null;
@@ -511,8 +540,9 @@ export async function installApp(opts, deps = {}) {
     // Stage a verified copy on the destination volume so the swap is rename(2) only.
     failedStage = "stage";
     const base = appName.replace(/\.app$/, "");
-    // Staging is never run from: it is verified, then renamed into place. The rollback copy is the fixed `<installed>.previous`.
-    const staged = path.join(opts.dest, `.${base}.rightkit-install-${pid}.app`);
+    // Staging is never run from: it is verified, then renamed into place. Its name is fixed per app (no per-pid sibling), like the
+    // journal beside it; the old bundle's transient park is the fixed `<installed>.previous`, deleted once verified.
+    const staged = path.join(opts.dest, `.${base}.rightkit-install.app`);
     // Dev installs keep NO old copy of any kind (Orthic-Labs/rightkit#348): the old bundle is removed, never moved to `.previous`.
     const backup = hadInstalled && !dev ? previousPathOf(installed) : null;
     const journal = journalPathFor(opts.dest, appName);
@@ -573,7 +603,7 @@ export async function installApp(opts, deps = {}) {
         swap.mode = "two-rename";
         jd = { ...journalData, swap: "two-rename" };
         writeJournal(fsImpl, journal, { ...jd, phase: "swapping" });
-        removeQuiet(backup); // an older .previous; the one kept copy is the bundle moving aside now
+        removeQuiet(backup); // clear the transient park (or a stale .previous) before parking the old bundle
         fsImpl.renameSync(installed, backup); swap.backedUp = true;
         fsImpl.renameSync(staged, installed);
         swap.stagedIn = true;
@@ -594,20 +624,13 @@ export async function installApp(opts, deps = {}) {
     writeJournal(fsImpl, journal, { ...jd, phase: "verified", mount: null, mountRoot: null });
     swap.final = true;
 
-    // Only now is the old bundle retired, to <installed>.previous (never the Trash).
-    let kept = null;
-    let keepFailed = false;
+    // Only now is the old bundle retired: deleted, never kept as `<installed>.previous` (D01).
     const oldBundle = swapMode === "atomic" ? staged : backup; // atomic: the exchange left the old bundle at the staged path
-    if (hadInstalled && oldBundle) {
-      try { kept = await keepPreviousBundle(run, fsImpl, oldBundle, installed); }
-      catch (error) { event("previous-keep-failed", { backup: oldBundle, reason: errText(error) }); kept = oldBundle; }
-    }
-    if (!oldBundle || kept !== previousPathOf(installed)) { if (!oldBundle) removeQuiet(journal); }
-    else removeQuiet(journal);
-    // A stale `.previous` from an older RightKit must not survive a dev install either.
-    if (dev) removeQuiet(previousPathOf(installed));
+    if (hadInstalled && oldBundle) retireOldBundle(fsImpl, oldBundle, installed);
+    else removeQuiet(previousPathOf(installed)); // a stale `.previous` from an older RightKit survives no install
+    removeQuiet(journal);
     swap = null;
-    event("replaced", { installed, previous: kept, swap: swapMode });
+    event("replaced", { installed, previous: null, swap: swapMode });
 
     // Relaunch hidden and in the background only.
     const relaunch = opts.relaunch === null ? wasRunning : opts.relaunch;
@@ -616,7 +639,7 @@ export async function installApp(opts, deps = {}) {
       await run("/usr/bin/open", ["-g", "-j", "-b", bundleId]);
       event("relaunched", { bundleId });
     }
-    const result = { ok: true, app: appName, installed, bundleId, teamId: newTeam, previous: kept, swap: swapMode, relaunched: relaunch, ...(dev ? { dev: true } : {}) };
+    const result = { ok: true, app: appName, installed, bundleId, teamId: newTeam, previous: null, swap: swapMode, relaunched: relaunch, ...(dev ? { dev: true } : {}) };
     event("done", result);
     return result;
   } catch (error) {
@@ -634,6 +657,7 @@ export async function installApp(opts, deps = {}) {
     rollbackSwap();
     await detach();
     cleanupExtract();
+    releaseLock();
   }
 }
 
@@ -713,16 +737,6 @@ async function quitApp(run, kill, sleep, app) {
   return { pids, killed: remaining };
 }
 
-async function moveAside(run, fsImpl, from, to) {
-  try {
-    fsImpl.renameSync(from, to);
-  } catch (error) {
-    if (error.code !== "EXDEV") throw error;
-    await run("/usr/bin/ditto", [from, to]);
-    fsImpl.rmSync(from, { recursive: true, force: true });
-  }
-}
-
 export async function main(argv = process.argv.slice(2), io = {}) {
   const stdout = io.stdout || ((s) => console.log(s));
   const stderr = io.stderr || ((s) => console.error(s));

package/ios-asc-credentials.mjs

@@ -0,0 +1,163 @@
+// App Store Connect API credentials for the iOS lane (bogusyogi/rightkit#349, settled decision D4: no credential sits in a file).
+//
+// The .p8 key, the key id and the issuer id are read at run time from the macOS login Keychain:
+//   security find-generic-password -s <service> -a <account> -w
+// Service names are configurable (`distribution.credentials`), with documented defaults. They are never read from config
+// values, environment variables or file paths:
+//   - a config key that names a path, a key id, an issuer or a secret is refused (IOS_ASC_CREDENTIAL_SOURCE_REFUSED);
+//   - key material in ANY environment variable is refused on every host; the usual ASC variable names are refused on managed
+//     hosts, exactly as macOS notarization does (managed-host-secrets.mjs);
+//   - key material never reaches a log line, an error message or a command argument.
+// `right-release ios-credentials store` writes the three items once (ios-credentials-command.mjs); the key is stored as the
+// single-line base64 of its PKCS#8 DER so no newline or quoting problem can occur, and it is sent to `security -i` on stdin so
+// it never appears in any process argument list.
+import { createPrivateKey } from "node:crypto";
+import os from "node:os";
+import { spawnSync } from "./background-process.mjs";
+import { refuseManagedEnvSecrets } from "./managed-host-secrets.mjs";
+
+export const DEFAULT_ASC_SERVICES = Object.freeze({
+  keyService: "rightkit-asc-api-key",
+  keyIdService: "rightkit-asc-key-id",
+  issuerService: "rightkit-asc-issuer-id",
+});
+
+export class IosCredentialsError extends Error {
+  constructor(code, message) { super(message); this.name = "IosCredentialsError"; this.code = code; }
+}
+const refuse = (code, message) => { throw new IosCredentialsError(code, message); };
+
+const SERVICE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const ACCOUNT = /^[A-Za-z0-9][A-Za-z0-9._@-]{0,63}$/;
+const KEY_ID = /^[A-Z0-9]{10}$/;
+const ISSUER = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+const PEM_MARKER = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
+const SOURCE_KEYS = ["keyService", "keyIdService", "issuerService", "account"];
+// Config keys that would carry a path, an identifier or a secret instead of a Keychain service name.
+const FORBIDDEN_SOURCE_KEYS = /^(?:key|keyPath|keyFile|file|path|p8|pem|keyId|keyID|issuer|issuerId|issuerID|env|envKey|password|secret|token|value)$/i;
+
+/** Environment variable names that carry ASC key material or paths; refused on managed hosts. */
+export const ASC_ENV_NAMES = Object.freeze([
+  "APPLE_API_KEY_PATH", "APPLE_API_KEY", "APPLE_API_ISSUER",
+  "ASC_KEY_PATH", "ASC_KEY_ID", "ASC_ISSUER_ID", "ASC_API_KEY", "ASC_API_KEY_PATH",
+  "APP_STORE_CONNECT_API_KEY", "APP_STORE_CONNECT_API_KEY_PATH", "APP_STORE_CONNECT_KEY_ID", "APP_STORE_CONNECT_ISSUER_ID",
+  "HR_IOS_ASC_KEY_PATH", "HR_IOS_ASC_KEY_ID", "HR_IOS_ASC_ISSUER_ID",
+]);
+
+/** Validate an optional credentials block and return the service names and account (defaults applied). */
+export function resolveAscCredentialSource(credentials, { env = process.env, label = "ASC credentials" } = {}) {
+  if (credentials !== undefined && (credentials === null || typeof credentials !== "object" || Array.isArray(credentials))) {
+    refuse("IOS_ASC_CONFIG_INVALID", `${label} must be an object of Keychain service names`);
+  }
+  const given = credentials ?? {};
+  for (const key of Object.keys(given)) {
+    if (FORBIDDEN_SOURCE_KEYS.test(key)) {
+      refuse("IOS_ASC_CREDENTIAL_SOURCE_REFUSED", `${label}.${key} is refused: App Store Connect credentials are read only from the macOS login Keychain (service names ${SOURCE_KEYS.join(", ")}), never from a file path, an inline value or the environment`);
+    }
+    if (!SOURCE_KEYS.includes(key)) refuse("IOS_ASC_CONFIG_INVALID", `${label} has unknown key ${key} (allowed: ${SOURCE_KEYS.join(", ")})`);
+  }
+  const source = {};
+  for (const key of ["keyService", "keyIdService", "issuerService"]) {
+    const value = given[key] ?? DEFAULT_ASC_SERVICES[key];
+    if (typeof value !== "string" || !SERVICE.test(value)) refuse("IOS_ASC_CONFIG_INVALID", `${label}.${key} must be a Keychain service name (letters, digits, dot, underscore, hyphen)`);
+    source[key] = value;
+  }
+  const names = new Set([source.keyService, source.keyIdService, source.issuerService]);
+  if (names.size !== 3) refuse("IOS_ASC_CONFIG_INVALID", `${label} must use three different Keychain service names`);
+  const account = given.account ?? (env.USER || os.userInfo().username);
+  if (typeof account !== "string" || !ACCOUNT.test(account)) refuse("IOS_ASC_CONFIG_INVALID", `${label}.account must be a Keychain account name`);
+  return { ...source, account };
+}
+
+/** Key material in any variable is refused on every host (names only); the ASC variable names are refused on managed hosts. */
+export function refuseIosAscEnv(env = process.env) {
+  for (const [name, value] of Object.entries(env)) {
+    if (PEM_MARKER.test(String(value ?? ""))) {
+      refuse("IOS_ASC_ENV_SECRET_REFUSED", `${name} is refused: App Store Connect key material must never be passed in the environment; keep it in the macOS login Keychain (right-release ios-credentials store)`);
+    }
+  }
+  refuseManagedEnvSecrets(env, ASC_ENV_NAMES);
+}
+
+/** Parse a .p8 (PEM text) or the stored single-line base64 PKCS#8 DER into a P-256 private KeyObject. */
+export function parseAscPrivateKey(text) {
+  const value = String(text ?? "").trim();
+  let key;
+  try {
+    key = PEM_MARKER.test(value) ? createPrivateKey(value) : createPrivateKey({ key: Buffer.from(value, "base64"), format: "der", type: "pkcs8" });
+  } catch { refuse("IOS_ASC_KEY_INVALID", "the App Store Connect API key is not a valid .p8 private key"); }
+  if (key.asymmetricKeyType !== "ec" || key.asymmetricKeyDetails?.namedCurve !== "prime256v1") refuse("IOS_ASC_KEY_INVALID", "the App Store Connect API key must be an ES256 (P-256) key");
+  return key;
+}
+
+export function validateAscKeyId(value) {
+  if (!KEY_ID.test(String(value ?? ""))) refuse("IOS_ASC_KEY_ID_INVALID", "the App Store Connect key id must be 10 upper-case letters or digits");
+  return String(value);
+}
+export function validateAscIssuer(value) {
+  if (!ISSUER.test(String(value ?? ""))) refuse("IOS_ASC_ISSUER_INVALID", "the App Store Connect issuer id must be a UUID");
+  return String(value);
+}
+
+export function iosCredentialsStoreHint() {
+  return "pipe the .p8 into: right-release ios-credentials store --key-id <KEYID> --issuer <issuer-uuid> (then delete the .p8 file)";
+}
+
+function keychainRead({ service, account, run }) {
+  const result = run("security", ["find-generic-password", "-s", service, "-a", account, "-w"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], shell: false, windowsHide: true, timeout: 30_000 });
+  if (result.error || result.status !== 0) return undefined;
+  const value = String(result.stdout ?? "").trim();
+  return value || undefined;
+}
+
+/**
+ * Read the key, key id and issuer from the login Keychain. macOS only. Returns the parsed KeyObject (never the text).
+ * A missing item names the service, never a value.
+ */
+export function readAscCredentials({ credentials, env = process.env, platform = process.platform, run = spawnSync } = {}) {
+  if (platform !== "darwin") refuse("IOS_ASC_HOST_UNSUPPORTED", "App Store Connect credentials are read from the macOS login Keychain; this host is not macOS");
+  refuseIosAscEnv(env);
+  const source = resolveAscCredentialSource(credentials, { env });
+  const read = (service, what) => {
+    const value = keychainRead({ service, account: source.account, run });
+    if (!value) refuse("IOS_ASC_CREDENTIAL_MISSING", `the ${what} is not in the login Keychain (service ${service}, account ${source.account}); ${iosCredentialsStoreHint()}`);
+    return value;
+  };
+  const keyText = read(source.keyService, "App Store Connect API key");
+  const keyId = validateAscKeyId(read(source.keyIdService, "App Store Connect key id"));
+  const issuer = validateAscIssuer(read(source.issuerService, "App Store Connect issuer id"));
+  return { keyId, issuer, privateKey: parseAscPrivateKey(keyText), source };
+}
+
+/**
+ * Write the three items into the login Keychain through `security -i` (commands on stdin, so the key is never an argument).
+ * The items are read back and compared; a missing or different item fails the store. Never writes the key to disk.
+ */
+export function storeAscCredentials({ keyText, keyId, issuer, credentials, env = process.env, platform = process.platform, run = spawnSync } = {}) {
+  if (platform !== "darwin") refuse("IOS_ASC_HOST_UNSUPPORTED", "App Store Connect credentials are stored in the macOS login Keychain; this host is not macOS");
+  refuseIosAscEnv(env);
+  const source = resolveAscCredentialSource(credentials, { env });
+  const key = parseAscPrivateKey(keyText);
+  const encodedKey = key.export({ type: "pkcs8", format: "der" }).toString("base64");
+  const items = [
+    { service: source.keyService, value: encodedKey },
+    { service: source.keyIdService, value: validateAscKeyId(keyId) },
+    { service: source.issuerService, value: validateAscIssuer(issuer) },
+  ];
+  // Base64, a key id and a UUID need no escaping inside double quotes; service and account were validated above.
+  const script = `${items.map((item) => `add-generic-password -U -a "${source.account}" -s "${item.service}" -l "${item.service}" -w "${item.value}"`).join("\n")}\nexit\n`;
+  const result = run("security", ["-i"], { input: script, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], shell: false, windowsHide: true, timeout: 60_000 });
+  if (result.error) refuse("IOS_ASC_STORE_FAILED", "could not run security to store the App Store Connect credentials");
+  for (const item of items) {
+    if (keychainRead({ service: item.service, account: source.account, run }) !== item.value) {
+      refuse("IOS_ASC_STORE_FAILED", `the Keychain item ${item.service} was not stored correctly (is the login keychain unlocked in this session?)`);
+    }
+  }
+  return { services: [source.keyService, source.keyIdService, source.issuerService], account: source.account, keyId: items[1].value, issuer: items[2].value };
+}
+
+/** Report which items exist, without returning or printing any key material. */
+export function checkAscCredentials(options) {
+  const credentials = readAscCredentials(options);
+  return { keyId: credentials.keyId, issuer: credentials.issuer, services: [credentials.source.keyService, credentials.source.keyIdService, credentials.source.issuerService], account: credentials.source.account };
+}

package/ios-build-context.mjs

@@ -0,0 +1,129 @@
+// What the sealed `build` path does differently for a native iOS app with no Cargo host (no src-tauri, no
+// nativeAssembly manifest; iosPackage.prepare commands are refused there, see release-invocation.mjs), so the
+// release owns no Cargo manifest, lock, target directory, broker target or Rust cache identity. Pure and
+// stub-friendly, the same shape as swift-build-context.mjs, so build-release.mjs branches once.
+
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { declaredCargoManifest } from "./native-cargo-layout.mjs";
+import { isNativeIosTarget, nativeIosPrepareProblems } from "./release-invocation.mjs";
+
+// Everything the release lane exports for Rust builds is removed from a native iOS build: releaseEnvironment() sets
+// CARGO_TARGET_DIR, CARGO_HOME, SCCACHE_DIR, RUSTC_WRAPPER (and in shared mode SCCACHE_CACHE_SIZE, SCCACHE_BASEDIRS,
+// SCCACHE_IGNORE_SERVER_IO_ERROR), and the host shell may carry RUSTFLAGS, RUSTC_* and other Cargo settings or registry secrets. Matching by
+// prefix keeps any later addition covered.
+const RUST_ENV_PREFIXES = ["CARGO_", "RUST", "SCCACHE_", "RIGHT_RELEASE_CACHE_OWNER"];
+// Kept as the host has them, so a hand `cargo build` in iosPackage.prepare behaves as it does in the user's shell: harmless tuning
+// knobs, the rustup toolchain locator, CARGO_HOME (the release lane's value is replaced by the host's own, or removed when the host
+// has none) and the proxy / network settings.
+const RUST_ENV_KEEP = new Set(["CARGO_BUILD_JOBS", "CARGO_JOBS", "RUST_TEST_THREADS", "CARGO_HOME"]);
+const RUST_ENV_KEEP_PREFIXES = ["RUSTUP_", "CARGO_NET_", "CARGO_HTTP_"];
+const isRustEnv = (upper) => RUST_ENV_PREFIXES.some((prefix) => upper.startsWith(prefix));
+const isKeptRustEnv = (upper) => RUST_ENV_KEEP.has(upper) || RUST_ENV_KEEP_PREFIXES.some((prefix) => upper.startsWith(prefix));
+
+/**
+ * env is the release lane's environment (host variables plus what releaseEnvironment exported); host is the process
+ * environment the release was started from. Release-lane Rust variables are dropped; the kept ones come from host, never from the lane.
+ */
+export function stripRustEnvironment(env, host = env) {
+  const next = {};
+  for (const [name, value] of Object.entries(env)) if (!isRustEnv(name.toUpperCase())) next[name] = value;
+  for (const [name, value] of Object.entries(host)) {
+    const upper = name.toUpperCase();
+    if (isRustEnv(upper) && isKeptRustEnv(upper)) next[name] = value;
+  }
+  return next;
+}
+
+// ---- release-switch inputs: the Rust the prepare commands build must be checked, never skipped --------------------------
+
+/**
+ * What the release-switch gates need for a build that runs Rust: the manifest to resolve the feature closure from
+ * (targets.<os>.cargoManifest, else the declared nativeAssembly.cargoManifest), the iosPackage.prepare commands to scan, the
+ * prepare cargo commands whose --features / --no-default-features / --all-features define the closure, and the reasons the
+ * features cannot be determined (which refuse the build). A prepare command that is a shell or wrapper, or a cargo command
+ * whose feature list comes from an unexpanded variable, hides what it builds, so it is refused when a Rust manifest is declared.
+ */
+export function releaseSwitchInputs({ appRoot, config, target, prepare = [], nativeIos = false }) {
+  // Every other platform, and iOS with src-tauri, keeps the pre-existing resolver order: targets.<os>.cargoManifest only.
+  if (!nativeIos) return { cargoManifest: target?.cargoManifest, commands: [], cargoCommands: [], problems: [] };
+  const cargoManifest = target?.cargoManifest ?? declaredCargoManifest(config);
+  const commands = prepare.map((command, index) => ({ label: `iosPackage.prepare[${index}]`, command }));
+  const cargoCommands = prepare.filter((command) => command?.cmd === "cargo");
+  return { cargoManifest, commands, cargoCommands, problems: nativeIosPrepareProblems({ appRoot, config, prepare }) };
+}
+
+/** Bare executable names the iosPackage.prepare commands invoke (a path such as ./script.sh is the app's own file, not a tool). */
+export function iosPrepareExecutables(iosSpec) {
+  return [...new Set((iosSpec?.prepare ?? []).map((command) => command?.cmd).filter((cmd) => typeof cmd === "string" && cmd && !/[\\/]/.test(cmd)))];
+}
+
+/**
+ * The iOS side of the sealed build, with every host effect injected: whether the app owns a Cargo layout (null when not), the
+ * tool versions to record, and nothing probed before its presence is asserted. exec(cmd, args) -> stdout;
+ * assertExecutables(names) throws the normal "required executable not found" failure.
+ */
+export function resolveIosBuildContext({ appRoot, config, target, iosSpec, exec, assertExecutables, exists = existsSync }) {
+  // An iOS app with src-tauri (Pulse) returns null: its build is exactly the Cargo-backed one, with nothing added or probed here.
+  if (!isNativeIosTarget({ appRoot, target })) return null;
+  const hasPackageJson = exists(path.join(appRoot, "package.json"));
+  const packageManager = hasPackageJson ? config.packageManager ?? "pnpm" : null;
+  const rust = Boolean(declaredCargoManifest(config));
+  assertExecutables(["xcodebuild", ...(iosSpec.projectSpec ? ["xcodegen"] : []), ...(packageManager ? [packageManager] : []), ...(rust ? ["cargo", "rustc"] : [])]);
+  const toolVersions = collectIosNativeToolVersions({ packageManager, exec, projectSpec: iosSpec.projectSpec, rust });
+  return { nativeIos: true, nativeLayout: null, hasPackageJson, toolVersions, prepareExecutables: iosPrepareExecutables(iosSpec) };
+}
+
+const oneLine = (text) => String(text ?? "").trim().split(/\r?\n/).map((line) => line.trim()).filter(Boolean).join(" ");
+
+/**
+ * The Xcode toolchain an iOS release is built with, in the exact form the IPA receipt records it
+ * (`xcodebuild -version`, one line). `xcodegen --version` only when iosPackage names a project.yml.
+ * exec(cmd, args) -> stdout string; throws when the tool is missing, which is correct: the iOS lane cannot build without it.
+ */
+export function collectIosXcodeToolVersions({ exec, projectSpec }) {
+  const xcodebuild = oneLine(exec("xcodebuild", ["-version"]));
+  if (!xcodebuild) throw new Error("xcodebuild -version printed nothing");
+  const xcodegen = projectSpec ? oneLine(exec("xcodegen", ["--version"])) : null;
+  if (projectSpec && !xcodegen) throw new Error("xcodegen --version printed nothing");
+  return { xcodebuild, xcodegen };
+}
+
+/** Tool versions for a native iOS build: Rust fields are explicit nulls unless a Rust manifest is declared (then cargo -V and rustc -V). */
+export function collectIosNativeToolVersions({ packageManager, exec, projectSpec, rust = false, nodeVersion = process.version }) {
+  return {
+    node: nodeVersion,
+    packageManager: packageManager ? `${packageManager} ${exec(packageManager, ["--version"]).trim()}` : null,
+    ...collectIosXcodeToolVersions({ exec, projectSpec }),
+    cargo: rust ? oneLine(exec("cargo", ["-V"])) : null,
+    rustc: rust ? oneLine(exec("rustc", ["-V"])) : null,
+    rustHost: null,
+    sccache: null,
+  };
+}
+
+export function iosArchitecture({ hostArch = process.arch } = {}) {
+  return hostArch === "arm64" ? "arm64" : "x64";
+}
+
+/**
+ * Plan for a Cargo-less iOS sealed build: identity from the Xcode toolchain, forced non-shared cache mode, no broker
+ * cargo target, no target bridge, a plain cache dir under the vault, and an environment with every Rust variable removed.
+ */
+export function planIosNativeBuild({ vaultRoot, appRoot, platform = "ios", toolVersions, profile = "release", hostArch, hostEnv = process.env }) {
+  if (!toolVersions?.xcodebuild) throw new Error("iOS build identity requires the xcodebuild version");
+  const architecture = iosArchitecture({ hostArch });
+  const payload = { projectType: "ios-native", xcodebuild: toolVersions.xcodebuild, xcodegen: toolVersions.xcodegen ?? null, architecture, profile };
+  const identity = { ...payload, target: architecture, features: [], fingerprint: createHash("sha256").update(JSON.stringify(payload)).digest("hex").slice(0, 16) };
+  const buildDir = path.resolve(vaultRoot, "cache", "ios-native", platform, identity.fingerprint);
+  return {
+    identity, architecture, buildDir,
+    cacheMode: "legacy",
+    managedCargoTarget: null,
+    targetBridge: { run: (fn) => fn(), ensure() {} },
+    // The kept Rust variables (CARGO_HOME, proxy settings, rustup) come from the environment the release was started from.
+    sanitizeEnv: (env) => stripRustEnvironment(env, hostEnv),
+    watchDirs: [buildDir, path.join(appRoot, ".cache")],
+  };
+}