@rightkit/release 0.2.18 → 0.2.20

package/cargo-contract.mjs

@@ -0,0 +1,159 @@
+import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const SKIP_DIRECTORIES = new Set([".cache", ".git", ".claude", ".worktrees", "node_modules", "target", "vendor"]);
+const CRATES_IO_SOURCES = new Set([
+  "registry+https://github.com/rust-lang/crates.io-index",
+  "registry+https://index.crates.io/",
+]);
+
+export function validateRightKitCargoContract(root, publishedVersions, label = path.basename(root)) {
+  const scanRoot = path.resolve(root);
+  const boundary = findRepositoryRoot(scanRoot);
+  const published = publishedVersions instanceof Map
+    ? publishedVersions
+    : new Map(Object.entries(publishedVersions ?? {}));
+  const manifests = findCargoManifests(scanRoot);
+  const cargoHome = mkdtempSync(path.join(tmpdir(), "rightkit-cargo-home-"));
+  try {
+    for (const manifestPath of manifests) {
+      const manifestLabel = path.relative(boundary, manifestPath) || "Cargo.toml";
+      assertNoRightKitCargoOverrides(manifestPath, boundary, `${label}/${manifestLabel}`);
+      const dependencies = readCargoManifestDependencies(manifestPath, cargoHome, `${label}/${manifestLabel}`);
+      assertPublishedRightKitCargoDependencies(dependencies, published, `${label}/${manifestLabel}`);
+    }
+  } finally {
+    rmSync(cargoHome, { recursive: true, force: true });
+  }
+  return manifests.length;
+}
+
+export function assertPublishedRightKitCargoDependencies(dependencies, published, label) {
+  let checked = 0;
+  for (const dependency of dependencies.filter(({ name }) => name.startsWith("rightkit-"))) {
+    checked += 1;
+    const expected = published.get(dependency.name);
+    if (!expected) throw new Error(`${label} ${dependency.name} is not a published RightKit crate`);
+    if (!CRATES_IO_SOURCES.has(dependency.source) || dependency.path || dependency.registry || dependency.req !== `=${expected}`) {
+      throw new Error(`${label} ${dependency.name} must use the exact crates.io version "=${expected}"`);
+    }
+  }
+  return checked;
+}
+
+export function assertNoRightKitCargoOverrides(manifestPath, repoRoot, label) {
+  const boundary = path.resolve(repoRoot);
+  const manifest = path.resolve(manifestPath);
+  assertInsideBoundary(manifest, boundary);
+  assertNoRightKitOverrides(readToml(manifest, label), label, path.relative(boundary, manifest) || "Cargo.toml");
+
+  for (const configPath of findRepoCargoConfigs(path.dirname(manifest), boundary)) {
+    const source = path.relative(boundary, configPath);
+    const parsed = readToml(configPath, source);
+    assertNoRightKitOverrides(parsed, label, source);
+    const cratesIo = parsed.source?.["crates-io"];
+    if (cratesIo && typeof cratesIo === "object"
+      && ["replace-with", "directory", "git", "registry", "local-registry"].some((key) => key in cratesIo)) {
+      throw new Error(`${label} has forbidden crates.io source replacement in ${source}`);
+    }
+  }
+}
+
+function readCargoManifestDependencies(manifestPath, cargoHome, label) {
+  const result = spawnSync(
+    "cargo",
+    ["metadata", "--no-deps", "--offline", "--format-version", "1", "--manifest-path", manifestPath],
+    {
+      cwd: path.dirname(manifestPath),
+      encoding: "utf8",
+      env: { ...process.env, CARGO_HOME: cargoHome },
+      windowsHide: true,
+    },
+  );
+  if (result.status !== 0) {
+    throw new Error(`${label} Cargo metadata rejected manifest; RightKit dependencies must use exact crates.io versions: ${String(result.stderr ?? "").trim()}`);
+  }
+  const metadata = JSON.parse(result.stdout);
+  const expectedPath = path.resolve(manifestPath).toLowerCase();
+  const pkg = metadata.packages.find(({ manifest_path: candidate }) => path.resolve(candidate).toLowerCase() === expectedPath);
+  if (!pkg && path.resolve(metadata.workspace_root, "Cargo.toml").toLowerCase() === expectedPath) return [];
+  if (!pkg) throw new Error(`${label} was not returned by Cargo metadata`);
+  return pkg.dependencies;
+}
+
+function assertNoRightKitOverrides(parsed, label, source) {
+  for (const overrides of Object.values(parsed.patch ?? {})) {
+    if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) continue;
+    for (const [name, specifier] of Object.entries(overrides)) {
+      const packageName = typeof specifier === "object" && specifier ? specifier.package : undefined;
+      if (name.startsWith("rightkit-") || packageName?.startsWith("rightkit-")) {
+        throw new Error(`${label} has forbidden RightKit Cargo override ${name} in ${source}`);
+      }
+    }
+  }
+  for (const [name, specifier] of Object.entries(parsed.replace ?? {})) {
+    const packageName = typeof specifier === "object" && specifier ? specifier.package : undefined;
+    if (name.split(":", 1)[0].startsWith("rightkit-") || packageName?.startsWith("rightkit-")) {
+      throw new Error(`${label} has forbidden RightKit Cargo override ${name} in ${source}`);
+    }
+  }
+}
+
+function readToml(file, label) {
+  const script = "import json,pathlib,sys,tomllib; json.dump(tomllib.loads(pathlib.Path(sys.argv[1]).read_text(encoding='utf-8')),sys.stdout,default=str)";
+  const command = process.platform === "win32" ? "py" : "python3";
+  const args = process.platform === "win32" ? ["-3.11", "-c", script, file] : ["-c", script, file];
+  const result = spawnSync(command, args, { encoding: "utf8", windowsHide: true });
+  if (result.status !== 0) throw new Error(`${label} is not valid TOML: ${String(result.stderr ?? "").trim()}`);
+  return JSON.parse(result.stdout);
+}
+
+function findCargoManifests(root) {
+  const found = [];
+  const visit = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory() && SKIP_DIRECTORIES.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) visit(full);
+      else if (entry.isFile() && entry.name === "Cargo.toml") found.push(full);
+    }
+  };
+  visit(root);
+  return found;
+}
+
+function findRepoCargoConfigs(start, repoRoot) {
+  const boundary = path.resolve(repoRoot);
+  let current = path.resolve(start);
+  assertInsideBoundary(current, boundary);
+  const configs = [];
+  while (true) {
+    for (const filename of ["config", "config.toml"]) {
+      const candidate = path.join(current, ".cargo", filename);
+      if (existsSync(candidate)) configs.push(candidate);
+    }
+    if (current.toLowerCase() === boundary.toLowerCase()) break;
+    current = path.dirname(current);
+  }
+  return configs;
+}
+
+function assertInsideBoundary(candidate, boundary) {
+  const relative = path.relative(boundary, candidate);
+  if (relative !== "" && (relative.startsWith("..") || path.isAbsolute(relative))) {
+    throw new Error(`${candidate} is outside ${boundary}`);
+  }
+}
+
+function findRepositoryRoot(start) {
+  const original = path.resolve(start);
+  let current = original;
+  while (true) {
+    if (existsSync(path.join(current, ".git"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return original;
+    current = parent;
+  }
+}

package/package.json

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

package/release.mjs

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
+import { validateRightKitCargoContract } from "./cargo-contract.mjs";
 
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const HARDENING_SCAN = path.resolve(TOOL_ROOT, "hardeningscan.mjs");
@@ -62,6 +63,7 @@ if (config.schema !== 1) fail(`unsupported config schema: ${config.schema ?? "<m
 const root = path.dirname(configPath);
 const workdir = path.resolve(root, config.workdir ?? ".");
 await validateRightKitPackageContract(root, config.app);
+validateRightKitCargoContract(root, RIGHTKIT_VERSIONS.cargo, config.app ?? path.basename(root));
 const target = config.targets?.[opts.platform];
 if (!target) fail(`${config.app ?? "app"} has no ${opts.platform} release target`);
 if (target.signed !== true) {

package/release.test.mjs

@@ -9,8 +9,10 @@ import test from "node:test";
 const release = fileURLToPath(new URL("./release.mjs", import.meta.url));
 const versions = JSON.parse(readFileSync(new URL("./rightkit-versions.json", import.meta.url), "utf8"));
 
-function fixture({ signed = true, publish = false, packageJson } = {}) {
-  const dir = mkdtempSync(path.join(os.tmpdir(), "right-release-test-"));
+function fixture({ signed = true, publish = false, packageJson, cargoManifest, cargoConfig, repoCargoConfig, siblingCargoManifest } = {}) {
+  const fixtureRoot = mkdtempSync(path.join(os.tmpdir(), "right-release-test-"));
+  const dir = repoCargoConfig ? path.join(fixtureRoot, "apps", "fixture") : fixtureRoot;
+  mkdirSync(dir, { recursive: true });
   const config = path.join(dir, "right-release.config.mjs");
   writeFileSync(
     path.join(dir, "package.json"),
@@ -49,6 +51,26 @@ function fixture({ signed = true, publish = false, packageJson } = {}) {
       },
     })};\n`,
   );
+  if (cargoManifest) {
+    writeFileSync(path.join(dir, "Cargo.toml"), `${cargoManifest}\n[lib]\npath = "fixture.rs"\n`, "utf8");
+    writeFileSync(path.join(dir, "fixture.rs"), "", "utf8");
+  }
+  if (cargoConfig) {
+    const cargoDir = path.join(dir, ".cargo");
+    mkdirSync(cargoDir, { recursive: true });
+    writeFileSync(path.join(cargoDir, "config.toml"), cargoConfig, "utf8");
+  }
+  if (repoCargoConfig) {
+    mkdirSync(path.join(fixtureRoot, ".git"), { recursive: true });
+    const cargoDir = path.join(fixtureRoot, ".cargo");
+    mkdirSync(cargoDir, { recursive: true });
+    writeFileSync(path.join(cargoDir, "config.toml"), repoCargoConfig, "utf8");
+  }
+  if (siblingCargoManifest) {
+    const sibling = path.join(fixtureRoot, "docs", "archived-workspace");
+    mkdirSync(sibling, { recursive: true });
+    writeFileSync(path.join(sibling, "Cargo.toml"), siblingCargoManifest, "utf8");
+  }
   return config;
 }
 
@@ -171,6 +193,46 @@ test("rejects hosted workflow files before release work starts", () => {
   assert.match(result.stderr, /hosted workflow.*forbidden/i);
 });
 
+test("doctor accepts an exact crates.io RightKit pin with benign Cargo config", () => {
+  const config = fixture({
+    cargoManifest: `[package]\nname = "fixture"\nversion = "0.0.0"\nedition = "2021"\n[dependencies]\nrightkit-license = "=0.1.2"`,
+    cargoConfig: `[net]\nretry = 2\n[registries.private]\nindex = "https://example.test/index"`,
+  });
+  const result = run(config, "--doctor");
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /right-release/);
+});
+
+test("doctor scopes Cargo inspection to the configured app inside a monorepo", () => {
+  const config = fixture({
+    cargoManifest: `[package]\nname = "fixture"\nversion = "0.0.0"\nedition = "2021"\n[dependencies]\nrightkit-license = "=0.1.2"`,
+    repoCargoConfig: `[net]\nretry = 2`,
+    siblingCargoManifest: `[package]\nname = "archived-copy"\nversion = "0.0.0"\n[dependencies]\nrightkit-license = { path = "../../rightkit-license" }`,
+  });
+  const result = run(config, "--doctor");
+  assert.equal(result.status, 0, result.stderr);
+});
+
+test("doctor rejects a repo-local RightKit Cargo override", () => {
+  const config = fixture({
+    cargoManifest: `[package]\nname = "fixture"\nversion = "0.0.0"\nedition = "2021"\n[dependencies]\nrightkit-license = "=0.1.1"`,
+    cargoConfig: `[patch.crates-io]\nrightkit-license = { path = "../rightkit-license" }`,
+  });
+  const result = run(config, "--doctor");
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /forbidden RightKit Cargo override/i);
+});
+
+test("doctor rejects a RightKit override at an ancestor repository root", () => {
+  const config = fixture({
+    cargoManifest: `[package]\nname = "fixture"\nversion = "0.0.0"\nedition = "2021"\n[dependencies]\nrightkit-license = "=0.1.1"`,
+    repoCargoConfig: `[patch.crates-io]\nrightkit-license = { git = "https://example.test/rightkit-license.git" }`,
+  });
+  const result = run(config, "--doctor");
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /forbidden RightKit Cargo override/i);
+});
+
 test("publish runs the signed package step before the updater publication step", () => {
   const result = run(fixture({ publish: true }), "--tier=update", "--upload");
   assert.equal(result.status, 0, result.stderr);

package/right-suite-contract.test.mjs

@@ -1,12 +1,21 @@
 import assert from "node:assert/strict";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
-import test from "node:test";
+import test, { after } from "node:test";
+import {
+  assertNoRightKitCargoOverrides,
+  assertPublishedRightKitCargoDependencies,
+  validateRightKitCargoContract,
+} from "./cargo-contract.mjs";
 
 const workspace = path.resolve(new URL("../../../..", import.meta.url).pathname.replace(/^\/(\w:)/, "$1"));
 const versionsPath = path.join(path.dirname(new URL(import.meta.url).pathname.replace(/^\/(\w:)/, "$1")), "rightkit-versions.json");
 const versions = JSON.parse(readFileSync(versionsPath, "utf8"));
+const isolatedCargoHome = mkdtempSync(path.join(tmpdir(), "rightkit-cargo-home-"));
+after(() => rmSync(isolatedCargoHome, { recursive: true, force: true }));
 const pubkey = "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IDI5Mzk1RjlGRjQ2NjI2MUQKUldRZEptYjBuMTg1S1VSUXlBdFM4WmtzaHArYko0U2hRMDVlSDJmSExVZG82Q0hoQ2srUlhqanAK";
 const apps = [
   { key: "viewright", root: "viewright", tauri: "src-tauri/tauri.conf.json", releaseFiles: ["scripts/build-mac-notarized.sh"] },
@@ -16,19 +25,301 @@ const apps = [
   { key: "coderight", root: "coderight/apps/coderight-tauri", tauri: "src-tauri/tauri.conf.json", releaseFiles: ["scripts/mac-dmg.mjs"] },
 ];
 
+function resolveCargoVersionContract(versionManifest, canonicalVersions) {
+  const consumer = new Map(Object.entries(versionManifest.cargo ?? {}));
+  const staged = new Map(Object.entries(versionManifest.stagedCargo ?? {}));
+  const canonical = new Map();
+
+  for (const [crate, version] of staged) {
+    if (!canonicalVersions.has(crate)) throw new Error(`unknown staged Cargo crate: ${crate}`);
+    const actual = canonicalVersions.get(crate);
+    if (actual !== version) {
+      throw new Error(`${crate} canonical manifest is ${actual}, expected staged version ${version}`);
+    }
+    canonical.set(crate, version);
+  }
+
+  for (const [crate, version] of consumer) {
+    if (!canonicalVersions.has(crate)) throw new Error(`unknown published Cargo crate: ${crate}`);
+    const expected = staged.get(crate) ?? version;
+    const actual = canonicalVersions.get(crate);
+    if (actual !== expected) {
+      const source = staged.has(crate) ? "staged" : "published";
+      throw new Error(`${crate} canonical manifest is ${actual}, expected ${source} version ${expected}`);
+    }
+    canonical.set(crate, expected);
+  }
+
+  return { canonical, consumer };
+}
+
+let currentCargoVersionContract;
+function getCurrentCargoVersionContract() {
+  currentCargoVersionContract ??= resolveCargoVersionContract(versions, readCanonicalCrateVersions());
+  return currentCargoVersionContract;
+}
+
+const cargoContractCache = new Map();
+function readCargoManifestContract(manifestPath, label) {
+  const cacheKey = path.resolve(manifestPath).toLowerCase();
+  if (cargoContractCache.has(cacheKey)) return cargoContractCache.get(cacheKey);
+  const result = spawnSync(
+    "cargo",
+    ["metadata", "--no-deps", "--offline", "--format-version", "1", "--manifest-path", manifestPath],
+    {
+      cwd: path.dirname(manifestPath),
+      encoding: "utf8",
+      env: { ...process.env, CARGO_HOME: isolatedCargoHome },
+      windowsHide: true,
+    },
+  );
+  assert.equal(
+    result.status,
+    0,
+    `${label} Cargo metadata rejected manifest; RightKit dependencies must use exact crates.io versions: ${String(result.stderr ?? "").trim()}`,
+  );
+  const metadata = JSON.parse(result.stdout);
+  const expectedPath = path.resolve(manifestPath).toLowerCase();
+  const pkg = metadata.packages.find(({ manifest_path: candidate }) => path.resolve(candidate).toLowerCase() === expectedPath);
+  if (!pkg && path.resolve(metadata.workspace_root, "Cargo.toml").toLowerCase() === expectedPath) {
+    const contract = { dependencies: [], workspaceRoot: path.resolve(metadata.workspace_root) };
+    cargoContractCache.set(cacheKey, contract);
+    return contract;
+  }
+  assert.ok(pkg, `${label} was not returned by Cargo metadata`);
+  const contract = { dependencies: pkg.dependencies, workspaceRoot: path.resolve(metadata.workspace_root) };
+  cargoContractCache.set(cacheKey, contract);
+  return contract;
+}
+
+function assertCargoFixture(manifest, published, label) {
+  const fixtureRoot = mkdtempSync(path.join(tmpdir(), "rightkit-cargo-contract-"));
+  const manifestPath = path.join(fixtureRoot, "Cargo.toml");
+  const packageMetadata = /^\s*\[\s*package\s*\]/m.test(manifest)
+    ? ""
+    : '\n[package]\nname = "rightkit-contract-fixture"\nversion = "0.0.0"\nedition = "2021"\n';
+  writeFileSync(manifestPath, `${manifest}${packageMetadata}\n[lib]\npath = "fixture.rs"\n`, "utf8");
+  writeFileSync(path.join(fixtureRoot, "fixture.rs"), "", "utf8");
+  try {
+    return assertPublishedRightKitCargoDependencies(
+      readCargoManifestContract(manifestPath, label).dependencies,
+      published,
+      label,
+    );
+  } finally {
+    rmSync(fixtureRoot, { recursive: true, force: true });
+  }
+}
+
+function assertCargoOverrideFixture({ manifest, workspaceManifest, localConfig, ancestorConfig, outsideConfig }) {
+  const fixtureRoot = mkdtempSync(path.join(tmpdir(), "rightkit-cargo-override-"));
+  const repoRoot = path.join(fixtureRoot, "repo");
+  const appRoot = path.join(repoRoot, "app");
+  mkdirSync(appRoot, { recursive: true });
+  const manifestPath = path.join(appRoot, "Cargo.toml");
+  writeFileSync(manifestPath, manifest, "utf8");
+  if (workspaceManifest) writeFileSync(path.join(repoRoot, "Cargo.toml"), workspaceManifest, "utf8");
+  for (const [root, filename, source] of [
+    [appRoot, "config", localConfig],
+    [repoRoot, "config.toml", ancestorConfig],
+    [fixtureRoot, "config.toml", outsideConfig],
+  ]) {
+    if (!source) continue;
+    const cargoDir = path.join(root, ".cargo");
+    mkdirSync(cargoDir, { recursive: true });
+    writeFileSync(path.join(cargoDir, filename), source, "utf8");
+  }
+  try {
+    assertNoRightKitCargoOverrides(manifestPath, repoRoot, "fixture/Cargo.toml");
+    if (workspaceManifest) {
+      assertNoRightKitCargoOverrides(path.join(repoRoot, "Cargo.toml"), repoRoot, "fixture/workspace Cargo.toml");
+    }
+    return 0;
+  } finally {
+    rmSync(fixtureRoot, { recursive: true, force: true });
+  }
+}
+
+test("Cargo override contract accepts exact registry pins without repo-local overrides", () => {
+  assert.equal(assertCargoOverrideFixture({
+    manifest: `[package]\nname = "fixture"\nversion = "0.0.0"\n[dependencies]\nrightkit-license = "=0.1.1"`,
+    localConfig: `[net]\nretry = 2\n[registries.private]\nindex = "https://example.test/index"`,
+    outsideConfig: `[source.crates-io]\nreplace-with = "user-global-vendor"`,
+  }), 0);
+});
+
+test("Cargo override contract rejects RightKit patches and replacements in repo-local Cargo config", () => {
+  for (const config of [
+    { localConfig: `[patch.crates-io]\nrightkit-license = { path = "../rightkit-license" }` },
+    { localConfig: `patch . "https://github.com/rust-lang/crates.io-index" . "rightkit-logs" = { git = "https://example.test/rightkit-logs.git" }` },
+    { localConfig: `[ replace ]\n"rightkit-license:0.1.1" = { path = "../rightkit-license" }` },
+    { ancestorConfig: `[patch.private-source]\nadapter = { package = "rightkit-license", registry = "private" }` },
+  ]) {
+    assert.throws(
+      () => assertCargoOverrideFixture({
+        manifest: `[package]\nname = "fixture"\nversion = "0.0.0"\n[dependencies]\nrightkit-license = "=0.1.1"`,
+        ...config,
+      }),
+      /forbidden RightKit Cargo override/,
+    );
+  }
+});
+
+test("Cargo override contract rejects path patches, Git patches, and replace entries", () => {
+  for (const manifest of [
+    `patch . "crates-io" . "rightkit-license" = { path = "../rightkit-license" } # dotted path patch`,
+    `[ patch . "https://github.com/rust-lang/crates.io-index" ]\n"rightkit-logs" = { git = "https://example.test/rightkit-logs.git" }`,
+    `[ replace ]\n"rightkit-license:0.1.1" = { path = "../rightkit-license" }`,
+  ]) {
+    assert.throws(
+      () => assertCargoOverrideFixture({ manifest }),
+      /forbidden RightKit Cargo override/,
+    );
+  }
+});
+
+test("Cargo override contract rejects workspace-root patches inherited by a member", () => {
+  assert.throws(
+    () => assertCargoOverrideFixture({
+      manifest: `[package]\nname = "fixture"\nversion = "0.0.0"`,
+      workspaceManifest: `[workspace]\nmembers = ["app"]\n[patch.crates-io]\nrightkit-license = { path = "patched/rightkit-license" }`,
+    }),
+    /forbidden RightKit Cargo override/,
+  );
+});
+
+test("Cargo override contract rejects local and repo-ancestor crates.io source replacement", () => {
+  for (const fixture of [
+    {
+      localConfig: `source . crates-io . replace-with = "vendored-sources"\n[source.vendored-sources]\ndirectory = "vendor"`,
+    },
+    {
+      ancestorConfig: `[source."crates-io"]\nreplace-with = "rightkit-git"\n[source.rightkit-git]\ngit = "https://example.test/rightkit-index.git"`,
+    },
+    {
+      ancestorConfig: `[source.crates-io]\nreplace-with = "private-registry"\n[source.private-registry]\nregistry = "https://example.test/index"`,
+    },
+  ]) {
+    assert.throws(
+      () => assertCargoOverrideFixture({
+        manifest: `[package]\nname = "fixture"\nversion = "0.0.0"\n[dependencies]\nrightkit-license = "=0.1.1"`,
+        ...fixture,
+      }),
+      /forbidden crates\.io source replacement/,
+    );
+  }
+});
+
+test("direct Cargo dependency contract accepts only published exact RightKit pins", () => {
+  const published = new Map([
+    ["rightkit-license", "0.1.2"],
+    ["rightkit-logs", "0.1.0"],
+    ["rightkit-tauri", "0.1.0"],
+  ]);
+  const manifest = `
+[ package ]
+name = "rightkit-tauri"
+# rightkit-tauri = "=0.1.0"
+
+[ dependencies ]
+"rightkit-license" = "=0.1.2" # published exact pin
+"rightkit-tauri" = "=0.1.0"
+
+[ target . 'cfg(windows)' . dependencies . "rightkit-logs" ]
+version = "=0.1.0"
+
+[ target . 'cfg(unix)' . dev-dependencies ]
+license-adapter = { package = "rightkit-license", version = "=0.1.2" }
+`;
+
+  assert.equal(assertCargoFixture(manifest, published, "fixture/Cargo.toml"), 4);
+});
+
+test("direct Cargo dependency contract rejects staged-only RightKit crates", () => {
+  const { consumer } = resolveCargoVersionContract(
+    {
+      cargo: { "rightkit-license": "0.1.2" },
+      stagedCargo: { "rightkit-tauri": "0.1.0" },
+    },
+    new Map([
+      ["rightkit-license", "0.1.2"],
+      ["rightkit-tauri", "0.1.0"],
+    ]),
+  );
+  assert.equal(consumer.has("rightkit-tauri"), false);
+  assert.throws(
+    () => assertCargoFixture(
+      `dependencies . "rightkit-tauri" = "=0.1.0" # staged only`,
+      consumer,
+      "fixture/Cargo.toml",
+    ),
+    /fixture\/Cargo\.toml rightkit-tauri is not a published RightKit crate/,
+  );
+});
+
+test("direct Cargo dependency contract still rejects path, Git, and custom registry sources", () => {
+  const published = new Map([
+    ["rightkit-license", "0.1.1"],
+    ["rightkit-logs", "0.1.0"],
+  ]);
+  for (const manifest of [
+    `dependencies . rightkit-license = { path = "../rightkit-license" }`,
+    `target . 'cfg(windows)' . dependencies . "rightkit-logs" = { git = "https://example.test/rightkit.git" }`,
+    `dependencies . rightkit-license = { version = "=0.1.1", registry = "private" }`,
+  ]) {
+    assert.throws(
+      () => assertCargoFixture(manifest, published, "fixture/Cargo.toml"),
+      /must use exact crates\.io versions|must use the exact crates\.io version/,
+    );
+  }
+});
+
+test("Cargo version contract keeps staged versions out of consumer pins", () => {
+  const resolved = resolveCargoVersionContract(
+    {
+      cargo: { "rightkit-license": "0.1.1" },
+      stagedCargo: { "rightkit-license": "0.1.2" },
+    },
+    new Map([["rightkit-license", "0.1.2"]]),
+  );
+
+  assert.equal(resolved.consumer.get("rightkit-license"), "0.1.1");
+  assert.equal(resolved.canonical.get("rightkit-license"), "0.1.2");
+});
+
+test("Cargo version contract rejects unknown staged crates", () => {
+  assert.throws(
+    () => resolveCargoVersionContract(
+      { cargo: {}, stagedCargo: { "rightkit-unknown": "0.1.0" } },
+      new Map(),
+    ),
+    /unknown staged Cargo crate: rightkit-unknown/,
+  );
+});
+
+test("Cargo version contract rejects staged versions that mismatch canonical manifests", () => {
+  assert.throws(
+    () => resolveCargoVersionContract(
+      { cargo: { "rightkit-license": "0.1.1" }, stagedCargo: { "rightkit-license": "0.1.3" } },
+      new Map([["rightkit-license", "0.1.2"]]),
+    ),
+    /rightkit-license canonical manifest is 0\.1\.2, expected staged version 0\.1\.3/,
+  );
+});
+
 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.18");
+  assert.equal(versions.npm["@rightkit/release"], "0.2.20");
   assert.equal(versions.npm["@rightkit/license"], "0.1.5");
   assert.equal(versions.npm["@rightkit/logs"], "0.1.3");
-  assert.equal(versions.npm["@rightkit/updates"], "0.2.2");
-  assert.equal(versions.cargo["rightkit-license"], "0.1.1");
+  assert.equal(versions.npm["@rightkit/tauri"], "0.1.0");
+  assert.equal(versions.npm["@rightkit/updates"], "0.2.3");
+  assert.equal(versions.cargo["rightkit-license"], "0.1.2");
   assert.equal(versions.cargo["rightkit-logs"], "0.1.0");
-  for (const [crate, version] of Object.entries(versions.cargo)) {
-    const manifest = readFileSync(path.join(workspace, `tools/rightkit/crates/${crate}/Cargo.toml`), "utf8");
-    assert.match(manifest, new RegExp(`^version\\s*=\\s*"${version.replaceAll(".", "\\.")}"$`, "m"));
-  }
+  assert.equal(versions.cargo["rightkit-tauri"], "0.1.0");
+  assert.deepEqual(versions.stagedCargo, {});
+  getCurrentCargoVersionContract();
 });
 
 test("license v2 public vector is identical at every portable consumer boundary", () => {
@@ -119,18 +410,8 @@ for (const app of apps) {
     ]);
     assert.equal(tauri.bundle.createUpdaterArtifacts, true);
 
-    for (const manifestPath of findCargoManifests(root)) {
-      const manifest = readFileSync(manifestPath, "utf8");
-      for (const [crate, version] of Object.entries(versions.cargo)) {
-        const dependency = manifest.match(new RegExp(`^${crate}\\s*=\\s*(.+)$`, "m"));
-        if (!dependency) continue;
-        assert.equal(
-          dependency[1].trim(),
-          `"=${version}"`,
-          `${path.relative(workspace, manifestPath)} ${crate} must use the exact crates.io version`,
-        );
-      }
-    }
+    const { consumer } = getCurrentCargoVersionContract();
+    validateRightKitCargoContract(root, consumer, app.key);
 
     for (const localCopy of [
       "src-tauri/vendor/rightkit-license",
@@ -173,7 +454,7 @@ function findFiles(root, filename) {
   const found = [];
   const visit = (dir) => {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      if (entry.isDirectory() && [".git", ".claude", ".worktrees", "node_modules", "target", "vendor"].includes(entry.name)) continue;
+      if (entry.isDirectory() && [".cache", ".git", ".claude", ".worktrees", "node_modules", "target", "vendor"].includes(entry.name)) continue;
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) visit(full);
       else if (entry.isFile() && entry.name === filename) found.push(full);
@@ -183,7 +464,19 @@ function findFiles(root, filename) {
   return found;
 }
 
-const findCargoManifests = (root) => findFiles(root, "Cargo.toml");
+function readCanonicalCrateVersions() {
+  const crateRoot = path.join(workspace, "tools/rightkit/crates");
+  return new Map(
+    readdirSync(crateRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && existsSync(path.join(crateRoot, entry.name, "Cargo.toml")))
+      .map((entry) => {
+        const manifest = readFileSync(path.join(crateRoot, entry.name, "Cargo.toml"), "utf8");
+        const version = manifest.match(/^version\s*=\s*"([^"]+)"$/m)?.[1];
+        assert.ok(version, `${entry.name} canonical manifest must declare a package version`);
+        return [entry.name, version];
+      }),
+  );
+}
 
 test("Right Suite has no hosted workflow files", () => {
   for (const root of ["viewright", "scraperight", "heardright", "mailright", "coderight", "genright", "voiceright", "tools/rightkit"]) {

package/rightkit-versions.json

@@ -4,11 +4,14 @@
   "npm": {
     "@rightkit/license": "0.1.5",
     "@rightkit/logs": "0.1.3",
-    "@rightkit/release": "0.2.18",
-    "@rightkit/updates": "0.2.2"
+    "@rightkit/release": "0.2.20",
+    "@rightkit/tauri": "0.1.0",
+    "@rightkit/updates": "0.2.3"
   },
   "cargo": {
-    "rightkit-license": "0.1.1",
-    "rightkit-logs": "0.1.0"
-  }
+    "rightkit-license": "0.1.2",
+    "rightkit-logs": "0.1.0",
+    "rightkit-tauri": "0.1.0"
+  },
+  "stagedCargo": {}
 }