@rightkit/release 0.6.5 → 0.6.6

package/release-qa-policy.mjs

@@ -1,21 +1,38 @@
-// QA admission policy (ADR-0001 item 10): the per-app warn -> refuse switch and the approved rightkit-qa runner
-// digests, recorded in `qa-admission-policy.json` next to this module.
+// QA admission policy (ADR-0001 item 10): the per-app, per-stage warn -> refuse switch and the approved rightkit-qa
+// runners, recorded in `qa-admission-policy.json` next to this module.
 //
 //   { "schema": 1,
-//     "apps": { "<app>": { "mode": "warn" | "refuse", "since": "YYYY-MM-DD", "set_by": "<name>" } },
-//     "approvedRunners": [ { "sha256": "<64 hex>", "version": "<rightkit-qa version>", "note": "..." } ] }
+//     "apps": { "<app>": { "mode": "warn" | "refuse", "since": "YYYY-MM-DD", "set_by": "<name>",
+//                          "stages": { "source":    { "mode": .., "since": .., "set_by": .. },
+//                                      "installed": { "mode": .., "since": .., "set_by": .. } } } },
+//     "approvedRunners": [ { "sha256": "<64 hex>", "version": "<rightkit-qa version>", "platform": "mac" | "win",
+//                            "set_by": "<name>", "since": "YYYY-MM-DD", "note": "..." } ] }
 //
 // An app with no entry is in `warn` mode (default). In `refuse` mode `admit()` throws instead of warning.
 //
-// Only the owner (`adrian`) may move an app back from `refuse` to `warn` (or delete its entry). What is checkable
-// here, and enforced:
-//   - every write through `setAdmissionMode` goes through `checkPolicyTransition`, which refuses a downgrade whose
-//     new entry is not `set_by: "adrian"`;
+// Stages: the build (`source`) and publication (`installed`) admissions each have their own mode. An app entry is the
+// app-level { mode, since, set_by } (governs both stages), a `stages` object, or both; a stage entry overrides the
+// app-level mode for that stage. An app entry needs a mode or a non-empty `stages`. Only `source` and `installed` are
+// stage keys.
+//
+// Approved runners: `sha256` is required (lowercase hex). `platform` ("mac" | "win") binds the approval to the
+// platform the receipt is sealed or published for; an entry without it approves the digest on every platform (legacy
+// entries). `version`, `set_by`, `since` and `note` record who approved which rightkit-qa build and when. Add an entry
+// with `approve-runner`, which checks the file's `--version` output against the published rightkit-qa version.
+//
+// Only the owner (`adrian`) may loosen admission. What is checkable here, and enforced:
+//   - every write goes through `checkPolicyTransition`, which refuses (a) a downgrade of any app and stage from refuse
+//     to anything else (a warn entry, a removed stage entry or a removed app) whose deciding entry is not
+//     `set_by: "adrian"`, and (b) a new approved runner (a sha256 + platform pair not in the previous policy) that is
+//     not `set_by: "adrian"`; removing a runner tightens admission and is always allowed;
 //   - every load compares the working file with the copy committed at `baselineRef` (default HEAD) and refuses a
-//     hand-edited downgrade the same way, so an uncommitted edit cannot quietly switch an app off refuse;
+//     hand-edited loosening the same way, so an uncommitted edit cannot quietly switch an app off refuse or approve a
+//     runner. A baseline ref that was asked for explicitly (the argument or RIGHT_RELEASE_QA_POLICY_BASELINE_REF) and
+//     cannot be read is a hard error; only the default (HEAD, nothing requested) falls back to no baseline, for a
+//     tree that is not a git checkout (an app's node_modules);
 //   - an unreadable or malformed policy file is a hard error, never a silent fall back to warn.
 // What is NOT checkable from this file: `set_by` is a recorded claim, not an authenticated identity, and a
-// downgrade that was already committed is the new baseline. The file must therefore be owner-protected in the
+// loosening that was already committed is the new baseline. The file must therefore be owner-protected in the
 // repository (CODEOWNERS on this path plus branch protection, and the file belongs in the protected policy bundle,
 // see ownership-policy-bundle.mjs). CI should set RIGHT_RELEASE_QA_POLICY_BASELINE_REF=origin/main so the baseline
 // is the protected branch rather than the local HEAD.
@@ -33,7 +50,11 @@ const DATE = /^\d{4}-\d{2}-\d{2}$/;
 export const QA_ADMISSION_POLICY_FILE = "qa-admission-policy.json";
 export const QA_POLICY_BASELINE_REF_ENV = "RIGHT_RELEASE_QA_POLICY_BASELINE_REF";
 export const ADMISSION_MODES = Object.freeze(["warn", "refuse"]);
