@rightkit/release 0.2.165 → 0.2.172

package/install-app.mjs

@@ -4,6 +4,9 @@
 // Never uses a shell, osascript, AppleEvents, or foreground activation.
 import { execFile as nodeExecFile, execFileSync as nodeExecFileSync } from "./background-process.mjs";
 import { detachWithRetry } from "./hdiutil-detach.mjs";
+import { previousPathOf } from "./in-place-install.mjs";
+import { assertShippedSwapHelperSigned } from "./swap-helper-bundle.mjs";
+import { installAppWindows, InstallAppWindowsError } from "./install-app-windows.mjs";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -19,11 +22,11 @@ export class InstallAppError extends Error {
   }
 }
 
-const VALUE_FLAGS = new Set(["--dmg", "--zip", "--app", "--app-name", "--bundle-id", "--dest"]);
+const VALUE_FLAGS = new Set(["--dmg", "--zip", "--app", "--app-name", "--bundle-id", "--dest", "--installer", "--exe"]);
 const BOOL_FLAGS = new Set(["--relaunch", "--no-relaunch", "--json", "--dev", "--recover"]);
 
 export function parseArgs(argv) {
-  const opts = { dmg: null, zip: null, app: null, dev: false, appName: null, bundleId: null, dest: "/Applications", relaunch: null, json: false, recover: false };
+  const opts = { dmg: null, zip: null, app: null, installer: null, exe: null, dev: false, appName: null, bundleId: null, dest: "/Applications", relaunch: null, json: false, recover: false };
   for (let i = 0; i < argv.length; i += 1) {
     const flag = argv[i];
     if (VALUE_FLAGS.has(flag)) {
@@ -35,6 +38,8 @@ export function parseArgs(argv) {
       else if (flag === "--app") opts.app = value;
       else if (flag === "--app-name") opts.appName = value;
       else if (flag === "--bundle-id") opts.bundleId = value;
+      else if (flag === "--installer") opts.installer = value;
+      else if (flag === "--exe") opts.exe = value;
       else opts.dest = value;
     } else if (BOOL_FLAGS.has(flag)) {
       if (flag === "--json") opts.json = true;
@@ -45,6 +50,12 @@ export function parseArgs(argv) {
       throw new InstallAppError("usage", `unknown argument: ${flag}`);
     }
   }
+  if (opts.installer !== null) {
+    // Windows: run the sealed NSIS installer in place at one fixed folder, keeping <dest>.previous.
+    if (opts.dmg !== null || opts.zip !== null || opts.app !== null || opts.recover || opts.dev) throw new InstallAppError("usage", "--installer cannot be combined with --dmg, --zip, --app, --dev or --recover");
+    if (!argv.includes("--dest") || opts.exe === null) throw new InstallAppError("usage", "--installer requires --dest <fixed install folder> and --exe <App.exe>");
+    return opts;
+  }
   if (argv.includes("--relaunch") && argv.includes("--no-relaunch")) throw new InstallAppError("usage", "--relaunch and --no-relaunch are mutually exclusive");
   const inputs = [opts.dmg, opts.zip, opts.app].filter((v) => v !== null).length;
   if (opts.recover) {
@@ -220,10 +231,15 @@ function coded(code, message) {
 
 // Sync on purpose: signal-handler rollback must be able to swap back. Throws an error whose `code`
 // is in SWAP_FALLBACK_CODES when no atomic swap is possible here (no helper, or exit 3 / ENOTSUP / EINVAL).
-export function createSwapPaths({ env = process.env, resolve = resolveSwapHelper, execFileSync = nodeExecFileSync } = {}) {
+// A helper that exists must be code-signed (#258): an unsigned one is a typed SWAP_HELPER_UNSIGNED error naming the fix,
+// never a silent downgrade. No helper at all keeps the documented journaled two-rename fallback, which is logged
+// (`swap-fallback`, then `replaced {swap}`).
+export function createSwapPaths({ env = process.env, resolve = resolveSwapHelper, execFileSync = nodeExecFileSync, assertSigned = assertShippedSwapHelperSigned } = {}) {
+  const checked = new Set();
   return (a, b) => {
     const helper = resolve({ env });
     if (!helper) throw coded("ENOHELPER", `${SWAP_HELPER_NAME} helper not found`);
+    if (!checked.has(helper)) { assertSigned({ file: helper, execFileSync }); checked.add(helper); }
     try { execFileSync(helper, [a, b], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }); }
     catch (error) {
       const text = `${error?.stderr || ""}`.trim();
@@ -251,12 +267,15 @@ const defaultIsAlive = (pid) => {
   try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
 };
 
-async function trashBundle(run, fsImpl, home, now, bundle, appName) {
-  const trashDir = path.join(home, ".Trash");
-  fsImpl.mkdirSync(trashDir, { recursive: true });
-  const trashed = path.join(trashDir, trashName(appName, now()));
-  await moveAside(run, fsImpl, bundle, trashed);
-  return trashed;
+// 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;
 }
 
 // Deterministic roll-forward/back of any interrupted install journal in `dest`. Idempotent.
@@ -292,8 +311,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 { await trashBundle(run, fsImpl, home, now, j.staged, path.basename(j.installed)); action = "rolled-forward"; }
-            catch { action = "rolled-forward-trash-pending"; keepJournal = true; keepStaged = true; }
+            try { await keepPreviousBundle(run, fsImpl, j.staged, j.installed); action = "rolled-forward"; }
+            catch { action = "rolled-forward-previous-pending"; keepJournal = true; keepStaged = true; }
           } else {
             swapBack(swapPaths, fsImpl, j.staged, j.installed); // staged now holds the bad new bundle
             action = "rolled-back";
@@ -306,8 +325,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 { await trashBundle(run, fsImpl, home, now, j.backup, path.basename(j.installed)); action = "rolled-forward"; }
-          catch { action = "rolled-forward-trash-pending"; keepJournal = true; }
+          try { await keepPreviousBundle(run, fsImpl, j.backup, j.installed); action = "rolled-forward"; }
+          catch { action = "rolled-forward-previous-pending"; keepJournal = true; }
         } else {
           rm(j.installed);
           fsImpl.renameSync(j.backup, j.installed);
@@ -376,7 +395,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 the Trash, so it must not be touched.
+        // staged holds the verified-old bundle awaiting retirement to .previous, so it must not be touched.
         if (!s.final) {
           if (s.swapped) swapBack(swapPaths, fsImpl, s.staged, s.installed);
           removeQuiet(s.staged);
@@ -486,8 +505,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`);
-    const backup = hadInstalled ? path.join(opts.dest, `.${base}.rightkit-backup-${pid}.app`) : null;
+    const backup = hadInstalled ? previousPathOf(installed) : null;
     const journal = journalPathFor(opts.dest, appName);
     const journalData = { schema: 1, appName, pid, phase: "staging", dev, installed, backup, staged, mount: mountPoint, mountRoot };
     removeQuiet(staged);
@@ -512,7 +532,7 @@ export async function installApp(opts, deps = {}) {
 
     // Swap. Preferred: one atomic exchange (renamex_np RENAME_SWAP), so `installed` is never absent even
     // under SIGKILL; the old bundle then sits at the staged path. Fallback (no helper, or a volume without
-    // RENAME_SWAP): old -> backup, staged -> installed, journaled. The old bundle is never trashed before
+    // RENAME_SWAP): old -> backup, staged -> installed, journaled. The old bundle is never retired before
     // the new one is verified.
     failedStage = "replace";
     let jd = journalData;
@@ -535,6 +555,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
         fsImpl.renameSync(installed, backup); swap.backedUp = true;
         fsImpl.renameSync(staged, installed);
         swap.stagedIn = true;
@@ -555,16 +576,18 @@ export async function installApp(opts, deps = {}) {
     writeJournal(fsImpl, journal, { ...jd, phase: "verified", mount: null, mountRoot: null });
     swap.final = true;
 
-    // Only now does the old bundle go to the Trash.
-    let trashed = null;
+    // Only now is the old bundle retired, to <installed>.previous (never the Trash).
+    let kept = null;
+    let keepFailed = false;
     const oldBundle = swapMode === "atomic" ? staged : backup; // atomic: the exchange left the old bundle at the staged path
     if (hadInstalled && oldBundle) {
-      try { trashed = await trashBundle(run, fsImpl, home, now, oldBundle, appName); }
-      catch (error) { event("backup-trash-failed", { backup: oldBundle, reason: errText(error) }); trashed = oldBundle; }
+      try { kept = await keepPreviousBundle(run, fsImpl, oldBundle, installed); }
+      catch (error) { event("previous-keep-failed", { backup: oldBundle, reason: errText(error) }); kept = oldBundle; }
     }
-    if (!oldBundle || trashed !== oldBundle) removeQuiet(journal);
+    if (!oldBundle || kept !== previousPathOf(installed)) { if (!oldBundle) removeQuiet(journal); }
+    else removeQuiet(journal);
     swap = null;
-    event("replaced", { installed, previous: trashed, swap: swapMode });
+    event("replaced", { installed, previous: kept, swap: swapMode });
 
     // Relaunch hidden and in the background only.
     const relaunch = opts.relaunch === null ? wasRunning : opts.relaunch;
@@ -573,7 +596,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: trashed, swap: swapMode, relaunched: relaunch, ...(dev ? { dev: true } : {}) };
+    const result = { ok: true, app: appName, installed, bundleId, teamId: newTeam, previous: kept, swap: swapMode, relaunched: relaunch, ...(dev ? { dev: true } : {}) };
     event("done", result);
     return result;
   } catch (error) {
@@ -685,6 +708,7 @@ export async function main(argv = process.argv.slice(2), io = {}) {
     stderr(`right-release install-app: ${error.message}`);
     stderr("usage: right-release install-app (--dmg <path.dmg> | --dev (--zip <path.zip> | --app <path.app> | --dmg <path.dmg>)) [--app-name Pulse.app] [--bundle-id dev.orthic.pulse] [--dest /Applications] [--relaunch|--no-relaunch] [--json]");
     stderr("       right-release install-app --recover [--dest /Applications] [--app-name Pulse.app] [--json]");
+    stderr("       right-release install-app --installer <Setup.exe> --dest <fixed install folder> --exe <App.exe> [--json]   (Windows: in place, keeps <dest>.previous)");
     stderr("  --dev installs a Developer ID-signed, NOT notarized build (skips spctl/stapler, clears quarantine on the new bundle).");
     return 2;
   }
@@ -696,10 +720,16 @@ export async function main(argv = process.argv.slice(2), io = {}) {
     else stdout(`install-app: ${event}${Object.keys(rest).length ? ` ${JSON.stringify(rest)}` : ""}`);
   };
   try {
+    if (opts.installer !== null) {
+      installAppWindows(opts, { ...io.deps, event: (name, data = {}) => emit({ event: name, ...data }) });
+      emit({ event: "done", dest: opts.dest });
+      return 0;
+    }
     if (opts.recover) await recoverApp(opts, { ...io.deps, emit });
     else await installApp(opts, { ...io.deps, emit });
     return 0;
   } catch (error) {
+    if (error instanceof InstallAppWindowsError) { stderr(`install-app: ${error.code}: ${error.message}`); return error.code === "unsupported" ? 3 : 1; }
     return error.code === "unsupported" ? 3 : 1;
   }
 }

package/local-publish.mjs

@@ -17,7 +17,8 @@ import { GATE_SCHEMA, defaultEvidencePath, enforcePublicationGate, publishGatedT
 import { runCargoPublish } from "./publish-cargo.mjs";
 import { cargoIndexUrl } from "./cargo-registry-readback.mjs";
 import { readCargoPackage } from "./crate-graph.mjs";
-import { recordPublished } from "./rightkit-sync.mjs";
+import { recordPublished, stageSourceVersions } from "./rightkit-sync.mjs";
+import { prepareSwapHelper, SWAP_HELPER_CARGO_ARGS, SWAP_HELPER_PACKAGE } from "./swap-helper-bundle.mjs";
 
 export const LOCAL_OPERATOR = "agent (local-build grant)";
 export const LOCAL_HOST_POLICY_REASON = "Adrian 2026-10-14 local-build grant (.rightkit-local-build.json); Windows covered by the next CI run";
@@ -194,7 +195,16 @@ export async function runLocalPublish(kind, argv, deps = {}) {
   const cleanup = () => fs.rmSync(scratch, { recursive: true, force: true });
   try {
     let artifactFile; const packCommands = [];
+    if (kind === "npm" && unit === SWAP_HELPER_PACKAGE) {
+      // #258: the package ships a Developer-ID-signed bin/darwin/rightkit-swap; build, sign and verify it before packing (fails closed).
+      try { (deps.prepareSwapHelper ?? prepareSwapHelper)({ workspaceRoot, packageDir: unitPath, platform, run, env, log }); }
+      catch (error) { refuse(`${error.code ? `[${error.code}] ` : ""}${error.message}`); }
+      packCommands.push(`rightkit cargo ${SWAP_HELPER_CARGO_ARGS.join(" ")} && codesign --verify --strict bin/darwin/rightkit-swap`);
+    }
     if (kind === "npm") {
+      // The feed a tarball ships must list the version it ships with (#319): stage it before packing.
+      const feedFile = path.join(workspaceRoot, "packages", "release", "rightkit-versions.json");
+      if (fs.existsSync(feedFile)) (deps.stageSourceVersions ?? stageSourceVersions)([{ registry: "npm", name: unit, version }], { file: feedFile, root: workspaceRoot, log });
       const args = ["--dir", dir, "pack", "--pack-destination", scratch];
       packCommands.push(`pnpm ${args.join(" ")}`);
       const packed = run("pnpm", args, { cwd: workspaceRoot, env });

package/mac-signing-matrix.mjs

@@ -1,8 +1,9 @@
 // Per-file macOS signing matrix for `sign.prePackageFiles[]` object entries and `sign.nestedCode`.
 //
 //   sign: {
-//     prePackageFiles: ["dist/tool", { file: "dist/App.app", entitlements: "release/app.entitlements.plist" }],
-//     nestedCode: { "Contents/Helpers/Helper": { options: ["library"] },
+//     prePackageFiles: ["dist/tool", { file: "dist/App.app", entitlements: "release/app.entitlements.plist" },
+//                       { file: "dist/legion-hook", identifier: "com.example.legion-hook" }],
+//     nestedCode: { "Contents/Helpers/Helper": { options: ["library"], identifier: "com.example.helper" },
 //                   "Contents/PlugIns/Ext.appex": { entitlements: "release/ext.entitlements.plist" } },
 //   }
 //
@@ -16,8 +17,12 @@ const invalid = (message) => Object.assign(new Error(message), { code: "MAC_SIGN
 
 /** codesign `--options` names accepted in `options[]` (man codesign, OPTION FLAGS). `runtime` is always on. */
 export const CODESIGN_OPTION_FLAGS = Object.freeze(["expires", "hard", "host", "kill", "library", "runtime"]);
-const ENTRY_KEYS = new Set(["file", "entitlements", "hardenedRuntime", "options"]);
-const SETTING_KEYS = new Set(["entitlements", "hardenedRuntime", "options"]);
+const ENTRY_KEYS = new Set(["file", "entitlements", "hardenedRuntime", "options", "identifier"]);
+const SETTING_KEYS = new Set(["entitlements", "hardenedRuntime", "options", "identifier"]);
+// A stable per-file code identity: codesign `--identifier`. A loose tool otherwise gets an identifier derived from its file
+// name or cdhash, and macOS keys privacy grants (TCC) to the code identity, so it must not change between builds.
+// Same pattern as mac-sign-core.mjs (not imported: that module imports this one).
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9.-]{0,254}$/;
 
 const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 
@@ -33,7 +38,11 @@ function looksLikePlist(file) {
 }
 
 function validateSettings(settings, label, { root, errors, isFile }) {
-  const out = { entitlements: undefined, hardenedRuntime: true, options: [] };
+  const out = { entitlements: undefined, hardenedRuntime: true, options: [], identifier: undefined };
+  if (settings.identifier !== undefined) {
+    if (typeof settings.identifier !== "string" || !IDENTIFIER_PATTERN.test(settings.identifier)) errors.push(`${label}.identifier must be 1-255 characters of letters, digits, '.' and '-', starting with a letter or digit`);
+    else out.identifier = settings.identifier;
+  }
   if (settings.entitlements !== undefined) {
     const value = settings.entitlements;
     if (typeof value !== "string" || !value.trim()) errors.push(`${label}.entitlements must be a non-empty path string`);
@@ -79,8 +88,8 @@ function validateNestedKey(key) {
 /**
  * Validate and normalize `sign` for a macOS target. Collects every problem, then throws one
  * MAC_SIGN_CONFIG_INVALID error. Returns { entries, nestedCode } where
- *   entries:    [{ file, entitlements?: absolute, options: [] }]   (file stays as declared)
- *   nestedCode: [{ key, entitlements?: absolute, options: [] }]
+ *   entries:    [{ file, identifier?, entitlements?: absolute, options: [] }]   (file stays as declared)
+ *   nestedCode: [{ key, identifier?, entitlements?: absolute, options: [] }]
  * Injectable: isFile.
  */
 export function validateMacSigningConfig(sign, { root, isFile = (file) => existsSync(file) && statSync(file).isFile() } = {}) {
@@ -106,7 +115,7 @@ export function validateMacSigningConfig(sign, { root, isFile = (file) => exists
       if (seen.has(file)) errors.push(`${label}: duplicate signing entry ${file}`);
       seen.add(file);
       const normalized = validateSettings(settings, label, context);
-      entries.push({ file, ...(normalized.entitlements ? { entitlements: normalized.entitlements } : {}), options: normalized.options });
+      entries.push({ file, ...(normalized.identifier ? { identifier: normalized.identifier } : {}), ...(normalized.entitlements ? { entitlements: normalized.entitlements } : {}), options: normalized.options });
     });
   }
   if (sign.nestedCode !== undefined) {
@@ -119,7 +128,7 @@ export function validateMacSigningConfig(sign, { root, isFile = (file) => exists
         if (!isPlainObject(settings)) { errors.push(`${label} must be an object { entitlements?, hardenedRuntime?, options? }`); continue; }
         for (const name of Object.keys(settings)) if (!SETTING_KEYS.has(name)) errors.push(`${label}: unknown key ${JSON.stringify(name)} (allowed: ${[...SETTING_KEYS].join(", ")})`);
         const normalized = validateSettings(settings, label, context);
-        nestedCode.push({ key, ...(normalized.entitlements ? { entitlements: normalized.entitlements } : {}), options: normalized.options });
+        nestedCode.push({ key, ...(normalized.identifier ? { identifier: normalized.identifier } : {}), ...(normalized.entitlements ? { entitlements: normalized.entitlements } : {}), options: normalized.options });
       }
       if (nestedCode.length) {
         const apps = entries.filter((entry) => /\.app\/?$/.test(entry.file));
@@ -132,7 +141,7 @@ export function validateMacSigningConfig(sign, { root, isFile = (file) => exists
 }
 
 /** True when an entry or nested item carries anything beyond the default (hardened runtime, no entitlements). */
-export const hasNonDefaultSettings = (item) => Boolean(item.entitlements) || (item.options?.length ?? 0) > 0;
+export const hasNonDefaultSettings = (item) => Boolean(item.entitlements) || Boolean(item.identifier) || (item.options?.length ?? 0) > 0;
 
 const depth = (file) => file.split(path.sep).length;
 
@@ -162,7 +171,7 @@ export function planMacSigning({ entries, nestedCode = [], expand = expandMacSig
       const real = realpath(file);
       if (real !== appReal && !real.startsWith(appReal + path.sep)) throw invalid(`${label}: resolves outside the bundle`);
       if (real === mainReal) throw invalid(`${label}: the main executable is signed with the bundle; set entitlements on its sign.prePackageFiles entry`);
-      byPath.set(file, { file, ...(item.entitlements ? { entitlements: item.entitlements } : {}), options: item.options });
+      byPath.set(file, { file, ...(item.identifier ? { identifier: item.identifier } : {}), ...(item.entitlements ? { entitlements: item.entitlements } : {}), options: item.options });
     }
   }
   const nested = [...byPath.values()].sort((a, b) => depth(b.file) - depth(a.file) || a.file.localeCompare(b.file));
@@ -178,6 +187,9 @@ export function matrixReceiptProblems(evidenceFiles, entries, hashFile) {
     if (!item) { problems.push(`missing receipt entry for ${entry.file}`); continue; }
     const wantOptions = ["runtime", ...(entry.options ?? [])].join(",");
     if ((item.codesignOptions ?? "runtime") !== wantOptions) problems.push(`${entry.file}: signed with options ${item.codesignOptions ?? "runtime"}, expected ${wantOptions}`);
+    if (entry.identifier) {
+      if (item.identifier !== entry.identifier) problems.push(`${entry.file}: signed with identifier ${item.identifier ?? "(none recorded)"}, expected ${entry.identifier}`);
+    } else if (item.identifier) problems.push(`${entry.file}: signed with identifier ${item.identifier} the plan did not declare`);
     if (entry.entitlements) {
       if (item.entitlements?.sha256 !== hashFile(entry.entitlements)) problems.push(`${entry.file}: receipt entitlements digest does not match ${entry.entitlements}`);
     } else if (item.entitlements) problems.push(`${entry.file}: signed with entitlements the plan did not declare`);

package/managed-cargo.mjs

@@ -1,5 +1,6 @@
 import { discoverBrokerSocket, managedControlCandidates, resolveManagedRoots } from './managed-roots.mjs';
 import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
@@ -12,6 +13,11 @@ export function managedRuntimeClient(env = process.env, platform = process.platf
     const client = paths.join(root, "runtime-current", platform === 'win32' ? "rustright.exe" : "rustright");
     if (exists(client)) return client;
   }
+  // RustRight's own install (2026-10-17 cutover): the Mac agent-bin shims exec this client directly.
+  if (platform === 'darwin') {
+    const client = path.posix.join(env.HOME || homedir(), 'Library', 'Application Support', 'RustRight', 'runtime', 'rustright');
+    if (exists(client)) return client;
+  }
   return undefined;
 }
 

package/media-sidecar-catalog.mjs

@@ -0,0 +1,45 @@
+// Find the rightkit-ffmpeg crate (its catalog and notice files) for a release.
+//
+// Order: `mediaSidecar.catalog` in the release config (the crate's catalog/artifacts.json; the crate directory is the
+// catalog's grandparent), otherwise the crate Cargo resolves for the app's native manifest (`cargo metadata --offline`,
+// so the catalog is exactly the one the app was compiled against, at the version in its Cargo.lock).
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { runCargoSync } from "./managed-cargo.mjs";
+
+const invalid = (code, message) => Object.assign(new Error(message), { code });
+
+export function cargoFfmpegCrate(manifestPath, { run = runCargoSync } = {}) {
+  const result = run(["metadata", "--offline", "--format-version", "1", "--manifest-path", manifestPath], {
+    cwd: path.dirname(manifestPath),
+    encoding: "utf8",
+    maxBuffer: 256 * 1024 * 1024,
+    windowsHide: true,
+  });
+  if (result.error) throw invalid("MEDIA_SIDECAR_CRATE_NOT_FOUND", `could not run cargo metadata: ${result.error.message}`);
+  if (result.status !== 0) throw invalid("MEDIA_SIDECAR_CRATE_NOT_FOUND", `cargo metadata failed: ${String(result.stderr ?? "").trim()}`);
+  const metadata = JSON.parse(result.stdout);
+  const crates = metadata.packages.filter((pkg) => pkg.name === "rightkit-ffmpeg");
+  if (crates.length !== 1) throw invalid("MEDIA_SIDECAR_CRATE_NOT_FOUND", `the app's dependency graph has ${crates.length} rightkit-ffmpeg packages (expected exactly one)`);
+  return { crateDir: path.dirname(crates[0].manifest_path), crateVersion: crates[0].version };
+}
+
+/** Returns { catalog, catalogBytes, crateDir, crateVersion }. Injectable: read, crateFor. */
+export function loadSidecarCatalog({ config, root, manifestPath, read = readFileSync, crateFor = cargoFfmpegCrate }) {
+  let crateDir;
+  let crateVersion;
+  let catalogPath;
+  if (config.catalog) {
+    catalogPath = path.resolve(root, config.catalog);
+    crateDir = path.dirname(path.dirname(catalogPath));
+  } else {
+    if (!manifestPath) throw invalid("MEDIA_SIDECAR_CRATE_NOT_FOUND", "no mediaSidecar.catalog and no native Cargo manifest to resolve rightkit-ffmpeg from");
+    ({ crateDir, crateVersion } = crateFor(manifestPath));
+    catalogPath = path.join(crateDir, "catalog", "artifacts.json");
+  }
+  let catalogBytes;
+  try { catalogBytes = read(catalogPath); } catch (error) { throw invalid("MEDIA_SIDECAR_CATALOG_INVALID", `cannot read ${catalogPath}: ${error.message}`); }
+  let catalog;
+  try { catalog = JSON.parse(String(catalogBytes)); } catch { throw invalid("MEDIA_SIDECAR_CATALOG_INVALID", `${catalogPath} is not JSON`); }
+  return { catalog, catalogBytes, crateDir, crateVersion };
+}