@rightkit/release 0.6.4 → 0.6.5

package/bin/rightkit-gate.mjs

@@ -24,10 +24,16 @@
 //   rightkit-gate [--base <ref>] [--plan] [--no-cache]
 //                                             run the gate (default base origin/main); --plan prints the scans and runs none;
 //                                             --no-cache (or RK_GATE_CACHE=0) reruns every scan
+//   rightkit-gate check [--repo <dir>] [--commit <rev> | --worktree] [--only <rule,...>] [--list] [--print-baseline] [--baseline <file>]
+//                                             the offline app check (../app-check.mjs): committed files only, no network, compile or
+//                                             broker, every finding in one run. Exit 0 pass, 1 findings, 2 could not run
 //   rightkit-gate install-hook [--force]      write .githooks/pre-push and set core.hooksPath. core.hooksPath hides .git/hooks, so the
-//                                             pre-push hook runs the repository's own .git/hooks/pre-push first and every other hook
-//                                             present in .git/hooks gets a .githooks/<name> trampoline that runs it; the hook finds
-//                                             the gate binary in the root node_modules/.bin, then any workspace package's, then pnpm exec
+//                                             pre-push hook runs the repository's own .git/hooks/pre-push first, then `rightkit-gate
+//                                             check --commit HEAD`, then the gate; every other hook present in .git/hooks gets a
+//                                             .githooks/<name> trampoline that runs it; the hook finds the gate binary in the root
+//                                             node_modules/.bin, then any workspace package's, then pnpm exec. Where @rightkit/release is
+//                                             installed it also writes the advisory ownership pre-commit step (`right-release hooks install`
+//                                             is an alias of this command)
 //
 // From the pre-push hook, git's ref lines arrive on stdin: the commit being pushed must be the checked-out HEAD (broker scans
 // read the live checkout), and the remote's current commit is the diff base. To push an earlier commit of the local stack,
@@ -58,7 +64,7 @@ const text = (r) => String(r?.stdout ?? "");
 const failed = (r) => !r || Boolean(r.error) || r.status !== 0;
 const why = (r) => String(r?.error?.message ?? r?.stderr ?? "").trim().split(/\r?\n/).slice(-3).join(" | ");
 
-const USAGE = `usage: rightkit-gate [--base <ref>] [--plan] [--no-cache] [--pre-push] | rightkit-gate install-hook [--force] | --version`;
+const USAGE = `usage: rightkit-gate [--base <ref>] [--plan] [--no-cache] [--pre-push] | rightkit-gate install-hook [--force] | rightkit-gate check [--repo <dir>] [--commit <rev> | --worktree] [--only <rule,...>] [--list] [--print-baseline] [--baseline <file>] | --version`;
 
 // ---- pure helpers (exported for tests) ----------------------------------------------------------------------
 