-/** The only `set_by` that may move an app from refuse back to warn. */
+/** The admissions an app's mode can be set for: the build (source) and the publication (installed). */
+export const ADMISSION_STAGES = Object.freeze(["source", "installed"]);
+/** The platforms an approved runner can be bound to. */
+export const RUNNER_PLATFORMS = Object.freeze(["mac", "win"]);
+/** The only `set_by` that may move an app back from refuse, or approve a runner. */
 export const POLICY_OWNER = "adrian";
 
 export class QaPolicyError extends Error {
@@ -44,42 +65,98 @@ export class QaPolicyError extends Error {
   }
 }
 
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const nonEmpty = (value) => typeof value === "string" && value.trim() !== "";
+
+function validateModeEntry(entry, label, problems) {
+  if (!ADMISSION_MODES.includes(entry.mode)) problems.push(`${label} mode must be warn or refuse`);
+  if (typeof entry.since !== "string" || !DATE.test(entry.since)) problems.push(`${label} since must be YYYY-MM-DD`);
+  if (!nonEmpty(entry.set_by)) problems.push(`${label} set_by is required`);
+}
+
+function validateRunnerEntry(runner, problems) {
+  const label = `approvedRunners entry ${runner.sha256.slice(0, 16)}`;
+  if (runner.version !== undefined && !nonEmpty(runner.version)) problems.push(`${label} version must be a non-empty string`);
+  if (runner.platform !== undefined && !RUNNER_PLATFORMS.includes(runner.platform)) problems.push(`${label} platform must be ${RUNNER_PLATFORMS.join(" or ")}`);
+  if (runner.set_by !== undefined && !nonEmpty(runner.set_by)) problems.push(`${label} set_by must be a non-empty string`);
+  if (runner.since !== undefined && (typeof runner.since !== "string" || !DATE.test(runner.since))) problems.push(`${label} since must be YYYY-MM-DD`);
+  if (runner.note !== undefined && typeof runner.note !== "string") problems.push(`${label} note must be a string`);
+}
+
 export function validateAdmissionPolicy(policy) {
   const problems = [];
-  if (!policy || typeof policy !== "object" || Array.isArray(policy)) return ["policy must be an object"];
+  if (!isObject(policy)) return ["policy must be an object"];
   if (policy.schema !== 1) problems.push("policy schema must be 1");
-  if (!policy.apps || typeof policy.apps !== "object" || Array.isArray(policy.apps)) problems.push("policy apps must be an object");
+  if (!isObject(policy.apps)) problems.push("policy apps must be an object");
   else {
     for (const [app, entry] of Object.entries(policy.apps)) {
+      const label = `policy app ${app}`;
       if (!app.trim()) problems.push("policy app name is empty");
-      if (!entry || typeof entry !== "object") { problems.push(`policy app ${app} must be an object`); continue; }
-      if (!ADMISSION_MODES.includes(entry.mode)) problems.push(`policy app ${app} mode must be warn or refuse`);
-      if (typeof entry.since !== "string" || !DATE.test(entry.since)) problems.push(`policy app ${app} since must be YYYY-MM-DD`);
-      if (typeof entry.set_by !== "string" || !entry.set_by.trim()) problems.push(`policy app ${app} set_by is required`);
+      if (!entry || typeof entry !== "object") { problems.push(`${label} must be an object`); continue; }
+      if (entry.stages !== undefined) {
+        if (!isObject(entry.stages)) problems.push(`${label} stages must be an object`);
+        else {
+          if (!Object.keys(entry.stages).length && entry.mode === undefined) problems.push(`${label} needs a mode or a non-empty stages object`);
+          for (const [stage, stageEntry] of Object.entries(entry.stages)) {
+            if (!ADMISSION_STAGES.includes(stage)) { problems.push(`${label} has unknown stage ${JSON.stringify(stage)} (expected ${ADMISSION_STAGES.join(" or ")})`); continue; }
+            if (!isObject(stageEntry)) { problems.push(`${label} stage ${stage} must be an object`); continue; }
+            validateModeEntry(stageEntry, `${label} stage ${stage}`, problems);
+          }
+        }
+      }
+      // The app-level fields are required unless the app is governed by its stages alone.
+      if (entry.mode !== undefined || entry.stages === undefined) validateModeEntry(entry, label, problems);
     }
   }
   if (!Array.isArray(policy.approvedRunners)) problems.push("policy approvedRunners must be an array");
   else {
     for (const runner of policy.approvedRunners) {
       if (!runner || typeof runner.sha256 !== "string" || !HEX64.test(runner.sha256)) problems.push("approvedRunners entries need a lowercase 64-hex sha256");
+      else validateRunnerEntry(runner, problems);
     }
   }
   return problems;
 }
 
