@rightkit/release 0.6.15 → 0.6.20

package/release-qa-command.mjs

@@ -6,13 +6,17 @@
 //   right-release qa audit [--app <dir>] [--json] [--since <YYYY-MM-DD>]   (release-qa-audit.mjs; exit 1 when an uploaded build lacks passing QA)
 //   right-release qa policy show | set --app <app> --mode warn|refuse --set-by <name> [--stage source|installed]
 //                         | approve-runner --runner <file> --version <v> --platform mac|win --set-by <name> [--note <text>]   (release-qa-policy.mjs)
+//   right-release qa runner enroll --runner <built rightkit-qa> --version <v> [--platform mac|win] [--rotate] | show   (qa-runner.mjs)
 //
 // The release config declares the app's QA plan:
 //   qa: { version: "1", config: "rightkit-qa.toml", runner?: "<path to rightkit-qa>",
 //         args?: { source?: [..], installed?: [..] },                                   // {sealedDir} {releaseId} expand; installed also {installedApp} {installedDir} {qaRoot}
 //         installed?: { installDir?: "<abs dir>" },                                       // opt in: mount the sealed DMG (mac) / run the sealed NSIS installer (win, needs RIGHT_RELEASE_QA_ALLOW_INSTALL=1 off CI), see release-qa-installed.mjs
 //         journeys?: { manifest?: "journeys.toml", receipt?: "<path to a rightkit.journeys.receipt/1>", args?: { source?: [..], installed?: [..] } },
+//         layout?: { binary: "<bin target of the QA shell>", beside?: [..], build?: [<tests.suites names>] },   // source stage: run against the gate-built QA shell in the layout an install has, see qa-layout.mjs
 //         checks: { "smoke.launch": ["app.launch"], journey: ["journey.*"] } }          // floor id -> evidence check names
+// `qa.version` that is a rightkit-qa version (0.10.0) names the runner: the managed, digest-recorded one enrolled by `right-release qa runner enroll`
+// (qa-runner.mjs), never a PATH binary. A legacy plan version ("1") with no `qa.runner` still takes the first `rightkit-qa` on PATH.
 // Every id in release-qa-floor.json must be mapped; skipped/failed/missing required checks fail the receipt.
 // `qa.journeys` maps the floor's `journey` id to "every release-critical journey required on this platform passed":
 // `rightkit-qa journeys run` is run (or `receipt` is read), the receipt is validated through `rightkit-qa journeys
@@ -37,6 +41,11 @@ import {
   qaReceiptPath, QA_STAGES, sealQaReceipt, sourceIdentity, validateAppQaConfig, writeQaReceipt,
 } from "./release-qa-receipt.mjs";
 import { platformDirOf } from "./platform-dir.mjs";
+import { isRunnerVersion, main as runnerMain, resolveManagedQaRunner } from "./qa-runner.mjs";
+import { compiledDirsFromEnv, QA_APP_BINARY_ENV, stageQaLayout, validateQaLayout } from "./qa-layout.mjs";
+import { gateRunsRoot, resolveManagedRoots } from "./managed-roots.mjs";
+import { planTests, runSuites } from "./test-command.mjs";
+import { QA_SIGNED_FILES_ENV } from "./suite-signing-policy.mjs";
 
 const sha256File = (file) => createHash("sha256").update(readFileSync(file)).digest("hex");
 
@@ -119,6 +128,8 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
   const { floor, digest: floorDigest } = loadQaFloor(deps.floorDir);
   const problems = validateAppQaConfig(config.qa, floor, stage);
   if (problems.length) throw new Error(`release config QA plan does not meet the protected QA floor:\n- ${problems.join("\n- ")}`);
+  const layoutProblems = config.qa.layout === undefined ? [] : validateQaLayout(config.qa.layout);
+  if (layoutProblems.length) throw new Error(`release config qa.layout is invalid:\n- ${layoutProblems.join("\n- ")}`);
 
   let releaseId = releaseIdArg;
   let sealed = null;
@@ -145,8 +156,17 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
     if (journeysDeclared.receipt) assertInsideSource(release, path.resolve(appRoot, String(journeysDeclared.receipt)), "qa.journeys.receipt");
   }
   if (config.qa.runner && !deps.runnerFile) assertInsideSource(release, path.resolve(appRoot, config.qa.runner), "qa.runner");
