@rightkit/release 0.2.174 → 0.4.0

package/command-spec.mjs

@@ -0,0 +1,80 @@
+// Shared argv command shape for the declarative `tests` and `web` config sections (`right-release test`, `web-build`).
+// A step is one command run without a shell:
+//   { cmd, args?, cwd?, env? }                  any executable ("node" means this Node binary)
+//   { node, args?, nodeFlags?, nodeOptions? }   a Node script path inside the app, run by this Node binary
+// `cwd` and `node` are app-relative and may not leave the app. `nodeFlags` go before the script, `nodeOptions` are merged
+// (de-duplicated) into NODE_OPTIONS for the child. Unknown keys are refused so a typo cannot silently change a run.
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** Load an app's `right-release.config.mjs`; the app root is the config file's directory. */
+export async function loadAppConfig(configFile = "right-release.config.mjs") {
+  const configPath = path.resolve(configFile);
+  const loaded = await import(pathToFileURL(configPath).href);
+  return { config: loaded.default ?? loaded.config ?? loaded, appRoot: path.dirname(configPath), configPath };
+}
+
+export class CommandSpecError extends Error {
+  constructor(message) { super(message); this.name = "CommandSpecError"; this.code = "RK_COMMAND_SPEC"; }
+}
+
+const fail = (message) => { throw new CommandSpecError(message); };
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+export const STEP_KEYS = ["cmd", "node", "args", "cwd", "env", "nodeFlags", "nodeOptions"];
+
+export function relativeInside(value, label) {
+  if (typeof value !== "string" || !value.trim()) fail(`${label} must be a non-empty relative path`);
+  const normalized = value.replaceAll("\\", "/");
+  if (path.isAbsolute(value) || /^[A-Za-z]:/.test(value) || normalized.split("/").includes("..")) fail(`${label} must be relative and stay inside the app: ${value}`);
+  return normalized;
+}
+
+const stringList = (value, label) => {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) fail(`${label} must be a list of strings`);
+  return [...value];
+};
+
+/** Validate one step; `extraKeys` are accepted and left to the caller. Returns the step. */
+export function validateStep(step, label, extraKeys = []) {
+  if (!isObject(step)) fail(`${label} must be an object`);
+  const allowed = new Set([...STEP_KEYS, ...extraKeys]);
+  const unknown = Object.keys(step).filter((key) => !allowed.has(key));
+  if (unknown.length) fail(`${label} has unknown key(s): ${unknown.join(", ")} (allowed: ${[...allowed].join(", ")})`);
+  if (step.cmd !== undefined && step.node !== undefined) fail(`${label} sets both cmd and node; use one`);
+  if (step.cmd !== undefined && (typeof step.cmd !== "string" || !step.cmd.trim())) fail(`${label}.cmd must be a non-empty string`);
+  if (step.node !== undefined) relativeInside(step.node, `${label}.node`);
+  if (step.cwd !== undefined) relativeInside(step.cwd, `${label}.cwd`);
+  if (step.args !== undefined) stringList(step.args, `${label}.args`);
+  if (step.nodeFlags !== undefined) stringList(step.nodeFlags, `${label}.nodeFlags`);
+  if (step.nodeOptions !== undefined) stringList(step.nodeOptions, `${label}.nodeOptions`);
+  if (step.env !== undefined && (!isObject(step.env) || Object.values(step.env).some((value) => typeof value !== "string"))) fail(`${label}.env must be an object of strings`);
+  return step;
+}
+
+/** Add flags to a NODE_OPTIONS string without repeating one already present. */
+export function mergeNodeOptions(existing, flags) {
+  const present = (existing ?? "").trim().split(/\s+/).filter(Boolean);
+  for (const flag of flags) if (!present.includes(flag)) present.push(flag);
+  return present.join(" ");
+}
+
+/**
+ * Resolve a validated step to what to spawn: `{ cmd, args, cwd, env }`. `extraArgs` are appended after the step's own
+ * arguments (the `--` passthrough of `right-release test`). `cmd: "node"` and `node:` use `process.execPath`.
+ */
+export function resolveInvocation(step, { appRoot, baseEnv = process.env, extraArgs = [] }) {
+  const args = [...(step.args ?? []), ...extraArgs];
+  let cmd;
+  let argv;
+  if (step.node !== undefined) {
+    cmd = process.execPath;
+    argv = [...(step.nodeFlags ?? []), path.resolve(appRoot, step.node), ...args];
+  } else {
+    if (typeof step.cmd !== "string" || !step.cmd.trim()) fail("a step needs cmd or node");
+    cmd = step.cmd === "node" ? process.execPath : step.cmd;
+    argv = [...(step.cmd === "node" ? (step.nodeFlags ?? []) : []), ...args];
+  }
+  const env = { ...baseEnv, ...(step.env ?? {}) };
+  if (step.nodeOptions?.length) env.NODE_OPTIONS = mergeNodeOptions(env.NODE_OPTIONS, step.nodeOptions);
+  return { cmd, args: argv, cwd: path.resolve(appRoot, step.cwd ?? "."), env };
+}

package/content-digest.mjs

