@rightkit/release 0.2.37 → 0.2.39

package/build-invocation-contract.test.mjs

@@ -0,0 +1,96 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { assertPrimaryReleaseCheckout, dirtyBuildInputs } from "./release-invocation.mjs";
+
+function git(cwd, ...args) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function makeRepo() {
+  const root = mkdtempSync(path.join(os.tmpdir(), "right-release-invocation-"));
+  git(root, "init", "--initial-branch", "main");
+  git(root, "config", "user.email", "release-test@example.com");
+  git(root, "config", "user.name", "Release Test");
+  mkdirSync(path.join(root, "src"));
+  mkdirSync(path.join(root, "tests"));
+  mkdirSync(path.join(root, "docs"));
+  writeFileSync(path.join(root, "package.json"), "{}\n");
+  writeFileSync(path.join(root, "src", "app.js"), "export const app = true;\n");
+  writeFileSync(path.join(root, "tests", "app.test.js"), "// test\n");
+  writeFileSync(path.join(root, "docs", "notes.md"), "notes\n");
+  git(root, "add", ".");
+  git(root, "commit", "-m", "initial");
+  return root;
+}
+
+const buildInputs = {
+  include: ["package.json", "src/**"],
+  exclude: ["**/*.test.*", "**/tests/**"],
+  json: {
+    "package.json": [["dependencies"], ["scripts", "build"]],
+  },
+};
+
+test("rejects release invocation from a linked Git worktree", () => {
+  const primary = makeRepo();
+  const linked = path.join(path.dirname(primary), `${path.basename(primary)}-linked`);
+  git(primary, "worktree", "add", "--detach", linked);
+
+  assert.throws(
+    () => assertPrimaryReleaseCheckout(linked),
+    /must be invoked from the primary Git worktree/i,
+  );
+});
+
+test("allows release invocation from the primary Git checkout", () => {
+  const primary = makeRepo();
+
+  assert.doesNotThrow(() => assertPrimaryReleaseCheckout(primary));
+});
+
+test("reports dirty files that can change the packaged app", () => {
+  const primary = makeRepo();
+  writeFileSync(path.join(primary, "src", "app.js"), "export const app = false;\n");
+  writeFileSync(path.join(primary, "src", "new-runtime.js"), "export {};\n");
+
+  assert.deepEqual(dirtyBuildInputs(primary, buildInputs), [
+    "src/app.js",
+    "src/new-runtime.js",
+  ]);
+});
+
+test("ignores dirty files outside the packaged app input set", () => {
+  const primary = makeRepo();
+  writeFileSync(path.join(primary, "docs", "notes.md"), "changed notes\n");
+  writeFileSync(path.join(primary, "tests", "app.test.js"), "// changed test\n");
+  writeFileSync(path.join(primary, "scratch.txt"), "evaluation output\n");
+
+  assert.deepEqual(dirtyBuildInputs(primary, buildInputs), []);
+});
+
+test("checks only build-relevant fields in mixed-purpose JSON manifests", () => {
+  const primary = makeRepo();
+  writeFileSync(path.join(primary, "package.json"), `${JSON.stringify({ scripts: { bakeoff: "node eval.mjs" } })}\n`);
+  assert.deepEqual(dirtyBuildInputs(primary, buildInputs), []);
+
+  writeFileSync(path.join(primary, "package.json"), `${JSON.stringify({ dependencies: { tauri: "2.0.0" } })}\n`);
+  assert.deepEqual(dirtyBuildInputs(primary, buildInputs), ["package.json"]);
+});
+
+test("does not report a locally dirty file whose bytes already equal the release commit", () => {
+  const primary = makeRepo();
+  const localHead = git(primary, "rev-parse", "HEAD");
+  writeFileSync(path.join(primary, "src", "app.js"), "export const app = false;\n");
+  git(primary, "add", "src/app.js");
+  git(primary, "commit", "-m", "release change");
+  const releaseCommit = git(primary, "rev-parse", "HEAD");
+  git(primary, "checkout", localHead);
+  writeFileSync(path.join(primary, "src", "app.js"), "export const app = false;\n");
+
+  assert.deepEqual(dirtyBuildInputs(primary, buildInputs, releaseCommit), []);
+});

