@rightkit/release 0.2.38 → 0.2.40

package/build-invocation-contract.test.mjs

@@ -53,15 +53,28 @@ test("allows release invocation from the primary Git checkout", () => {
   assert.doesNotThrow(() => assertPrimaryReleaseCheckout(primary));
 });
 
-test("reports dirty files that can change the packaged app", () => {
+test("rejects a detached HEAD even in the primary Git checkout", () => {
+  const primary = makeRepo();
+  git(primary, "checkout", "--detach");
+
+  assert.throws(
+    () => assertPrimaryReleaseCheckout(primary),
+    /detached HEAD is forbidden/i,
+  );
+});
+
+test("reports a dirty tracked file declared as a build input", () => {
   const primary = makeRepo();
   writeFileSync(path.join(primary, "src", "app.js"), "export const app = false;\n");
+
+  assert.deepEqual(dirtyBuildInputs(primary, buildInputs), ["src/app.js"]);
+});
+
+test("reports an untracked file declared as a build input", () => {
+  const primary = makeRepo();
   writeFileSync(path.join(primary, "src", "new-runtime.js"), "export {};\n");
 
-  assert.deepEqual(dirtyBuildInputs(primary, buildInputs), [
-    "src/app.js",
-    "src/new-runtime.js",
-  ]);
+  assert.deepEqual(dirtyBuildInputs(primary, buildInputs), ["src/new-runtime.js"]);
 });
 
 test("ignores dirty files outside the packaged app input set", () => {
@@ -73,6 +86,21 @@ test("ignores dirty files outside the packaged app input set", () => {
   assert.deepEqual(dirtyBuildInputs(primary, buildInputs), []);
 });
 
+test("required release metadata cannot be hidden by build-input exclusions", () => {
+  const primary = makeRepo();
+  writeFileSync(path.join(primary, "package.json"), "{\"version\":\"2.0.0\"}\n");
+
+  assert.deepEqual(dirtyBuildInputs(primary, {
+    ...buildInputs,
+    exclude: [...buildInputs.exclude, "package.json"],
+    required: ["package.json"],
+  }), ["package.json"]);
+  assert.deepEqual(dirtyBuildInputs(primary, {
+    include: ["package.json"],
+    required: ["package.json"],
+  }), ["package.json"]);
+});
+
 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`);

package/build-release.mjs

@@ -21,7 +21,8 @@ import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { assertPrimaryReleaseCheckout, dirtyBuildInputs } from "./release-invocation.mjs";
-import { cacheFingerprint, commandOutputPortable, releaseEnvironment, resolveReleaseLayout, runBuildStateMachine, watchProgress } from "./release-state.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");
@@ -41,69 +42,73 @@ for (let i = 0; i < args.length; i += 1) {
 }
 if (platform !== "win" && platform !== "mac") fail("--platform must be win or mac");
 
-const invocationRoot = path.dirname(path.resolve(configName));
+const configPath = path.resolve(configName);
+const invocationRoot = path.dirname(configPath);
 const repoRoot = git(invocationRoot, ["rev-parse", "--show-toplevel"]);
 assertPrimaryReleaseCheckout(repoRoot);
-const relativeConfig = path.relative(repoRoot, path.resolve(configName)).replaceAll("\\", "/");
+const relativeConfig = path.relative(repoRoot, configPath).replaceAll("\\", "/");
 if (relativeConfig.startsWith("../")) fail("release config must live inside the Git repository");
-const vaultRoot = resolveReleaseLayout({ repoRoot, configPath: path.resolve(configName) }).vaultRoot;
+const appRoot = path.dirname(configPath);
+const layout = resolveReleaseLayout({ repoRoot, configPath });
+const vaultRoot = layout.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 {
-  if (!dryRun) git(repoRoot, ["fetch", "origin", "main"]);
-  const commit = git(repoRoot, ["rev-parse", dryRun ? "HEAD" : "origin/main"]);
+  throwIfInterrupted();
+  const commit = git(repoRoot, ["rev-parse", "HEAD"]);
   const shortCommit = commit.slice(0, 8);
-  const worktree = path.join(vaultRoot, "worktrees", `${platform}-${shortCommit}`);
-  if (!existsSync(worktree)) {
-    if (dryRun) fail(`dry-run needs an existing worktree: ${worktree}`);
-    mkdirSync(path.dirname(worktree), { recursive: true });
-    runChecked("git", ["worktree", "add", "--detach", worktree, commit], repoRoot);
-  } else if (git(worktree, ["rev-parse", "HEAD"]) !== commit) {
-    fail(`release worktree exists at the wrong commit: ${worktree}`);
-  }
-
-  const worktreeConfigPath = path.join(worktree, relativeConfig);
-  const appRoot = path.dirname(worktreeConfigPath);
-  const layout = resolveReleaseLayout({ repoRoot, configPath: path.resolve(configName) });
-  const config = (await import(`${pathToFileURL(worktreeConfigPath).href}?commit=${commit}`)).default;
+  const dirtyConfig = dirtyBuildInputs(repoRoot, { include: [relativeConfig], required: [relativeConfig] }, commit);
+  if (dirtyConfig.length > 0) fail(`dirty release config cannot be executed:\n${dirtyConfig.map((file) => `- ${file}`).join("\n")}`);
+  const config = (await import(`${pathToFileURL(configPath).href}?commit=${commit}`)).default;
   if (!config?.app || !config?.version) fail("release config must expose app and version");
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(config.app) || !/^[A-Za-z0-9][A-Za-z0-9._+-]*$/.test(config.version)) {
     fail("app and version must be safe release-id components");
   }
   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 requiredInputs = inputPaths(appRoot, configPath, target);
+  const dirtyInputs = dirtyBuildInputs(repoRoot, repoBuildInputs(repoRoot, appRoot, target.buildInputs ?? config.buildInputs, requiredInputs), 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 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);
@@ -128,9 +133,19 @@ try {
     commit,
     platform,
     requiredInputs,
+    inputHashes,
+    cacheKey,
     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);
@@ -141,19 +156,21 @@ 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 });
         if (!existsSync(targetLink)) symlinkSync(cacheTarget, targetLink, process.platform === "win32" ? "junction" : "dir");
         else if (realpathSync(targetLink) !== realpathSync(cacheTarget)) {
-          fail(`worktree target exists and is not the release cache link: ${targetLink}`);
+          fail(`primary checkout target exists and is not the release cache link: ${targetLink}`);
         }
         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"],
+          [WORKER, "--config", configPath, "--platform", platform, "--no-upload"],
           appRoot,
           env,
           [env.CARGO_TARGET_DIR, path.join(appRoot, ".cache")],
@@ -163,14 +180,23 @@ try {
         checkpoint(stateRoot, "hardened");
       },
       seal: async ({ sealedDir }) => {
-        sealRelease({ configRoot: path.dirname(worktreeConfigPath), sealedDir, releaseId, config, target, platform, commit, inputHashes, toolVersions, cacheKey });
+        sealRelease({ configRoot: appRoot, 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();
 }
 
@@ -188,20 +214,19 @@ function inputPaths(appRoot, configPath, target) {
   return required;
 }
 
-function repoBuildInputs(repoRoot, appRoot, relativeConfig, configured) {
+function repoBuildInputs(repoRoot, appRoot, configured, requiredInputs) {
   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("/");
+  const qualify = (pattern) => path.posix.normalize([appPrefix, pattern.replaceAll("\\", "/").replace(/^\.\//, "")].filter(Boolean).join("/"));
+  const required = requiredInputs
+    .map((file) => path.relative(repoRoot, file).replaceAll("\\", "/"))
+    .filter((file) => file && file !== ".." && !file.startsWith("../") && !path.isAbsolute(file));
   return {
-    include: [
-      relativeConfig,
-      qualify("package.json"),
-      qualify("pnpm-lock.yaml"),
-      ...configured.include.map(qualify),
-    ],
+    include: configured.include.map(qualify),
     exclude: (configured.exclude ?? []).map(qualify),
+    required,
     json: Object.fromEntries(Object.entries(configured.json ?? {}).map(([file, fields]) => [qualify(file), fields])),
   };
 }
@@ -374,6 +399,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);
@@ -419,5 +449,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,44 @@
+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/);
+});
+
+test("production builds package from the real primary app checkout", () => {
+  assert.match(source, /const configPath = path\.resolve\(configName\)/);
+  assert.match(source, /const appRoot = path\.dirname\(configPath\)/);
+  assert.match(source, /\[WORKER, "--config", configPath, "--platform", platform, "--no-upload"\]/);
+  assert.match(source, /sealRelease\(\{ configRoot: appRoot,/);
+});
+
+test("production builds never create or use an internal Git worktree", () => {
+  assert.doesNotMatch(source, /git", \["worktree", "add"/);
+  assert.doesNotMatch(source, /path\.join\(vaultRoot, "worktrees"/);
+  assert.doesNotMatch(source, /worktreeConfigPath/);
+});
+
+test("dirty release config is rejected before the config module is imported", () => {
+  const guard = source.indexOf("dirtyBuildInputs(repoRoot, { include: [relativeConfig], required: [relativeConfig] }, commit)");
+  const imported = source.indexOf("await import(");
+  assert.ok(guard >= 0, "config cleanliness guard must exist");
+  assert.ok(guard < imported, "config cleanliness guard must run before module import");
+});

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");
+});