-/** Problems when `next` weakens `previous`: a refuse entry that is gone or now warn without `set_by: "adrian"`. */
+/** The entry that decides `stage` for `app`: its stage entry, else its app-level entry when that has a mode, else none. */
+function decidingEntry(policy, app, stage) {
+  const entry = policy?.apps?.[app];
+  return entry?.stages?.[stage] ?? (entry?.mode ? entry : undefined);
+}
+
+const runnerKey = (runner) => `${runner?.sha256}|${runner?.platform ?? ""}`;
+
+/**
+ * Problems when `next` loosens `previous`: for every app and stage, a refuse that is gone or now warn without the
+ * deciding entry being `set_by: "adrian"`; and every approved runner that is new without `set_by: "adrian"`.
+ */
 export function checkPolicyTransition(previous, next) {
-  const problems = [];
-  for (const [app, before] of Object.entries(previous?.apps ?? {})) {
-    if (before?.mode !== "refuse") continue;
-    const after = next?.apps?.[app];
-    if (!after) problems.push(`${app}: the refuse entry was removed; only ${POLICY_OWNER} may move an app back to warn (set mode warn with set_by "${POLICY_OWNER}")`);
-    else if (after.mode !== "refuse" && after.set_by !== POLICY_OWNER) problems.push(`${app}: refuse -> warn requires set_by "${POLICY_OWNER}", got ${JSON.stringify(after.set_by)}`);
+  const grouped = new Map();
+  const note = (app, stage, body) => {
+    const key = `${app}\u0000${body}`;
+    if (!grouped.has(key)) grouped.set(key, { app, body, stages: [] });
+    grouped.get(key).stages.push(stage);
+  };
+  for (const app of Object.keys(previous?.apps ?? {})) {
+    for (const stage of ADMISSION_STAGES) {
+      if (decidingEntry(previous, app, stage)?.mode !== "refuse") continue;
+      const after = decidingEntry(next, app, stage);
+      if (after?.mode === "refuse") continue;
+      if (!after) note(app, stage, `the refuse entry was removed; only ${POLICY_OWNER} may move an app back to warn (set mode warn with set_by "${POLICY_OWNER}")`);
+      else if (after.set_by !== POLICY_OWNER) note(app, stage, `refuse -> warn requires set_by "${POLICY_OWNER}", got ${JSON.stringify(after.set_by)}`);
+    }
+  }
+  const problems = [...grouped.values()].map(({ app, body, stages }) => `${app} (${stages.join(", ")}): ${body}`);
+  const known = new Set((previous?.approvedRunners ?? []).map(runnerKey));
+  for (const runner of next?.approvedRunners ?? []) {
+    if (known.has(runnerKey(runner)) || runner?.set_by === POLICY_OWNER) continue;
+    problems.push(`approvedRunners: runner ${String(runner?.sha256).slice(0, 16)}${runner?.platform ? ` (${runner.platform})` : ""} is new with set_by ${JSON.stringify(runner?.set_by ?? null)}; only ${POLICY_OWNER} may approve a runner (set_by "${POLICY_OWNER}")`);
   }
   return problems;
 }
 
 const digestOf = (policy) => createHash("sha256").update(canonicalJson(policy)).digest("hex");
+const sha256Of = (bytes) => createHash("sha256").update(bytes).digest("hex");
 
 function parsePolicyText(text, label) {
   let policy;
@@ -89,15 +166,20 @@ function parsePolicyText(text, label) {
   return policy;
 }
 
+/** { text } when git shows the policy file at `ref`; { text: null, detail } when it cannot. */
 function gitBaselineText({ dir, ref, runner = spawnSync }) {
   try {
     const result = runner("git", ["-C", dir, "show", `${ref}:./${QA_ADMISSION_POLICY_FILE}`], { encoding: "utf8", windowsHide: true });
-    return result?.status === 0 ? String(result.stdout) : null;
-  } catch { return null; }
+    if (result?.status === 0) return { text: String(result.stdout) };
+    return { text: null, detail: String(result?.stderr ?? "").trim().split(/\r?\n/)[0] || `git exited ${result?.status ?? "without a status"}` };
+  } catch (error) { return { text: null, detail: error.message }; }
 }
 
 /**
  * Load the policy. `baseline` (policy text) overrides the git lookup; `baseline: false` disables the comparison.
+ * A baseline ref requested explicitly (`baselineRef` or the env var) that cannot be read is an error: the comparison
+ * the caller asked for must not silently become no comparison. With no ref requested the baseline is HEAD, and a tree
+ * that is not a git checkout has none.
  * Returns { policy, digest, baseline: "supplied" | "git" | "none" }.
  */
 export function loadAdmissionPolicy({ dir = here, baseline, baselineRef, env = process.env, gitRunner } = {}) {
@@ -108,7 +190,11 @@ export function loadAdmissionPolicy({ dir = here, baseline, baselineRef, env = p
   let baselineText = null;
   if (typeof baseline === "string") { baselineText = baseline; source = "supplied"; }
   else if (baseline !== false) {
-    baselineText = gitBaselineText({ dir, ref: baselineRef ?? env?.[QA_POLICY_BASELINE_REF_ENV] ?? "HEAD", runner: gitRunner });
+    const requested = [baselineRef, env?.[QA_POLICY_BASELINE_REF_ENV]].find(nonEmpty);
+    const ref = requested ?? "HEAD";
+    const found = gitBaselineText({ dir, ref, runner: gitRunner });
+    if (found.text === null && requested) throw new QaPolicyError(`QA admission policy baseline ${ref} cannot be read (${found.detail}); refusing to continue without the comparison that was requested`);
+    baselineText = found.text;
     if (baselineText !== null) source = "git";
   }
   if (baselineText !== null) {
@@ -118,46 +204,127 @@ export function loadAdmissionPolicy({ dir = here, baseline, baselineRef, env = p
   return { policy, digest: digestOf(policy), baseline: source };
 }
 
-/** The mode for an app; an app with no entry is `warn`. */
-export function admissionModeFor(policy, app) {
-  const entry = policy?.apps?.[app];
+/**
+ * The mode for an app at `stage` ("source" | "installed"): the stage entry, else the app-level entry, else `warn`.
+ * Without a stage it is the app-level result.
+ */
+export function admissionModeFor(policy, app, stage) {
+  const entry = stage ? decidingEntry(policy, app, stage) : policy?.apps?.[app];
   return entry?.mode === "refuse" ? { mode: "refuse", since: entry.since, set_by: entry.set_by } : { mode: "warn", since: entry?.since ?? null, set_by: entry?.set_by ?? null };
 }
 
 export const approvedRunnerDigests = (policy) => (policy?.approvedRunners ?? []).map((runner) => runner.sha256);
 
+/** Write the policy atomically, apps and runners in a deterministic order. */
+function writePolicy(file, policy) {
+  const sorted = {
+    ...policy,
+    apps: Object.fromEntries(Object.entries(policy.apps).sort(([a], [b]) => a.localeCompare(b))),
+    approvedRunners: [...policy.approvedRunners].sort((a, b) => a.sha256.localeCompare(b.sha256) || (a.platform ?? "").localeCompare(b.platform ?? "")),
+  };
+  mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(sorted, null, 2)}\n`);
+  renameSync(temp, file);
+}
+
+/** Refuse a result that loosens `current` or is not a valid policy; the file is left untouched. */
+function assertAllowed(current, next) {
+  const problems = [...checkPolicyTransition(current, next), ...validateAdmissionPolicy(next)];
+  if (problems.length) throw new QaPolicyError(`QA admission policy change refused: ${problems.join("; ")}`);
+}
+
 /**
- * Record an app's mode. A downgrade (refuse -> warn) is refused unless `setBy` is the owner. Writes atomically.
+ * Record an app's mode. With a `stage` only that stage's entry is written (the app-level mode and the other stage are
+ * kept); without one the app-level entry is written and any `stages` are removed, so one mode governs both stages.
+ * A refuse -> warn move at any stage is refused unless `setBy` is the owner. Writes atomically.
  * The file is read without the git baseline here (the transition rule is applied directly to what is on disk).
+ * Returns the entry written.
  */
-export function setAdmissionMode({ app, mode, setBy, dir = here, now = () => new Date() }) {
+export function setAdmissionMode({ app, mode, setBy, stage, dir = here, now = () => new Date() }) {
   if (!app || !String(app).trim()) throw new QaPolicyError("app is required");
   if (!ADMISSION_MODES.includes(mode)) throw new QaPolicyError("mode must be warn or refuse");
   if (!setBy || !String(setBy).trim()) throw new QaPolicyError("set_by is required");
+  if (stage !== undefined && !ADMISSION_STAGES.includes(stage)) throw new QaPolicyError(`stage must be ${ADMISSION_STAGES.join(" or ")}`);
   const file = path.join(dir, QA_ADMISSION_POLICY_FILE);
   const current = parsePolicyText(readFileSync(file, "utf8"), QA_ADMISSION_POLICY_FILE);
-  const next = { ...current, apps: { ...current.apps, [app]: { mode, since: now().toISOString().slice(0, 10), set_by: String(setBy) } } };
-  const problems = checkPolicyTransition(current, next);
-  if (problems.length) throw new QaPolicyError(`QA admission policy change refused: ${problems.join("; ")}`);
-  const sorted = { ...next, apps: Object.fromEntries(Object.entries(next.apps).sort(([a], [b]) => a.localeCompare(b))) };
-  mkdirSync(path.dirname(file), { recursive: true });
-  const temp = `${file}.${process.pid}.tmp`;
-  writeFileSync(temp, `${JSON.stringify(sorted, null, 2)}\n`);
-  renameSync(temp, file);
-  return sorted.apps[app];
+  const entry = { mode, since: now().toISOString().slice(0, 10), set_by: String(setBy) };
+  let written;
+  if (stage) {
+    const stages = { ...current.apps[app]?.stages, [stage]: entry };
+    written = { ...current.apps[app], stages: Object.fromEntries(ADMISSION_STAGES.filter((name) => stages[name]).map((name) => [name, stages[name]])) };
+  } else written = entry;
+  const next = { ...current, apps: { ...current.apps, [app]: written } };
+  assertAllowed(current, next);
+  writePolicy(file, next);
+  return entry;
 }
 
-// `node release-qa-policy.mjs show | set --app <app> --mode warn|refuse --set-by <name>`
-export function main(args, { stdout = (text) => console.log(text), stderr = (text) => console.error(text) } = {}) {
+function readRunnerBytes(file) {
+  try { return readFileSync(file); } catch (error) { throw new QaPolicyError(`runner file is unreadable (${file}): ${error.message}`); }
+}
+
+/**
+ * Approve a rightkit-qa runner build for a platform: only the owner may (it loosens admission), the file must report
+ * `rightkit-qa <version>` from `--version`, and that version must be the published rightkit-qa version in
+ * rightkit-versions.json (`registry.cargo`). Records { sha256, version, platform, set_by, since, note? } and returns it;
+ * an entry with the same sha256 and platform that is already present is returned unchanged. Writes atomically.
+ */
+export function approveRunner({
+  runner, version, platform, setBy, note, dir = here, now = () => new Date(), spawn = spawnSync, versionsFile = path.join(here, "rightkit-versions.json"),
+}) {
+  if (setBy !== POLICY_OWNER) throw new QaPolicyError(`approving a runner loosens QA admission; only ${POLICY_OWNER} may approve one (set_by ${JSON.stringify(setBy ?? null)})`);
+  if (!RUNNER_PLATFORMS.includes(platform)) throw new QaPolicyError(`platform must be ${RUNNER_PLATFORMS.join(" or ")}`);
+  if (!runner || !String(runner).trim()) throw new QaPolicyError("runner is required");
+  if (!nonEmpty(version)) throw new QaPolicyError("version is required");
+  if (note !== undefined && typeof note !== "string") throw new QaPolicyError("note must be a string");
+  let published;
+  try { published = JSON.parse(readFileSync(versionsFile, "utf8")).registry?.cargo?.["rightkit-qa"]; }
+  catch (error) { throw new QaPolicyError(`the published rightkit-qa version cannot be read (${versionsFile}): ${error.message}`); }
+  if (published !== version) throw new QaPolicyError(`rightkit-qa ${version} is not the published version (rightkit-versions.json registry.cargo has ${published ?? "no rightkit-qa"}); only the published runner can be approved`);
+  // The file that is digested is the file that is run: an absolute path, never a PATH lookup, and re-digested after.
+  const file = path.resolve(String(runner));
+  const sha256 = sha256Of(readRunnerBytes(file));
+  const run = spawn(file, ["--version"], { encoding: "utf8", windowsHide: true });
+  const output = String(run?.stdout ?? "").trim();
+  if (run?.status !== 0 || output !== `rightkit-qa ${version}`) {
+    throw new QaPolicyError(`${file} --version reported ${JSON.stringify(output.slice(0, 80))} (exit ${run?.status ?? run?.error?.message ?? "none"}), expected "rightkit-qa ${version}"`);
+  }
+  if (sha256Of(readRunnerBytes(file)) !== sha256) throw new QaPolicyError(`${file} changed while its version was being checked; nothing was approved`);
+  const policyFile = path.join(dir, QA_ADMISSION_POLICY_FILE);
+  const current = parsePolicyText(readFileSync(policyFile, "utf8"), QA_ADMISSION_POLICY_FILE);
+  const present = current.approvedRunners.find((item) => item.sha256 === sha256 && (item.platform ?? null) === platform);
+  if (present) return present;
+  const entry = { sha256, version, platform, set_by: setBy, since: now().toISOString().slice(0, 10), ...(note ? { note } : {}) };
+  const next = { ...current, approvedRunners: [...current.approvedRunners, entry] };
+  assertAllowed(current, next);
+  writePolicy(policyFile, next);
+  return entry;
+}
+
+/**
+ * `node release-qa-policy.mjs show | set ... | approve-runner ...` (also `right-release qa policy ...`). The options
+ * are test seams: `dir` (the policy directory), `env`, `now`, `spawn`, `versionsFile`, and `program` (the usage name).
+ */
+export function main(args, {
+  stdout = (text) => console.log(text), stderr = (text) => console.error(text), dir, env, now, spawn, versionsFile, program = "release-qa-policy.mjs",
+} = {}) {
   const value = (flag) => { const index = args.indexOf(flag); return index >= 0 ? args[index + 1] : undefined; };
   try {
-    if (args[0] === "show") { stdout(JSON.stringify(loadAdmissionPolicy().policy, null, 2)); return 0; }
+    if (args[0] === "show") { stdout(JSON.stringify(loadAdmissionPolicy({ dir, env }).policy, null, 2)); return 0; }
     if (args[0] === "set") {
-      const entry = setAdmissionMode({ app: value("--app"), mode: value("--mode"), setBy: value("--set-by") });
-      stdout(`qa admission: ${value("--app")} -> ${entry.mode} (since ${entry.since}, set_by ${entry.set_by})`);
+      // A `--stage` with no value must not fall through to the app-level write, which removes the stages.
+      const stage = args.includes("--stage") ? value("--stage") ?? "" : undefined;
+      const entry = setAdmissionMode({ app: value("--app"), mode: value("--mode"), setBy: value("--set-by"), stage, dir, now });
+      stdout(`qa admission: ${value("--app")}${stage ? ` (${stage} stage)` : ""} -> ${entry.mode} (since ${entry.since}, set_by ${entry.set_by})`);
+      return 0;
+    }
+    if (args[0] === "approve-runner") {
+      const entry = approveRunner({ runner: value("--runner"), version: value("--version"), platform: value("--platform"), setBy: value("--set-by"), note: value("--note"), dir, now, spawn, versionsFile });
+      stdout(`qa runner approved: ${entry.sha256} rightkit-qa ${entry.version} (${entry.platform ?? "any platform"}, since ${entry.since}, set_by ${entry.set_by})`);
       return 0;
     }
-    stderr("usage: release-qa-policy.mjs show | set --app <app> --mode warn|refuse --set-by <name>");
+    stderr(`usage: ${program} show\n       ${program} set --app <app> --mode warn|refuse --set-by <name> [--stage source|installed]\n       ${program} approve-runner --runner <file> --version <v> --platform mac|win --set-by <name> [--note <text>]`);
     return 2;
   } catch (error) {
     stderr(`release-qa-policy: ${error.message}`);

package/release.mjs

@@ -58,7 +58,7 @@ import { runIosPackageRecipe } from "./ios-package-recipe.mjs";
 import { releaseSwitchInputs } from "./ios-build-context.mjs";
 import { productionBuildEnv, productionModeProblems } from "./production-mode.mjs";
 import { evaluatePrebuildGates } from "./prebuild-gates.mjs";
-import { releaseConfigFieldProblems } from "./release-config.mjs";
+import { defaultReleaseConfigFile, importReleaseConfig, releaseConfigFieldProblems } from "./release-config.mjs";
 import { describeRegistryError, formatNotRun, runAdmission } from "./admission.mjs";
 import { sccacheRefusal } from "./admission-host.mjs";
 
@@ -126,7 +126,7 @@ const SWIFT_PRIVATE_DISPATCH_WORKFLOWS = new Set(["release-candidate.yml", "rege
 
 const args = process.argv.slice(2);
 const opts = {
-  config: "right-release.config.mjs",
+  config: defaultReleaseConfigFile(),
   platform: process.platform === "win32" ? "win" : process.platform === "darwin" ? "mac" : process.platform,
   upload: false,
   install: false,
@@ -245,7 +245,7 @@ if (opts.doctor) {
   doctorInvocation = { repoRoot, commit };
 }
 let config;
-try { config = (await import(pathToFileURL(configPath))).default; } catch (error) { fail(`release config could not be loaded (${configPath}): ${error instanceof Error ? error.message : String(error)}`); }
+try { config = await importReleaseConfig(configPath); } catch (error) { fail(`release config could not be loaded (${configPath}): ${error instanceof Error ? error.message : String(error)}`); }
 if (!config) usage(2, `config did not export default: ${configPath}`);
 if (config.schema !== 1) fail(`unsupported config schema: ${config.schema ?? "<missing>"} (expected 1)`);
 // Field-level config refusals (updater.keyFile: keys come from the OS credential provider) are listed with every other finding.
@@ -841,7 +841,7 @@ releaseLock.release();
 
 function usage(code, message) {
   if (message) console.error(`right-release: ${message}\n`);
-  console.error("usage: right-release build --platform mac|win [--config right-release.config.mjs]   (build is tier-neutral; tier applies only to: right-release upload --release <id> --platform mac|win --tier patch|update)");
+  console.error("usage: right-release build --platform mac|win [--config right-release.config.json]   (build is tier-neutral; tier applies only to: right-release upload --release <id> --platform mac|win --tier patch|update)");
   process.exit(code);
 }
 

package/rightkit-registry-resolver.mjs

@@ -29,6 +29,7 @@ import { parse as parseToml } from "smol-toml";
 import { isExcludedScanDirectory } from "./cargo-contract.mjs";
 import { resolveSharedCacheRoot } from "./cache-policy.mjs";
 import { parsePnpmYaml } from "./ownership-lockfiles.mjs";
+import { UPDATE_COMMAND } from "./outdated-command.mjs";
 import { compareVersions } from "./rightkit-sync.mjs";
 
 export const SNAPSHOT_SCHEMA = 1;
@@ -42,7 +43,9 @@ export const REGISTRIES = Object.freeze({
 const CRATES_IO_SOURCES = new Set(["registry+https://github.com/rust-lang/crates.io-index", "registry+https://index.crates.io/"]);
 const EXACT_SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 const USER_AGENT = "right-release-resolver/1 (https://github.com/bogusyogi/rightkit)";
-const FIX = "run `right-update run` (@rightkit/outdated 0.2.0) to move the pin";
+// The updater is @rightkit/outdated, a dependency of this package; `right-release update` runs its bin (pnpm links only an
+// app's direct dependencies' bins, so `pnpm exec right-update` does not exist in an app that has just @rightkit/release).
+export const FIX = `run \`${UPDATE_COMMAND}\` (the pinned @rightkit/outdated updater; it reads .rightkit/update.json) to move the pin`;
 const DEFAULT_ATTEMPTS = 3;
 const DEFAULT_TIMEOUT_MS = 15000;
 const CONCURRENCY = 6;
@@ -589,7 +592,7 @@ function matchesPattern(name, pattern) {
 }
 /**
  * Holds named in the nearest .rightkit/update.json (app root up to the repository boundary). A hold is a migration
- * lane task for right-update; it is reported next to a stale pin and never grants permission to seal it.
+ * lane task for the updater (right-update); it is reported next to a stale pin and never grants permission to seal it.
  * Only holds the file itself declares are read (policy.held, policy.tier.held); no built-in pattern is applied here.
  */
 export function readUpdateHolds(root) {

package/rightkit-versions.json

@@ -30,9 +30,9 @@
     "@rightkit/pdf-ui": "0.2.0",
     "@rightkit/platform-ui": "0.4.0",
     "@rightkit/qa": "0.6.1",
-    "@rightkit/qa-chrome": "0.1.11",
+    "@rightkit/qa-chrome": "0.1.12",
     "@rightkit/react-shell": "0.7.2",
-    "@rightkit/release": "0.6.5",
+    "@rightkit/release": "0.6.6",
     "@rightkit/settings-ui": "0.7.0",
     "@rightkit/tauri": "0.3.0",
     "@rightkit/tauri-shell": "0.1.3",
@@ -231,7 +231,8 @@
       "0.6.1",
       "0.6.2",
       "0.6.3",
-      "0.6.4"
+      "0.6.4",
+      "0.6.5"
     ],
     "@rightkit/qa": [
       "0.1.0",
@@ -373,7 +374,8 @@
       "0.1.5",
       "0.1.6",
       "0.1.8",
-      "0.1.10"
+      "0.1.10",
+      "0.1.11"
     ],
     "@rightkit/updates": [
       "0.2.4"
@@ -486,7 +488,7 @@
     "rightkit-pdf": "0.3.3",
     "rightkit-platform-rules": "0.1.0",
     "rightkit-playback": "0.3.0",
-    "rightkit-qa": "0.9.0",
+    "rightkit-qa": "0.9.1",
     "rightkit-qa-driver": "0.7.0",
     "rightkit-record": "0.3.3",
     "rightkit-review": "0.4.0",
@@ -610,7 +612,7 @@
       "@rightkit/app-shell": "0.6.2",
       "@rightkit/app-update": "0.4.2",
       "@rightkit/ax": "0.3.2",
-      "@rightkit/ci": "0.3.0",
+      "@rightkit/ci": "0.3.1",
       "@rightkit/doc-render": "0.2.1",
       "@rightkit/git": "0.2.42",
       "@rightkit/hooks": "0.1.2",
@@ -628,7 +630,7 @@
       "@rightkit/qa": "0.6.1",
       "@rightkit/qa-chrome": "0.1.11",
       "@rightkit/react-shell": "0.7.2",
-      "@rightkit/release": "0.6.4",
+      "@rightkit/release": "0.6.5",
       "@rightkit/settings-ui": "0.7.0",
       "@rightkit/shell": "0.1.1",
       "@rightkit/tauri": "0.3.0",
@@ -762,7 +764,8 @@
       "0.6.4",
       "0.7.0",
       "0.7.1",
-      "0.8.0"
+      "0.8.0",
+      "0.9.0"
     ],
     "rightkit-sandbox": [
       "0.1.0",

package/stage-sidecar-command.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
-// `right-release stage-sidecar [--config right-release.config.mjs] [--target <triple>] [--check] [--json]` (bogusyogi/rightkit#345):
+// `right-release stage-sidecar [--config right-release.config.json] [--target <triple>] [--check] [--json]` (bogusyogi/rightkit#345):
 // stages the config's declarative `sidecars` into src-tauri/binaries with Tauri externalBin naming. `--check` validates
 // the manifest and prints the plan without building, downloading, copying or deleting anything (for template gates).
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { defaultReleaseConfigFile, importReleaseConfig } from "./release-config.mjs";
 import { planSidecarStaging, resolveTargetTriple, stageSidecars } from "./stage-sidecar.mjs";
 
-export function parseStageSidecarArgs(argv) {
-  const opts = { config: "right-release.config.mjs", target: undefined, json: false, check: false };
+export function parseStageSidecarArgs(argv, cwd = process.cwd()) {
+  const opts = { config: defaultReleaseConfigFile(cwd), target: undefined, json: false, check: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--config" || arg === "--target") {
@@ -49,8 +50,7 @@ async function main() {
   const opts = parseStageSidecarArgs(process.argv.slice(2));
   const configPath = path.resolve(opts.config);
   const appRoot = path.dirname(configPath);
-  const loaded = await import(pathToFileURL(configPath).href);
-  const config = loaded.default ?? loaded.config ?? loaded;
+  const config = await importReleaseConfig(configPath, { lenient: true });
   if (config?.sidecars === undefined) throw new Error(`${opts.config} declares no sidecars`);
   if (opts.check) {
     const target = opts.target ?? process.env.TAURI_ENV_TARGET_TRIPLE ?? nodeHostTriple();

package/test-command.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // `right-release test [--config <file>] [--suite <name>[,<name>]]... [--runner <name>] [--list] [--json] [-- <args>]`
-// runs the app's declared test suites from `right-release.config.mjs`, one after another, and stops at the first failure.
+// runs the app's declared test suites from its release config (`right-release.config.json`), one after another, and stops at the first failure.
 //
 //   tests: {
 //     eventPrefix: "e2e",                       // optional; events are `<prefix>_suite_started` / `<prefix>_suite_completed`
@@ -26,6 +26,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { spawn } from "./background-process.mjs";
 import { CommandSpecError, loadAppConfig, resolveInvocation, validateStep } from "./command-spec.mjs";
+import { defaultReleaseConfigFile } from "./release-config.mjs";
 
 const fail = (message) => { throw new CommandSpecError(message); };
 const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
@@ -34,7 +35,7 @@ const PREFIX = /^[a-z][a-z0-9_]*$/;
 const uniq = (...lists) => [...new Set(lists.flatMap((list) => list ?? []))];
 
 export function parseTestArgs(argv) {
-  const opts = { config: "right-release.config.mjs", suites: [], runner: undefined, list: false, json: false, passthrough: [] };
+  const opts = { config: defaultReleaseConfigFile(), suites: [], runner: undefined, list: false, json: false, passthrough: [] };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--") { opts.passthrough = argv.slice(i + 1); break; }

package/upload-release.mjs

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { prepareGitHubRelease, publishGitHubRelease } from "./github-release.mjs";
+import { defaultReleaseConfigFile } from "./release-config.mjs";
 import { authorizeGitHubUpload } from "./github-upload-gate.mjs";
 import { recordPublishedVersion } from "./artifact-storage.mjs";
 import { admitInstalledQa } from "./release-qa-audit.mjs";
@@ -12,7 +13,7 @@ let platform = process.platform === "win32" ? "win" : process.platform === "darw
 let releaseId = "";
 let tier = "";
 let repo = "";
-let configName = "right-release.config.mjs";
+let configName = defaultReleaseConfigFile();
 let dryRun = false;
 let apply = false;
 
@@ -87,7 +88,7 @@ function writeJson(file, value) {
 }
 
 function usage(code) {
-  console.log("usage: right-release upload --release <sealed-id> --platform win|mac --tier patch|update [--config right-release.config.mjs] [--repo owner/repo] [--dry-run]\n       right-release upload --platform android --release <sealed-id> [--config right-release.config.mjs] [--apply]   (Play internal track; dry run unless --apply)\n       right-release upload --platform ios --release <sealed-id> [--config right-release.config.mjs] [--apply]   (TestFlight; dry run unless --apply)");
+  console.log("usage: right-release upload --release <sealed-id> --platform win|mac --tier patch|update [--config right-release.config.json] [--repo owner/repo] [--dry-run]\n       right-release upload --platform android --release <sealed-id> [--config right-release.config.json] [--apply]   (Play internal track; dry run unless --apply)\n       right-release upload --platform ios --release <sealed-id> [--config right-release.config.json] [--apply]   (TestFlight; dry run unless --apply)");
   process.exit(code);
 }
 

package/web-build.mjs

@@ -15,9 +15,10 @@
 import { pathToFileURL } from "node:url";
 import { spawnSync } from "./background-process.mjs";
 import { CommandSpecError, loadAppConfig, resolveInvocation, validateStep } from "./command-spec.mjs";
+import { defaultReleaseConfigFile } from "./release-config.mjs";
 
 export function parseWebBuildArgs(argv) {
-  const opts = { config: "right-release.config.mjs", dryRun: false };
+  const opts = { config: defaultReleaseConfigFile(), dryRun: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--config") {