-  const runnerFile = deps.runnerFile ?? resolveRunner({ qa: config.qa, appRoot });
+  // A runner the config names is read from the source; else the managed runner of the version `qa.version` names (qa-runner.mjs); else, for a legacy plan version only, PATH.
+  let managedRunner = null;
+  let runnerFile = deps.runnerFile;
+  if (!runnerFile) {
+    if (!config.qa.runner && isRunnerVersion(config.qa.version)) {
+      managedRunner = (deps.resolveManagedRunner ?? resolveManagedQaRunner)({ dataRoot: resolveManagedRoots({ env: deps.env ?? process.env }).dataRoot, platform, version: String(config.qa.version) });
+      runnerFile = managedRunner.file;
+    } else runnerFile = resolveRunner({ qa: config.qa, appRoot });
+  }
   const runnerSha = sha256File(runnerFile);
+  if (managedRunner && managedRunner.sha256 !== runnerSha) throw new Error(`the managed rightkit-qa ${managedRunner.version} changed between its verification and its digest; refusing to seal`);
   const journeysConfig = config.qa.journeys ?? null;
   const qaConfig = path.resolve(appRoot, config.qa.config);
   if (!existsSync(qaConfig)) throw new Error(`qa.config does not exist: ${qaConfig}`);
@@ -161,25 +181,50 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
     });
   }
   let run, journeysRun = null;
