@rightkit/release 0.2.165 → 0.2.173

package/publish-update.mjs

@@ -14,6 +14,7 @@ import { verifyPublicationRelease, PublicationError, assertArtifactUnchanged, di
 import { uploadVerifiedR2Artifact } from "./r2-verified-upload.mjs";
 import { verifyPlatformTrust } from "./github-release.mjs";
 import { admitInstalledQa } from "./release-qa-audit.mjs";
+import { assertAssetName, assertGitHubRepository, assertUpdaterKeyId, assertUpdaterPlatform, buildLatestJson, githubAssetUrl, githubTag, publishGitHubUpdaterRelease } from "./github-updater-release.mjs";
 
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const API_BASE = process.env.RIGHTAPPS_API_URL || "https://api.spoares.com";
@@ -44,9 +45,18 @@ if (!["win", "mac"].includes(platform)) throw new PublicationError("PUBLICATION_
 const configPath = path.resolve(configName);
 const root = path.dirname(configPath);
 const config = (await import(pathToFileURL(configPath))).default;
-if (config?.distribution?.provider !== "r2-rightapps") {
-  fail("release config distribution.provider must be r2-rightapps");
+const provider = config?.distribution?.provider;
+if (provider !== "r2-rightapps" && provider !== "github-releases") {
+  fail("release config distribution.provider must be r2-rightapps or github-releases");
 }
+// github-releases: the same sealed, suite-key-signed updater artifacts, published as release assets plus a Tauri v2
+// static latest.json (github-updater-release.mjs). Nothing below forks the r2 signing or platforms code.
+const githubLane = provider === "github-releases";
+let githubRepo = "";
+if (githubLane) {
+  try { githubRepo = assertGitHubRepository(config.distribution.repository); } catch (error) { fail(error.message); }
+}
+const githubKey = (item) => item.key ?? path.basename(item.file);
 const target = config?.targets?.[platform];
 const artifacts = target?.updater?.artifacts ?? [];
 const installers = target?.installer?.artifacts ?? [];
@@ -59,19 +69,24 @@ if (!dryRun || releaseId) {
   const commit = git(["rev-parse", "HEAD"]);
   assertCleanSource({ status: git(["status", "--porcelain=v1", "-z", "--untracked-files=all"]), commandId: "right-release publish-update" });
   sealed = verifyPublicationRelease({ sealedDir: path.join(repoRoot, ".right-release", "sealed", releaseId, platform === "win" ? "windows" : "mac"), repoRoot, appRoot: root, commit, app: config.app, version: versionForStorage, platform, configPath, releaseId });
-  const routes = sealed.manifest.routes?.[tier] ?? [];
-  const configured = [...(tier === "patch" ? installers.map((item) => ({ ...item, role: "installer" })) : []), ...artifacts.map((item) => ({ ...item, key: tier === "patch" ? patchInstallerKey(item) : item.key, role: "updater" }))];
+  const routes = sealed.manifest.routes?.[githubLane ? "update" : tier] ?? [];
+  const configured = githubLane
+    ? artifacts.map((item) => ({ ...item, key: githubKey(item), role: "updater" }))
+    : [...(tier === "patch" ? installers.map((item) => ({ ...item, role: "installer" })) : []), ...artifacts.map((item) => ({ ...item, key: tier === "patch" ? patchInstallerKey(item) : item.key, role: "updater" }))];
   for (const item of configured) {
-    if (!routes.some((route) => route.key === item.key && route.role === item.role && route.bucket === (tier === "patch" ? "public" : "private") && route.name === path.basename(item.file) && (!item.signature || route.signature === path.basename(item.signature)))) throw new PublicationError("PUBLICATION_ROUTE_INVALID", `config route is not sealed: ${item.key}`);
+    if (!routes.some((route) => route.key === item.key && route.role === item.role && route.bucket === (tier === "patch" && !githubLane ? "public" : "private") && route.name === path.basename(item.file) && (!item.signature || route.signature === path.basename(item.signature)))) throw new PublicationError("PUBLICATION_ROUTE_INVALID", `config route is not sealed: ${item.key}`);
   }
   if (!configured.length) throw new PublicationError("PUBLICATION_ROUTE_INVALID", "seal has no configured upload route");
   const installer = sealed.manifest.files.find((item) => item.role.split("+").includes("installer"));
-  if (!installer) throw new PublicationError("PUBLICATION_SIGNATURE_MISSING", "sealed installer required for platform trust verification");
-  verifyPlatformTrust({ sealed, installer: path.join(sealed.sealedDir, installer.name) });
+  if (!installer && !githubLane) throw new PublicationError("PUBLICATION_SIGNATURE_MISSING", "sealed installer required for platform trust verification");
+  // A github-releases app may ship only updater bundles and portable zips; their trust is the sealed signing
+  // receipts plus the updater signature, so platform trust runs only when a sealed installer exists.
+  if (installer) verifyPlatformTrust({ sealed, installer: path.join(sealed.sealedDir, installer.name) });
+  else console.log("no sealed installer; skipping installer platform trust check (github-releases updater-only seal)");
   for (const artifact of sealed.artifacts.values()) assertArtifactUnchanged(artifact);
   // Hardening step 4: installed QA is recorded, not enforced (R2 patch + update tiers); a missing receipt warns and is written to state.
   if (!dryRun) {
-    admitInstalledQa({ repoRoot, manifest: sealed.manifest, platform, configName: path.relative(process.cwd(), configPath) || configName, releaseConfigSha256: digestBytes(readFileSync(configPath)) }, { provider: "r2" });
+    admitInstalledQa({ repoRoot, manifest: sealed.manifest, platform, configName: path.relative(process.cwd(), configPath) || configName, releaseConfigSha256: digestBytes(readFileSync(configPath)) }, { provider: githubLane ? "github-releases" : "r2" });
   }
 }
 const artifactFile = (declared) => {
@@ -98,12 +113,12 @@ function git(args) {
   return result.stdout.trim();
 }
 
-if (tier === "patch" && !installers.length) fail(`${config?.app ?? "app"} ${platform} patch has no installer.artifacts`);
-if (tier === "update" && !artifacts.length) fail(`${config?.app ?? "app"} ${platform} update has no updater.artifacts`);
+if (!githubLane && tier === "patch" && !installers.length) fail(`${config?.app ?? "app"} ${platform} patch has no installer.artifacts`);
+if ((githubLane || tier === "update") && !artifacts.length) fail(`${config?.app ?? "app"} ${platform} update has no updater.artifacts`);
 
 if (sealed) for (const artifact of artifacts) signatureFor(artifact);
 let releaseToken = null;
-if (!dryRun && (tier === "update" || artifacts.length > 0)) {
+if (!githubLane && !dryRun && (tier === "update" || artifacts.length > 0)) {
   try {
     releaseToken = await loadReleaseToken();
   } catch (error) {
@@ -111,6 +126,52 @@ if (!dryRun && (tier === "update" || artifacts.length > 0)) {
   }
 }
 
+if (githubLane) {
+  const version = config.version || target.updater.version;
+  if (!version) fail(`${config.app} config must expose version or targets.${platform}.updater.version`);
+  try {
+    const tag = githubTag(version);
+    const notes = process.env.RIGHT_RELEASE_NOTES || `${config.app} ${version}`;
+    const platforms = {};
+    const assets = new Map();
+    for (const artifact of artifacts) {
+      assertUpdaterPlatform(artifact.platform);
+      const file = artifactFile(artifact.file);
+      const name = assertAssetName(path.basename(file));
+      // Same signature source and process as the r2 lane: the sealed minisign .sig written by sign-updater.
+      const signature = dryRun ? `<signature:${artifact.signature ?? "msix-authenticode"}>` : signatureFor(artifact);
+      if (!dryRun && !appInstallerKind) assertUpdaterKeyId(signature, config.distribution.updaterKeyId, `signature of ${name}`);
+      platforms[artifact.platform] = { signature, url: githubAssetUrl(githubRepo, tag, name) };
+      assets.set(file, { file, evidence: dryRun ? undefined : verifiedArtifact(file) });
+      if (!appInstallerKind) {
+        const sigFile = artifactFile(artifact.signature);
+        assets.set(sigFile, { file: sigFile, evidence: dryRun ? undefined : verifiedArtifact(artifact.signature) });
+      }
+    }
+    for (const asset of assets.values()) if (asset.evidence) assertArtifactUnchanged(asset.evidence);
+    const latest = buildLatestJson({ version, notes, pubDate: new Date().toISOString(), platforms });
+    for (const asset of assets.values()) console.log(`${dryRun ? "[dry-run] " : ""}UPLOAD ${githubRepo}@${tag}/${path.basename(asset.file)}`);
+    console.log(`${dryRun ? "[dry-run] " : ""}UPLOAD ${githubRepo}@${tag}/latest.json`);
+    console.log(JSON.stringify(latest));
+    const stateDir = path.join(root, ".right-release", "state", releaseId || "dry-run", platform === "win" ? "windows" : "mac", "github-updater");
+    const result = publishGitHubUpdaterRelease({
+      repo: githubRepo,
+      tag,
+      title: `${config.app} ${version}`,
+      notes,
+      assets: [...assets.values()].map((asset) => ({ file: asset.file, evidence: asset.evidence })),
+      latest,
+      stateDir,
+      dryRun,
+    });
+    console.log(`publish-update: github-releases ${result.status} ${tag}${result.latestJsonUrl ? ` ${result.latestJsonUrl}` : ""}`);
+  } catch (error) {
+    fail(error.message);
+  }
+  if (!dryRun) recordPublishedVersion({ app: config.app, version: versionForStorage, platform, configPath, releaseId });
+  process.exit(0);
+}
+
 if (tier === "patch") {
   for (const installer of installers) {
     assertCurrentKey(installer.key, "installer");

package/qa-adoption-exemptions.json

@@ -0,0 +1,5 @@
+{
+  "schema": 1,
+  "description": "Repositories that are not apps and so need no RightKit QA lane. RightKit-owned: a change needs a RightKit release. Never list an app here; there is no per-app opt-out. The RightKit source tree itself is recognised by packages/release/package.json (name @rightkit/release) and needs no entry.",
+  "nonAppRepositories": []
+}

package/qa-build-features.mjs

@@ -16,6 +16,9 @@ export const FORBIDDEN_FEATURES = Object.freeze(["devtools", "content-devtools",
   "qa-shot", "qa-tools", "dev-control", "bench-native",
   // D4 (M21/M23): rightkit-daemon `test-mode` compiles the override selectors; never in a release build.
   "test-mode"]);
+// rightkit-qa 0.6.0 moved the embedded control server (the former rightkit-qa-driver `qa-control`) behind its `control`
+// feature. It emits the same QA_CONTROL_MARKER, so the binary layer refuses it unchanged; this is the source layer.
+export const QUALIFIED_FORBIDDEN_FEATURES = Object.freeze(["rightkit-qa/control", "rightkit-qa?/control"]);
 // The only forbidden features an allow-listed app may enable: rightkit-tauri-shell's `content-devtools` (and the Tauri
 // `devtools` it switches on). See devtools-policy.mjs; every other app is refused them.
 const DEVTOOLS_FEATURES = Object.freeze(["devtools", "content-devtools"]);
@@ -31,6 +34,8 @@ export function isForbiddenFeature(item, { allowDevtools = false } = {}) {
   const text = String(item).trim();
   const name = featureName(text);
   if (allowDevtools && DEVTOOLS_FEATURES.includes(name)) return false;
+  // `control` is too generic to forbid by bare name; rightkit-qa's dev-only server feature is refused when qualified.
+  if (QUALIFIED_FORBIDDEN_FEATURES.includes(text.replace(/\s+/g, ""))) return true;
   return text === `dep:${FORBIDDEN_DEPENDENCY}` || FORBIDDEN_FEATURES.includes(name);
 }
 
@@ -163,6 +168,8 @@ export function cargoManifestIssues(manifestText, label = "Cargo.toml", { allowD
     const control = dependencies.get(name);
     if (control && !control.optional && control.features.includes("qa-control")) issues.push(`${label}: dependency \`${name}\` lists \`qa-control\` unconditionally`);
   }
+  const qa = dependencies.get("rightkit-qa");
+  if (qa && !qa.optional && qa.features.includes("control")) issues.push(`${label}: dependency \`rightkit-qa\` lists \`control\` unconditionally`);
   // The crate was renamed from rightkit-shell; apps still on the old published name must stay covered.
   for (const name of ["rightkit-tauri-shell", "rightkit-shell"]) {
     const shell = dependencies.get(name);

package/qa-contract.mjs

@@ -1,5 +1,7 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
+import { spawnSync } from "./background-process.mjs";
+import { breakingBump, loadRightkitVersions } from "./rightkit-drift.mjs";
 
 export function validateQaBackdoorContract(root, packageScripts = {}) {
   if (!existsSync(path.join(root, "right-qa.config.mjs"))) return [];
@@ -59,3 +61,183 @@ function readRustSources(root) {
   visit(root);
   return files.sort().map((file) => readFileSync(file, "utf8")).join("\n");
 }
+
+// ---------------------------------------------------------------- QA adoption (mandatory for every app)
+//
+// RightKit QA is a mandatory component: every Orthic Labs app must carry a recognised QA lane. Recognised lanes:
+//  - the native wdio lane (`right-qa.config.mjs`, validated by validateQaBackdoorContract above),
+//  - `@rightkit/qa` in any non-node_modules package.json (dependencies or devDependencies), and/or
+//  - `rightkit-qa` in any Cargo.toml (dependencies, dev-dependencies or build-dependencies).
+// `@rightkit/qa-chrome` is the web-UI companion; its presence is not enforced (a UI cannot be detected reliably)
+// but its pin is lag-checked like the others.
+// A pin behind the latest published version (rightkit-versions.json) is a warning; a breaking-bump lag (the
+// `breakingBump` rule rightkit-drift uses) refuses. The only exemption is for repositories that are not apps
+// (qa-adoption-exemptions.json, RightKit-owned: changing it takes a RightKit release). No per-app opt-out.
+
+export const QA_EXEMPTIONS_FILE = "qa-adoption-exemptions.json";
+const NPM_QA = "@rightkit/qa";
+const NPM_QA_CHROME = "@rightkit/qa-chrome";
+const CARGO_QA = "rightkit-qa";
+const NPM_SECTIONS = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
+const SKIP_DIRS = /^(node_modules(\..*)?|target|vendor|dist|build|\.git|\.cache|\.right-release)$/;
+const MAX_DEPTH = 6;
+const EXEMPTION_KINDS = ["library", "tooling"];
+
+const numeric = (value) => String(value).split("-")[0].split(".").map((part) => Number.parseInt(part, 10) || 0);
+const newer = (candidate, current) => { const a = numeric(candidate); const b = numeric(current); for (let i = 0; i < 3; i += 1) if (a[i] !== b[i]) return a[i] > b[i]; return false; };
+const latestFor = (versions, ecosystem, name) => versions.registry
+  ? versions.registry[ecosystem]?.[name]
+  : ecosystem === "npm" ? versions.stagedNpm?.[name] ?? versions.npm?.[name] : versions.stagedCargo?.[name] ?? versions.cargo?.[name];
+
+/** package.json and Cargo.toml files in the app tree, skipping node_modules (any suffix), target, vendor, dist and the RightKit tree. */
+export function qaManifests(appRoot, { readdir = readdirSync } = {}) {
+  const found = [];
+  const visit = (dir, depth) => {
+    let entries;
+    try { entries = readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const relative = path.relative(appRoot, path.join(dir, entry.name)).split(path.sep).join("/");
+      if (entry.isDirectory()) {
+        if (depth < MAX_DEPTH && !SKIP_DIRS.test(entry.name) && relative !== "rightkit" && relative !== "tools/rightkit") visit(path.join(dir, entry.name), depth + 1);
+      } else if (entry.name === "package.json" || entry.name === "Cargo.toml") found.push(relative);
+    }
+  };
+  visit(appRoot, 0);
+  return found.sort();
+}
+
+/** `[dependencies]`-style section header that holds dependencies (including target-specific ones). */
+const DEPENDENCY_HEADER = /^\[\s*(?:target\.[^\]]+\.)?(?:dev-|build-)?dependencies\s*\]/;
+const DEPENDENCY_TABLE_HEADER = /^\[\s*(?:target\.[^\]]+\.)?(?:dev-|build-)?dependencies\.([A-Za-z0-9_-]+)\s*\]/;
+const WORKSPACE_DEPENDENCY = /^\[\s*workspace\.dependencies\s*\]/;
+
+/** `rightkit-qa` declarations in a Cargo.toml: [{ version | null }]. Path, git and workspace deps carry no version. */
+export function cargoQaPins(text, crate = CARGO_QA) {
+  const pins = [];
+  let section = null;
+  let table = null;
+  const push = (body) => {
+    const version = (body.match(/\bversion\s*=\s*"[=^~<>\s]*(\d+\.\d+\.\d+)/) ?? body.match(/^"[=^~<>\s]*(\d+\.\d+\.\d+)/))?.[1] ?? null;
+    pins.push({ version: /\bpath\s*=|\bgit\s*=/.test(body) ? null : version });
+  };
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.replace(/\s+#.*$/, "").trim();
+    if (!line || line.startsWith("#")) continue;
+    if (line.startsWith("[")) {
+      table = line.match(DEPENDENCY_TABLE_HEADER);
+      if (table && table[1] === crate) { section = "table"; pins.push({ version: null, open: true }); continue; }
+      section = DEPENDENCY_HEADER.test(line) || WORKSPACE_DEPENDENCY.test(line) ? "deps" : null;
+      continue;
+    }
+    if (section === "table") {
+      const open = pins.at(-1);
+      const version = line.match(/^version\s*=\s*"[=^~<>\s]*(\d+\.\d+\.\d+)/)?.[1];
+      if (version) open.version = version;
+      if (/^(path|git)\s*=/.test(line)) open.local = true;
+      continue;
+    }
+    if (section === "deps") {
+      const match = line.match(new RegExp(`^${crate}(?:\\.[A-Za-z-]+)?\\s*=\\s*(.*)$`));
+      if (match) push(match[1]);
+    }
+  }
+  return pins.map(({ version, local }) => ({ version: local ? null : version }));
+}
+
+/** `@rightkit/qa` style declarations in one parsed package.json. */
+export function npmQaPins(manifest, name) {
+  const pins = [];
+  for (const section of NPM_SECTIONS) {
+    const spec = manifest?.[section]?.[name];
+    if (typeof spec !== "string") continue;
+    pins.push({ version: spec.match(/^[\^~=]?(\d+\.\d+\.\d+)$/)?.[1] ?? null });
+  }
+  return pins;
+}
+
+/** Normalise a git remote to `host/owner/repo` lowercase, so ssh and https spellings of one repository agree. */
+export function normalizeRepositoryIdentity(url) {
+  const text = String(url ?? "").trim().replace(/\.git$/i, "").replace(/\/+$/, "");
+  const ssh = text.match(/^(?:ssh:\/\/)?git@([^:/]+)[:/](.+)$/);
+  if (ssh) return `${ssh[1]}/${ssh[2]}`.toLowerCase();
+  return text.replace(/^[a-z+]+:\/\//i, "").replace(/^[^@/]+@/, "").toLowerCase();
+}
+
+function originRemote(root) {
+  const result = spawnSync("git", ["-C", root, "remote", "get-url", "origin"], { encoding: "utf8", windowsHide: true });
+  return result.status === 0 ? String(result.stdout).trim() : null;
+}
+
+function loadExemptions() {
+  try { return JSON.parse(readFileSync(new URL(`./${QA_EXEMPTIONS_FILE}`, import.meta.url), "utf8")); } catch { return { nonAppRepositories: [] }; }
+}
+
+/**
+ * The exemption for a repository that is not an app, or null. Matched by git `origin` identity against the
+ * RightKit-owned list; the RightKit source tree itself is recognised by its release package, with no list entry.
+ */
+export function qaExemption({ appRoot, repoRoot }, { exemptions = loadExemptions(), remote = originRemote, exists = existsSync, readFile = readFileSync } = {}) {
+  for (const root of [appRoot, repoRoot].filter(Boolean)) {
+    try {
+      const manifest = path.join(root, "packages", "release", "package.json");
+      if (exists(manifest) && JSON.parse(readFile(manifest, "utf8")).name === "@rightkit/release") return { kind: "tooling", reason: "the RightKit source tree is not an app" };
+    } catch { /* not the RightKit tree */ }
+  }
+  for (const entry of exemptions.nonAppRepositories ?? []) {
+    if (!EXEMPTION_KINDS.includes(entry?.kind) || !entry.reason || !entry.repositoryIdentity) continue;
+    for (const root of [appRoot, repoRoot].filter(Boolean)) {
+      const origin = remote(root);
+      if (origin && normalizeRepositoryIdentity(origin) === normalizeRepositoryIdentity(entry.repositoryIdentity)) return { kind: entry.kind, reason: entry.reason };
+    }
+  }
+  return null;
+}
+
+
+/** Pure evaluation: { exempt, lane, refusals[], warnings[] }. */
+export function evaluateQaAdoption({ appRoot, repoRoot, app }, deps = {}) {
+  const { readFile = readFileSync, exists = existsSync, versions = loadRightkitVersions() } = deps;
+  const exempt = qaExemption({ appRoot, repoRoot }, deps);
+  if (exempt) return { exempt, lane: null, refusals: [], warnings: [] };
+  const files = deps.manifests ?? qaManifests(appRoot, deps);
+  const pins = [];
+  const unreadable = [];
+  for (const file of files) {
+    let text;
+    try { text = readFile(path.join(appRoot, file), "utf8"); } catch (error) { unreadable.push(`${file}: ${error.message}`); continue; }
+    if (file.endsWith("package.json")) {
+      let manifest;
+      try { manifest = JSON.parse(text); } catch { unreadable.push(`${file}: not valid JSON`); continue; }
+      for (const name of [NPM_QA, NPM_QA_CHROME]) for (const pin of npmQaPins(manifest, name)) pins.push({ ecosystem: "npm", name, file, ...pin });
+    } else {
+      for (const pin of cargoQaPins(text)) pins.push({ ecosystem: "cargo", name: CARGO_QA, file, ...pin });
+    }
+  }
+  const label = app ?? "this app";
+  const adopted = [...new Set(pins.filter((pin) => pin.name === NPM_QA || pin.name === CARGO_QA).map((pin) => pin.name))];
+  const lane = exists(path.join(appRoot, "right-qa.config.mjs")) ? ["native wdio lane (right-qa.config.mjs)", ...adopted] : adopted;
+  const refusals = [];
+  const warnings = [];
+  if (lane.length === 0) {
+    refusals.push(`RightKit QA is mandatory for every Orthic Labs app, and ${label} has no QA lane: no right-qa.config.mjs, no ${NPM_QA} in a package.json, no ${CARGO_QA} in a Cargo.toml${unreadable.length ? ` (unreadable: ${unreadable.join("; ")})` : ""}. Adopt it: add ${NPM_QA} to devDependencies (plus ${NPM_QA_CHROME} for a web UI) and/or ${CARGO_QA} to Cargo.toml [dev-dependencies], add the rightkit-qa floor run (smoke.launch, journey), see docs/ADOPTION.md, then run: node rightkit-drift.mjs --apply. Only a repository that is not an app is exempt (${QA_EXEMPTIONS_FILE}); an app cannot opt out`);
+  }
+  const lagging = pins
+    .map((pin) => ({ ...pin, latest: pin.version && latestFor(versions, pin.ecosystem, pin.name) }))
+    .filter((pin) => pin.latest && newer(pin.latest, pin.version))
+    .map((pin) => ({ ...pin, breaking: breakingBump(pin.version, pin.latest) }));
+  const describe = (list) => list.map((pin) => `${pin.name} ${pin.version} -> ${pin.latest}${pin.breaking ? " (breaking)" : ""} (${pin.file})`).join("; ");
+  const breaking = lagging.filter((pin) => pin.breaking);
+  const soft = lagging.filter((pin) => !pin.breaking);
+  if (breaking.length) refusals.push(`${label} runs RightKit QA behind a breaking version: ${describe(breaking)}. Move the QA pins forward and adapt the QA setup: node rightkit-drift.mjs --apply --all`);
+  if (soft.length) warnings.push(`${label} runs RightKit QA behind the latest published version: ${describe(soft)}. Update with: node rightkit-drift.mjs --apply`);
+  return { exempt: null, lane, refusals, warnings };
+}
+
+/** Release gate: throws when the app has no QA lane or lags a breaking version; warnings go to `warn`. */
+export function assertQaAdoption(opts, deps = {}) {
+  const { warn = (line) => console.error(line) } = deps;
+  const result = evaluateQaAdoption(opts, deps);
+  for (const line of result.warnings) warn(`[right-release] QA warning: ${line}`);
+  if (result.refusals.length) throw new Error(`QA adoption contract failed:\n- ${result.refusals.join("\n- ")}`);
+  return result;
+}

package/qa-control-scan.mjs

@@ -6,7 +6,7 @@
 // (signing set, staged payloads, hardening targets, sealed files). The development lane (`development.mjs`)
 // never calls it: dev builds are the QA builds. The source-level layer is `qa-build-features.mjs`.
 //
-//   qa-control-server  `rightkit-qa-driver` feature `qa-control`: every binary with the embedded server carries
+//   qa-control-server  `rightkit-qa` feature `control` (and the `rightkit-qa-driver` shim feature `qa-control`): every binary with the embedded server carries
 //                      QA_CONTROL_MARKER (a `#[used]` static in `embedded/mod.rs`, also read by `Control::build`).
 //   wdio-webdriver     `tauri-plugin-wdio-webdriver` (HeardRight/MailRight/ViewRight `qa-native`): needs 2 of 3
 //                      independent signatures. WEAKER than the marker: the plugin source was not on disk when
@@ -20,7 +20,7 @@ import { closeSync, lstatSync, openSync, readFileSync, readSync, readdirSync } f
 import path from "node:path";
 import { inflateRawSync } from "node:zlib";
 
-// Keep identical to `QA_CONTROL_MARKER` in crates/rightkit-qa-driver/src/embedded/mod.rs.
+// Keep identical to `QA_CONTROL_MARKER` in crates/rightkit-qa/src/embedded/mod.rs.
 export const QA_CONTROL_MARKER = "RIGHTKIT-QA-CONTROL-SERVER-PRESENT";
 // Keep identical to `DEV_INSPECT_MARKER` in crates/rightkit-tauri-shell/src/devtools.rs (a `#[used]` static compiled only
 // with rightkit-tauri-shell's `dev-inspect` feature and read by the process guard). No allow-list lifts this rule.
@@ -31,7 +31,7 @@ const CHUNK = 4 * 1024 * 1024;
 // Each signature is matched as Latin-1/UTF-8 bytes and as UTF-16LE (Windows wide strings). `min` signatures of a
 // rule must be present for it to fire; a signature counts once however often or in whichever encoding it occurs.
 export const QA_RULES = Object.freeze([
-  { id: "qa-control-server", min: 1, label: "RightKit QA control server (rightkit-qa-driver qa-control)",
+  { id: "qa-control-server", min: 1, label: "RightKit QA control server (rightkit-qa control, or rightkit-qa-driver qa-control)",
     signatures: [{ id: "marker", text: QA_CONTROL_MARKER }] },
   { id: "shell-dev-inspect", min: 1, marker: DEV_INSPECT_MARKER, label: "rightkit-tauri-shell developer inspection (rightkit-tauri-shell dev-inspect)",
     signatures: [{ id: "marker", text: DEV_INSPECT_MARKER }] },

package/release-qa-command.mjs

@@ -7,7 +7,8 @@
 //
 // 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
+//         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
 //         checks: { "smoke.launch": ["app.launch"], journey: ["journey.*"] } }          // floor id -> evidence check names
 // Every id in release-qa-floor.json must be mapped; skipped/failed/missing required checks fail the receipt.
 import { createHash } from "node:crypto";
@@ -20,6 +21,7 @@ import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
 import { assertCleanSource } from "./source-gate.mjs";
 import { verifySealedRelease } from "./release-state.mjs";
 import { auditMain } from "./release-qa-audit.mjs";
+import { prepareInstalledArtifacts } from "./release-qa-installed.mjs";
 import { darwinKeyFile, PROTECTED_SECRETS } from "./protected-credentials.mjs";
 import {
   buildQaReceipt, currentPolicyBundleDigest, dependencyClosure, ensureQaReceiptKey, evaluateRequiredChecks, loadQaFloor,
@@ -53,7 +55,7 @@ export function evidencePathFromOutput(stdout) {
 }
 
 /** Run the QA plan through the runner, then seal a receipt. `deps` are test seams; production uses the defaults. */
-export async function runQa({ stage, platform, releaseIdArg, configPath, deps = {} }) {
+export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo = null, deps = {} }) {
   const gitRunner = deps.gitRunner ?? spawnSync;
   const appRoot = path.dirname(configPath);
   const repoRoot = String(gitRunner("git", ["-C", appRoot, "rev-parse", "--show-toplevel"], { encoding: "utf8", windowsHide: true }).stdout ?? "").trim();
@@ -86,12 +88,28 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, deps =
   const runnerSha = sha256File(runnerFile);
   const qaConfig = path.resolve(appRoot, config.qa.config);
   if (!existsSync(qaConfig)) throw new Error(`qa.config does not exist: ${qaConfig}`);
-  const expand = (value) => String(value).replaceAll("{sealedDir}", sealed?.sealedDir ?? "").replaceAll("{releaseId}", releaseId);
-  const args = ["run", "--config", qaConfig, ...((config.qa.args?.[stage] ?? []).map(expand))];
-  const run = (deps.spawnRunner ?? spawnSync)(runnerFile, args, {
-    cwd: appRoot, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024,
-    env: { ...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 } : {}) },
-  });
+  // #184: opt in with `qa.installed: { installDir? }`. Mounts the sealed DMG (mac) or runs the sealed NSIS installer into a
+  // throwaway directory (win) and hands the runner the opened app; always cleaned up, even when the runner throws.
+  let installedQa = null;
+  if (stage === "installed" && config.qa.installed && config.qa.installed !== false) {
+    installedQa = (deps.prepareInstalled ?? prepareInstalledArtifacts)({
+      sealedDir: sealed.sealedDir, manifest: sealed.manifest, platform,
+      installDir: typeof config.qa.installed === "object" ? config.qa.installed.installDir ?? null : null,
+      deps: { log: (event) => { if (!deps.quiet) console.error(`[qa] ${JSON.stringify(event)}`); } },
+    });
+  }
+  let run;
+  try {
+    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 args = ["run", "--config", qaConfig, ...((config.qa.args?.[stage] ?? []).map(expand))];
+    run = (deps.spawnRunner ?? spawnSync)(runnerFile, args, {
+      cwd: appRoot, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024,
+      env: { ...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 } : {}), ...(installedQa?.env ?? {}) },
+    });
+  } finally {
+    installedQa?.cleanup();
+  }
   if (!deps.quiet) { process.stdout.write(String(run.stdout ?? "")); process.stderr.write(String(run.stderr ?? "")); }
   const evidenceFile = evidencePathFromOutput(run.stdout);
   let evidence = null, evidenceSha256 = null;
@@ -112,31 +130,39 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, deps =
   }), key);
   const file = qaReceiptPath({ repoRoot, releaseId, platform, stage });
   writeQaReceipt(file, receipt);
-  return { receipt, file };
+  // #183: copy the sealed receipt next to the candidate handoff so the signing job (a different runner) can read it.
+  let carriedFile = null;
+  if (carryTo) {
+    carriedFile = path.join(path.resolve(carryTo), `${stage}.receipt.json`);
+    writeQaReceipt(carriedFile, receipt);
+  }
+  return { receipt, file, carriedFile };
 }
 
 function usage(code) {
-  console.log("usage: right-release qa --stage source|installed --platform mac|win [--release <sealed-id>] [--config right-release.config.mjs]\n       right-release qa audit [--app <dir>] [--json] [--since <YYYY-MM-DD>]");
+  console.log("usage: right-release qa --stage source|installed --platform mac|win [--release <sealed-id>] [--config right-release.config.mjs] [--carry-to <dir>]\n       right-release qa audit [--app <dir>] [--json] [--since <YYYY-MM-DD>]");
   process.exit(code);
 }
 
 export async function main(args) {
   if (args[0] === "audit") process.exit(auditMain(args.slice(1)));
-  let stage = "", platform = process.platform === "win32" ? "win" : "mac", releaseId = "", configName = "right-release.config.mjs";
+  let stage = "", platform = process.platform === "win32" ? "win" : "mac", releaseId = "", configName = "right-release.config.mjs", carryTo = null;
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--stage") stage = args[++index];
     else if (arg === "--platform") platform = args[++index];
     else if (arg === "--release") releaseId = args[++index];
     else if (arg === "--config") configName = args[++index];
+    else if (arg === "--carry-to") carryTo = args[++index];
     else if (arg === "-h" || arg === "--help") usage(0);
     else { console.error(`right-release qa: unknown argument: ${arg}`); process.exit(2); }
   }
   if (!QA_STAGES.includes(stage)) { console.error("right-release qa: --stage must be source or installed"); process.exit(2); }
   if (platform !== "win" && platform !== "mac") { console.error("right-release qa: --platform must be win or mac"); process.exit(2); }
   try {
-    const { receipt, file } = await runQa({ stage, platform, releaseIdArg: releaseId, configPath: path.resolve(configName) });
+    const { receipt, file, carriedFile } = await runQa({ stage, platform, releaseIdArg: releaseId, configPath: path.resolve(configName), carryTo });
     console.log(`right-release qa: ${stage} receipt ${receipt.status} ${receipt.digest.slice(0, 16)} -> ${file}`);
+    if (carriedFile) console.log(`right-release qa: carried copy -> ${carriedFile}`);
     for (const item of receipt.required) console.log(`  ${item.id}: ${item.status}`);
     process.exit(receipt.status === "passed" ? 0 : 1);
   } catch (error) {

package/release-qa-installed.mjs

@@ -0,0 +1,136 @@
+// Installed QA stage artifact preparation (Orthic-Labs/rightkit#184).
+//
+// `right-release qa --stage installed` used to hand the sealed directory to the QA runner and nothing more:
+// install-app is Mac-only and nothing mounted or ran the sealed artifacts. This module opens the exact sealed
+// bytes the receipt will name, without touching real user data:
+//
+//   macOS    mounts the sealed DMG read-only and not browsable (`hdiutil attach -readonly -nobrowse -noautoopen`)
+//            at a throwaway mount root under the OS temp directory, and exposes the .app inside the mount.
+//            Nothing is copied to /Applications and no user data directory is read or written.
+//   Windows  runs the sealed NSIS installer silently (`/S /D=<throwaway dir>`; /D is the NSIS install-dir
+//            override and must be last) into a directory under the OS temp directory. Running an installer registers
+//            an uninstall entry for the current user, so it needs an explicit opt-in on a VM or throwaway host
+//            (`RIGHT_RELEASE_QA_ALLOW_INSTALL=1`) or GitHub-hosted CI. It is refused when an install directory
+//            outside the throwaway root is requested without that opt-in. Cleanup runs the installed uninstaller
+//            silently and removes the directory.
+//
+// Both paths also give the runner a throwaway QA data root (`RIGHT_RELEASE_QA_ROOT`) so the app under QA never
+// has to use the real per-user data location. The caller owns `cleanup()`; it never throws.
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync as defaultSpawnSync } from "./background-process.mjs";
+import { detachWithRetrySync } from "./hdiutil-detach.mjs";
+import { mountPointsFromAttach } from "./install-app.mjs";
+
+export const QA_ALLOW_INSTALL_ENV = "RIGHT_RELEASE_QA_ALLOW_INSTALL";
+
+export class InstalledQaError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "InstalledQaError";
+    this.code = code;
+  }
+}
+
+const lower = (name) => String(name).toLowerCase();
+
+/** The one sealed DMG (macOS) or NSIS setup executable (Windows). Anything else is ambiguous and refused. */
+export function selectSealedInstaller({ files, platform }) {
+  const names = (files ?? []).map((file) => file.name);
+  const pick = platform === "win"
+    ? names.filter((name) => lower(name).endsWith(".exe") && lower(name).includes("setup"))
+    : names.filter((name) => lower(name).endsWith(".dmg"));
+  if (pick.length !== 1) {
+    throw new InstalledQaError("INSTALLED_QA_ARTIFACT", `installed QA needs exactly one sealed ${platform === "win" ? "NSIS setup .exe" : ".dmg"}; found ${pick.length}${pick.length ? ` (${pick.join(", ")})` : ""}`);
+  }
+  return pick[0];
+}
+
+/** Windows installers write an uninstall entry: only on CI, or when the operator opted in on a VM / throwaway host. */
+export function assertWindowsInstallAllowed(env = process.env) {
+  const ci = env.GITHUB_ACTIONS === "true" && env.RUNNER_ENVIRONMENT === "github-hosted";
+  if (ci || env[QA_ALLOW_INSTALL_ENV] === "1") return;
+  throw new InstalledQaError("INSTALLED_QA_INSTALL_NOT_ALLOWED", `running the sealed NSIS installer registers the app for the current user; run it on a VM or throwaway host and set ${QA_ALLOW_INSTALL_ENV}=1 (never on a machine holding real app data)`);
+}
+
+const describe = (result) => `${result?.stderr ?? ""}${result?.stdout ?? ""}`.trim() || result?.error?.message || `exit ${result?.status}`;
+
+function prepareMac({ sealedDir, name, tmpdir, spawn, log }) {
+  const dmg = path.join(sealedDir, name);
+  const mountRoot = mkdtempSync(path.join(tmpdir, "right-qa-dmg-"));
+  let mountPoint = null;
+  const cleanup = () => {
+    if (mountPoint) {
+      const out = detachWithRetrySync({ mount: mountPoint, log, detach: (args) => spawn("/usr/bin/hdiutil", args, { encoding: "utf8", windowsHide: true }) });
+      if (!out.ok) log({ event: "installed-qa-detach-failed", mount: mountPoint });
+      mountPoint = null;
+    }
+    try { rmSync(mountRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+  };
+  const attached = spawn("/usr/bin/hdiutil", ["attach", "-nobrowse", "-readonly", "-noautoopen", "-mountrandom", mountRoot, "-plist", dmg], { encoding: "utf8", windowsHide: true, maxBuffer: 16 * 1024 * 1024 });
+  if (attached.status !== 0) { cleanup(); throw new InstalledQaError("INSTALLED_QA_MOUNT", `hdiutil attach failed for ${name}: ${describe(attached)}`); }
+  let mounts;
+  try { mounts = mountPointsFromAttach(attached.stdout); } catch (error) { cleanup(); throw new InstalledQaError("INSTALLED_QA_MOUNT", `cannot read hdiutil attach output for ${name}: ${error.message}`); }
+  if (!mounts.length) { cleanup(); throw new InstalledQaError("INSTALLED_QA_MOUNT", `${name} attached but exposed no mount point`); }
+  mountPoint = mounts[0];
+  const apps = [];
+  for (const mount of mounts) for (const entry of readdirSync(mount)) if (entry.endsWith(".app")) apps.push(path.join(mount, entry));
+  if (apps.length !== 1) { cleanup(); throw new InstalledQaError("INSTALLED_QA_APP", `expected exactly one .app in ${name}; found ${apps.length}`); }
+  log({ event: "installed-qa-mounted", dmg: name, mount: mountPoint, app: apps[0] });
+  return { kind: "dmg", installedApp: apps[0], installedDir: mountPoint, cleanup };
+}
+
+function prepareWindows({ sealedDir, name, tmpdir, spawn, log, env, installDir }) {
+  assertWindowsInstallAllowed(env);
+  const installer = path.join(sealedDir, name);
+  const root = mkdtempSync(path.join(tmpdir, "right-qa-nsis-"));
+  const target = installDir ?? path.join(root, "app");
+  if (!path.isAbsolute(target)) { rmSync(root, { recursive: true, force: true }); throw new InstalledQaError("INSTALLED_QA_INSTALL_DIR", `install directory must be absolute: ${target}`); }
+  if (installDir && !path.resolve(installDir).toLowerCase().startsWith(path.resolve(tmpdir).toLowerCase() + path.sep) && env[QA_ALLOW_INSTALL_ENV] !== "1") {
+    rmSync(root, { recursive: true, force: true });
+    throw new InstalledQaError("INSTALLED_QA_INSTALL_DIR", `install directory ${installDir} is outside the throwaway root and ${QA_ALLOW_INSTALL_ENV}=1 is not set`);
+  }
+  const cleanup = () => {
+    try {
+      const uninstaller = path.join(target, "uninstall.exe");
+      // `_?=<dir>` keeps the uninstaller in place and synchronous so the directory can be removed afterwards.
+      if (existsSync(uninstaller)) spawn(uninstaller, ["/S", `_?=${target}`], { encoding: "utf8", windowsHide: true, shell: false });
+    } catch { /* best effort */ }
+    try { rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ }
+    if (installDir) { try { rmSync(target, { recursive: true, force: true }); } catch { /* best effort */ } }
+  };
+  mkdirSync(target, { recursive: true });
+  // NSIS: /S silent, /D=<dir> install directory; /D must be the last argument, unquoted.
+  const result = spawn(installer, ["/S", `/D=${target}`], { encoding: "utf8", windowsHide: true, shell: false });
+  if (result.status !== 0) { cleanup(); throw new InstalledQaError("INSTALLED_QA_INSTALL", `sealed installer ${name} failed: ${describe(result)}`); }
+  const exes = existsSync(target) ? readdirSync(target).filter((entry) => lower(entry).endsWith(".exe") && lower(entry) !== "uninstall.exe") : [];
+  log({ event: "installed-qa-installed", installer: name, dir: target, executables: exes });
+  return { kind: "nsis", installedApp: exes.length === 1 ? path.join(target, exes[0]) : null, installedDir: target, cleanup };
+}
+
+/**
+ * Open the sealed installer for the runner. Returns `{ kind, installedApp, installedDir, qaRoot, env, cleanup }`.
+ * `env` is merged into the runner environment; `expand` placeholders are `{installedApp}`, `{installedDir}`, `{qaRoot}`.
+ */
+export function prepareInstalledArtifacts({ sealedDir, manifest, platform, installDir = null, deps = {} }) {
+  const { spawn = defaultSpawnSync, tmpdir = os.tmpdir(), env = process.env, log = () => {}, hostPlatform = process.platform } = deps;
+  if (platform === "mac" && hostPlatform !== "darwin") throw new InstalledQaError("INSTALLED_QA_HOST", "mounting the sealed DMG needs macOS");
+  if (platform === "win" && hostPlatform !== "win32") throw new InstalledQaError("INSTALLED_QA_HOST", "running the sealed NSIS installer needs Windows");
+  const name = selectSealedInstaller({ files: manifest.files, platform });
+  const opened = platform === "win"
+    ? prepareWindows({ sealedDir, name, tmpdir, spawn, log, env, installDir })
+    : prepareMac({ sealedDir, name, tmpdir, spawn, log });
+  const qaRoot = mkdtempSync(path.join(tmpdir, "right-qa-root-"));
+  const cleanup = () => { opened.cleanup(); try { rmSync(qaRoot, { recursive: true, force: true }); } catch { /* best effort */ } };
+  return {
+    kind: opened.kind, installedApp: opened.installedApp, installedDir: opened.installedDir, qaRoot, cleanup,
+    env: {
+      RIGHT_RELEASE_QA_INSTALLED_KIND: opened.kind,
+      RIGHT_RELEASE_QA_INSTALLED_ARTIFACT: name,
+      RIGHT_RELEASE_QA_INSTALLED_DIR: opened.installedDir,
+      ...(opened.installedApp ? { RIGHT_RELEASE_QA_INSTALLED_APP: opened.installedApp } : {}),
+      RIGHT_RELEASE_QA_ROOT: qaRoot,
+    },
+  };
+}