package/build-release.mjs

@@ -20,7 +20,9 @@ import {
 import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { cacheFingerprint, commandOutputPortable, releaseEnvironment, resolveReleaseLayout, runBuildStateMachine, watchProgress } from "./release-state.mjs";
+import { assertPrimaryReleaseCheckout, dirtyBuildInputs } from "./release-invocation.mjs";
+import { commandOutputPortable, releaseEnvironment, resolveReleaseLayout, runBuildStateMachine, verifySealedRelease, watchProgress } from "./release-state.mjs";
+import { acquireCacheLease, acquireSuiteBuildSlot, applyCachePrune, assertWriteVolumeFloors, inspectCache, inspectWriteVolumes, markCacheEntrySuccessful, planCachePrune, readCachePolicy, resolveCacheLayout, resolveSharedCacheIdentity, resolveSharedCacheRoot } from "./cache-policy.mjs";
 
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const WORKER = path.join(TOOL_ROOT, "release.mjs");
@@ -42,22 +44,27 @@ if (platform !== "win" && platform !== "mac") fail("--platform must be win or ma
 
 const invocationRoot = path.dirname(path.resolve(configName));
 const repoRoot = git(invocationRoot, ["rev-parse", "--show-toplevel"]);
+assertPrimaryReleaseCheckout(repoRoot);
 const relativeConfig = path.relative(repoRoot, path.resolve(configName)).replaceAll("\\", "/");
 if (relativeConfig.startsWith("../")) fail("release config must live inside the Git repository");
 const vaultRoot = resolveReleaseLayout({ repoRoot, configPath: path.resolve(configName) }).vaultRoot;
 mkdirSync(path.join(vaultRoot, "locks"), { recursive: true });
 const lock = acquireLock(path.join(vaultRoot, "locks", `${platform}.lock.json`));
 let child = null;
+let suiteSlot;
+let cacheLease;
+let interrupted;
 
 for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
   process.once(signal, () => {
     if (child?.pid) killTree(child.pid);
-    lock.release();
-    process.exit(signal === "SIGINT" ? 130 : 143);
+    interrupted = new Error(`release interrupted by ${signal}`);
+    process.exitCode = signal === "SIGINT" ? 130 : 143;
   });
 }
 
 try {
+  throwIfInterrupted();
   if (!dryRun) git(repoRoot, ["fetch", "origin", "main"]);
   const commit = git(repoRoot, ["rev-parse", dryRun ? "HEAD" : "origin/main"]);
   const shortCommit = commit.slice(0, 8);
@@ -80,24 +87,36 @@ try {
   }
   const target = config.targets?.[platform];
   if (!target?.package) fail(`${config.app} has no ${platform} package command`);
+  const dirtyInputs = dirtyBuildInputs(repoRoot, repoBuildInputs(repoRoot, invocationRoot, relativeConfig, target.buildInputs ?? config.buildInputs), commit);
+  if (dirtyInputs.length > 0) fail(`dirty files can change the packaged app; resolve them before release:\n${dirtyInputs.map((file) => `- ${file}`).join("\n")}`);
   const requiredInputs = inputPaths(appRoot, worktreeConfigPath, target);
   const toolVersions = collectToolVersions(config.packageManager ?? "pnpm");
   const inputHashes = hashInputs(requiredInputs);
   const cargoLock = requiredInputs.find((file) => /Cargo\.lock$/i.test(file));
   const cargoToml = requiredInputs.find((file) => /Cargo\.toml$/i.test(file));
-  const cacheKey = cacheFingerprint({
-    cargoLockSha256: cargoLock ? inputHashes[path.relative(worktree, cargoLock)] : "none",
-    rustc: toolVersions.rustc,
-    target: toolVersions.rustHost,
-    features: cargoToml ? sqlCipherFeatures(readFileSync(cargoToml, "utf8")) : [],
-  });
+  const cacheIdentity = resolveSharedCacheIdentity({ cargoLockPath: cargoLock, cargoTomlPath: cargoToml, rustcVerbose: toolVersions.rustc, targetTriple: target.cargoTarget ?? target.targetTriple ?? target.rustTarget ?? toolVersions.rustHost, profile: target.profile ?? "release" });
+  const cacheKey = cacheIdentity.fingerprint;
+  const cacheMode = process.env.RIGHT_RELEASE_CACHE_MODE ?? (platform === "mac" ? "shared" : "legacy");
+  if (cacheMode !== "legacy" && cacheMode !== "shared") fail("RIGHT_RELEASE_CACHE_MODE must be legacy or shared");
+  const sharedCacheRoot = cacheMode === "shared" ? resolveSharedCacheRoot({ platform, env: process.env }) : undefined;
+  const sharedLayout = cacheMode === "shared"
+    ? resolveCacheLayout({ cacheRoot: sharedCacheRoot, platform, architecture: cacheIdentity.architecture, app: config.app, fingerprint: cacheKey, kind: "release" })
+    : undefined;
+  if (cacheMode === "shared") assertSccacheVersion(toolVersions.sccache);
   const env = {
     ...process.env,
-    ...releaseEnvironment({ root: vaultRoot, platform, cacheKey, kind: "release" }),
+    ...releaseEnvironment({ root: vaultRoot, cacheRoot: sharedCacheRoot, platform, architecture: cacheIdentity.architecture, app: config.app, cacheKey, kind: "release", appRoot, mode: cacheMode }),
     RIGHT_RELEASE_REPO_ROOT: layout.repoRoot,
     RIGHT_RELEASE_APP_ROOT: layout.appRoot,
   };
-  if (!commandExists("sccache")) delete env.RUSTC_WRAPPER;
+  if (cacheMode === "legacy") delete env.RIGHT_RELEASE_CACHE_OWNER;
+  if (cacheMode === "shared" && env.RIGHT_RELEASE_CACHE_OWNER !== "rightkit-v2") fail("shared cache ownership token was not configured");
+  if (cacheMode === "legacy" && !commandExists("sccache")) delete env.RUSTC_WRAPPER;
+  if (cacheMode === "shared") {
+    suiteSlot = acquireSuiteBuildSlot({ layout: sharedLayout, pid: process.pid, argv: process.argv, waitMs: Number(process.env.BUILD_GUARD_WAIT_SECS ?? 900) * 1000 });
+    cacheLease = acquireCacheLease({ layout: sharedLayout, pid: process.pid, argv: process.argv });
+  }
+  throwIfInterrupted();
   const releaseId = `${config.app}-${config.version}-${shortCommit}`;
   const platformDir = platform === "win" ? "windows" : "mac";
   const buildRoot = path.join(vaultRoot, "build", config.app, config.version, shortCommit, platformDir);
@@ -124,7 +143,15 @@ try {
     requiredInputs,
     ops: {
       preflight: async () => {
-        assertDiskSpace(repoRoot, target.preflight?.minFreeGb ?? 20);
+        throwIfInterrupted();
+        if (cacheMode === "shared") {
+          const policy = readCachePolicy(process.env);
+          const snapshot = inspectCache({ cacheRoot: sharedCacheRoot });
+          const plan = planCachePrune({ snapshot, policy, protectedEntryIds: new Set([sharedLayout.id]) });
+          applyCachePrune({ plan, cacheRoot: sharedCacheRoot, dryRun: false });
+          const volumes = inspectWriteVolumes({ repoRoot, vaultRoot, cacheRoot: sharedCacheRoot });
+          assertWriteVolumeFloors({ volumes, policy, configuredRepoMinimumBytes: Math.max(Number(target.preflight?.minFreeGb ?? 25), 25) * 1024 ** 3 });
+        } else assertDiskSpace(repoRoot, target.preflight?.minFreeGb ?? 20);
         assertExecutables(["git", config.packageManager ?? "pnpm", "cargo", "rustc", ...(target.preflight?.executables ?? [])]);
         for (const name of target.preflight?.env ?? []) if (!process.env[name]) fail(`missing required environment variable: ${name}`);
         for (const command of target.preflight?.commands ?? []) runChecked(command.cmd, command.args ?? [], path.resolve(appRoot, command.cwd ?? "."), env);
@@ -135,6 +162,7 @@ try {
         checkpoint(stateRoot, "preflight_complete");
       },
       prepare: async () => {
+        throwIfInterrupted();
         const cacheTarget = env.CARGO_TARGET_DIR;
         const targetLink = path.join(appRoot, "src-tauri", "target");
         mkdirSync(cacheTarget, { recursive: true });
@@ -145,6 +173,7 @@ try {
         await runProgress(config.packageManager ?? "pnpm", ["install", "--frozen-lockfile"], appRoot, env, cacheTarget);
       },
       build: async () => {
+        throwIfInterrupted();
         await runProgress(
           process.execPath,
           [WORKER, "--config", worktreeConfigPath, "--platform", platform, "--no-upload"],
@@ -158,13 +187,22 @@ try {
       },
       seal: async ({ sealedDir }) => {
         sealRelease({ configRoot: path.dirname(worktreeConfigPath), sealedDir, releaseId, config, target, platform, commit, inputHashes, toolVersions, cacheKey });
+        verifySealedRelease(sealedDir);
+        if (cacheMode === "shared") markCacheEntrySuccessful({ layout: sharedLayout });
         checkpoint(stateRoot, "sealed");
       },
     },
   });
+  if (cacheMode === "shared") {
+    const snapshot = inspectCache({ cacheRoot: sharedCacheRoot });
+    const plan = planCachePrune({ snapshot, policy: readCachePolicy(process.env), protectedEntryIds: new Set([sharedLayout.id]) });
+    applyCachePrune({ plan, cacheRoot: sharedCacheRoot, dryRun: false });
+  }
   console.log(`right-release build: ${result.resumed ? "resumed" : "sealed"} ${result.releaseId}`);
   console.log(`sealed: ${result.sealedDir}`);
 } finally {
+  cacheLease?.release();
+  suiteSlot?.release();
   lock.release();
 }
 
@@ -182,6 +220,24 @@ function inputPaths(appRoot, configPath, target) {
   return required;
 }
 
+function repoBuildInputs(repoRoot, appRoot, relativeConfig, configured) {
+  if (!Array.isArray(configured?.include) || configured.include.length === 0) {
+    fail("release config must declare non-empty buildInputs.include paths");
+  }
+  const appPrefix = path.relative(repoRoot, appRoot).replaceAll("\\", "/");
+  const qualify = (pattern) => [appPrefix, pattern.replaceAll("\\", "/").replace(/^\.\//, "")].filter(Boolean).join("/");
+  return {
+    include: [
+      relativeConfig,
+      qualify("package.json"),
+      qualify("pnpm-lock.yaml"),
+      ...configured.include.map(qualify),
+    ],
+    exclude: (configured.exclude ?? []).map(qualify),
+    json: Object.fromEntries(Object.entries(configured.json ?? {}).map(([file, fields]) => [qualify(file), fields])),
+  };
+}
+
 function hashInputs(files) {
   return Object.fromEntries(files.map((file) => [path.relative(path.dirname(path.dirname(file)), file), hashFile(file)]));
 }
@@ -350,6 +406,11 @@ function commandExists(name) {
   return probe.status === 0;
 }
 
+function assertSccacheVersion(version) {
+  const match = String(version ?? "").match(/sccache\s+(\d+)\.(\d+)\.(\d+)/i);
+  if (!match || Number(match[1]) === 0 && Number(match[2]) < 15) fail("shared cache requires sccache >= 0.15.0; install with: cargo install sccache --locked; then verify: sccache --version");
+}
+
 function commandOutput(cmd, runArgs) {
   try {
     return commandOutputPortable(cmd, runArgs);
@@ -395,5 +456,7 @@ function usage(code) {
 
 function fail(message) {
   console.error(`right-release build: ${message}`);
-  process.exit(1);
+  throw new Error(message);
 }
+
+function throwIfInterrupted() { if (interrupted) throw interrupted; }

package/build-release.test.mjs

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import test from "node:test";
+
+const source = readFileSync(path.join(path.dirname(new URL(import.meta.url).pathname), "build-release.mjs"), "utf8");
+
+test("macOS builds default to Cache V2 while explicit legacy mode remains available", () => {
+  assert.match(source, /RIGHT_RELEASE_CACHE_MODE/);
+  assert.match(source, /platform === "mac" \? "shared" : "legacy"/);
+  assert.match(source, /cacheMode !== "legacy" && cacheMode !== "shared"/);
+  assert.match(source, /resolveSharedCacheRoot/);
+  assert.match(source, /acquireSuiteBuildSlot/);
+  assert.match(source, /acquireCacheLease/);
+  assert.match(source, /markCacheEntrySuccessful/);
+  assert.match(source, /RIGHT_RELEASE_CACHE_OWNER/);
+  assert.match(source, /suiteSlot\?\.release\(\)/);
+  assert.match(source, /cacheLease\?\.release\(\)/);
+  assert.doesNotMatch(source, /process\.exit\(signal/);
+  assert.match(source, /throwIfInterrupted/);
+  assert.match(source, /delete env\.RIGHT_RELEASE_CACHE_OWNER/);
+  assert.match(source, /assertPrimaryReleaseCheckout\(repoRoot\)/);
+  assert.match(source, /dirtyBuildInputs\(repoRoot/);
+});

package/cache-command.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  applyCachePrune,
+  inspectCache,
+  migrateLegacyCache,
+  planCachePrune,
+  readCachePolicy,
+  resolveCacheLayout,
+  resolveSharedCacheIdentity,
+  resolveSharedCacheRoot,
+} from "./cache-policy.mjs";
+import { resolveReleaseLayout } from "./release-state.mjs";
+
+export async function runCacheCommand(args = process.argv.slice(2), { env = process.env, stdout = console.log, stderr = console.error } = {}) {
+  const [command, ...rest] = args;
+  const json = rest.includes("--json");
+  const platform = platformFrom(env);
+  const cacheRoot = resolveSharedCacheRoot({ platform, env });
+  if (command === "status") {
+    rejectUnknown(rest, new Set(["--json"]));
+    const snapshot = inspectCache({ cacheRoot });
+    return output({ schema: 1, command, ...snapshot, policy: readCachePolicy(env) }, json, stdout);
+  }
+  if (command === "prune") {
+    rejectUnknown(rest, new Set(["--json", "--dry-run", "--apply"]));
+    if (rest.includes("--dry-run") && rest.includes("--apply")) throw new Error("cache prune accepts either --dry-run or --apply");
+    const dryRun = !rest.includes("--apply");
+    const snapshot = inspectCache({ cacheRoot });
+    const plan = planCachePrune({ snapshot, policy: readCachePolicy(env), protectedEntryIds: new Set(snapshot.entries.filter((entry) => entry.leased).map((entry) => entry.id)) });
+    const result = dryRun ? { candidateIds: plan.candidateIds, removedIds: [], reclaimedBytes: 0, dryRun: true } : applyCachePrune({ plan, cacheRoot, dryRun: false });
+    return output({ schema: 1, command, cacheRoot, dryRun, plan, ...result }, json, stdout);
+  }
+  if (command === "migrate") {
+    const configPath = option(rest, "--config");
+    if (!configPath) throw new Error("cache migrate requires --config <right-release.config.mjs>");
+    rejectUnknown(rest.filter((value) => value !== "--config" && value !== configPath), new Set(["--json", "--dry-run", "--apply"]));
+    if (rest.includes("--dry-run") && rest.includes("--apply")) throw new Error("cache migrate accepts either --dry-run or --apply");
+    const configFile = path.resolve(configPath);
+    const config = (await import(pathToFileURL(configFile).href)).default;
+    if (!config?.app) throw new Error("cache migrate config must expose app");
+    const appRoot = path.dirname(configFile);
+    const configuredTarget = config.targets?.[platform] ?? {};
+    const lockPath = path.join(appRoot, "src-tauri", "Cargo.lock");
+    const identity = resolveSharedCacheIdentity({ cargoLockPath: lockPath, cargoTomlPath: path.join(appRoot, "src-tauri", "Cargo.toml"), rustcVerbose: env.RIGHT_RELEASE_RUSTC_VERBOSE, targetTriple: configuredTarget.cargoTarget ?? configuredTarget.targetTriple ?? configuredTarget.rustTarget ?? env.TAURI_ENV_TARGET_TRIPLE, profile: configuredTarget.profile ?? "release" });
+    const fingerprint = env.RIGHT_RELEASE_CACHE_KEY || identity.fingerprint;
+    const layout = resolveCacheLayout({ cacheRoot, platform, architecture: identity.architecture, app: config.app, fingerprint, kind: "release" });
+    const dryRun = !rest.includes("--apply");
+    const legacy = resolveReleaseLayout({ repoRoot: findRepoRoot(appRoot), configPath: configFile });
+    const legacyTargetRoot = path.join(legacy.vaultRoot, "cache", "cargo-target", platform, fingerprint);
+    const result = migrateLegacyCache({ legacyRoot: path.join(appRoot, "src-tauri", "target"), legacyTargetRoot, legacyCargoHome: path.join(legacy.vaultRoot, "cache", "cargo-home"), legacyReleaseLockPath: path.join(legacy.vaultRoot, "locks", `${platform}.lock.json`), layout, app: config.app, dryRun });
+    return output({ schema: 1, command, cacheRoot, ...result }, json, stdout);
+  }
+  throw new Error("right-release cache: expected status, prune, or migrate");
+}
+
+function output(value, json, stdout) {
+  if (json) stdout(JSON.stringify(value));
+  else if (value.command === "status") stdout(`RightKit cache root: ${value.cacheRoot}\nTargets: ${value.targetBytes} bytes\nFree: ${(value.cacheFreeBytes / 1024 ** 3).toFixed(1)} GiB\nLeases: ${value.entries.filter((entry) => entry.leased).length}`);
+  else stdout(`RightKit cache ${value.command}: ${value.dryRun ? "dry-run" : "applied"}\nRoot: ${value.cacheRoot}\nCandidates: ${(value.candidateIds ?? value.plan?.candidateIds ?? []).join(", ") || "none"}\nReclaimed: ${value.reclaimedBytes ?? 0} bytes`);
+  return value;
+}
+
+function option(args, name) { const index = args.indexOf(name); return index >= 0 ? args[index + 1] : undefined; }
+function rejectUnknown(args, allowed) { for (const arg of args) if (!allowed.has(arg)) throw new Error(`unknown cache argument: ${arg}`); }
+function platformFrom(env) { return env.RIGHT_RELEASE_PLATFORM || (process.platform === "win32" ? "win" : process.platform === "darwin" ? "mac" : process.platform); }
+function findRepoRoot(start) { let current = path.resolve(start); for (;;) { if (existsSync(path.join(current, ".git"))) return current; const parent = path.dirname(current); if (parent === current) throw new Error(`cache migrate could not find Git repository for ${start}`); current = parent; } }
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runCacheCommand().catch((error) => { console.error(error.message); process.exitCode = 2; });
+}

package/cache-command.test.mjs

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+
+const root = path.dirname(new URL(import.meta.url).pathname);
+const cli = path.join(root, "cli", "right-release.mjs");
+
+function run(args, cacheRoot, env = {}) {
+  return spawnSync(process.execPath, [cli, "cache", ...args], { encoding: "utf8", env: { ...process.env, RIGHT_RELEASE_CACHE_ROOT: cacheRoot, ...env } });
+}
+
+test("cache status has human and schema-stable JSON output", () => {
+  const cacheRoot = mkdtempSync(path.join(os.tmpdir(), "rightkit-cache-command-"));
+  const human = run(["status"], cacheRoot);
+  const json = run(["status", "--json"], cacheRoot);
+  assert.equal(human.status, 0, human.stderr);
+  assert.match(human.stdout, /RightKit cache root:/);
+  assert.equal(json.status, 0, json.stderr);
+  assert.equal(JSON.parse(json.stdout).schema, 1);
+});
+
+test("cache prune defaults to dry-run and only apply can mutate an admitted temporary entry", () => {
+  const cacheRoot = mkdtempSync(path.join(os.tmpdir(), "rightkit-cache-command-"));
+  const target = path.join(cacheRoot, "targets", "mac", "fixture", "1111111111111111");
+  mkdirSync(target, { recursive: true });
+  writeFileSync(path.join(target, "payload"), "payload");
+  writeFileSync(path.join(target, ".rightkit-cache-entry.json"), JSON.stringify({ schema: 1, id: "target:mac:fixture:1111111111111111", kind: "release", platform: "mac", architecture: "aarch64", app: "fixture", fingerprint: "1111111111111111", createdAt: "2020-01-01T00:00:00.000Z", lastUsedAt: "2020-01-01T00:00:00.000Z", lastSuccessfulBuildAt: "2020-01-01T00:00:00.000Z", toolchain: {} }));
+  const dry = run(["prune", "--dry-run", "--json"], cacheRoot);
+  assert.equal(dry.status, 0, dry.stderr);
+  assert.equal(JSON.parse(dry.stdout).dryRun, true);
+  assert.equal(run(["prune", "--apply", "--json"], cacheRoot).status, 0);
+});
+
+test("cache rejects unknown commands and migration requires a config", () => {
+  const cacheRoot = mkdtempSync(path.join(os.tmpdir(), "rightkit-cache-command-"));
+  assert.notEqual(run(["unknown"], cacheRoot).status, 0);
+  assert.notEqual(run(["migrate"], cacheRoot).status, 0);
+});
+
+test("status and prune dry-run do not create a cache root or lock file", () => {
+  const parent = mkdtempSync(path.join(os.tmpdir(), "rightkit-cache-command-"));
+  const cacheRoot = path.join(parent, "never-created");
+  assert.equal(run(["status", "--json"], cacheRoot).status, 0);
+  assert.equal(run(["prune", "--dry-run", "--json"], cacheRoot).status, 0);
+  assert.equal(existsSync(cacheRoot), false);
+});
+
+test("cache migrate uses the repository vault Cargo home, not an app-local lookalike", () => {
+  const sandbox = mkdtempSync(path.join(os.tmpdir(), "rightkit-cache-command-"));
+  const repo = path.join(sandbox, "repo"); const app = path.join(repo, "app"); const cacheRoot = path.join(sandbox, "shared-cache");
+  const config = path.join(app, "right-release.config.mjs"); const fingerprint = "abcdef0123456789";
+  const target = path.join(repo, ".right-release", "cache", "cargo-target", "mac", fingerprint);
+  const vaultCargoHome = path.join(repo, ".right-release", "cache", "cargo-home");
+  const appCargoHome = path.join(app, ".right-release", "cache", "cargo-home");
+  mkdirSync(path.join(repo, ".git"), { recursive: true });
+  mkdirSync(path.dirname(config), { recursive: true });
+  writeFileSync(config, "export default { app: 'fixture', targets: { mac: { targetTriple: 'aarch64-apple-darwin' } } };\n");
+  mkdirSync(path.join(app, "src-tauri"), { recursive: true });
+  writeFileSync(path.join(app, "src-tauri", "Cargo.lock"), "fixture-lock\n");
+  writeFileSync(path.join(app, "src-tauri", "Cargo.toml"), "[package]\nname = 'fixture'\n");
+  mkdirSync(target, { recursive: true }); writeFileSync(path.join(target, "artifact"), "target");
+  symlinkSync(target, path.join(app, "src-tauri", "target"));
+  mkdirSync(vaultCargoHome, { recursive: true }); writeFileSync(path.join(vaultCargoHome, "registry"), "vault");
+  mkdirSync(appCargoHome, { recursive: true }); writeFileSync(path.join(appCargoHome, "registry"), "app-local");
+  const result = run(["migrate", "--config", config, "--apply", "--json"], cacheRoot, { RIGHT_RELEASE_PLATFORM: "mac", RIGHT_RELEASE_RUSTC_VERBOSE: "rustc 1.91.0\nhost: aarch64-apple-darwin", RIGHT_RELEASE_CACHE_KEY: fingerprint });
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(JSON.parse(result.stdout).cargoHomeMoved, true);
+  assert.equal(readFileSync(path.join(cacheRoot, "cargo-home", "registry"), "utf8"), "vault");
+  assert.equal(readFileSync(path.join(appCargoHome, "registry"), "utf8"), "app-local");
+});