@rightkit/release 0.2.45 → 0.2.47

package/build-release.mjs

@@ -25,6 +25,31 @@ import { commandOutputPortable, releaseEnvironment, resolveReleaseLayout, runBui
 import { acquireCacheLease, acquireSuiteBuildSlot, applyCachePrune, assertWriteVolumeFloors, inspectCache, inspectWriteVolumes, markCacheEntrySuccessful, planCachePrune, readCachePolicy, resolveCacheLayout, resolveSharedCacheIdentity, resolveSharedCacheRoot } from "./cache-policy.mjs";
 import { createTargetBridge } from "./target-bridge.mjs";
 import { assertNsisInPlaceUpgradeContract } from "./nsis-upgrade-contract.mjs";
+import { buildPathPrefix, collectPreflight, formatPreflight, preflightFailures } from "./preflight.mjs";
+
+/** Assemble preflight inputs from the app's own files (mirrors release.mjs). */
+function buildPreflight({ config, appRoot, repoRoot, platform }) {
+  let version;
+  try {
+    version = JSON.parse(readFileSync(path.join(appRoot, "package.json"), "utf8")).version;
+  } catch {
+    version = undefined;
+  }
+  return collectPreflight({
+    platform,
+    appRoot,
+    repoRoot,
+    app: config.app,
+    // The version check is the doctor's job: by the time `build` runs, seal
+    // collision is already enforced downstream, and duplicating it here would
+    // reject a legitimate resume of an in-flight build.
+    version: undefined,
+    cargoLockPaths: [
+      path.join(appRoot, "src-tauri", "Cargo.lock"),
+      path.join(appRoot, "Cargo.lock"),
+    ],
+  });
+}
 
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const WORKER = path.join(TOOL_ROOT, "release.mjs");
@@ -98,9 +123,28 @@ try {
     ? resolveCacheLayout({ cacheRoot: sharedCacheRoot, platform, architecture: cacheIdentity.architecture, app: config.app, fingerprint: cacheKey, kind: "release" })
     : undefined;
   if (cacheMode === "shared") assertSccacheVersion(toolVersions.sccache);
+
+  // Preflight BEFORE any compile. These preconditions used to be discovered one
+  // per build cycle, minutes deep, with errors that named a symptom instead of a
+  // cause. Blocking problems stop here, in seconds, naming the fix.
+  const preflight = buildPreflight({ config, appRoot, repoRoot: layout.repoRoot, platform });
+  const preflightBlockers = preflightFailures(preflight);
+  if (preflightBlockers.length > 0) {
+    fail(`preflight found ${preflightBlockers.length} blocking problem(s):\n${formatPreflight(preflightBlockers)}`);
+  }
+  for (const check of preflight) {
+    if (check.status !== "ok") console.error(`[right-release] preflight ${check.name}: ${check.detail}`);
+  }
+
+  // A tool being INSTALLED is not the same as it being the one PATH picks. The
+  // vendored-OpenSSL build shells out to `perl`, and under Git Bash/MSYS that
+  // resolves to MSYS Perl, which cannot configure OpenSSL. Put the real Windows
+  // Perl first so the build behaves the same from any shell.
+  const pathPrefix = buildPathPrefix({ platform });
   const env = {
     ...process.env,
     ...releaseEnvironment({ root: vaultRoot, cacheRoot: sharedCacheRoot, platform, architecture: cacheIdentity.architecture, app: config.app, cacheKey, kind: "release", appRoot, mode: cacheMode }),
+    ...(pathPrefix ? { PATH: `${pathPrefix}${path.delimiter}${process.env.PATH ?? ""}` } : {}),
     RIGHT_RELEASE_REPO_ROOT: layout.repoRoot,
     RIGHT_RELEASE_APP_ROOT: layout.appRoot,
   };
@@ -129,7 +173,14 @@ try {
     createdAt: new Date().toISOString(),
   };
   const targetLink = path.join(appRoot, "src-tauri", "target");
-  const targetBridge = createTargetBridge({ link: targetLink, target: env.CARGO_TARGET_DIR });
+  // ownedRoot is the per-app cache parent holding every fingerprint dir, so a
+  // link left by an earlier fingerprint is recognised as ours and repointed
+  // instead of hard-stopping the build.
+  const targetBridge = createTargetBridge({
+    link: targetLink,
+    target: env.CARGO_TARGET_DIR,
+    ownedRoot: path.dirname(env.CARGO_TARGET_DIR),
+  });
 
   const result = await targetBridge.run(async () => runBuildStateMachine({
     root: repoRoot,

package/build-release.test.mjs

@@ -45,7 +45,11 @@ test("dirty release config is rejected before the config module is imported", ()
 });
 
 test("shared Cache V2 target bridge is owned by a finally-cleaned lifecycle", () => {
-  assert.match(source, /createTargetBridge\(\{ link: targetLink, target: env\.CARGO_TARGET_DIR \}\)/);
+  assert.match(source, /createTargetBridge\(\{\s*link: targetLink,\s*target: env\.CARGO_TARGET_DIR,/);
+  // ownedRoot must stay wired: without it the bridge refuses every link left by
+  // an earlier fingerprint, so any Cargo.lock or version bump hard-stops the
+  // next build until someone deletes the link by hand.
+  assert.match(source, /ownedRoot: path\.dirname\(env\.CARGO_TARGET_DIR\)/);
   assert.match(source, /targetBridge\.run\(.*runBuildStateMachine/s);
   assert.match(source, /if \(cacheMode === "shared"\) targetBridge\.ensure\(\)/);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/release",
-  "version": "0.2.45",
+  "version": "0.2.47",
   "description": "Portable Right Suite release CLI/SDK: signed installers, updater artifacts, patch/update routing, hardening, R2 publish, and RightApps registration.",
   "type": "module",
   "bin": {

package/preflight.mjs

@@ -0,0 +1,278 @@
+// Release preflight — verify THIS MACHINE can actually complete a build, before
+// the expensive work starts.
+//
+// Why this file exists: every one of these preconditions used to be discovered
+// by failing at it, one per build cycle, deep inside a multi-minute compile,
+// usually with an error that names a symptom rather than the cause. The
+// knowledge then lived in a commit message, a doc, or an agent's memory — which
+// only helps whoever happens to read it. An executable check helps everyone,
+// deterministically, in about a second.
+//
+// Rules for anything added here:
+//  - It must be a precondition that can FAIL A BUILD, and it must be checkable
+//    cheaply. No network calls, no compiles.
+//  - It must name the actual cause and the actual fix, not the symptom.
+//  - It must not cry wolf. A check that warns on healthy machines gets ignored,
+//    and then so does every other check. (Concrete example of what NOT to add:
+//    signing-certificate expiry. Azure Trusted Signing mints short-lived ~3-day
+//    certs on purpose and timestamps the signature, so "expires in 2 days" is
+//    the healthy state, not a problem.)
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+export const PREFLIGHT_OK = "ok";
+export const PREFLIGHT_WARN = "warn";
+export const PREFLIGHT_FAIL = "fail";
+
+function ok(name, detail) {
+  return { name, status: PREFLIGHT_OK, detail };
+}
+function warn(name, detail, fix) {
+  return { name, status: PREFLIGHT_WARN, detail, fix };
+}
+function fail(name, detail, fix) {
+  return { name, status: PREFLIGHT_FAIL, detail, fix };
+}
+
+/**
+ * Windows SDK tools are versioned directories; pinning one version is why builds
+ * broke on machines that had a different SDK installed. Find the newest by
+ * NUMERIC segment order — string sort puts 10.0.9 above 10.0.26100.
+ */
+export function findWindowsSdkTool(
+  tool,
+  { sdkRoot = "C:\\Program Files (x86)\\Windows Kits\\10\\bin", arch = "x64", readdir = readdirSync, exists = existsSync } = {},
+) {
+  if (!exists(sdkRoot)) return null;
+  let entries;
+  try {
+    entries = readdir(sdkRoot);
+  } catch {
+    return null;
+  }
+  const candidates = entries
+    .filter((entry) => /^10\.\d+(\.\d+)*$/.test(entry))
+    .map((entry) => ({
+      version: entry,
+      segments: entry.split(".").map((part) => Number(part) || 0),
+      toolPath: path.join(sdkRoot, entry, arch, tool),
+    }))
+    .filter((entry) => exists(entry.toolPath));
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => {
+    const length = Math.max(a.segments.length, b.segments.length);
+    for (let index = 0; index < length; index += 1) {
+      const diff = (b.segments[index] ?? 0) - (a.segments[index] ?? 0);
+      if (diff !== 0) return diff;
+    }
+    return 0;
+  });
+  return candidates[0];
+}
+
+/**
+ * OpenSSL's ./Configure is a Perl script that needs a real Windows Perl. When a
+ * build is launched from Git Bash/MSYS, PATH resolves `perl` to MSYS Perl first,
+ * which lacks Locale::Maketext::Simple and dies with an error that reads like an
+ * OpenSSL problem. Strawberry Perl is usually installed and simply shadowed —
+ * nothing is missing, it just is not the one that wins.
+ */
+export function resolveWindowsPerl({
+  env = process.env,
+  exists = existsSync,
+  candidates = ["C:\\Strawberry\\perl\\bin\\perl.exe", "C:\\Perl64\\bin\\perl.exe"],
+} = {}) {
+  const explicit = [env.OPENSSL_SRC_PERL, env.PERL].filter(Boolean);
+  for (const candidate of [...explicit, ...candidates]) {
+    if (exists(candidate)) return { perlPath: candidate, dir: path.dirname(candidate) };
+  }
+  return null;
+}
+
+/** True when the dependency graph vendors OpenSSL, i.e. a Perl build is required. */
+export function graphVendorsOpenssl(lockPath, { read = readFileSync, exists = existsSync } = {}) {
+  if (!exists(lockPath)) return false;
+  try {
+    return /name = "openssl-src"/.test(read(lockPath, "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * right-release refuses to rebuild an already-sealed version, so a stale sealed
+ * record turns into a hard stop at build start. Report the next free version
+ * instead of just saying "sealed".
+ */
+export function nextFreeVersion(sealedDir, app, currentVersion, { readdir = readdirSync, exists = existsSync } = {}) {
+  if (!exists(sealedDir)) return { taken: [], collision: false, suggestion: currentVersion };
+  let entries = [];
+  try {
+    entries = readdir(sealedDir);
+  } catch {
+    return { taken: [], collision: false, suggestion: currentVersion };
+  }
+  const prefix = `${app}-`;
+  const taken = new Set();
+  for (const entry of entries) {
+    if (!entry.startsWith(prefix)) continue;
+    const version = entry.slice(prefix.length).split("-")[0];
+    if (/^\d+\.\d+\.\d+$/.test(version)) taken.add(version);
+  }
+  if (!taken.has(currentVersion)) {
+    return { taken: [...taken], collision: false, suggestion: currentVersion };
+  }
+  const [major, minor] = currentVersion.split(".").map(Number);
+  let patch = Number(currentVersion.split(".")[2]);
+  let suggestion = currentVersion;
+  do {
+    patch += 1;
+    suggestion = `${major}.${minor}.${patch}`;
+  } while (taken.has(suggestion));
+  return { taken: [...taken], collision: true, suggestion };
+}
+
+function freeDiskGb(targetPath) {
+  if (process.platform === "win32") {
+    const drive = path.parse(path.resolve(targetPath)).root.replace(/\\$/, "");
+    const result = spawnSync(
+      "powershell",
+      ["-NoProfile", "-Command", `(Get-PSDrive -Name '${drive.replace(":", "")}').Free`],
+      { encoding: "utf8", windowsHide: true },
+    );
+    const bytes = Number(String(result.stdout ?? "").trim());
+    return Number.isFinite(bytes) && bytes > 0 ? bytes / 1024 ** 3 : null;
+  }
+  const result = spawnSync("df", ["-k", targetPath], { encoding: "utf8" });
+  const line = String(result.stdout ?? "").trim().split("\n").at(-1) ?? "";
+  const available = Number(line.split(/\s+/)[3]);
+  return Number.isFinite(available) ? (available * 1024) / 1024 ** 3 : null;
+}
+
+function commandVersion(command, args = ["--version"]) {
+  const result = spawnSync(command, args, { encoding: "utf8", windowsHide: true, shell: process.platform === "win32" });
+  if (result.status !== 0) return null;
+  return String(result.stdout ?? result.stderr ?? "").trim().split("\n")[0] || null;
+}
+
+/**
+ * Run every precondition check. Pure-ish: all filesystem/process access is via
+ * the injected helpers so this is testable without a real toolchain.
+ */
+export function collectPreflight({
+  platform,
+  appRoot,
+  repoRoot,
+  app,
+  version,
+  cargoLockPaths = [],
+  minFreeGb = 25,
+  env = process.env,
+} = {}) {
+  const checks = [];
+  const windows = platform === "win" || platform === "win32";
+
+  if (version && app && repoRoot) {
+    const sealedDir = path.join(repoRoot, ".right-release", "sealed");
+    const sealed = nextFreeVersion(sealedDir, app, version);
+    checks.push(
+      sealed.collision
+        ? fail(
+            "version",
+            `${app} ${version} is already sealed at ${sealedDir}; right-release will refuse to rebuild it`,
+            `bump to ${sealed.suggestion} in package.json, src-tauri/tauri.conf.json and src-tauri/Cargo.toml, then re-run the legal notices generator`,
+          )
+        : ok("version", `${version} is free to build`),
+    );
+  }
+
+  if (windows) {
+    const makeappx = findWindowsSdkTool("makeappx.exe");
+    checks.push(
+      makeappx
+        ? ok("windows-sdk", `makeappx.exe from SDK ${makeappx.version}`)
+        : fail(
+            "windows-sdk",
+            "no makeappx.exe found under any installed Windows 10/11 SDK",
+            "install the Windows SDK, or set MAKEAPPX_PATH to an explicit makeappx.exe",
+          ),
+    );
+
+    const signtool = findWindowsSdkTool("signtool.exe");
+    checks.push(
+      signtool
+        ? ok("signtool", `signtool.exe from SDK ${signtool.version}`)
+        : warn(
+            "signtool",
+            "no signtool.exe found under any installed Windows SDK",
+            "install the Windows SDK Build Tools, or set AZURE_SIGNTOOL_PATH",
+          ),
+    );
+
+    const vendorsOpenssl = cargoLockPaths.some((lockPath) => graphVendorsOpenssl(lockPath));
+    if (vendorsOpenssl) {
+      const perl = resolveWindowsPerl({ env });
+      checks.push(
+        perl
+          ? ok("perl", `${perl.perlPath} (prepended to PATH for the vendored OpenSSL build)`)
+          : fail(
+              "perl",
+              "the dependency graph vendors OpenSSL, whose ./Configure needs a real Windows Perl, and none was found",
+              "install Strawberry Perl (https://strawberryperl.com), or set OPENSSL_SRC_PERL to a Windows perl.exe. MSYS/Git-Bash perl will NOT work: it lacks Locale::Maketext::Simple",
+            ),
+      );
+    }
+  }
+
+  const sccache = commandVersion("sccache");
+  checks.push(
+    sccache
+      ? ok("sccache", sccache)
+      : warn("sccache", "sccache not found; the shared cache will compile without a compiler cache", "cargo install sccache --locked"),
+  );
+
+  if (appRoot) {
+    const free = freeDiskGb(appRoot);
+    if (free === null) {
+      checks.push(warn("disk", "could not determine free disk space", null));
+    } else {
+      checks.push(
+        free < minFreeGb
+          ? fail(
+              "disk",
+              `${free.toFixed(1)}GB free on the build drive, below the ${minFreeGb}GB floor`,
+              "prune Rust target directories, or run right-release cache prune",
+            )
+          : ok("disk", `${free.toFixed(1)}GB free`),
+      );
+    }
+  }
+
+  return checks;
+}
+
+export function formatPreflight(checks) {
+  const symbol = { [PREFLIGHT_OK]: "ok  ", [PREFLIGHT_WARN]: "WARN", [PREFLIGHT_FAIL]: "FAIL" };
+  const lines = checks.map((check) => {
+    const head = `  [${symbol[check.status]}] ${check.name}: ${check.detail}`;
+    return check.fix && check.status !== PREFLIGHT_OK ? `${head}\n         fix: ${check.fix}` : head;
+  });
+  return lines.join("\n");
+}
+
+export function preflightFailures(checks) {
+  return checks.filter((check) => check.status === PREFLIGHT_FAIL);
+}
+
+/**
+ * PATH additions the build must inherit. Today this is only Windows Perl, but it
+ * is the right home for any "the tool is installed and simply not the one that
+ * wins" fix — those are invisible to a plain existence check.
+ */
+export function buildPathPrefix({ platform, env = process.env } = {}) {
+  if (platform !== "win" && platform !== "win32") return null;
+  const perl = resolveWindowsPerl({ env });
+  return perl ? perl.dir : null;
+}

package/preflight.test.mjs

@@ -0,0 +1,123 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import path from "node:path";
+
+import {
+  buildPathPrefix,
+  collectPreflight,
+  findWindowsSdkTool,
+  formatPreflight,
+  graphVendorsOpenssl,
+  nextFreeVersion,
+  preflightFailures,
+  resolveWindowsPerl,
+  PREFLIGHT_FAIL,
+} from "./preflight.mjs";
+
+test("windows SDK lookup orders versions numerically, not as strings", () => {
+  const root = "C:\\Kits";
+  const present = new Set([
+    root,
+    path.join(root, "10.0.9.0", "x64", "makeappx.exe"),
+    path.join(root, "10.0.26100.0", "x64", "makeappx.exe"),
+  ]);
+  const found = findWindowsSdkTool("makeappx.exe", {
+    sdkRoot: root,
+    readdir: () => ["10.0.9.0", "10.0.26100.0"],
+    exists: (candidate) => present.has(candidate),
+  });
+  // String sort would pick 10.0.9.0 — that is the bug this guards.
+  assert.equal(found.version, "10.0.26100.0");
+});
+
+test("windows SDK lookup returns null when the tool is absent from every SDK", () => {
+  const found = findWindowsSdkTool("makeappx.exe", {
+    sdkRoot: "C:\\Kits",
+    readdir: () => ["10.0.26100.0"],
+    exists: (candidate) => candidate === "C:\\Kits",
+  });
+  assert.equal(found, null);
+});
+
+test("explicit OPENSSL_SRC_PERL wins over the default Strawberry location", () => {
+  const resolved = resolveWindowsPerl({
+    env: { OPENSSL_SRC_PERL: "D:\\perl\\bin\\perl.exe" },
+    exists: () => true,
+  });
+  assert.equal(resolved.perlPath, "D:\\perl\\bin\\perl.exe");
+  assert.equal(resolved.dir, "D:\\perl\\bin");
+});
+
+test("perl resolution reports nothing when no windows perl exists", () => {
+  assert.equal(resolveWindowsPerl({ env: {}, exists: () => false }), null);
+});
+
+test("vendored openssl is detected from the cargo lock", () => {
+  assert.equal(
+    graphVendorsOpenssl("Cargo.lock", { exists: () => true, read: () => 'name = "openssl-src"\n' }),
+    true,
+  );
+  assert.equal(
+    graphVendorsOpenssl("Cargo.lock", { exists: () => true, read: () => 'name = "rustls"\n' }),
+    false,
+  );
+  assert.equal(graphVendorsOpenssl("missing.lock", { exists: () => false }), false);
+});
+
+test("a sealed version collision suggests the next free patch, skipping taken ones", () => {
+  const result = nextFreeVersion("/sealed", "heardright", "0.1.33", {
+    exists: () => true,
+    readdir: () => [
+      "heardright-0.1.33-6f2f5e64",
+      "heardright-0.1.34-839ad700",
+      "heardright-0.1.36-f7035acc",
+      "viewright-0.1.35-aaaaaaaa",
+    ],
+  });
+  assert.equal(result.collision, true);
+  // 0.1.34 is taken, 0.1.35 is free — and viewright's record must not be counted.
+  assert.equal(result.suggestion, "0.1.35");
+});
+
+test("an unsealed version is reported as free", () => {
+  const result = nextFreeVersion("/sealed", "heardright", "0.1.37", {
+    exists: () => true,
+    readdir: () => ["heardright-0.1.33-6f2f5e64"],
+  });
+  assert.equal(result.collision, false);
+  assert.equal(result.suggestion, "0.1.37");
+});
+
+test("a sealed version collision is a hard failure carrying a concrete fix", () => {
+  const checks = collectPreflight({
+    platform: "linux",
+    repoRoot: process.cwd(),
+    app: "nothing-is-sealed-here",
+    version: "9.9.9",
+  });
+  // No sealed dir for this app, so the version check must pass rather than throw.
+  const version = checks.find((check) => check.name === "version");
+  assert.equal(version.status, "ok");
+});
+
+test("formatting surfaces the fix line only for non-ok checks", () => {
+  const text = formatPreflight([
+    { name: "a", status: "ok", detail: "fine", fix: "unused" },
+    { name: "b", status: PREFLIGHT_FAIL, detail: "broken", fix: "do the thing" },
+  ]);
+  assert.match(text, /\[ok {2}\] a: fine/);
+  assert.doesNotMatch(text, /fix: unused/);
+  assert.match(text, /fix: do the thing/);
+});
+
+test("failures are filtered from warnings so warnings never block a build", () => {
+  const failures = preflightFailures([
+    { name: "a", status: "warn", detail: "" },
+    { name: "b", status: PREFLIGHT_FAIL, detail: "" },
+  ]);
+  assert.deepEqual(failures.map((check) => check.name), ["b"]);
+});
+
+test("build PATH prefix is windows-only", () => {
+  assert.equal(buildPathPrefix({ platform: "mac" }), null);
+});

package/release.mjs

@@ -8,6 +8,7 @@ import { validateRightKitCargoContract } from "./cargo-contract.mjs";
 import { assertQaBackdoorContract } from "./qa-contract.mjs";
 import { assertLegalReleaseContract } from "./legal-contract.mjs";
 import { assertPrimaryReleaseCheckout, dirtyBuildInputs, resolveReleaseBuildInputs } from "./release-invocation.mjs";
+import { collectPreflight, formatPreflight, preflightFailures } from "./preflight.mjs";
 
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const HARDENING_SCAN = path.resolve(TOOL_ROOT, "hardeningscan.mjs");
@@ -98,6 +99,34 @@ if (opts.platform === "win" && !target.sign?.files?.length) {
   fail(`${config.app ?? "app"} win must declare sign.files for the signed release pipeline`);
 }
 if (opts.upload && target.publishBlocked) fail(`${config.app ?? "app"} ${opts.platform} publish blocked: ${target.publishBlocked}`);
+/**
+ * Assemble preflight inputs from the app's own files. Kept here (not in
+ * preflight.mjs) so the check module stays free of release.mjs's config shape.
+ */
+function releasePreflight({ config, root, repoRoot, platform }) {
+  let version;
+  try {
+    version = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")).version;
+  } catch {
+    version = undefined;
+  }
+  // Every Cargo.lock the build compiles from; a vendored-OpenSSL edge in any of
+  // them means the build needs a real Windows Perl.
+  const cargoLockPaths = [
+    path.join(root, "src-tauri", "Cargo.lock"),
+    path.join(root, "Cargo.lock"),
+    ...(config.cargoLocks ?? []).map((entry) => path.resolve(root, entry)),
+  ];
+  return collectPreflight({
+    platform,
+    appRoot: root,
+    repoRoot,
+    app: config.app,
+    version,
+    cargoLockPaths,
+  });
+}
+
 if (opts.doctor) {
   const { buildInputs } = resolveReleaseBuildInputs({
     repoRoot: doctorInvocation.repoRoot,
@@ -126,6 +155,16 @@ if (opts.doctor) {
   }
   if (target.sign?.files?.length) console.log(`sign: ${target.sign.files.join(", ")}`);
   if (target.publishBlocked) console.log(`publishBlocked: ${target.publishBlocked}`);
+
+  // Config above, MACHINE below. Printing config never told anyone whether this
+  // box could finish a build; these checks do.
+  const checks = releasePreflight({ config, root, repoRoot: doctorInvocation.repoRoot, platform: opts.platform });
+  console.log("preflight:");
+  console.log(formatPreflight(checks));
+  const failures = preflightFailures(checks);
+  if (failures.length > 0) {
+    fail(`preflight found ${failures.length} blocking problem(s); the build would fail on these`);
+  }
   process.exit(0);
 }
 

package/release.test.mjs

@@ -238,7 +238,10 @@ test("doctor rejects a selected target with missing or empty buildInputs.include
 test("doctor passes a clean selected target", () => {
   const result = runDoctor(fixture());
   assert.equal(result.status, 0, result.stderr);
-  assert.match(result.stdout, /right-release 0\.2\.45/);
+  // Derived from the version manifest, not hardcoded: a literal here has to be
+  // hand-edited on every bump and fails the suite when someone forgets.
+  const expected = versions.stagedNpm?.["@rightkit/release"] ?? versions.npm["@rightkit/release"];
+  assert.match(result.stdout, new RegExp(`right-release ${expected.replace(/\./g, "\\.")}`));
 });
 
 test("doctor permits unrelated dirt", () => {

package/right-suite-contract.test.mjs

@@ -432,7 +432,7 @@ test("every app platform requires effective non-empty build inputs", () => {
 test("RightKit exposes one current version manifest", () => {
   assert.equal(existsSync(versionsPath), true, "rightkit-versions.json must be the single current-version source");
   assert.match(versions.packageManager, /^pnpm@\d+\.\d+\.\d+$/);
-  assert.equal(versions.npm["@rightkit/release"], "0.2.45");
+  assert.equal(versions.npm["@rightkit/release"], "0.2.47");
   assert.equal(versions.npm["@rightkit/legal"], "0.2.0");
   assert.equal(versions.npm["@rightkit/license"], "0.1.5");
   assert.equal(versions.npm["@rightkit/logs"], "0.1.3");
@@ -444,11 +444,11 @@ test("RightKit exposes one current version manifest", () => {
     "@rightkit/license": "0.1.6",
   });
   assert.deepEqual(versions.legacyNpm, {
-    "@rightkit/release": ["0.2.22", "0.2.29", "0.2.30", "0.2.31", "0.2.41", "0.2.42", "0.2.43", "0.2.44"],
+    "@rightkit/release": ["0.2.22", "0.2.29", "0.2.30", "0.2.31", "0.2.41", "0.2.42", "0.2.43", "0.2.44", "0.2.45", "0.2.46"],
   });
   assert.ok(
     new Set([versions.npm["@rightkit/release"], ...versions.legacyNpm["@rightkit/release"]]).has("0.2.42"),
-    "previously published @rightkit/release versions must remain accepted during the 0.2.45 rollout",
+    "previously published @rightkit/release versions must remain accepted during the 0.2.46 rollout",
   );
   const licensePackage = JSON.parse(readFileSync(
     path.join(workspace, "tools/rightkit/packages/license/package.json"),

package/rightkit-versions.json

@@ -7,7 +7,7 @@
     "@rightkit/logs": "0.1.3",
     "@rightkit/platform-ui": "0.1.0",
     "@rightkit/qa": "0.1.0",
-    "@rightkit/release": "0.2.45",
+    "@rightkit/release": "0.2.47",
     "@rightkit/tauri": "0.1.0",
     "@rightkit/updates": "0.2.3"
   },
@@ -17,7 +17,7 @@
     "@rightkit/license": "0.1.6"
   },
   "legacyNpm": {
-    "@rightkit/release": ["0.2.22", "0.2.29", "0.2.30", "0.2.31", "0.2.41", "0.2.42", "0.2.43", "0.2.44"]
+    "@rightkit/release": ["0.2.22", "0.2.29", "0.2.30", "0.2.31", "0.2.41", "0.2.42", "0.2.43", "0.2.44", "0.2.45", "0.2.46"]
   },
   "cargo": {
     "rightkit-license": "0.1.2",

package/target-bridge.mjs

@@ -1,9 +1,19 @@
 import { lstatSync, mkdirSync, realpathSync, symlinkSync, unlinkSync } from "node:fs";
 import path from "node:path";
 
+/**
+ * @param ownedRoot Directory this bridge owns (the app's per-fingerprint cache
+ *   parent). An existing link resolving INSIDE it was created by this system for
+ *   an earlier fingerprint, so it is safe to relink: a symlink is a pointer, not
+ *   data, and the directory it pointed at is untouched. Without this, every
+ *   fingerprint change — i.e. every Cargo.lock or version bump — left a stale
+ *   link that hard-stopped the next build until someone deleted it by hand.
+ *   Omit it to keep the strict refuse-everything behavior.
+ */
 export function createTargetBridge({
   link,
   target,
+  ownedRoot,
   platform = process.platform,
   lstat = lstatSync,
   mkdir = mkdirSync,
@@ -29,9 +39,40 @@ export function createTargetBridge({
         ownership = entryIdentity(entry);
         created = true;
       } else {
-        if (!entry.isSymbolicLink()) throw new Error(`primary checkout target is not a symbolic link; refusing to replace it: ${link}`);
-        if (!sameRealPath(link, target, realpath, platform)) {
-          throw new Error(`primary checkout target is not the owned shared cache target; refusing to replace it: ${link}`);
+        if (!entry.isSymbolicLink()) {
+          throw new Error(
+            `primary checkout target is not a symbolic link; refusing to replace it: ${link}\n` +
+              `  It is a real directory holding build output. Delete it yourself if that output is disposable, then re-run.`,
+          );
+        }
+        // A dangling link (its cache entry was pruned) makes realpath throw, so
+        // this comparison must tolerate ENOENT rather than crash before the
+        // reclaim path below gets a chance to handle exactly that case.
+        let pointsAtTarget = false;
+        try {
+          pointsAtTarget = sameRealPath(link, target, realpath, platform);
+        } catch (error) {
+          if (error?.code !== "ENOENT") throw error;
+        }
+        if (!pointsAtTarget) {
+          // Stale link from an earlier fingerprint, or one whose cache entry a
+          // prune already removed. Both are ours to repoint.
+          if (isReclaimableLink(link, ownedRoot, realpath, platform)) {
+            unlink(link);
+            symlink(target, link, platform === "win32" ? "junction" : "dir");
+            entry = lstat(link);
+            if (!sameRealPath(link, target, realpath, platform)) {
+              throw new Error(`RightKit target bridge did not repoint to the owned shared cache target: ${link}`);
+            }
+            ownership = entryIdentity(entry);
+            created = true;
+          } else {
+            throw new Error(
+              `primary checkout target is not the owned shared cache target; refusing to replace it: ${link}\n` +
+                `  It is a symlink pointing outside this app's release cache, so it was not created by RightKit.\n` +
+                `  Repoint or remove it yourself, then re-run.`,
+            );
+          }
         }
       }
       acquired = true;
@@ -110,6 +151,29 @@ function readEntry(file, lstat) {
   }
 }
 
+/**
+ * True when `link` is a symlink RightKit may repoint: it resolves inside
+ * `ownedRoot`, or it dangles entirely (its cache entry was pruned). A link
+ * resolving anywhere else is someone else's and is never touched.
+ */
+function isReclaimableLink(link, ownedRoot, realpath, platform) {
+  if (!ownedRoot) return false;
+  const canonical = (value) => {
+    const resolved = path.normalize(value);
+    return platform === "win32" ? resolved.toLowerCase() : resolved;
+  };
+  let resolved;
+  try {
+    resolved = canonical(realpath(link));
+  } catch (error) {
+    // Dangling link: the entry it pointed at is gone, so nothing can be lost.
+    if (error?.code === "ENOENT") return true;
+    throw error;
+  }
+  const root = canonical(ownedRoot);
+  return resolved === root || resolved.startsWith(root.endsWith(path.sep) ? root : `${root}${path.sep}`);
+}
+
 function sameRealPath(left, right, realpath, platform) {
   const canonical = (value) => {
     const resolved = path.normalize(realpath(value));

package/target-bridge.test.mjs

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -153,3 +153,54 @@ test("cleanup is idempotent and reports process errors without masking a build f
   assert.equal(lstatSync(fx.link).isSymbolicLink(), true);
   unlinkSync(fx.link);
 });
+
+test("a stale link from an earlier fingerprint is repointed, not a hard stop", () => {
+  const dir = mkdtempSync(path.join(os.tmpdir(), "bridge-stale-"));
+  const ownedRoot = path.join(dir, "cache", "heardright");
+  const oldTarget = path.join(ownedRoot, "aaaaaaaa");
+  const newTarget = path.join(ownedRoot, "bbbbbbbb");
+  mkdirSync(oldTarget, { recursive: true });
+  const link = path.join(dir, "target");
+  symlinkSync(oldTarget, link, "junction");
+
+  const bridge = createTargetBridge({ link, target: newTarget, ownedRoot });
+  const result = bridge.ensure();
+
+  assert.equal(result.created, true);
+  assert.equal(realpathSync(link), realpathSync(newTarget));
+  // The directory the stale link pointed at must survive: it is cache, and the
+  // link was only ever a pointer to it.
+  assert.equal(existsSync(oldTarget), true);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("a link pointing outside the owned root is still refused", () => {
+  const dir = mkdtempSync(path.join(os.tmpdir(), "bridge-foreign-"));
+  const ownedRoot = path.join(dir, "cache", "heardright");
+  const foreign = path.join(dir, "somewhere-else");
+  const newTarget = path.join(ownedRoot, "bbbbbbbb");
+  mkdirSync(foreign, { recursive: true });
+  const link = path.join(dir, "target");
+  symlinkSync(foreign, link, "junction");
+
+  const bridge = createTargetBridge({ link, target: newTarget, ownedRoot });
+  assert.throws(() => bridge.ensure(), /refusing to replace it/);
+  assert.equal(realpathSync(link), realpathSync(foreign));
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("a dangling link whose cache entry was pruned is reclaimed", () => {
+  const dir = mkdtempSync(path.join(os.tmpdir(), "bridge-dangling-"));
+  const ownedRoot = path.join(dir, "cache", "heardright");
+  const pruned = path.join(ownedRoot, "aaaaaaaa");
+  const newTarget = path.join(ownedRoot, "bbbbbbbb");
+  mkdirSync(pruned, { recursive: true });
+  const link = path.join(dir, "target");
+  symlinkSync(pruned, link, "junction");
+  rmSync(pruned, { recursive: true, force: true });
+
+  const bridge = createTargetBridge({ link, target: newTarget, ownedRoot });
+  assert.equal(bridge.ensure().created, true);
+  assert.equal(realpathSync(link), realpathSync(newTarget));
+  rmSync(dir, { recursive: true, force: true });
+});