@@ -0,0 +1,209 @@
+// Signature-independent content digest: exact JS port of crates/rightkit-ffmpeg/src/content_digest.rs.
+// PE (Authenticode rule), thin 64-bit LE Mach-O (canonical unsigned image) & universal Mach-O (per-slice).
+// A malformed recognized format FAILS (ContentDigestError); never falls back to a plain hash.
+// Anything else is plain SHA-256. Archive/download SHA-256 remains a separate, independent value.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+export class ContentDigestError extends Error {
+  constructor(message) { super(message); this.name = "ContentDigestError"; this.code = "CONTENT_DIGEST_MALFORMED"; }
+}
+const malformed = (why) => { throw new ContentDigestError(why); };
+
+const MH_MAGIC_64 = 0xfeedfacf, LC_SEGMENT_64 = 0x19, LC_CODE_SIGNATURE = 0x1d;
+const FAT_MAGIC = 0xcafebabe, FAT_MAGIC_64 = 0xcafebabf;
+const CPU_X86_64 = 0x01000007, CPU_ARM64 = 0x0100000c;
+const MAX_FAT_ARCHS = 16;
+
+const sha256Parts = (parts) => { const h = createHash("sha256"); for (const p of parts) h.update(p); return h.digest("hex"); };
+export const sha256Bytes = (bytes) => sha256Parts([Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes)]);
+
+const le32 = (b, at) => (at + 4 <= b.length ? b.readUInt32LE(at) : null);
+const le16 = (b, at) => (at + 2 <= b.length ? b.readUInt16LE(at) : null);
+const be32 = (b, at) => (at + 4 <= b.length ? b.readUInt32BE(at) : null);
+const le64n = (b, at) => (at + 8 <= b.length ? Number(b.readBigUInt64LE(at)) : null);
+const be64n = (b, at) => (at + 8 <= b.length ? Number(b.readBigUInt64BE(at)) : null);
+
+function archName(cputype) {
+  if (cputype === CPU_ARM64) return "aarch64";
+  if (cputype === CPU_X86_64) return "x86_64";
+  malformed("unsupported CPU type");
+}
+const roundUp = (v, to) => Math.floor((v + to - 1) / to) * to;
+
+/** @returns {{format:"macho"|"macho-universal"|"pe"|"plain", slices:{arch:string|null, sha256:string}[]}} */
+export function contentIdentity(input) {
+  const bytes = Buffer.isBuffer(input) ? input : Buffer.from(input);
+  const magicBe = be32(bytes, 0), magicLe = le32(bytes, 0);
+  if (magicBe === FAT_MAGIC || magicBe === FAT_MAGIC_64) return fatIdentity(bytes);
+  if (magicLe === MH_MAGIC_64) {
+    const { arch, sha256 } = machoSliceDigest(bytes);
+    return { format: "macho", slices: [{ arch, sha256 }] };
+  }
+  if ([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe, 0xbebafeca, 0xbfbafeca].includes(magicBe)) {
+    malformed("unsupported Mach-O flavour (only 64-bit little-endian is catalogued)");
+  }
+  if (bytes.subarray(0, 2).toString("latin1") === "MZ") {
+    const { arch, sha256 } = peDigest(bytes);
+    return { format: "pe", slices: [{ arch, sha256 }] };
+  }
+  return { format: "plain", slices: [{ arch: null, sha256: sha256Bytes(bytes) }] };
+}
+
+export function contentIdentityFile(file) { return contentIdentity(readFileSync(file)); }
+export function digestFor(identity, arch) {
+  return identity.slices.find((s) => s.arch?.toLowerCase() === String(arch).toLowerCase())?.sha256 ?? null;
+}
+
+function machoSliceDigest(slice) {
+  const bad = (why) => malformed(`Mach-O: ${why}`);
+  if (le32(slice, 0) !== MH_MAGIC_64) bad("not a 64-bit little-endian Mach-O");
+  const cputype = le32(slice, 4); if (cputype === null) bad("truncated header");
+  const arch = archName(cputype);
+  const ncmds = le32(slice, 16), sizeofcmds = le32(slice, 20);
+  if (ncmds === null || sizeofcmds === null) bad("truncated header");
+  const cmdsEnd = 32 + sizeofcmds;
+  if (cmdsEnd > slice.length) bad("load commands run past the end of the file");
+  const commands = [];
+  let offset = 32;
+  for (let i = 0; i < ncmds; i += 1) {
+    const cmd = le32(slice, offset), size = le32(slice, offset + 4);
+    if (cmd === null || size === null) bad("truncated load command");
+    if (size < 8 || size % 8 !== 0 || offset + size > cmdsEnd) bad("load command size is invalid");
+    commands.push({ offset, size, cmd });
+    offset += size;
+  }
+  if (offset !== cmdsEnd) bad("load commands do not fill sizeofcmds");
+  let signature = null, linkedit = null;
+  commands.forEach((c, index) => {
+    if (c.cmd === LC_CODE_SIGNATURE) {
+      if (c.size !== 16 || signature !== null) bad("invalid or repeated LC_CODE_SIGNATURE");
+      signature = index;
+    } else if (c.cmd === LC_SEGMENT_64) {
+      if (c.size < 72) bad("short LC_SEGMENT_64");
+      const name = slice.subarray(c.offset + 8, c.offset + 24);
+      const end = name.indexOf(0) === -1 ? name.length : name.indexOf(0);
+      if (name.subarray(0, end).toString("latin1") === "__LINKEDIT") {
+        if (linkedit !== null) bad("repeated __LINKEDIT");
+        linkedit = index;
+      }
+    }
+  });
+  if (linkedit === null) bad("no __LINKEDIT segment");
+  const leOff = commands[linkedit].offset;
+  const vmsize = le64n(slice, leOff + 32), fileoff = le64n(slice, leOff + 40), filesize = le64n(slice, leOff + 48);
+  if (vmsize === null || fileoff === null || filesize === null) bad("truncated __LINKEDIT");
+  const len = slice.length;
+  if (fileoff < cmdsEnd || fileoff + filesize !== len || vmsize < filesize || vmsize % 0x1000 !== 0) bad("__LINKEDIT does not run to the end of the file");
+  let contentEnd = len;
+  if (signature !== null) {
+    const off = commands[signature].offset;
+    const dataoff = le32(slice, off + 8), datasize = le32(slice, off + 12);
+    if (dataoff === null || datasize === null) bad("truncated signature");
+    if (dataoff < fileoff || dataoff + datasize !== len) bad("code signature is not the tail of __LINKEDIT");
+    contentEnd = dataoff;
+  }
+  let end = contentEnd;
+  while (end > fileoff && slice[end - 1] === 0) end -= 1;
+  const canonicalFilesize = end - fileoff;
+  const page = cputype === CPU_ARM64 ? 0x4000 : 0x1000;
+  const canonicalVmsize = roundUp(canonicalFilesize, page);
+  const head = Buffer.alloc(cmdsEnd);
+  slice.copy(head, 0, 0, 32);
+  let cursor = 32, newLinkeditAt = 0, removed = 0;
+  commands.forEach((c, index) => {
+    if (index === signature) { removed = c.size; return; }
+    if (index === linkedit) newLinkeditAt = cursor;
+    slice.copy(head, cursor, c.offset, c.offset + c.size);
+    cursor += c.size;
+  });
+  head.writeBigUInt64LE(BigInt(canonicalVmsize), newLinkeditAt + 32);
+  head.writeBigUInt64LE(BigInt(canonicalFilesize), newLinkeditAt + 48);
+  head.writeUInt32LE(ncmds - (signature === null ? 0 : 1), 16);
+  head.writeUInt32LE(sizeofcmds - removed, 20);
+  return { arch, sha256: sha256Parts([head, slice.subarray(cmdsEnd, end)]) };
+}
+
+function fatIdentity(bytes) {
+  const bad = (why) => malformed(`universal Mach-O: ${why}`);
+  const wide = be32(bytes, 0) === FAT_MAGIC_64;
+  const count = be32(bytes, 4);
+  if (count === null) bad("truncated header");
+  if (count === 0 || count > MAX_FAT_ARCHS) bad("implausible architecture count");
+  const entrySize = wide ? 32 : 20;
+  const tableEnd = 8 + entrySize * count;
+  if (tableEnd > bytes.length) bad("architecture table runs past the end of the file");
+  const slices = [], seen = [], ranges = [];
+  for (let index = 0; index < count; index += 1) {
+    const at = 8 + index * entrySize;
+    const cputype = be32(bytes, at);
+    const off = wide ? be64n(bytes, at + 8) : be32(bytes, at + 8);
+    const size = wide ? be64n(bytes, at + 16) : be32(bytes, at + 12);
+    if (cputype === null || off === null || size === null) bad("truncated entry");
+    const end = off + size;
+    if (size === 0 || off < tableEnd || end > bytes.length) bad("slice is empty or out of bounds");
+    if (seen.includes(cputype)) bad("duplicate architecture");
+    if (ranges.some(([s, e]) => off < e && s < end)) bad("slices overlap");
+    seen.push(cputype); ranges.push([off, end]);
+    const { arch, sha256 } = machoSliceDigest(bytes.subarray(off, end));
+    if (arch !== archName(cputype)) bad("slice architecture differs from the fat header");
+    slices.push({ arch, sha256 });
+  }
+  return { format: "macho-universal", slices };
+}
+
+function peDigest(bytes) {
+  const bad = (why) => malformed(`PE: ${why}`);
+  const len = bytes.length;
+  const pe = le32(bytes, 0x3c);
+  if (pe === null) bad("no PE header offset");
+  if (bytes.subarray(pe, pe + 4).toString("latin1") !== "PE\0\0") bad("missing PE signature");
+  const machine = le16(bytes, pe + 4);
+  const arch = machine === 0x8664 ? "x86_64" : machine === 0xaa64 ? "aarch64" : bad("unsupported machine type");
+  const nsections = le16(bytes, pe + 6), optSize = le16(bytes, pe + 20);
+  if (nsections === null || optSize === null) bad("truncated COFF header");
+  const opt = pe + 24;
+  const sectionsAt = opt + optSize;
+  if (sectionsAt > len) bad("optional header runs past the end of the file");
+  const magic = le16(bytes, opt);
+  const dirs = magic === 0x10b ? 96 : magic === 0x20b ? 112 : bad("unknown optional header magic");
+  if (optSize < dirs) bad("optional header too short");
+  const checksumAt = opt + 64;
+  const sizeOfHeaders = le32(bytes, opt + 60), dirCount = le32(bytes, opt + dirs - 4);
+  if (sizeOfHeaders === null || dirCount === null) bad("truncated optional header");
+  const certEntry = dirCount > 4 && optSize >= dirs + 40 ? opt + dirs + 32 : null;
+  const tableEnd = sectionsAt + nsections * 40;
+  if (tableEnd > len) bad("section table runs past the end of the file");
+  let floor = checksumAt + 4;
+  if (certEntry !== null) floor = Math.max(floor, certEntry + 8);
+  if (sizeOfHeaders > len || sizeOfHeaders < Math.max(floor, tableEnd)) bad("SizeOfHeaders is inconsistent");
+  let certOffset = 0, certSize = 0;
+  if (certEntry !== null) {
+    certOffset = le32(bytes, certEntry); certSize = le32(bytes, certEntry + 4);
+    if (certOffset === null || certSize === null) bad("truncated directory");
+  }
+  if (certSize > 0 && (certOffset < sizeOfHeaders || certOffset + certSize !== len)) bad("certificate table is not the tail of the file");
+  const sections = [];
+  for (let i = 0; i < nsections; i += 1) {
+    const at = sectionsAt + i * 40;
+    const size = le32(bytes, at + 16), off = le32(bytes, at + 20);
+    if (size === null || off === null) bad("truncated section");
+    if (size > 0) sections.push([off, size]);
+  }
+  sections.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  const parts = [bytes.subarray(0, checksumAt)];
+  if (certEntry !== null) {
+    parts.push(bytes.subarray(checksumAt + 4, certEntry), bytes.subarray(certEntry + 8, sizeOfHeaders));
+  } else parts.push(bytes.subarray(checksumAt + 4, sizeOfHeaders));
+  let hashed = sizeOfHeaders, previousEnd = sizeOfHeaders;
+  const bodyEnd = len - certSize;
+  for (const [off, size] of sections) {
+    const end = off + size;
+    if (off < previousEnd || end > bodyEnd) bad("section overlaps the headers or the certificate table");
+    parts.push(bytes.subarray(off, end));
+    hashed += size; previousEnd = end;
+  }
+  if (hashed > bodyEnd) bad("hashed bytes exceed the file");
+  parts.push(bytes.subarray(hashed, bodyEnd));
+  return { arch, sha256: sha256Parts(parts) };
+}

