@rightkit/release 0.6.5 → 0.6.6

package/init-command.mjs

@@ -3,7 +3,8 @@
 // (bogusyogi/rightkit#385): renames the desktop app template into a real app, in place. Ports PostRight's
 // crates/tools/src/init.rs. The template identity (`RightApp`, `rightapp`, `RIGHTAPP`, `app.rightsuite.rightapp`)
 // is rewritten in text files; nothing else is touched and no gate or build is run.
-import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -50,6 +51,60 @@ export function resolveIdentity({ name, id, slug }) {
   return { name, id, slug: resolvedSlug, warnings };
 }
 
+// Cargo writes Cargo.lock with its [[package]] tables sorted by name (then version) and each `dependencies` list sorted by name, and
+// `cargo --locked` refuses a lock that differs from what it would write. Renaming the template's own crates moves them in that order,
+// so the lock is re-sorted after the text rename; without it every `--locked` script fails on the first build of the new app.
+const LOCK_FILE = "Cargo.lock";
+const byteOrder = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const semverParts = (version) => {
+  const [core, pre] = String(version ?? "").split("+")[0].split(/-(.*)/s);
+  return { nums: core.split(".").map((part) => Number.parseInt(part, 10) || 0), pre: pre ?? null };
+};
+function compareSemver(a, b) {
+  const x = semverParts(a);
+  const y = semverParts(b);
+  for (let i = 0; i < 3; i += 1) if (x.nums[i] !== y.nums[i]) return (x.nums[i] ?? 0) - (y.nums[i] ?? 0);
+  if (x.pre === y.pre) return 0;
+  if (x.pre === null) return 1;
+  if (y.pre === null) return -1;
+  return byteOrder(x.pre, y.pre);
+}
+const lockField = (block, key) => new RegExp(`^${key} = "([^"]*)"$`, "m").exec(block)?.[1] ?? "";
+/** `"name"`, `"name version"` or `"name version (source)"`: the name and version of one `dependencies` entry. */
+const lockDependency = (line) => {
+  const [name = "", version = ""] = line.trim().replace(/^"|",?$/g, "").split(" ");
+  return { name, version };
+};
+
+/** Sort one lock's [[package]] tables and their `dependencies` lists the way cargo writes them; everything else is kept byte for byte. */
+export function sortCargoLock(text) {
+  const crlf = text.includes("\r\n");
+  const lf = crlf ? text.replace(/\r\n/g, "\n") : text;
+  const first = /^\[\[package\]\]$/m.exec(lf);
+  if (!first) return text;
+  const head = lf.slice(0, first.index);
+  let body = lf.slice(first.index);
+  let tail = "";
+  const other = /^\[(?!\[package\]\]$)/m.exec(body);
+  if (other) {
+    tail = body.slice(other.index);
+    body = body.slice(0, other.index);
+  }
+  const blocks = body.replace(/\n+$/, "").split(/\n\n(?=\[\[package\]\]$)/m).map((block) => block.replace(
+    /^dependencies = \[\n([\s\S]*?)\n\]$/m,
+    (_, list) => `dependencies = [\n${list.split("\n").map((line) => ({ line, ...lockDependency(line) }))
+      .sort((a, b) => byteOrder(a.name, b.name) || compareSemver(a.version, b.version)).map((entry) => entry.line).join("\n")}\n]`,
+  ));
+  blocks.sort((a, b) => byteOrder(lockField(a, "name"), lockField(b, "name")) || compareSemver(lockField(a, "version"), lockField(b, "version")));
+  const out = `${head}${blocks.join("\n\n")}\n${tail ? `\n${tail}` : ""}`;
+  return crlf ? out.replace(/\n/g, "\r\n") : out;
+}
+
+/** Rename the template identity in a Cargo.lock and restore cargo's order, so `cargo --locked` accepts the renamed lock. */
+export function reidentifyCargoLock(text, identity) {
+  return sortCargoLock(renameText(text, identity));
+}
+
 export function walkTextFiles(dir, out = []) {
   let entries;
   try {
@@ -61,26 +116,66 @@ export function walkTextFiles(dir, out = []) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       if (!SKIP_DIRS.has(entry.name)) walkTextFiles(full, out);
-    } else if (entry.isFile() && TEXT_EXT.has(path.extname(entry.name).slice(1))) {
+    } else if (entry.isFile() && (TEXT_EXT.has(path.extname(entry.name).slice(1)) || entry.name === LOCK_FILE)) {
       out.push(full);
     }
   }
   return out;
 }
 