+  let layoutStage = null;
   try {
+    // Source stage with a declared layout: the QA shell and its layout are staged in a run-scoped directory from the gate's compile outputs (qa-layout.mjs); the snapshot is never written.
+    if (stage === "source" && config.qa.layout?.build) {
+      // The QA shell is built here, by the app's own build (and sign) suites, never by the release compile (qa-layout.mjs `build`).
+      const env = deps.env ?? process.env;
+      const plan = planTests(config, { suites: config.qa.layout.build, appRoot });
+      const stageFrom = ({ outputs, env: suiteEnv }) => {
+        const dirs = [...new Set(plan.filter((item) => !item.sign).flatMap((item) => outputs.get(item.name) ?? []))];
+        if (!dirs.length) throw new Error(`qa.layout.build: ${plan.map((item) => item.name).join(", ")} passed but named no output directory (no carried receipt, and no RIGHTKIT_GATE_TARGET_DIRS from the gate)`);
+        const signed = plan.some((item) => item.sign) ? JSON.parse(suiteEnv[QA_SIGNED_FILES_ENV] ?? "{}") : null;
+        return (deps.stageLayout ?? stageQaLayout)({ layout: config.qa.layout, snapshotAppRoot: appRoot, qaConfigFile: qaConfig, runsRoot: deps.runsRoot ?? gateRunsRoot({ env }), dirs, platform, signed });
+      };
+      const built = await (deps.runSuites ?? runSuites)(plan, { appRoot, prefix: "qa_build", env, config, log: (line) => console.error(line), errLog: (line) => console.error(line), within: stageFrom });
+      if (built.exitCode !== 0) throw new Error(`qa.layout.build: the QA shell build failed (${built.results.filter((r) => r.exitCode !== 0).map((r) => r.suite).join(", ")}); no QA ran`);
+      layoutStage = built.within;
+    } else if (stage === "source" && config.qa.layout) {
+      const dirs = deps.compiledDirs ?? compiledDirsFromEnv(deps.env ?? process.env);
+      if (!dirs) throw new Error("qa.layout needs the gate's compile outputs (RIGHT_RELEASE_QA_COMPILED_DIRS names none): run source QA through `rightkit-gate --to package`, after its compile");
+      layoutStage = (deps.stageLayout ?? stageQaLayout)({ layout: config.qa.layout, snapshotAppRoot: appRoot, qaConfigFile: qaConfig, runsRoot: deps.runsRoot ?? gateRunsRoot({ env: deps.env ?? process.env }), dirs, platform });
+    }
     const expand = (value) => String(value).replaceAll("{sealedDir}", sealed?.sealedDir ?? "").replaceAll("{releaseId}", releaseId)
       .replaceAll("{installedApp}", installedQa?.installedApp ?? "").replaceAll("{installedDir}", installedQa?.installedDir ?? "").replaceAll("{qaRoot}", installedQa?.qaRoot ?? "");
     const installedDirs = installedDirNames(config, deps.env ?? process.env);
     const runEnv = {
       ...process.env, RIGHT_RELEASE_QA_STAGE: stage, RIGHT_RELEASE_QA_COMMIT: source.commit, RIGHT_RELEASE_QA_RELEASE_ID: releaseId,
       ...(sealed ? { RIGHT_RELEASE_QA_SEALED_DIR: sealed.sealedDir } : {}), ...(installedDirs.length ? { RIGHTKIT_QA_INSTALLED_DIRS: installedDirs.join(";") } : {}), ...(installedQa?.env ?? {}),
+      ...(layoutStage ? { [QA_APP_BINARY_ENV]: layoutStage.binary } : {}),
     };
-    const args = ["run", "--config", qaConfig, ...((config.qa.args?.[stage] ?? []).map(expand))];
+    const runCwd = layoutStage?.appRoot ?? appRoot;
+    const args = ["run", "--config", layoutStage?.configFile ?? qaConfig, ...((config.qa.args?.[stage] ?? []).map(expand))];
     run = (deps.spawnRunner ?? spawnSync)(runnerFile, args, {
-      cwd: appRoot, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024,
+      cwd: runCwd, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024,
       env: runEnv,
     });
     // Journeys lane: the one release proof (ADR-0001 item 10). A receipt named in the config is read as is.
     if (journeysConfig && !journeysConfig.receipt) {
-      journeysRun = (deps.spawnJourneys ?? deps.spawnRunner ?? spawnSync)(runnerFile, ["journeys", "run", "--root", appRoot, ...((journeysConfig.args?.[stage] ?? []).map(expand))], {
-        cwd: appRoot, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024, env: runEnv,
+      journeysRun = (deps.spawnJourneys ?? deps.spawnRunner ?? spawnSync)(runnerFile, ["journeys", "run", "--root", runCwd, ...((journeysConfig.args?.[stage] ?? []).map(expand))], {
+        cwd: runCwd, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024, env: runEnv,
       });
     }
+  } catch (error) {
+    layoutStage?.cleanup();
+    throw error;
   } finally {
     installedQa?.cleanup();
   }
@@ -207,19 +252,23 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
     required = required.map((item) => (item.id === floor.journeys.floorId ? journeyRequiredItem({ floorId: item.id, validation }) : item));
   }
   const executionFinishedAt = new Date();
+  // The runner's outputs (evidence, journeys receipt) have been read; the run-scoped layout is not evidence and goes.
+  const layoutEvidence = layoutStage?.evidence ?? null;
+  layoutStage?.cleanup();
   // A passing receipt needs the runner to exit cleanly AND an evidence bundle that itself passed.
   if (run.status !== 0 && evidence) evidence = { ...evidence, status: "failed" };
-  const receipt = sealQaReceipt(buildQaReceipt({
+  // The layout evidence rides beside the standard body (release-qa-receipt.mjs is a policy-bundle entrypoint and stays untouched); the seal covers it.
+  const receipt = sealQaReceipt({ ...buildQaReceipt({
     stage, app: config.app, platform, releaseId, source, closure: dependencyClosure(repoRoot, source.commit, gitRunner),
     releaseConfigSha256: sha256File(configPath), qa: config.qa, floor, floorDigest,
     policyBundleDigest: deps.policyBundleDigest ?? currentPolicyBundleDigest(deps.floorDir),
-    runner: { basename: path.basename(runnerFile).replace(/\.exe$/i, ""), path: runnerFile, sha256: runnerSha },
+    runner: { basename: path.basename(runnerFile).replace(/\.exe$/i, ""), path: runnerFile, sha256: runnerSha, ...(managedRunner ? { version: managedRunner.version, source: "managed" } : {}) },
     evidence, evidenceSha256, required, artifacts, sourceReceiptDigest, journeys,
     execution: {
       startedAt: executionStartedAt.toISOString(), finishedAt: executionFinishedAt.toISOString(),
       runnerPids: [run.pid, journeysRun?.pid].filter((pid) => Number.isInteger(pid) && pid > 0), sealerPid: process.pid,
     },
-  }), key);
+  }), ...(layoutEvidence ? { layout: layoutEvidence } : {}) }, key);
   const file = qaReceiptPath({ repoRoot, releaseId, platform, stage });
   writeQaReceipt(file, receipt);
   // #183: copy the sealed receipt next to the candidate handoff so the signing job (a different runner) can read it.
@@ -239,6 +288,7 @@ function usage(code) {
 export async function main(args) {
   if (args[0] === "audit") process.exit(auditMain(args.slice(1)));
   if (args[0] === "policy") process.exit(policyMain(args.slice(1), { program: "right-release qa policy" }));
+  if (args[0] === "runner") process.exit(runnerMain(args.slice(1), { program: "right-release qa runner" }));
   let stage = "", platform = process.platform === "win32" ? "win" : "mac", releaseId = "", configName = defaultReleaseConfigFile(), carryTo = null;
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];

package/release-qa-policy.mjs

@@ -278,10 +278,12 @@ export function approveRunner({
   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"]; }
+  // A runner is the published version or the one RightKit has staged for its next publication (`stagedCargo`): an app's `qa.version` may name the staged one
+  // while the gate-built binary is what runs (qa-runner.mjs); admission is still by this sha256, never by the version string.
+  let published; let staged;
+  try { const feed = JSON.parse(readFileSync(versionsFile, "utf8")); published = feed.registry?.cargo?.["rightkit-qa"]; staged = feed.stagedCargo?.["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`);
+  if (published !== version && staged !== 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));

package/release-source-identity.mjs

@@ -76,6 +76,7 @@ export function resolveReleaseSource({ cwd = process.cwd(), env = process.env, g
   let detail = "";
   try { repoRoot = plainGit(git, cwd, ["rev-parse", "--show-toplevel"]).trim(); } catch (error) { detail = ` (${error.message})`; }
   if (!repoRoot) throw new ReleaseSourceError(`${cwd} is not inside a Git repository${detail}`, NO_REPOSITORY_CODE);
+  repoRoot = path.normalize(repoRoot); // git prints C:/dir on Windows; every other path here is in the platform's own spelling
   const commit = plainGit(git, repoRoot, ["rev-parse", "HEAD"]).trim();
   const tree = plainGit(git, repoRoot, ["rev-parse", `${commit}^{tree}`]).trim();
   if (!OBJECT_ID.test(commit) || !OBJECT_ID.test(tree)) throw new Error("the checkout's HEAD is not a commit");

package/release.mjs

@@ -15,7 +15,7 @@ import { assertQaAdoption, assertQaBackdoorContract } from "./qa-contract.mjs";
 import { assertLegalReleaseContract } from "./legal-contract.mjs";
 import { DECLARED_UNRELATED_POLICY, declaredUnrelatedRefusal, releaseArtifactPaths } from "./hosted-workflow-policy.mjs";
 import { assertNativeIosPrepareHasManifest, assertPrimaryReleaseCheckout, dirtyBuildInputs, resolveReleaseBuildInputs } from "./release-invocation.mjs";
-import { resolveReleaseSource, sourceRootOf } from "./release-source-identity.mjs";
+import { gitRootOf, isSnapshotSource, resolveReleaseSource, sourceRootOf } from "./release-source-identity.mjs";
 import { ArtifactPathError, assertSplitCommandPaths, releaseCommandSteps, resolveArtifactPath, splitArtifactContext } from "./release-artifact-path.mjs";
 import { declaredCargoManifest, hasDefaultTauriManifest, resolveNativeCargoLayout } from "./native-cargo-layout.mjs";
 import {
@@ -622,7 +622,15 @@ if (problems.length || prebuildFindings.length) {
   process.exit(1);
 }
 
-const releaseLock = acquireReleaseLock(root, config.app ?? path.basename(root), opts.platform, opts.tier);
+// The lock is an output, so a door split keeps it in the checkout's app directory: the snapshot is the commit's bytes, and a lock directory left
+// there fails the door's after-stage verify (HeardRight Windows package, 2026-11-01: ".cache/right-release is an empty directory the commit does not have").
+const lockRoot = (() => {
+  if (!workerSource || !isSnapshotSource(workerSource)) return root;
+  const relative = path.relative(sourceRootOf(workerSource), root);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) fail(`the release config directory ${root} is not inside the door snapshot ${sourceRootOf(workerSource)}; the release lock has no checkout counterpart`);
+  return path.join(gitRootOf(workerSource), relative);
+})();
+const releaseLock = acquireReleaseLock(lockRoot, config.app ?? path.basename(root), opts.platform, opts.tier);
 const mode = "package";
 const command = target.package;
 if (!command && opts.platform !== "android" && opts.platform !== "ios" && !packageCommandOptional(target, resolveProjectType({ appRoot: root, config, target }), { expanded: true })) fail(`${config.app ?? "app"} has no ${opts.platform} ${mode} command`);