package/deps-cargo.mjs

@@ -0,0 +1,55 @@
+// `right-release deps --audit` for Cargo workdirs (Orthic-Labs/rightkit#674): replaces an app's own audit-rust script.
+//
+//   deps: { workdirs: ["."], cargoWorkdirs: ["src-tauri"] }   // app-relative folders that hold a Cargo.lock
+//
+// Declared only: an app with no `deps.cargoWorkdirs` audits no Rust, exactly as before. Each folder must be inside the app and
+// hold a `Cargo.lock` (an unlocked workspace cannot be audited, so it is refused, never skipped). `cargo audit` runs through
+// the managed cargo client (`runCargoSync`): on a managed host it goes through the RightKit broker, and a host with no
+// broker or no `cargo-audit` fails closed with the reason; there is never a bare-cargo fallback on a managed Mac.
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { runCargoSync } from "./managed-cargo.mjs";
+
+const isInside = (root, target) => {
+  const relative = path.relative(root, target);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+
+/** The validated Cargo workdirs `[{ rel, cwd }]` of a release config (empty when none are declared). Throws on a bad declaration. */
+export function cargoAuditWorkdirs(config, root, { exists = existsSync } = {}) {
+  const declared = config?.deps?.cargoWorkdirs;
+  if (declared === undefined) return [];
+  if (!Array.isArray(declared) || declared.some((item) => typeof item !== "string" || !item.trim())) {
+    throw new Error("deps.cargoWorkdirs must be a list of app-relative folders");
+  }
+  const seen = new Set();
+  const workdirs = [];
+  for (const rel of declared) {
+    const normalized = rel.replaceAll("\\", "/");
+    if (path.isAbsolute(rel) || /^[A-Za-z]:/.test(rel) || normalized.split("/").includes("..")) {
+      throw new Error(`deps.cargoWorkdirs entry must be relative and stay inside the app: ${rel}`);
+    }
+    const cwd = path.resolve(root, normalized);
+    if (!isInside(root, cwd)) throw new Error(`deps.cargoWorkdirs entry must stay inside the app: ${rel}`);
+    if (seen.has(cwd)) continue;
+    seen.add(cwd);
+    if (!exists(path.join(cwd, "Cargo.lock"))) throw new Error(`deps.cargoWorkdirs entry ${rel} has no Cargo.lock (${path.join(cwd, "Cargo.lock")}); an unlocked workspace cannot be audited`);
+    workdirs.push({ rel, cwd });
+  }
+  return workdirs;
+}
+
+/**
+ * Run `cargo audit` in each workdir and collect failures so every workdir reports. `run(args, options)` is the managed
+ * cargo runner (injectable). Returns `{ failures: string[] }`: one entry per workdir that could not start or exited non-zero.
+ */
+export function runCargoAudits(workdirs, { run = runCargoSync, log = console.log, env = process.env } = {}) {
+  const failures = [];
+  for (const { rel, cwd } of workdirs) {
+    log(`\n> cargo audit  (${cwd})`);
+    const result = run(["audit"], { cwd, env, stdio: "inherit" });
+    if (result?.error) failures.push(`${rel}: cargo audit could not start (${result.error.message})`);
+    else if (result?.status !== 0) failures.push(`${rel}: cargo audit exited ${result?.status ?? "without status"}`);
+  }
+  return { failures };
+}

package/deps.mjs

@@ -3,6 +3,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { spawnSync } from "./background-process.mjs";
 import { existsSync } from "node:fs";
+import { cargoAuditWorkdirs, runCargoAudits } from "./deps-cargo.mjs";
 
 const args = process.argv.slice(2);
 const opts = {
@@ -55,6 +56,12 @@ for (const { rel, cwd } of resolvedWorkdirs) {
     run("pnpm", ["install", ...workspaceArgs, "--lockfile-only", "--ignore-scripts"], cwd, { ignoreScripts: true });
   }
 }
+if (opts.mode === "audit") {
+  // Rust advisories (#674): every deps.cargoWorkdirs folder, through the managed cargo client; declared only.
+  let cargoWorkdirs;
+  try { cargoWorkdirs = cargoAuditWorkdirs(config, root); } catch (error) { fail(error.message); }
+  failures.push(...runCargoAudits(cargoWorkdirs).failures);
+}
 if (failures.length > 0) {
   for (const failure of failures) console.error(`right-deps: ${failure}`);
   fail(`${failures.length} dependency workdir(s) failed`);

package/development.mjs

@@ -14,6 +14,7 @@ import { stageDevelopmentBinaries, validateStageEntries } from "./stage-binary.m
 import { assertStableDesignatedRequirement, readBundleExecutable, requestedCiAdhocSigning, signMacosDevelopmentBundle } from "./development-signing.mjs";
 import { macosCodesignEnvironment } from "./codesign-environment.mjs";
 import { installTauriDevId, resolveTauriDevIdDescriptor, TAURI_DEVID_KIND } from "./install-tauri-devid.mjs";
+import { assertIosDevelopmentSession, installIosDevelopment, prepareIosDevelopment, validateIosDevelopment } from "./ios-dev.mjs";
 import { androidDevelopmentNdkCommand, androidDevelopmentSerial, installAndroidDevelopment, validateAndroidDevelopment } from "./android-dev.mjs";
 
 // One standard Cargo profile for every app (templates/cargo-profiles.toml): Cargo's built-in `dev`.
@@ -58,6 +59,8 @@ export function developmentEnvironment(env = process.env) {
 
 export function validateDevelopmentConfig(config, platform, { root = process.cwd() } = {}) {
   const target = config?.development?.targets?.[platform];
+  // iOS builds its commands from project, scheme and install (ios-dev.mjs); there is no hand-written build array.
+  if (platform === "ios") return validateIosDevelopment(target, { root });
   if (!target || !Array.isArray(target.build) || target.build.length === 0) throw new Error(`development.targets.${platform}.build must be a non-empty command array`);
   for (const [index, command] of target.build.entries()) validateCommand(command, `development.targets.${platform}.build[${index}]`);
   if (target.install?.kind === "command") validateCommand(target.install, `development.targets.${platform}.install`);
@@ -85,8 +88,9 @@ export function validateDevelopmentConfig(config, platform, { root = process.cwd
 
 export function runDevelopment({ root, platform, config, buildOnly = false, dryRun = false, env = process.env, run = spawnSync,
   codesignEnvironment = macosCodesignEnvironment, serial }) {
-  if (!new Set(["win", "mac", "android"]).has(platform)) throw new Error("--platform must be win, mac or android");
-  assertNativeDevelopmentHost(platform);
+  if (!new Set(["win", "mac", "android", "ios"]).has(platform)) throw new Error("--platform must be win, mac, android or ios");
+  // iOS: --dry-run validates the config and prints the plan on any host; everything else needs macOS with Xcode.
+  if (!(platform === "ios" && dryRun)) assertNativeDevelopmentHost(platform);
   const target = validateDevelopmentConfig(config, platform, { root });
   const repoRoot = git(root, ["rev-parse", "--show-toplevel"]);
   assertPrimaryReleaseCheckout(repoRoot, env);
@@ -94,6 +98,12 @@ export function runDevelopment({ root, platform, config, buildOnly = false, dryR
   assertReleaseExecutionAllowed({ cwd: repoRoot, environment: env, command: `right-release dev --platform ${platform}` });
   // Refuse an invalid or off-CI ad hoc opt-in before the (long) build, not after it.
   if (!buildOnly && platform === "mac" && target.install?.kind === "tauri") requestedCiAdhocSigning({ descriptor: target.install, env });
+  // iOS: the device or simulator is resolved (and a device proven ready) before the build, and a device build needs the GUI signing session.
+  let iosPrepared = null;
+  if (platform === "ios") {
+    assertIosDevelopmentSession(target, { env, run });
+    iosPrepared = prepareIosDevelopment(target, { root, env, run, serial });
+  }
   // Android: the device serial is required, so a missing one is refused before the (long) build too.
   if (!buildOnly && platform === "android" && target.install) androidDevelopmentSerial({ descriptor: target.install, serial, env });
   const childEnv = codesignEnvironment(developmentEnvironment(env));
@@ -104,12 +114,13 @@ export function runDevelopment({ root, platform, config, buildOnly = false, dryR
     const startedMs = Date.now();
     // Android: cargo-ndk (Cargo dev profile) fills the generated jniLibs, then the Gradle debug build packages it.
     if (target.ndk) { rmSync(target.ndk.jniLibs, { recursive: true, force: true }); execute(androidDevelopmentNdkCommand(target.ndk), { root, env: childEnv, dryRun, run, label: "native build" }); }
-    for (const command of target.build) execute(command, { root, env: childEnv, dryRun, run, label: "build" });
+    for (const command of iosPrepared ? iosPrepared.build : target.build) execute(command, { root, env: childEnv, dryRun, run, label: "build" });
     // Dev and QA binaries run from one stable staged path, copied in place (no backup of the old copy), never from the
     // broker's per-generation target folder or a hashed dev-targets folder.
     const staged = target.stage?.length ? stageDevelopmentBinaries(target.stage, { root, platform: platform === "win" ? "win32" : process.platform }) : [];
     for (const file of staged) console.log(`right-release dev: staged ${file}`);
     if (buildOnly || !target.install) return { built: true, installed: false, ...(staged.length ? { staged } : {}) };
+    if (iosPrepared) return { built: true, installed: true, ios: installIosDevelopment(iosPrepared.install, { root, env: childEnv, run }) };
     if (target.install.kind === TAURI_DEVID_KIND) {
       // installTauriDevId is async: the lease is held until it settles, so a broker cutover cannot land mid-install.
       const built = resolveTauriArtifact(target.install, { root, platform, env: childEnv });
@@ -124,7 +135,7 @@ export function runDevelopment({ root, platform, config, buildOnly = false, dryR
 }
 
 export function assertNativeDevelopmentHost(platform, host = process.platform) {
-  if ((platform === "win" && host !== "win32") || (platform === "mac" && host !== "darwin")) throw new Error(`development target ${platform} requires its native host`);
+  if ((platform === "win" && host !== "win32") || ((platform === "mac" || platform === "ios") && host !== "darwin")) throw new Error(`development target ${platform} requires its native host`);
 }
 
 function install(descriptor, { root, platform, config, env, run, sinceMs = null, serial }) {
@@ -338,7 +349,7 @@ function inside(root, child) { const rel = path.relative(path.resolve(root), pat
 export async function main(args = process.argv.slice(2)) {
   let platform, configPath = "right-release.config.mjs", dryRun = false, buildOnly = false, serial;
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === "-h" || args[i] === "--help") { console.log("usage: right-release dev --platform win|mac|android [--config right-release.config.mjs] [--dry-run] [--build-only] [--serial <adb serial>]"); return; }
+    if (args[i] === "-h" || args[i] === "--help") { console.log("usage: right-release dev --platform win|mac|android|ios [--config right-release.config.mjs] [--dry-run] [--build-only] [--serial <adb serial | iOS device id>]"); return; }
     if (args[i] === "--platform") platform = args[++i];
     else if (args[i] === "--config") configPath = args[++i];
     else if (args[i] === "--dry-run") dryRun = true;
@@ -346,7 +357,7 @@ export async function main(args = process.argv.slice(2)) {
     else if (args[i] === "--serial") serial = args[++i];
     else throw new Error(`unknown dev option: ${args[i]}`);
   }
-  if (!platform) throw new Error("right-release dev requires --platform win|mac|android");
+  if (!platform) throw new Error("right-release dev requires --platform win|mac|android|ios");
   const absoluteConfig = path.resolve(configPath);
   const safeEnv = developmentEnvironment(process.env);
   for (const [key, value] of Object.entries(safeEnv)) process.env[key] = value;

package/direct-bootstrap.mjs

@@ -289,7 +289,7 @@ export function renderPowerShellBootstrap({
     "$AcceptedSigners = @{}; $Contract.acceptedManifestSigners.PSObject.Properties | ForEach-Object { $AcceptedSigners[$_.Name] = $_.Value }",
     "$InstallRoot = Join-Path $env:LOCALAPPDATA " + psQuote(installRootSubdir),
     // In place at one fixed path: no versions/ folder, no per-version, per-digest or per-run directory, no junction.
-    // `current` is the real install; `current.staging` is written and verified but never run; `current.previous` is the one rollback copy.
+    // `current` is the real install; `current.staging` is written and verified but never run; `current.previous` is a transient park, deleted on success.
     "$Current = Join-Path $InstallRoot 'current'",
     "$Staging = Join-Path $InstallRoot 'current.staging'",
     "$Previous = Join-Path $InstallRoot 'current.previous'",
@@ -436,7 +436,6 @@ function Invoke-BoundedExe($Path, [string[]]$Arguments, [int]$TimeoutSeconds) {
     "$PriorCliCapable = $true; if ($Contract.priorExecutableMinVersion) { $PriorCliCapable = ($null -ne $PriorVersion -and ([version]$PriorVersion -ge [version]$Contract.priorExecutableMinVersion)) }",
     "$PriorStatus = $null; if ($PriorTarget -and $PriorCliCapable) { $PriorExe = Join-Path $Current " + psQuote(executablePath.replaceAll("/", "\\")) + "; $PriorStatusArgs = @(Expand-BootstrapArgs $StatusArgsTemplate ([string]$PriorTarget) $PriorVersion); try { $PriorStatus = ((Invoke-BoundedExe $PriorExe $PriorStatusArgs 60) | Out-String).Trim() } catch {} }",
     "@{ schemaVersion=1; priorTarget=$PriorTarget; priorVersion=$PriorVersion; targetVersion=$Version; priorStatus=$PriorStatus } | ConvertTo-Json -Depth 8 | Set-Content -Encoding UTF8 $Journal",
-    "$PriorWasJunction = $false; $CurrentItem = Get-Item -LiteralPath $Current -Force -ErrorAction SilentlyContinue; if ($CurrentItem -and $CurrentItem.LinkType -eq 'Junction') { $PriorWasJunction = $true }",
     "Remove-Retired $Previous",
     "$Switched = $false; $PriorDetached = $false",
     "try {",
@@ -449,10 +448,10 @@ function Invoke-BoundedExe($Path, [string[]]$Arguments, [int]$TimeoutSeconds) {
     "  $HealthText = ((Invoke-BoundedExe $StableExe $StatusArgs 120) | Out-String).Trim(); if ($LASTEXITCODE -ne 0) { throw 'Health command failed' }; $Health = $HealthText | ConvertFrom-Json",
     "  Assert-Health $Health $Version",
     "  $StableBin = Split-Path $StableExe -Parent; $InstallRootResolved = [IO.Path]::GetFullPath($InstallRoot).TrimEnd([IO.Path]::DirectorySeparatorChar); $UserPath = [Environment]::GetEnvironmentVariable('Path','User'); $Kept = @($UserPath -split ';' | Where-Object { $Entry = $_.Trim(); $Entry -ne '' -and -not ($Entry.TrimEnd([IO.Path]::DirectorySeparatorChar).StartsWith(($InstallRootResolved + [IO.Path]::DirectorySeparatorChar), [StringComparison]::OrdinalIgnoreCase) -and -not $Entry.TrimEnd([IO.Path]::DirectorySeparatorChar).Equals($StableBin.TrimEnd([IO.Path]::DirectorySeparatorChar), [StringComparison]::OrdinalIgnoreCase)) }); $NewPath = ((@($StableBin) + $Kept) -join ';'); if ($NewPath -ne $UserPath) { [Environment]::SetEnvironmentVariable('Path', $NewPath, 'User') }",
-    // Legacy cleanup only: the old layout's versions/ folder and its pointer junctions are removed once nothing needs them
-    // (a legacy `current` junction that was just moved to current.previous keeps its versions/ target until the next install).
-    "  $LegacyVersions = Join-Path $InstallRoot 'versions'; if (-not $PriorWasJunction -and (Test-Path -LiteralPath $LegacyVersions)) { try { Remove-Item -LiteralPath $LegacyVersions -Recurse -Force -ErrorAction SilentlyContinue } catch { } }; foreach ($Legacy in @('.current-previous', '.current-next')) { try { Remove-Retired (Join-Path $InstallRoot $Legacy) } catch { } }",
-    "  Remove-Item -Force $Journal; Write-Output (" + psQuote(product + " ") + " + $Version + ' installed')",
+    // Fixed-path install only (D01): no versioned folders, pointer junctions or legacy-layout cleanup in the
+    // generated script. A pre-existing legacy layout under $InstallRoot is left untouched, never deleted whole.
+    // No retained rollback copy (D01): $Previous is a transient park, deleted once health passes.
+    "  Remove-Retired $Previous; Remove-Item -Force $Journal; Write-Output (" + psQuote(product + " ") + " + $Version + ' installed')",
     "} catch {",
     "  $InstallError = $_; $RollbackErrors = New-Object 'System.Collections.Generic.List[string]'",
     "  try { if ($Switched) { Remove-Retired $Current }; if ($PriorDetached -and (Test-Path -LiteralPath $Previous)) { Rename-Item -LiteralPath $Previous -NewName (Split-Path -Leaf $Current) } } catch { $RollbackErrors.Add($_.Exception.Message) }",

package/disk-command.mjs

@@ -580,6 +580,7 @@ export async function runDiskCommand(args = process.argv.slice(2), { env = proce
     if (!self.ok) {
       for (const problem of self.problems) stdout(`ERROR: disk run self-check: ${problem}`);
       logEvent(logFile, { event: "disk.run.selfcheck.fail", problems: self.problems, version: self.version });
+      return { exitCode: 2, selfCheck: self };
     }
     ensureScratchRoots({ policy, platform, env });
     const before = check();

package/disk-policy.json

@@ -33,13 +33,14 @@
     {"id": "cache-parakeet", "platform": "mac", "path": "~/Library/Caches/parakeet_*", "capBytes": 1073741824, "action": "sweep", "unit": "self"},
     {"id": "cache-swiftright-factory", "platform": "mac", "path": "~/Library/Caches/SwiftRightFactory", "capBytes": 10737418240, "action": "sweep", "unit": "children"},
     {"id": "cache-cutright-engine", "platform": "mac", "path": "~/Library/Caches/cutright-engine", "capBytes": 2147483648, "action": "report", "unit": "children", "escalate": {"factor": 2, "staleDays": 7}},
+    {"id": "cache-cutright-app", "platform": "mac", "path": "~/Library/Caches/app.orthiclabs.cutright", "capBytes": 2147483648, "action": "report", "unit": "children", "escalate": {"factor": 2, "staleDays": 7}},
     {"id": "cache-heardright-engine", "platform": "mac", "path": "~/Library/Caches/heardright-engine", "capBytes": 2147483648, "action": "report", "unit": "children", "escalate": {"factor": 2, "staleDays": 7}},
     {"id": "cache-pnpm", "platform": "mac", "path": "~/Library/Caches/pnpm", "capBytes": 3221225472, "action": "report", "unit": "children", "escalate": {"factor": 2, "staleDays": 7}},
     {"id": "cache-python", "platform": "mac", "path": "~/Library/Caches/python", "capBytes": 3221225472, "action": "report", "unit": "children", "escalate": {"factor": 2, "staleDays": 7}},
     {"id": "xcode-deriveddata", "platform": "mac", "path": "~/Library/Developer/Xcode/DerivedData", "capBytes": 10737418240, "action": "sweep", "unit": "children"},
     {"id": "coresimulator", "platform": "mac", "path": "~/Library/Developer/CoreSimulator", "capBytes": 26843545600, "action": "report"},
     {"id": "documents-scratch", "platform": "mac", "path": "~/Documents", "capBytes": 21474836480, "action": "report"},
-    {"id": "shared-models", "platform": "mac", "path": "/Volumes/D/Orthic Labs/shared/models", "capBytes": 107374182400, "action": "report"},
+    {"id": "shared-models", "platform": "mac", "path": "~/Library/Application Support/Orthic Labs/shared/models", "capBytes": 107374182400, "action": "report"},
     {"id": "stale-release-tarballs", "platform": "mac", "path": "/Volumes/D/claude/rightkit/packages/release/rightkit-release-*.tgz", "capBytes": 1073741824, "action": "sweep", "unit": "self"},
     {"id": "win-temp", "platform": "win", "path": "${TEMP}", "capBytes": 10737418240, "action": "sweep", "unit": "children"},
     {"id": "win-pnpm", "platform": "win", "path": "${LOCALAPPDATA}\\pnpm", "capBytes": 21474836480, "action": "report"},
@@ -61,7 +62,10 @@
     {"id": "leftover-legion-final", "platform": "mac", "path": "/Volumes/D/claude/legion-final-*", "capBytes": 1073741824, "action": "sweep", "unit": "self"},
     {"id": "leftover-pulse-bak", "platform": "win", "path": "${LOCALAPPDATA}\\Programs\\Pulse.bak-*", "capBytes": 1073741824, "action": "sweep", "unit": "self"},
     {"id": "qa-evidence-runs", "platform": "mac", "path": "/Volumes/D/claude/*/.cache/rightkit-qa/*", "capBytes": 5368709120, "action": "sweep", "unit": "self", "staleDays": 3, "skipTracked": true},
-    {"id": "qa-evidence-runs", "platform": "win", "path": "D:\\claude\\*\\.cache\\rightkit-qa\\*", "capBytes": 5368709120, "action": "sweep", "unit": "self", "staleDays": 3, "skipTracked": true}
+    {"id": "qa-evidence-runs", "platform": "win", "path": "D:\\claude\\*\\.cache\\rightkit-qa\\*", "capBytes": 5368709120, "action": "sweep", "unit": "self", "staleDays": 3, "skipTracked": true},
+    {"id": "build-control-targets", "platform": "mac", "path": "/Volumes/D/.rightkit-managed/rightkit-build-control", "capBytes": 429496729600, "action": "report"},
+    {"id": "scratch-total", "platform": "mac", "path": "/Volumes/D/scratch", "capBytes": 322122547200, "action": "report"},
+    {"id": "claude-tmp", "platform": "mac", "path": "/Volumes/D/claude/tmp", "capBytes": 53687091200, "action": "report"}
   ],
   "protectedSegments": ["Application Support", "Keychains", "Keychain", "HeardRightNext", "Credentials", ".ssh", ".rightkit-managed", ".rightkit-swept"]
 }

package/disk-stable-root.mjs

@@ -64,9 +64,10 @@ export function collectDependencies(pkgRoot) {
   return [...found].map(([name, dir]) => ({ name, dir }));
 }
 
-/** Copy the installed @rightkit/release package (and its dependencies) into the stable root. The new tree is built and
- * built in the fixed `current.staging`, swapped in by rename (the old copy stays as `current.previous`), then smoke-tested at
- * `current`; a failed swap or smoke run renames `current.previous` back. Returns `{ stable, cli, version, replaced, unchanged }`. */
+/** Copy the installed @rightkit/release package (and its dependencies) into the stable root. The new tree is built in
+ * the fixed `current.staging`, swapped in by rename (the old copy is parked at `current.previous` only until the
+ * smoke test at `current` passes, then deleted; a failed swap or smoke run renames it back). No copy is retained.
+ * Returns `{ stable, cli, version, replaced, unchanged }`. */
 export function installStableRoot({ cli, platform = process.platform, env = process.env, home = os.homedir(), now = Date.now(), nodePath = process.execPath, smoke = true } = {}) {
   const stable = stableRootPath({ platform, env, home });
   const stableCli = stableCliPath(stable, platform);
@@ -107,10 +108,10 @@ export function installStableRoot({ cli, platform = process.platform, env = proc
     throw error;
   }
   // Swap first, then smoke-run at the fixed `current` path (never from the staging path). A failed run renames
-  // `current.previous` back. Exactly one `.previous` is kept.
-  let replaced = false;
+  // the transiently parked `current.previous` back; a passed run deletes it (nothing is retained).
+  const replaced = existsSync(stable);
   try {
-    const result = swapInPlace({
+    swapInPlace({
       staging, destination: stable, previous,
       verify: () => {
         if (!smoke) return;
@@ -118,7 +119,6 @@ export function installStableRoot({ cli, platform = process.platform, env = proc
         if (r.status !== 0) throw new Error(`the installed copy does not run: ${r.stderr || r.stdout || r.error?.message}`);
       },
     });
-    replaced = result.previous !== null;
   } catch (error) {
     throw new Error(`disk: could not replace ${stable}: ${error.message}`);
   }
@@ -130,8 +130,12 @@ export function readScheduleBinding({ platform = process.platform, home = os.hom
   if (platform === "darwin") {
     const plist = plistFile ?? file ?? path.join(home, "Library", "LaunchAgents", "dev.rightkit.disk-hygiene.plist");
     if (!existsSync(plist)) return null;
-    const m = /<key>ProgramArguments<\/key><array>\s*<string>([^<]*)<\/string>\s*<string>([^<]*)<\/string>/.exec(readFileSync(plist, "utf8"));
-    return m ? { node: m[1], cli: m[2], source: plist } : { node: null, cli: null, source: plist };
+    // Parse the plist natively: launchd/plutil formatting and XML escaping must not change the binding.
+    const result = run("/usr/bin/plutil", ["-extract", "ProgramArguments", "json", "-o", "-", "--", plist], { encoding: "utf8" });
+    let args;
+    try { if (result.status === 0) args = JSON.parse(String(result.stdout)); } catch { /* malformed binding fails evaluation below */ }
+    const valid = Array.isArray(args) && typeof args[0] === "string" && typeof args[1] === "string";
+    return valid ? { node: args[0], cli: args[1], source: plist } : { node: null, cli: null, source: plist };
   }
   const r = run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `$t = Get-ScheduledTask -TaskName '${label}' -ErrorAction SilentlyContinue; if (-not $t) { exit 3 }; $a = $t.Actions[0]; Write-Output $a.Execute; Write-Output $a.Arguments`], { encoding: "utf8" });
   if (r.status !== 0) return null;