+// `rightapps` is not the template identity: it is the RightApps distribution service (the `r2-rightapps` provider), which every app
+// keeps. A spelling followed by a whole-word `s` is therefore left alone; `rightapp-engine`, `rightapp_protocol`, `RIGHTAPP_HOME` and
+// the rest of the identity still rename.
+const spelling = (word) => new RegExp(`${word}(?![sS](?![A-Za-z0-9]))`, "g");
+const UPPER_WORD = spelling(UPPER);
+const TITLE_WORD = spelling(TITLE);
+const LOWER_WORD = spelling(LOWER);
+
 /** Rewrite the template identity in one string; the bundle id first, then the three spellings. */
 export function renameText(text, { name, id, slug }) {
   return text
     .replaceAll(TEMPLATE_ID, id)
-    .replaceAll(UPPER, slug.toUpperCase())
-    .replaceAll(TITLE, name)
-    .replaceAll(LOWER, slug);
+    .replace(UPPER_WORD, () => slug.toUpperCase())
+    .replace(TITLE_WORD, () => name)
+    .replace(LOWER_WORD, () => slug);
+}
+
+export const LEGAL_MANIFEST = "legal/legal-manifest.json";
+const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+/**
+ * Recompute the `sha256` of every document and appendix of a legal manifest from the bytes `read(relativePath)` returns (paths are
+ * relative to the manifest's directory; `read` returns Buffer, string or null for a missing file). Returns `{ text, changed, stale,
+ * material }`: the manifest text with the new digests (2-space JSON, as `legal-snapshot` writes it), the entries whose digest moved,
+ * and which of those are material agreements. Material documents feed the acceptance digest in src/generated/legal-contract.json, which
+ * only `legal-snapshot` can recompute, so the caller warns about them.
+ */
+export function rehashLegalManifest(text, read) {
+  const manifest = JSON.parse(text);
+  const changed = [];
+  const material = [];
+  for (const entry of [...(manifest.documents ?? []), ...(manifest.appendices ?? [])]) {
+    const bytes = typeof entry?.path === "string" ? read(entry.path) : null;
+    if (bytes === null || bytes === undefined) continue;
+    const digest = sha256Hex(typeof bytes === "string" ? Buffer.from(bytes) : bytes);
+    if (entry.sha256 === digest) continue;
+    entry.sha256 = digest;
+    changed.push(entry.path);
+    if (entry.material === true) material.push(entry.path);
+  }
+  return { text: changed.length ? `${JSON.stringify(manifest, null, 2)}\n` : text, changed, material };
 }
 
-/** Rename the template under `root`. Returns the identity and the changed file paths (relative, sorted). */
+/**
+ * Rename the template under `root`. Returns the identity, the changed file paths (relative, sorted) and `warnings`.
+ * The rename changes the bytes of text the legal manifest hashes (the privacy notice and the npm appendix carry the product name), so the
+ * manifest's digests are recomputed from the renamed bytes in the same pass.
+ */
 export function initTemplate(root, options) {
   const identity = resolveIdentity(options);
   const changed = [];
+  const warnings = [...identity.warnings];
+  const renamed = new Map();
   for (const file of walkTextFiles(root)) {
     if (path.basename(file) === SELF) continue;
     let before;
@@ -89,20 +184,51 @@ export function initTemplate(root, options) {
     } catch {
       continue;
     }
-    const after = renameText(before, identity);
+    const after = path.basename(file) === LOCK_FILE ? reidentifyCargoLock(before, identity) : renameText(before, identity);
     if (after === before) continue;
+    renamed.set(path.resolve(file), after);
     if (!options.dryRun) writeFileSync(file, after);
     changed.push(path.relative(root, file).split(path.sep).join("/"));
   }
-  return { ...identity, changed: changed.sort() };
+  const manifestFile = path.join(root, ...LEGAL_MANIFEST.split("/"));
+  if (existsSync(manifestFile)) {
+    const legalDir = path.dirname(manifestFile);
+    const read = (relative) => {
+      const target = path.resolve(legalDir, relative);
+      if (renamed.has(target)) return renamed.get(target);
+      try { return readFileSync(target); } catch { return null; }
+    };
+    const rehashed = rehashLegalManifest(renamed.get(path.resolve(manifestFile)) ?? readFileSync(manifestFile, "utf8"), read);
+    if (rehashed.changed.length) {
+      if (!options.dryRun) writeFileSync(manifestFile, rehashed.text);
+      if (!changed.includes(LEGAL_MANIFEST)) changed.push(LEGAL_MANIFEST);
+    }
+    for (const material of rehashed.material) {
+      warnings.push(`the rename changed the material legal document legal/${material}, which feeds src/generated/legal-contract.json; run \`pnpm exec legal-snapshot\` to regenerate the acceptance contract`);
+    }
+  }
+  return { ...identity, changed: changed.sort(), warnings };
 }
 