@@ -340,13 +346,15 @@ export function lockScope({ changed, cargoDir = ".", unitNames, showBase, readLo
 /**
  * The pre-push hook. git's ref lines arrive on stdin and the gate consumes them, so stdin is buffered once and fed to both the
  * repository's own .git/hooks/pre-push (which core.hooksPath=.githooks would otherwise hide; it runs first and a failure stops the
- * push) and the gate. The gate binary is the root node_modules/.bin/rightkit-gate, else any workspace package's (up to three
- * levels down: tauri-app-next, apps/*, packages/*), else `pnpm exec rightkit-gate`, else node with a package-relative path when
- * pnpm is absent; the line it chose is printed. No absolute path is written: everything is resolved from git at run time.
+ * push) and the gate. Between them runs the app check, `rightkit-gate check --commit HEAD`: seconds, committed files only, so a
+ * red tree stops the push before the gate's scans start; a push that only deletes refs has no content to check and skips it. The
+ * gate binary is the root node_modules/.bin/rightkit-gate, else any workspace package's (up to three levels down: tauri-app-next,
+ * apps/*, packages/*), else `pnpm exec rightkit-gate`, else node with a package-relative path when pnpm is absent; the line it
+ * chose is printed once. No absolute path is written: everything is resolved from git at run time.
  */
 export function hookText(nodePath) {
   return `#!/bin/sh
-# Mandatory local gate before every push (rightkit-gate install-hook). Never bypass with --no-verify.
+# Mandatory local check and gate before every push (rightkit-gate install-hook). Never bypass with --no-verify.
 cd "$(git rev-parse --show-toplevel)" || exit 1
 stdin=$(mktemp "\${TMPDIR:-/tmp}/rightkit-gate.XXXXXX") || exit 1
 trap 'rm -f "$stdin"' EXIT
@@ -358,18 +366,27 @@ if [ -x "$own" ]; then
   "$own" "$@" < "$stdin" || exit $?
 fi
 # The gate binary: the root install, any workspace package's install, then pnpm exec.
+found=""
 for bin in node_modules/.bin/rightkit-gate */node_modules/.bin/rightkit-gate */*/node_modules/.bin/rightkit-gate */*/*/node_modules/.bin/rightkit-gate; do
-  if [ -x "$bin" ]; then
-    echo "rightkit-gate: using $bin" >&2
-    ("$bin" --base origin/main) < "$stdin"; exit $?
-  fi
+  if [ -x "$bin" ]; then found="$bin"; break; fi
 done
-if command -v pnpm >/dev/null 2>&1; then
+if [ -n "$found" ]; then
+  echo "rightkit-gate: using $found" >&2
+  rightkit_gate() { "$found" "$@"; }
+elif command -v pnpm >/dev/null 2>&1; then
   echo "rightkit-gate: using pnpm exec rightkit-gate" >&2
-  (exec pnpm exec rightkit-gate --base origin/main) < "$stdin"; exit $?
+  rightkit_gate() { pnpm exec rightkit-gate "$@"; }
+else
+  echo "rightkit-gate: using node ${nodePath}" >&2
+  rightkit_gate() { node "${nodePath}" "$@"; }
 fi
-echo "rightkit-gate: using node ${nodePath}" >&2
-(exec node "${nodePath}" --base origin/main) < "$stdin"; exit $?
+# The check first, over the committed files of HEAD; a push that only deletes refs has nothing to check.
+if [ -s "$stdin" ] && ! awk '$2 !~ /^0+$/ { found = 1 } END { exit !found }' "$stdin"; then
+  echo "rightkit-gate: only deletions are pushed; nothing to check" >&2
+else
+  rightkit_gate check --commit HEAD < /dev/null >&2 || exit $?
+fi
+rightkit_gate --base origin/main < "$stdin"; exit $?
 `;
 }
 
@@ -780,7 +797,12 @@ function releaseProvider(o, root, git) {
   return null;
 }
 
-function installHook(o, root, force) {
+// The advisory ownership pre-commit step (`right-release hooks install`, ownership-hooks.mjs) runs the pinned @rightkit/release, so
+// it is written only where that is installed. Its own hook and the repository's .git/hooks/pre-commit both keep running.
+const PINNED_CLI = "node_modules/@rightkit/release/cli/right-release.mjs";
+const FOREIGN_PRE_COMMIT = "pre-commit.rightkit-foreign";
+
+async function installHook(o, root, force) {
   const git = (...a) => o.spawn("git", a, { cwd: root });
   const hooksDir = path.join(root, ".githooks");
   const hookPath = path.join(hooksDir, "pre-push");
@@ -797,15 +819,29 @@ function installHook(o, root, force) {
   const gitDirResult = git("rev-parse", "--git-dir");
   let present = [];
   if (!failed(gitDirResult) && text(gitDirResult).trim()) { try { present = o.readdir(path.join(path.resolve(root, text(gitDirResult).trim()), "hooks")); } catch { present = []; } }
+  const gitHooksDir = !failed(gitDirResult) && text(gitDirResult).trim() ? path.join(path.resolve(root, text(gitDirResult).trim()), "hooks") : null;
   const own = present.filter(chainableHook).sort();
-  const skipped = present.filter((name) => !name.endsWith(".sample") && !chainableHook(name)).sort();
+  // The ownership step takes .githooks/pre-commit. The repository's own pre-commit hook keeps running first, through a trampoline
+  // beside it, unless it is the ownership hook a plain `right-release hooks install` wrote (this one replaces that), whose own
+  // chained hook, pre-commit.rightkit-foreign, then runs instead. A name that is no plain hook name is reported, never chained.
+  const ownership = o.exists(path.join(root, PINNED_CLI)) ? await import("../ownership-hooks.mjs") : null;
+  const readHook = (name) => { try { return o.readFile(path.join(gitHooksDir, name)); } catch { return ""; } };
+  const chainName = !ownership ? null : own.includes("pre-commit") && !readHook("pre-commit").includes(ownership.HOOK_MARKER) ? "pre-commit" : present.includes(FOREIGN_PRE_COMMIT) ? FOREIGN_PRE_COMMIT : null;
+  const skipped = present.filter((name) => !name.endsWith(".sample") && !chainableHook(name) && !(ownership && name === FOREIGN_PRE_COMMIT)).sort();
   if (skipped.length) o.err(`rightkit-gate: WARNING: not chaining .git/hooks/${skipped.join(", .git/hooks/")}: not a plain hook file name (letters, digits, - and _ only); run it from a hook of its own.`);
-  const trampolines = own.filter((name) => name !== "pre-push").map((name) => ({ name, file: path.join(hooksDir, name), wanted: trampolineText(name) }));
+  const trampolines = own.filter((name) => name !== "pre-push" && !(ownership && name === "pre-commit")).map((name) => ({ name, file: path.join(hooksDir, name), wanted: trampolineText(name), note: `runs .git/hooks/${name}` }));
+  if (ownership) {
+    trampolines.push({ name: "pre-commit", file: path.join(hooksDir, "pre-commit"), wanted: ownership.renderPreCommitHook(), ownership: true, replaces: [trampolineText("pre-commit")], marker: ownership.HOOK_MARKER, note: "the advisory ownership gate: right-release ownership --staged" });
+    if (chainName) trampolines.push({ name: FOREIGN_PRE_COMMIT, file: path.join(hooksDir, FOREIGN_PRE_COMMIT), wanted: trampolineText(chainName), note: `runs .git/hooks/${chainName}, before the ownership gate` });
+  }
   for (const t of trampolines) {
     t.exists = o.exists(t.file);
-    t.current = t.exists ? o.readFile(t.file).replace(/\r\n/g, "\n") === t.wanted : false;
-    if (t.exists && !t.current && !force) {
-      o.err(`rightkit-gate: .githooks/${t.name} already exists and differs; nothing changed. Review it, or run \`rightkit-gate install-hook --force\` to replace it with a trampoline to .git/hooks/${t.name}.`);
+    const found = t.exists ? o.readFile(t.file).replace(/\r\n/g, "\n") : null;
+    t.current = found === t.wanted;
+    // Our own earlier artifacts are updated in place: a plain trampoline where the ownership hook now goes, and an older ownership hook.
+    const ours = found !== null && (t.current || t.replaces?.includes(found) || (t.marker && found.includes(t.marker)));
+    if (t.exists && !ours && !force) {
+      o.err(`rightkit-gate: .githooks/${t.name} already exists and differs; nothing changed. Review it, or run \`rightkit-gate install-hook --force\` to replace it with ${t.ownership ? "the ownership pre-commit hook" : `a trampoline to .git/hooks/${chainName ?? t.name}`}.`);
       return 1;
     }
   }
@@ -825,7 +861,7 @@ function installHook(o, root, force) {
   else put(hookPath, wanted, `${hasHook ? "replaced" : "wrote"} .githooks/pre-push`, ` (${nodePath} without pnpm)`);
   for (const t of trampolines) {
     if (t.current) done.push(`.githooks/${t.name} already current`);
-    else put(t.file, t.wanted, `${t.exists ? "replaced" : "wrote"} .githooks/${t.name}`, ` (runs .git/hooks/${t.name})`);
+    else put(t.file, t.wanted, `${t.exists ? "replaced" : "wrote"} .githooks/${t.name}`, ` (${t.note})`);
   }
   if (existingPath === ".githooks") done.push("core.hooksPath already .githooks");
   else {
@@ -836,6 +872,7 @@ function installHook(o, root, force) {
   for (const line of done) o.out(`rightkit-gate: ${line}`);
   const chained = own.length ? own.map((name) => (name === "pre-push" ? "pre-push (run first, then the gate)" : name)) : [];
   o.out(`rightkit-gate: chained hooks from .git/hooks: ${chained.length ? chained.join(", ") : "none"}${own.includes("pre-push") ? "" : "; the pre-push hook still runs .git/hooks/pre-push first if one appears later"}`);
+  if (!ownership) o.out(`rightkit-gate: no ownership pre-commit step: ${PINNED_CLI} is not installed here; install @rightkit/release, then run install-hook again`);
   const files = [".githooks/pre-push", ...trampolines.map((t) => `.githooks/${t.name}`)];
   o.out(`rightkit-gate: commit the hooks with executable mode (git add --chmod=+x ${files.join(" ")}); the pre-push hook finds rightkit-gate in node_modules/.bin of the repository root, else of any workspace package, else through \`pnpm exec\`.`);
   const provider = releaseProvider(o, root, git);
@@ -865,14 +902,16 @@ export async function main(argv, io = {}) {
   }
   if (args.includes("--help") || args.includes("-h")) { o.out(USAGE); return 0; }
   const sub = args[0] && !args[0].startsWith("-") ? args[0] : null;
-  if (sub && sub !== "install-hook") { o.err(`rightkit-gate: unknown command ${JSON.stringify(sub)}\n${USAGE}`); return 2; }
+  if (sub && sub !== "install-hook" && sub !== "check") { o.err(`rightkit-gate: unknown command ${JSON.stringify(sub)}\n${USAGE}`); return 2; }
+  // The app check has its own export and reads no gate state: it needs neither the base ref nor the pushed refs on stdin.
+  if (sub === "check") return (o.appCheck ?? (await import("../app-check.mjs")).main)(args.slice(1), { out: o.out, err: o.err, label: "check", cwd: o.cwd });
   if (args.includes("--base") && (!option("--base") || option("--base").startsWith("--"))) { o.err("rightkit-gate: --base needs a ref"); return 2; }
 
   const top = o.spawn("git", ["rev-parse", "--show-toplevel"], { cwd: o.cwd });
   if (failed(top) || !text(top).trim()) { o.err("rightkit-gate: not inside a git repository"); return 2; }
   const root = path.resolve(text(top).trim());
   const git = (...a) => o.spawn("git", a, { cwd: root });
-  if (sub === "install-hook") return installHook(o, root, args.includes("--force"));
+  if (sub === "install-hook") return await installHook(o, root, args.includes("--force"));
 
   const planOnly = args.includes("--plan");
   let base = option("--base") ?? "origin/main";

package/build-release.mjs

@@ -20,7 +20,9 @@ import {
 import path from "node:path";
 import { preflightOwnershipScope } from "./ownership-scope.mjs";
 import { spawn, spawnSync } from "./background-process.mjs";
-import { RightKitRegistryError, SNAPSHOT_ENV, SNAPSHOT_FILE, assertManifestRegistryEvidence, loadAdmittedSnapshot, prepareRightKitResolution, registryManifestFields, rightKitLockInventory, writeAdmissionRecord } from "./rightkit-registry-resolver.mjs";
+import { RightKitRegistryError, SNAPSHOT_ENV, SNAPSHOT_FILE, assertManifestRegistryEvidence, loadAdmittedSnapshot, prepareRightKitResolution, registryManifestFields, rightKitLockInventory, writeAdmissionRecord, writeSnapshot } from "./rightkit-registry-resolver.mjs";
+import { formatAdmission, formatNotRun, runAdmission } from "./admission.mjs";
+import { sccacheRefusal } from "./admission-host.mjs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { assertPrimaryReleaseCheckout, dirtyBuildInputs, resolveReleaseBuildInputs } from "./release-invocation.mjs";
 import { resolveNativeCargoLayout } from "./native-cargo-layout.mjs";
@@ -129,12 +131,15 @@ for (let i = 0; i < args.length; i += 1) {
 if (platform !== "win" && platform !== "mac" && platform !== "android" && platform !== "ios") fail("--platform must be win, mac, android or ios");
 if (resumeFrom && !["prepackage", "sign", "package", "post-sign", "harden"].includes(resumeFrom)) fail("--resume-from must be prepackage, sign, package, post-sign, or harden");
 
-const configPath = path.resolve(configName);
+// Native real paths: Git reports the long form of a Windows short name (RUNNER~1) and the target of a symlinked temp root
+// (macOS /var -> /private/var). The config path is resolved the same way the doctor resolves it (release.mjs), so every path
+// derived from it (app root, build inputs, scan roots) compares equal to what Git reports; a non-canonical app root made the
+// build-inputs qualification drop every input and the clean-source gate speak before the dirty-inputs row.
+const nativeReal = (file) => { try { return realpathSync.native(file); } catch { return file; } };
+const configPath = nativeReal(path.resolve(configName));
 const invocationRoot = path.dirname(configPath);
 const repoRoot = git(invocationRoot, ["rev-parse", "--show-toplevel"]);
 assertPrimaryReleaseCheckout(repoRoot);
-// Native real paths: Git reports the long form of a Windows short name (RUNNER~1).
-const nativeReal = (file) => { try { return realpathSync.native(file); } catch { return file; } };
 const relativeConfig = path.relative(nativeReal(repoRoot), nativeReal(configPath)).replaceAll("\\", "/");
 if (relativeConfig.startsWith("../")) fail("release config must live inside the Git repository");
 const appRoot = path.dirname(configPath);
@@ -148,21 +153,19 @@ let heavySlot;
 let interrupted;
 let requestActiveRunStop = null;
 
-// A dry-run is an inspection contract, not a partial build. It must finish
-// before locks, cache directories, receipts, dependency installation, or any
+// Admission (admission.mjs): every refusal the committed files, this host or the registries can decide is raised here, before the
+// dry-run exit, the clean-source gate, the release lock, any state file, the install, a slot or the worker. `right-release doctor`
+// runs the same rows with the same text, so the two cannot disagree (rightkit#946); a refused build leaves nothing behind.
+const admitted = await admit();
+
+// A dry-run is an inspection contract, not a partial build. It prints the admission rows and exits with their verdict, so it can
+// never pass what the build refuses. It must finish before locks, cache directories, receipts, dependency installation, or any
 // child build/sign process can exist.
 if (dryRun) {
-  const commit = git(invocationRoot, ["rev-parse", "HEAD"]);
-  const dirtyConfig = dirtyBuildInputs(repoRoot, { include: [relativeConfig], required: [relativeConfig] }, commit);
-  if (dirtyConfig.length > 0) fail(`dirty release config cannot be executed:\n${dirtyConfig.map((file) => `- ${file}`).join("\n")}`);
-  const config = (await import(`${pathToFileURL(configPath).href}?dry-run=${commit}`)).default;
-  if (!config?.app || !config?.version) fail("release config must expose app and version");
-  const target = config.targets?.[platform];
-  // Android builds with target.gradle (validated by release.mjs), not a package command; iOS with targets.ios.iosPackage.
-  if (platform !== "android" && platform !== "ios" && !target?.package && !packageCommandOptional(target, resolveProjectType({ appRoot, config, target }))) fail(`${config.app} has no ${platform} package command`);
-  console.log(`right-release build dry-run: ${config.app} ${config.version} ${platform}`);
+  console.log(`right-release build dry-run: ${admitted.config.app} ${admitted.config.version} ${platform}`);
   console.log(`config: ${configPath}`);
-  console.log(`commit: ${commit}`);
+  console.log(`commit: ${admitted.commit}`);
+  for (const line of formatAdmission(admitted.result)) console.log(line);
   process.exit(0);
 }
 
@@ -396,7 +399,8 @@ try {
   let rightKitResolution = null;
   if (!legacySealed) {
     try {
-      rightKitResolution = await prepareRightKitResolution({
+      // A fresh build already asked the registries in admission(); the snapshot is bound to this release's state root below.
+      rightKitResolution = (!rightKitReuse && admitted.registry) || await prepareRightKitResolution({
         root: appRoot,
         extraLocks: rightKitLockInventory({ requiredInputs, cargoLockPaths: pinnedCargoLocks, nativeLayout, config, root: appRoot }),
         versions: JSON.parse(readFileSync(path.join(TOOL_ROOT, "rightkit-versions.json"), "utf8")),
@@ -414,6 +418,7 @@ try {
       if (!(error instanceof RightKitRegistryError)) throw error;
       fail(`${error.recoverable ? "RECOVERABLE " : ""}${error.message}`);
     }
+    if (rightKitResolution === admitted.registry) writeSnapshot(rightKitSnapshotFile, rightKitResolution.snapshot);
     for (const line of rightKitResolution.freshness.tasks) console.error(`[right-release] LANE TASK ${line}`);
     for (const line of rightKitResolution.freshness.warnings) console.error(`[right-release] WARNING ${line}`);
     console.error(`[right-release] rightkit-registry: ${rightKitResolution.summary}`);
@@ -552,6 +557,52 @@ try {
   lock?.release();
 }
 
+// Read the config and run the admission rows (files, this host and, for a fresh build, the registries) with no side effect: no lock,
+// state directory, cache directory, install or snapshot file. A finding is printed with its row and the process exits 1, no stack.
+async function admit() {
+  let commit;
+  let config;
+  try {
+    commit = git(invocationRoot, ["rev-parse", "HEAD"]);
+    const dirtyConfig = dirtyBuildInputs(repoRoot, { include: [relativeConfig], required: [relativeConfig] }, commit);
+    if (dirtyConfig.length > 0) fail(`dirty release config cannot be executed:\n${dirtyConfig.map((file) => `- ${file}`).join("\n")}`);
+    try { config = (await import(`${pathToFileURL(configPath).href}?commit=${commit}`)).default; } catch (error) { fail(`release config could not be loaded (${configPath}): ${error instanceof Error ? error.message : String(error)}`); }
+  } catch (error) {
+    if (error?.reported) process.exit(1);
+    throw error;
+  }
+  // A fresh build asks the registries once, here; a resume or a re-run over a sealed release reuses its recorded snapshot instead.
+  const platformName = platform === "win" ? "windows" : platform;
+  const sealed = config?.app && config?.version
+    && existsSync(path.join(repoRoot, ".right-release", "sealed", `${config.app}-${config.version}-${commit.slice(0, 8)}`, platformName, "release-manifest.json"));
+  const reuse = Boolean(resumeFrom) || Boolean(sealed);
+  const result = await runAdmission({
+    root: appRoot, repoRoot, configPath, config: config ?? {}, platform, commit, skipChecks,
+    tiers: reuse ? ["files", "host"] : ["files", "host", "network"],
+    registry: async (ctx) => {
+      const inputs = ctx.buildInputs();
+      if (!inputs.ok) return undefined; // the build-inputs row reports it
+      return prepareRightKitResolution({
+        root: appRoot,
+        extraLocks: rightKitLockInventory({ requiredInputs: inputs.value.requiredInputs, cargoLockPaths: inputs.value.cargoLockPaths, nativeLayout: inputs.value.nativeLayout, config, root: appRoot }),
+        versions: JSON.parse(readFileSync(path.join(TOOL_ROOT, "rightkit-versions.json"), "utf8")),
+        ownership: JSON.parse(readFileSync(path.join(TOOL_ROOT, "rightkit-ownership.json"), "utf8")),
+        releaseVersion: RELEASE_TOOL_VERSION,
+        // Build admission: refuse every pin behind the registry's latest. A dry run asks, but keeps no cache on disk.
+        admission: true,
+        ...(dryRun ? { cacheDir: "" } : {}),
+      });
+    },
+  });
+  for (const finding of result.findings) console.error(`right-release build: ${finding.row}: ${finding.detail}`);
+  for (const line of formatNotRun(result)) console.error(`right-release build: ${line}`);
+  if (result.findings.length > 0) {
+    console.error(`right-release build: admission found ${result.findings.length} blocking problem(s); nothing was started`);
+    process.exit(1);
+  }
+  return { config, commit, result, registry: result.out.registry ?? null };
+}
+
 function hashInputs(files) {
   const hashes = {};
   for (const file of files) {
@@ -610,6 +661,14 @@ function sealRelease({ configRoot, managedCargoTarget, androidTarget, iosSpec, n
     current.add(role);
     sources.set(source, current);
   };
+  // Named refusals for a config the admission's seal-routes row already refused, so nothing here crashes on an undefined field.
+  for (const artifact of [...(target.installer?.artifacts ?? []), ...(target.updater?.artifacts ?? [])]) {
+    if (typeof artifact?.file !== "string" || !artifact.file) fail("installer and updater artifacts must each declare a file");
+  }
+  for (const artifact of target.updater?.artifacts ?? []) {
+    if (target.updater?.kind !== "appinstaller" && (typeof artifact.signature !== "string" || !artifact.signature)) fail(`updater artifact ${artifact.file} must declare the signature file sign-updater writes next to it`);
+    if (artifact.key === undefined && config.distribution?.provider !== "github-releases") fail(`updater artifact ${artifact.file} must declare the R2 route key (key); only github-releases names the route from the file`);
+  }
   for (const artifact of target.installer?.artifacts ?? []) addSource(resolveArtifactPath(artifact.file), "installer");
   for (const artifact of target.updater?.artifacts ?? []) {
     addSource(resolveArtifactPath(artifact.file), "updater");
@@ -741,9 +800,9 @@ function sealRelease({ configRoot, managedCargoTarget, androidTarget, iosSpec, n
     // an unsound seal, not a portable release.
     signing: signingIdentity ? { ...signingIdentity, receipts: (() => {
       const present = signingIdentity.receiptInputs.filter((file) => existsSync(file));
-      if (present.length === 0) throw new Error(`no signing receipts found to seal; expected at least ${signingIdentity.receiptInputs[0]}`);
+      if (present.length === 0) fail(`no signing receipts found to seal; expected at least ${signingIdentity.receiptInputs[0]}`);
       if (platform === "mac") {
-        if (present.length !== signingIdentity.receiptInputs.length) throw new Error("missing current-build macOS signing or notarization receipt");
+        if (present.length !== signingIdentity.receiptInputs.length) fail("missing current-build macOS signing or notarization receipt");
         validateNotarizationReceipt({ receiptPath: signingIdentity.receiptInputs[1], archive: resolveArtifactPath(target.notarize.file) });
       }
       return present.map((file) => ({ file, sha256: hashFile(file) }));
@@ -941,7 +1000,7 @@ function commandExists(name) {
 
 function assertSccacheVersion(version) {
   const match = String(version ?? "").match(/sccache\s+(\d+)\.(\d+)\.(\d+)/i);
-  if (!match || Number(match[1]) === 0 && Number(match[2]) < 15) fail("shared cache requires sccache >= 0.15.0; install with: cargo install sccache --locked; then verify: sccache --version");
+  if (!match || Number(match[1]) === 0 && Number(match[2]) < 15) fail(sccacheRefusal(match ? match.slice(1).join(".") : null));
 }
 
 function commandOutput(cmd, runArgs) {
@@ -1000,7 +1059,8 @@ function usage(code) {
 
 function fail(message) {
   console.error(`right-release build: ${message}`);
-  throw new Error(message);
+  // `reported` marks an error whose text is already printed, so a caller that exits on it prints nothing twice.
+  throw Object.assign(new Error(message), { reported: true });
 }
 
 function throwIfInterrupted() { if (interrupted) throw interrupted; }

package/cli/right-release.mjs

@@ -54,7 +54,17 @@ const commands = new Map([
 
 const args = process.argv.slice(2);
 const first = args[0];
+// The commands that compile, package, sign, ship or inspect a release run the app check (../app-check.mjs, CHECKED_COMMANDS) in this
+// process before they start a child. A red check prints its findings and exits 1; there is no flag that skips it.
+async function requireGreenCheck() {
+  const { guardCommand } = await import("../app-check.mjs");
+  const refused = guardCommand({ args });
+  if (!refused) return;
+  for (const line of refused.lines) console.error(line);
+  process.exit(refused.exitCode);
+}
 if (first === "dev") {
+  await requireGreenCheck();
   import("../development.mjs").then(({ main }) => main(args.slice(1))).catch((error) => {
     console.error(`right-release dev: ${error.code ? `[${error.code}] ` : ""}${error.message}`);
     process.exitCode = 1;
@@ -81,6 +91,8 @@ if (!first || first === "-h" || first === "--help") {
   process.exit(0);
 }
 
+await requireGreenCheck();
+
 if (first === "--version" || first === "-v") {
   run("release.mjs", ["--version"]);
 } else if (first === "doctor") {
@@ -89,6 +101,18 @@ if (first === "--version" || first === "-v") {
   } else {
     run("release.mjs", ["--doctor", ...args.slice(1)]);
   }
+} else if (first === "check") {
+  // The same offline check as `rightkit-gate check`; the repository is the git top-level of --config's folder, else the cwd.
+  const { appDirectory, main } = await import("../app-check.mjs");
+  process.exit(await main(args.slice(1), { label: "check", cwd: appDirectory(args, process.cwd()) }));
+} else if (first === "hooks" && args[1] === "install") {
+  // One installer: `hooks install` is `rightkit-gate install-hook` (pre-push check and gate, ownership pre-commit step) run in the app.
+  const app = args.indexOf("--app");
+  if (app >= 0 && (!args[app + 1] || args[app + 1].startsWith("-"))) {
+    console.error("right-release hooks install: --app needs a directory");
+    process.exit(2);
+  }
+  run("bin/rightkit-gate.mjs", ["install-hook", ...(args.includes("--force") ? ["--force"] : [])], { cwd: app >= 0 ? path.resolve(args[app + 1]) : process.cwd() });
 } else if (first === "hooks") {
   run("ownership-hooks.mjs", args.slice(1));
 } else if (first === "suite-doctor") {
@@ -170,9 +194,9 @@ if (first === "--version" || first === "-v") {
   process.exit(2);
 }
 
-function run(script, scriptArgs) {
+function run(script, scriptArgs, { cwd = process.cwd() } = {}) {
   const child = spawn(process.execPath, [path.join(packageRoot, script), ...scriptArgs], {
-    cwd: process.cwd(),
+    cwd,
     env: process.env,
     stdio: "inherit",
     windowsHide: true,
@@ -308,12 +332,21 @@ Commands:
   apple profile renew [--config <file>] [--profile <file>] [--dry-run]
                                                       Renew macOS profile for current Keychain signer
   signing-agent install|uninstall|status              Manage invisible Aqua-session signing service
-  doctor [--platform mac|win] [--gates]               Inspect one app's release config; --gates also runs the build's pre-build source gates
+  check [--repo <dir>] [--config <file>] [--commit <rev> | --worktree] [--only <rule,...>] [--list] [--print-baseline] [--baseline <file>]
+                                                      The offline app check, same as rightkit-gate check: committed files only, every finding in one run (exit 0 pass, 1 findings, 2 could not run).
+                                                      Build, package, dev, test, web-build, swift-package, recipe-build, stage-sidecar, qa, upload, publish, publish-update, github, doctor,
+                                                      sign-windows, sign-updater, sign-candidate, sign-dev-artifact, addon build and create-mac-updater run it first and start nothing when it is red; there is no flag that skips it.
+                                                      Baseline: .rightkit/app-check-baseline.json (entries carry issue, added and sunset; the sunset is at most 90 days after added)
+  doctor [--platform mac|win] [--gates] [--inspect] [--strict]
+                                                      Inspect one app's release config the way the build would refuse it; --gates also runs the build's pre-build source gates
+                                                      --inspect lists admission findings (newer RightKit versions) as information instead of refusing them
+                                                      --strict makes a row that could not run on this host (NOT RUN) a blocking problem; without it NOT RUN is printed and does not fail
+                                                      --admission is still accepted and does nothing (admission is the default); it cannot be combined with --inspect
   doctor --all                                       Verify all Right Suite app release contracts
   suite-doctor                                       Verify all local Right Suite repositories
   ownership [--app <dir>] [--json]                   Fail on app copies of RightKit-owned capabilities
   ownership --staged [--app <dir>] [--json]          Pre-commit gate: scan the staged index for block-tier findings
-  hooks install [--app <dir>]                        Install the advisory pre-commit ownership gate (pinned @rightkit/release)
+  hooks install [--app <dir>] [--force]              Alias of rightkit-gate install-hook: the pre-push check and gate, and the advisory pre-commit ownership gate (pinned @rightkit/release)
   ownership enroll [--root] [--name <device>] [--root-fingerprint <sha256>] [--app <dir>]
                                                       Enroll one native key or create a signed-device request
   ownership approve-key <fingerprint|request.json>    Approve one pending device key from an active host

package/deterministic-scans.mjs

@@ -205,10 +205,11 @@ const WORKSPACE_JS_FILE = /^(package\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|
 const ESLINT_FILES = ["eslint.config.js", "eslint.config.mjs", ".eslintrc.json"];
 const ROOT_LINT_FILES = [...ESLINT_FILES, "biome.json"];
 // Everything scripts/generate-index.mjs reads or writes (its header and loadInventory): crate and package manifests and
-// READMEs, the root Cargo.toml (workspace version), the versions and ownership data, the ownership-availability helper it imports, itself, and its outputs.
+// READMEs, the root Cargo.toml (workspace version), the versions and ownership data, the ownership-availability helper it imports, itself,
+// the port matrix generator it imports, and its outputs (the port matrix's MD and HTML are checked for consistency with its JSON).
 // The Right Suite API contract and every projection scripts/gen-suite-api.mjs writes from it (the test-vector copy included).
 const SUITE_API_INPUT = /^(contracts\/right-suite-api\.v1\.json|scripts\/gen-suite-api\.mjs|crates\/rightkit-license\/src\/suite_api_generated\.rs|packages\/app-update\/src\/suite-api\.generated\.ts|packages\/release\/suite-api\.generated\.mjs|crates\/rightkit-license\/test-vectors\/right-suite-api\.v1\.json)$/;
-const GENERATOR_INPUT = /^(crates\/[^/]+\/(Cargo\.toml|README\.md)|packages\/[^/]+\/(package\.json|README\.md)|Cargo\.toml|packages\/release\/(rightkit-versions\.json|rightkit-ownership\.json|ownership-availability\.mjs)|scripts\/generate-index\.mjs|INDEX\.md|docs\/(ADOPTION|CAPABILITY-MAP)\.md)$/;
+const GENERATOR_INPUT = /^(crates\/[^/]+\/(Cargo\.toml|README\.md)|packages\/[^/]+\/(package\.json|README\.md)|Cargo\.toml|packages\/release\/(rightkit-versions\.json|rightkit-ownership\.json|ownership-availability\.mjs)|scripts\/generate-(index|port-matrix)\.mjs|INDEX\.md|docs\/(ADOPTION|CAPABILITY-MAP|PORT-MATRIX)\.md|docs\/port-matrix\.(html|json))$/;
 const PROBES = Object.freeze({
   rustfmt: ["--version"], node: ["--version"], rustright: ["cargo", "--version"], pnpm: ["--version"],
   actionlint: ["-version"], "right-git": ["--version"], swift: ["--version"],
@@ -358,10 +359,25 @@ export function planScans({
   // ---- class A: content checks on the exported commit
   // A vendor/ file keeps upstream formatting only when vendor/upstream-files.json records it and its
   // bytes still match that upstream digest; any other vendor/ .rs (new, patched) is rustfmt-checked.
-  let upstream = {};
-  try { upstream = JSON.parse(readFile(path.join(contentRoot, "vendor/upstream-files.json"))).files ?? {}; } catch { /* no manifest: nothing exempt */ }
+  // A patched vendor/ file (rightkit#915) keeps upstream formatting only while its bytes match the
+  // reviewed `patched` record, which names its upstream base digest and the note describing the patch;
+  // reformatting it would bury the patch. Any edit changes the digest, so the file is checked until re-recorded.
+  let upstream = {}; let patched = {};
+  try {
+    const manifest = JSON.parse(readFile(path.join(contentRoot, "vendor/upstream-files.json")));
+    upstream = manifest.files ?? {}; patched = manifest.patched ?? {};
+  } catch { /* no manifest: nothing exempt */ }
+  const DIGEST = /^[0-9a-f]{64}$/;
   const verbatimUpstream = (f) => f.startsWith("vendor/") && typeof upstream[f] === "string" && bytesDigest(f) === upstream[f];
-  const rustFiles = files.filter((f) => f.endsWith(".rs") && !verbatimUpstream(f));
+  const recordedPatch = (f) => f.startsWith("vendor/") && DIGEST.test(patched[f]?.base ?? "") && typeof patched[f]?.note === "string"
+    && patched[f].note.startsWith("vendor/") && DIGEST.test(patched[f]?.sha256 ?? "") && bytesDigest(f) === patched[f].sha256;
+  // Generated Rust is not hand-formatted: bindgen output, or rustfmt's own `@generated` marker in the first five lines.
+  const generatedRust = (f) => {
+    let head = "";
+    try { head = readFile(path.join(contentRoot, f)).split("\n", 5).join("\n"); } catch { return false; }
+    return /@generated\b|automatically generated by rust-bindgen\b/.test(head);
+  };
+  const rustFiles = files.filter((f) => f.endsWith(".rs") && !verbatimUpstream(f) && !recordedPatch(f) && !generatedRust(f));
   const byEdition = new Map();
   for (const f of rustFiles) {
     let dir = path.dirname(path.join(contentRoot, f));

package/inventory-check.mjs

@@ -16,6 +16,7 @@ import {
   generateAdoption,
   generateLocal,
 } from "../../scripts/generate-index.mjs";
+import { PORT_MATRIX_OUTPUTS, generatePortMatrix } from "../../scripts/generate-port-matrix.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const DEFAULT_REPO_ROOT = resolve(HERE, "..", "..");
@@ -781,6 +782,16 @@ function checkGenerated({ repoRoot, appsRoot, apps, findings }) {
   for (const rel of driftOf(repoRoot, adoption)) {
     findings.push(issue("generated", rel, "generated-doc-drift", "committed adoption report differs from the app repos; run generate-index.mjs"));
   }
+  // The port matrix reads the app repos like the adoption report. Its stamp, app directories and HEADs, and per-app check counts
+  // are carried over from the committed docs/port-matrix.json, so only a change in the data itself reads as drift.
+  try {
+    const matrix = generatePortMatrix({ root: repoRoot, workspace: appsRoot, carry: true });
+    for (const rel of driftOf(repoRoot, matrix.outputs)) {
+      findings.push(issue("generated", rel, "generated-doc-drift", "committed port matrix differs from the app repos; run generate-index.mjs"));
+    }
+  } catch (error) {
+    findings.push(issue("generated", PORT_MATRIX_OUTPUTS[2], "generated-doc-drift", `the port matrix could not be regenerated: ${error.message}`));
+  }
   return { local, adoption: Object.values(adoption)[0] };
 }
 
@@ -842,7 +853,7 @@ export async function runInventoryCheck(options = {}) {
       account: { crates: account.crates, npm: account.npm },
       thirdParty: { declarations: thirdParty.declarations, uniquePackages: thirdParty.uniquePackages, lockDuplicates: thirdParty.lockDuplicates },
       apps: { rows: appRows },
-      generated: { checked: ["INDEX.md", "docs/CAPABILITY-MAP.md", "docs/ADOPTION.md"] },
+      generated: { checked: ["INDEX.md", "docs/CAPABILITY-MAP.md", "docs/ADOPTION.md", ...PORT_MATRIX_OUTPUTS] },
       hygiene: { checked: records.length },
     },
   };

package/ownership-dependency-allowlist.json

@@ -399,10 +399,12 @@
         "cargo:base64",
         "cargo:block2",
         "cargo:chrono",
+        "cargo:clap",
         "cargo:dirs",
         "cargo:futures",
         "cargo:getrandom",
         "cargo:image",
+        "cargo:libc",
         "cargo:objc2",
         "cargo:objc2-foundation",
         "cargo:reqwest",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/release",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Portable release CLI/SDK with fail-closed public GitHub Releases and private R2 + RightApps distribution.",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -33,7 +33,9 @@
     "LICENSE-MIT",
     "LICENSE-APACHE",
     "!*.test.mjs",
-    "!standalone-clone-evidence.json"
+    "!cli/*.test.mjs",
+    "!standalone-clone-evidence.json",
+    "!refusals.json"
   ],
   "sideEffects": false,
   "publishConfig": {
@@ -49,7 +51,7 @@
     "smol-toml": "1.9.1"
   },
   "scripts": {
-    "test": "node --import ./test-support/broker-guard.mjs --test --test-concurrency=1 --test-force-exit *.test.mjs",
+    "test": "node --import ./test-support/broker-guard.mjs --test --test-concurrency=1 --test-force-exit *.test.mjs cli/*.test.mjs",
     "test:registry-parity": "node registry-parity.mjs --allow-unpublished",
     "test:signer:windows": "node sign-release-manifest.integration.mjs",
     "doctor:all": "node --test right-suite-contract.test.mjs",

package/prebuild-gates.mjs

@@ -1,6 +1,6 @@
 // Source-level release gates that run before a build starts. The build (release.mjs) and `doctor --gates` call the
 // same function, so the doctor can never pass a config the build refuses. Gate order is part of the contract.
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
 import { assertReleaseDependencies } from "./release-dependencies.mjs";
@@ -145,11 +145,15 @@ export function evaluatePrebuildGates({ root, config, target, platform, iosSpec,
   let sourceRoots;
   let skipRoots;
   let repoTop;
+  let appRootReal;
+  const nativeReal = (file) => { try { return realpathSync.native(file); } catch { return file; } };
   if (releaseSwitchInventoryText != null) {
     gate("source-switch-roots", ["closure-commands", ...(strict ? ["feature-closure"] : [])], () => {
       if (platform === "ios") {
         repoTop = git(root, ["rev-parse", "--show-toplevel"]);
-        const swiftSide = (iosOwnershipScope({ repoRoot: repoTop, appRoot: root, target: config.targets?.ios }) ?? []).filter((dir) => dir !== ".rightkit").map((dir) => path.join(repoTop, dir));
+        // Git reports the canonical path; a caller's root may be a symlink or a Windows short name (hosted temp roots).
+        appRootReal = nativeReal(root);
+        const swiftSide = (iosOwnershipScope({ repoRoot: repoTop, appRoot: appRootReal, target: config.targets?.ios }) ?? []).filter((dir) => dir !== ".rightkit").map((dir) => path.join(repoTop, dir));
         sourceRoots = [...new Set([...swiftSide, ...localCrateDirsFromTree(treeText, repoTop)])].sort();
         console.log(`right-release: source switch scan (ios): ${sourceRoots.map((dir) => path.relative(repoTop, dir) || ".").join(", ")}`);
       } else {
@@ -162,7 +166,7 @@ export function evaluatePrebuildGates({ root, config, target, platform, iosSpec,
     if (platform === "ios") {
       gate("source-switch-prepare", ["source-switch-roots"], () => {
         for (const step of config.targets?.ios?.iosPackage?.prepare ?? []) {
-          const cwd = path.resolve(root, step?.cwd ?? ".");
+          const cwd = path.resolve(appRootReal, step?.cwd ?? ".");
           if (!sourceRoots.some((dir) => cwd === dir || cwd.startsWith(dir + path.sep))) throw new Error(`source switch inventory: targets.ios.iosPackage.prepare runs in ${path.relative(repoTop, cwd) || "."}, outside the iOS scan roots (${sourceRoots.map((dir) => path.relative(repoTop, dir) || ".").join(", ")}); list that directory in targets.ios.ownershipScope`);
         }
       });