+/** What a person does after init: the steps no command can do for them, in order. */
+export const NEXT_STEPS = Object.freeze([
+  "pnpm install                      (installs the pinned packages and, through `prepare`, the pre-push hook)",
+  "right-release doctor              (the build's own checks for this app, as rows)",
+  "set the app's public legal host in legal-snapshot.config.json, replace legal/PRODUCT_SCHEDULE.md and legal/PRIVACY_NOTICE.md with reviewed text, then `pnpm exec legal-snapshot`",
+  "register the repository on each host: add it to packages/release/ownership-repositories.json in RightKit (and its byte copy under packages/build-control-policy), then run `right-release ownership trust-refresh` on the Mac and the Dell (a person with administrator rights; an agent cannot)",
+  "README.md in the template: \"Create a new app (checklist)\"",
+]);
+
 export function runInitCommand(argv, io = { stdout: console.log, stderr: console.error }) {
   const opts = parseInitArgs(argv);
   const result = initTemplate(path.resolve(opts.dir), opts);
   for (const warning of result.warnings) io.stderr(`warning: ${warning}`);
   io.stdout(`right-release init${opts.dryRun ? " --dry-run" : ""}: ${result.changed.length} file(s) ${opts.dryRun ? "would change" : "changed"}`);
   for (const file of result.changed) io.stdout(`  ${file}`);
+  if (!opts.dryRun) {
+    io.stdout("next:");
+    for (const step of NEXT_STEPS) io.stdout(`  ${step}`);
+  }
   return result;
 }
 

package/ios-upload.mjs

@@ -21,8 +21,8 @@
 // TestFlight steps use the same in-memory ES256 JWT. No file, temp or not, ever holds the key; no altool, no Transporter.
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
 import { spawnSync } from "./background-process.mjs";
+import { defaultReleaseConfigFile, importReleaseConfig } from "./release-config.mjs";
 import { assertGuiSigningSession, assertIosHost, IosHostError } from "./ios-host.mjs";
 import { acquireFileLock } from "./ios-lock.mjs";
 import {
@@ -136,7 +136,7 @@ const git = (cwd, args) => {
 };
 
 /** Local checks only; no network, no secret. The sealed release is the only input: build-free by construction. */
-export async function authorizeIosUpload({ releaseId, configName = "right-release.config.mjs", cwd = process.cwd() }) {
+export async function authorizeIosUpload({ releaseId, cwd = process.cwd(), configName = defaultReleaseConfigFile(cwd) }) {
   if (!RELEASE_ID.test(releaseId ?? "")) refuse("IOS_UPLOAD_RELEASE_REQUIRED", "--release <sealed-id> is required");
   const repoRoot = git(cwd, ["rev-parse", "--show-toplevel"]);
   assertPrimaryReleaseCheckout(repoRoot);
@@ -144,8 +144,8 @@ export async function authorizeIosUpload({ releaseId, configName = "right-releas
   assertCleanSource({ status: git(repoRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]), commandId: "right-release upload" });
   const configPath = path.resolve(cwd, configName);
   if (!existsSync(configPath)) refuse("IOS_UPLOAD_CONFIG_INVALID", `release config is required: ${configName}`);
-  // The config is a module that runs on import: loaded only after the tree is proven clean.
-  const config = (await import(`${pathToFileURL(configPath).href}?upload=${Date.now()}`)).default;
+  // A legacy config is a module that runs on import (a JSON config is data): loaded only after the tree is proven clean.
+  const config = await importReleaseConfig(configPath, { query: `upload=${Date.now()}` });
   const distribution = validateIosDistribution(targetDistribution(config, "ios"));
   const sealedDir = path.join(repoRoot, ".right-release", "sealed", releaseId, "ios");
   const appRoot = path.dirname(configPath);

package/mirror-root-artifact.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Two forms:
 //   right-release mirror-root-artifact --file <artifact> --package-root <dir> [--name <filename>]
-//   right-release mirror-root-artifact --config <right-release.config.mjs> --platform mac|win [--package-root <dir>]
+//   right-release mirror-root-artifact --config <right-release.config.json> --platform mac|win [--package-root <dir>]
 // The config form mirrors every entry of `targets.<platform>.mirror`, a list of `"<app-relative file>"` or
 // `{ file, name?, pruneSuffix? }`. `pruneSuffix` (for example "-setup.exe") then removes the other files with that suffix
 // from the managed directory, so it holds exactly the current artifact. Run it as `targets.<platform>.postSign`.
@@ -10,7 +10,7 @@ import { configuredManagedRootSpellings } from "./artifact-storage.mjs";
 import { copyFileSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync } from "node:fs";
 import { execFileSync } from "./background-process.mjs";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { importReleaseConfig } from "./release-config.mjs";
 
 const args = parseArgs(process.argv.slice(2));
 const usage = "Usage: right-release mirror-root-artifact (--file <artifact> --package-root <dir> [--name <filename>] | --config <file> --platform mac|win [--package-root <dir>])";
@@ -31,8 +31,7 @@ let entries;
 let rootArg = args.packageRoot;
 if (args.config) {
   const configPath = path.resolve(args.config);
-  const loaded = await import(pathToFileURL(configPath).href);
-  const config = loaded.default ?? loaded.config ?? loaded;
+  const config = await importReleaseConfig(configPath, { lenient: true });
   const declared = config?.targets?.[args.platform]?.mirror;
   if (!Array.isArray(declared) || declared.length === 0) {
     console.error(`right-release mirror-root-artifact: targets.${args.platform}.mirror declares no files in ${args.config}`);

package/npm-license-notices.mjs

@@ -16,6 +16,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { spawnSync } from "./background-process.mjs";
 import { CommandSpecError, loadAppConfig, relativeInside } from "./command-spec.mjs";
+import { defaultReleaseConfigFile } from "./release-config.mjs";
 
 const fail = (message) => { throw new CommandSpecError(message); };
 
@@ -119,7 +120,7 @@ export function generateNpmNotices({ appRoot, config, flags = {}, check = false,
 }
 
 export function parseNoticeArgs(argv) {
-  const opts = { config: "right-release.config.mjs", output: undefined, productName: undefined, check: false };
+  const opts = { config: defaultReleaseConfigFile(), output: undefined, productName: undefined, check: false };
   const rest = argv[0] === "npm" ? argv.slice(1) : argv;
   if (argv[0] !== "npm") throw new Error("expected: license-notices npm");
   for (let i = 0; i < rest.length; i += 1) {

package/outdated-command.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// `right-release update <args>`: run the @rightkit/outdated updater (its `right-update` bin) that this package pins.
+//
+// Why a command and not only the dependency: pnpm links just the bins of a project's direct dependencies into
+// node_modules/.bin, so an app that depends on @rightkit/release alone has no `right-update` on its path even though
+// @rightkit/outdated is installed beneath release. This module finds the updater installed for @rightkit/release and
+// runs its bin, so `pnpm exec right-release update run` works in every app that can run `right-release`.
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "./background-process.mjs";
+
+export const OUTDATED_PACKAGE = "@rightkit/outdated";
+export const OUTDATED_BIN = "right-update";
+
+/** The exact command a refusal gives an app that must move a stale RightKit pin. */
+export const UPDATE_COMMAND = "pnpm exec right-release update run";
+
+export class OutdatedUnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OutdatedUnavailableError";
+    this.code = "OUTDATED_UNAVAILABLE";
+  }
+}
+
+const here = () => path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Directory of the @rightkit/outdated installed for the package at `fromDir`, or null. This is Node's lookup
+ * (each ancestor's node_modules, never one named node_modules itself) done on the filesystem, because
+ * @rightkit/outdated exports only "." under an `import` condition and a caller must not depend on that shape.
+ */
+export function findOutdatedPackage(fromDir = here()) {
+  let directory = realpathSync(fromDir);
+  for (;;) {
+    if (path.basename(directory) !== "node_modules") {
+      const candidate = path.join(directory, "node_modules", ...OUTDATED_PACKAGE.split("/"));
+      if (existsSync(path.join(candidate, "package.json"))) return realpathSync(candidate);
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+/** Absolute path of the `right-update` script of the @rightkit/outdated installed for the package at `fromDir`. */
+export function resolveOutdatedBin(fromDir = here()) {
+  const root = findOutdatedPackage(fromDir);
+  if (root === null) {
+    throw new OutdatedUnavailableError(`${OUTDATED_PACKAGE} is not installed for @rightkit/release; reinstall @rightkit/release so its pinned dependency is present`);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+  } catch {
+    throw new OutdatedUnavailableError(`${OUTDATED_PACKAGE} has an unreadable package.json at ${root}`);
+  }
+  const named = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.[OUTDATED_BIN];
+  if (manifest.name !== OUTDATED_PACKAGE || typeof named !== "string" || named === "") {
+    throw new OutdatedUnavailableError(`${root} is not an ${OUTDATED_PACKAGE} that provides ${OUTDATED_BIN}`);
+  }
+  const file = path.resolve(root, named);
+  const relative = path.relative(root, file);
+  if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative) || !existsSync(file)) {
+    throw new OutdatedUnavailableError(`${OUTDATED_PACKAGE} ${manifest.version ?? ""} lists ${OUTDATED_BIN} at ${named}, which is not installed`);
+  }
+  return file;
+}
+
+/** Run the updater with `argv` and resolve to its exit status. */
+export function runOutdated(argv, { fromDir = here(), cwd = process.cwd(), env = process.env, stdio = "inherit" } = {}) {
+  const bin = resolveOutdatedBin(fromDir);
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [bin, ...argv], { cwd, env, stdio, windowsHide: true });
+    child.on("error", reject);
+    child.on("exit", (code) => resolve(code ?? 1));
+  });
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  try {
+    process.exitCode = await runOutdated(argv);
+  } catch (error) {
+    console.error(`right-release update: ${error.message}`);
+    process.exitCode = error instanceof OutdatedUnavailableError ? 2 : 1;
+  }
+}
+
+const realOrSelf = (file) => { try { return realpathSync(file); } catch { return path.resolve(file); } };
+if (process.argv[1] && realOrSelf(process.argv[1]) === realOrSelf(fileURLToPath(import.meta.url))) await main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/release",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "Portable release CLI/SDK with fail-closed public GitHub Releases and private R2 + RightApps distribution.",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -8,8 +8,43 @@
     "right-release": "cli/right-release.mjs",
     "rightkit-gate": "bin/rightkit-gate.mjs"
   },
+  "exports": {
+    "./bin/rightkit-gate.mjs": "./bin/rightkit-gate.mjs",
+    "./cargo-contract.mjs": "./cargo-contract.mjs",
+    "./cargo-target.mjs": "./cargo-target.mjs",
+    "./cli/right-release.mjs": "./cli/right-release.mjs",
+    "./development.mjs": "./development.mjs",
+    "./direct-bootstrap.mjs": "./direct-bootstrap.mjs",
+    "./disk-policy.mjs": "./disk-policy.mjs",
+    "./dmg-build.mjs": "./dmg-build.mjs",
+    "./engine-locator.mjs": "./engine-locator.mjs",
+    "./github-release.mjs": "./github-release.mjs",
+    "./legal-contract.mjs": "./legal-contract.mjs",
+    "./macos-file-evidence.mjs": "./macos-file-evidence.mjs",
+    "./macos-notarization.mjs": "./macos-notarization.mjs",
+    "./macos-signing-identity.mjs": "./macos-signing-identity.mjs",
+    "./macos-signing-session.mjs": "./macos-signing-session.mjs",
+    "./managed-cargo.mjs": "./managed-cargo.mjs",
+    "./native-release-finalization.mjs": "./native-release-finalization.mjs",
+    "./notary-auth.mjs": "./notary-auth.mjs",
+    "./package.json": "./package.json",
+    "./packaged-app-identity.mjs": "./packaged-app-identity.mjs",
+    "./pe-content.mjs": "./pe-content.mjs",
+    "./publication-gate.mjs": "./publication-gate.mjs",
+    "./qa-build-features.mjs": "./qa-build-features.mjs",
+    "./release-dependencies.mjs": "./release-dependencies.mjs",
+    "./sign-windows.mjs": "./sign-windows.mjs",
+    "./signing-agent-client.mjs": "./signing-agent-client.mjs",
+    "./stage-binary.mjs": "./stage-binary.mjs",
+    "./stage-sidecar.mjs": "./stage-sidecar.mjs",
+    "./supply-chain-evidence.mjs": "./supply-chain-evidence.mjs",
+    "./tauri-bundle-marker.mjs": "./tauri-bundle-marker.mjs"
+  },
   "rightkit": {
     "publishCheck": {
+      "skipImport": [
+        "./sign-windows.mjs"
+      ],
       "binSmoke": {
         "right-release": [
           "--version"
@@ -48,6 +83,7 @@
     "directory": "packages/release"
   },
   "dependencies": {
+    "@rightkit/outdated": "0.2.0",
     "smol-toml": "1.9.1"
   },
   "scripts": {

package/pipeline-admission.mjs

@@ -230,6 +230,7 @@ function admitRuntime(bin, rest, options, label) {
     case "right-release": return admitRightRelease(rest, label);
     case "tauri": return admitTauri(rest, options, label);
     case "vite": return rest[0] === "build" ? (VITE_OPTIONS(rest.slice(1), label) ?? admit("vite-build", "runtime")) : rest.length === 1 && rest[0] === "--version" ? admit("vite-version", "runtime") : refuse("R1-option", `${label}: only vite build and vite --version are admitted`);
+    case "rightkit-gate": return admitRightKitGate(rest, label);
     case "tsc": return shellSafeArgs(rest, label) ?? admit("tsc", "runtime");
     case "vitest": return rest[0] === "run" || (rest.length === 1 && rest[0] === "--version") ? (shellSafeArgs(rest, label) ?? admit("vitest", "runtime")) : refuse("R1-option", `${label}: only vitest run is admitted`);
     case "eslint": return shellSafeArgs(rest, label) ?? admit("eslint", "runtime");
@@ -237,6 +238,16 @@ function admitRuntime(bin, rest, options, label) {
   }
 }
 
+/**
+ * `rightkit-gate install-hook`: writes the committed pre-push hook and sets core.hooksPath, so an app's `prepare` script may run it.
+ * It builds, signs, packages and uploads nothing. The gate itself (`rightkit-gate`, `--base`) compiles and is run by the hook, never
+ * by a release config; only the installer and the version probe are admitted.
+ */
+function admitRightKitGate(args, label) {
+  if (args.length === 1 && (args[0] === "install-hook" || args[0] === "--version")) return admit(`rightkit-gate-${args[0].replace(/^--/, "")}`, "owner");
+  return refuse("R1-owner-subcommand", `${label}: only rightkit-gate install-hook (and --version) is an admitted pipeline command; the gate itself runs from the pre-push hook`);
+}
+
 function admitRightRelease(args, label) {
   const sub = args[0];
   if (!OWNER_SUBCOMMANDS.has(sub)) return refuse("R1-owner-subcommand", `${label}: right-release ${JSON.stringify(sub ?? "")} is not a known RightKit command`);
@@ -350,6 +361,7 @@ export function admitInvocation(step, options = {}) {
   const tool = classifyTokens([name, ...args]);
   if (tool) return refuse("R3-pipeline-tool", `${label}: ${tool.tool} is a ${tool.stage} tool; build, sign, notarize, package and upload run only inside RightKit`);
   if (name === "right-release") return admitRightRelease(args, label);
+  if (name === "rightkit-gate") return admitRightKitGate(args, label);
   if (name === "pnpm") return admitPnpm(args, inner, label, chain);
   if (name === "node") return admitNode(args, inner, label);
   if (name === "rightkit") return refuse("R1-retired-client", `${label}: rightkit is the retired name of the RustRight client (rustright#91); use rustright ${args.slice(0, 2).join(" ")}`);