@rightkit/release 0.2.56 → 0.2.58

package/addon-command.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { addonManifestSha256, addonRoutes, canonicalAddonManifest, createAddonManifest, downloadImmutableAddOn, validateAddonConfig, validateAddonManifest } from "./addon-contract.mjs";
+import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
+import { assertCleanSource } from "./source-gate.mjs";
+
+const ROOT = path.dirname(fileURLToPath(import.meta.url));
+const SIGN_WINDOWS = path.join(ROOT, "sign-windows.mjs");
+const HARDEN = path.join(ROOT, "hardeningscan.mjs");
+const [operation, ...args] = process.argv.slice(2);
+const options = parse(args);
+if (!new Set(["doctor", "build", "upload", "adopt"]).has(operation)) usage(2);
+if (!new Set(["mac", "win"]).has(options.platform)) fail("--platform must be mac or win");
+
+if (operation === "adopt") await adopt(options);
+else {
+  if (!options.config) fail("--config is required");
+  const configPath = path.resolve(options.config);
+  const root = path.dirname(configPath);
+  const repoRoot = git(root, ["rev-parse", "--show-toplevel"]);
+  assertPrimaryReleaseCheckout(repoRoot);
+  const config = (await import(`${pathToFileURL(configPath).href}?addon=${Date.now()}`)).default;
+  if (operation === "doctor") doctor({ config, configPath, root, repoRoot, options });
+  else if (operation === "build") await build({ config, configPath, root, repoRoot, options });
+  else await upload({ config, root, repoRoot, options });
+}
+
+function doctor({ config, configPath, root, repoRoot, options }) {
+  validateAddonConfig(config, { root, platform: options.platform, allowMissingExecutables: true });
+  console.log(`right-release addon doctor: ${config.addon} ${config.version} ${options.platform}`);
+  console.log(`config: ${configPath}`);
+  console.log(`repo: ${repoRoot}`);
+}
+
+async function build({ config, configPath, root, repoRoot, options }) {
+  const commit = git(repoRoot, ["rev-parse", "HEAD"]);
+  const { target } = validateAddonConfig(config, { root, platform: options.platform, allowMissingExecutables: true });
+  if (options.dryRun) {
+    console.log(`right-release addon build dry-run: ${config.addon} ${config.version} ${options.platform}`);
+    console.log(`config: ${configPath}`);
+    console.log(`commit: ${commit}`);
+    console.log(`would run: ${target.build.cmd} ${target.build.args.join(" ")}`);
+    return;
+  }
+  assertCleanSource({ status: git(repoRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]), commandId: "right-release addon build" });
+  run(target.build.cmd, target.build.args, root);
+  const signing = signExecutableRoles(config, root, options.platform);
+  const manifest = createAddonManifest({ config, root, platform: options.platform, commit, signing });
+  const digest = addonManifestSha256(manifest);
+  const sealed = path.join(repoRoot, ".right-release", "addons", config.addon, config.version, commit.slice(0, 8), options.platform);
+  if (existsSync(sealed)) fail(`add-on seal already exists: ${sealed}`);
+  const temp = `${sealed}.tmp-${process.pid}`;
+  mkdirSync(temp, { recursive: true });
+  for (const file of config.targets[options.platform].files ?? config.files) copyFileSync(path.resolve(root, file.source), path.join(temp, file.name));
+  writeFileSync(path.join(temp, "addon-manifest.json"), canonicalAddonManifest(manifest));
+  run(process.execPath, [HARDEN, ...manifest.files.map((file) => path.join(temp, file.name))], root);
+  mkdirSync(path.dirname(sealed), { recursive: true });
+  renameSync(temp, sealed);
+  console.log(`right-release addon build: sealed ${sealed}`);
+  console.log(`manifestSha256: ${digest}`);
+}
+
+function signExecutableRoles(config, root, platform) {
+  const files = config.targets[platform].files ?? config.files;
+  const executable = files.filter((file) => file.executable === true);
+  if (platform === "win") run(process.execPath, [SIGN_WINDOWS, ...executable.map((file) => path.resolve(root, file.source))], root);
+  else for (const file of executable) {
+    const absolute = path.resolve(root, file.source);
+    run("codesign", ["--force", "--options", "runtime", "--sign", "Developer ID Application", absolute], root);
+    const output = command("codesign", ["-dv", "--verbose=4", absolute], root);
+    if (!new RegExp(`TeamIdentifier=${config.targets.mac.signing.teamId}`).test(output)) fail(`codesign team mismatch: ${file.name}`);
+    run("codesign", ["--verify", "--strict", "--verbose=2", absolute], root);
+  }
+  return Object.fromEntries(executable.map((file) => [file.role, { contract: config.targets[platform].signing.contract, status: "verified" }]));
+}
+
+async function upload({ config, root, repoRoot, options }) {
+  if (!new Set(["patch", "update"]).has(options.tier)) fail("add-on upload requires --tier patch|update");
+  const commit = git(repoRoot, ["rev-parse", "HEAD"]);
+  const sealed = path.join(repoRoot, ".right-release", "addons", config.addon, config.version, commit.slice(0, 8), options.platform);
+  const manifest = JSON.parse(readFileSync(path.join(sealed, "addon-manifest.json"), "utf8"));
+  validateAddonManifest(manifest);
+  const routes = addonRoutes(manifest);
+  if (options.dryRun) {
+    for (const route of routes) console.log(`would upload ${route.key}${route.manifest ? " (last)" : ""}`);
+    return;
+  }
+  if (!process.env.CLOUDFLARE_API_TOKEN) fail("CLOUDFLARE_API_TOKEN is required before R2 mutation");
+  for (const route of routes) {
+    const source = route.manifest ? path.join(sealed, "addon-manifest.json") : path.join(sealed, route.name);
+    await putImmutable({ source, route, repoRoot });
+  }
+  console.log(`right-release addon upload: verified ${config.addon} ${options.platform} tier=${options.tier}`);
+}
+
+async function putImmutable({ source, route, repoRoot }) {
+  const target = `rightapps-downloads/${route.key}`;
+  const temp = path.join(os.tmpdir(), `right-addon-r2-${process.pid}-${createHash("sha256").update(route.key).digest("hex").slice(0, 12)}`);
+  const existing = wrangler(["r2", "object", "get", target, "--file", temp, "--remote"], repoRoot);
+  if (existing.status === 0) {
+    const actual = sha256(temp); rmSync(temp, { force: true });
+    if (actual !== route.sha256) fail(`immutable object exists with different bytes: ${route.key}`);
+    return;
+  }
+  if (!/not found|does not exist|404/i.test(`${existing.stdout}\n${existing.stderr}`)) fail(`cannot inspect immutable object: ${route.key}`);
+  const uploaded = wrangler(["r2", "object", "put", target, "--file", source, "--remote"], repoRoot);
+  if (uploaded.status !== 0) fail(`immutable upload failed: ${route.key}`);
+}
+
+async function adopt(options) {
+  if (!options.lock || !options.output) fail("adopt requires --lock and --output");
+  const lockPath = path.resolve(options.lock);
+  const lock = JSON.parse(readFileSync(lockPath, "utf8"));
+  const entry = lock.targets?.[options.platform] ?? lock[options.platform];
+  if (!entry?.manifestSha256 || !entry?.manifestUrl) fail("add-on lock needs platform manifestUrl and manifestSha256");
+  const temporary = options.source ? null : mkdtempSync(path.join(os.tmpdir(), "right-addon-adopt-"));
+  const source = options.source ? path.resolve(options.source) : temporary;
+  if (!options.source) await downloadImmutableAddOn(entry.manifestUrl, source);
+  const manifest = JSON.parse(readFileSync(path.join(source, "addon-manifest.json"), "utf8"));
+  validateAddonManifest(manifest);
+  if (addonManifestSha256(manifest) !== entry.manifestSha256) fail("add-on lock manifest SHA mismatch");
+  const immutableSuffix = `/${manifest.addon}/addons/${manifest.platform}/sha256/${entry.manifestSha256}/addon-manifest.json`;
+  if (!entry.manifestUrl.endsWith(immutableSuffix) || /[?#]/.test(entry.manifestUrl)) fail("add-on lock manifestUrl is not immutable");
+  const output = path.resolve(options.output);
+  const destination = path.join(output, manifest.addon);
+  const stage = `${destination}.tmp-${process.pid}`;
+  const adoptedFiles = [];
+  rmSync(stage, { recursive: true, force: true }); mkdirSync(stage, { recursive: true });
+  for (const file of manifest.files) {
+    const sourceFile = path.join(source, file.name);
+    if (!existsSync(sourceFile) || statSync(sourceFile).size !== file.sizeBytes || sha256(sourceFile) !== file.sha256) fail(`add-on file verification failed: ${file.name}`);
+    verifyAdoptedSignature({ file, sourceFile, platform: manifest.platform, sourceFixture: Boolean(options.source) });
+    const subdir = file.role === "command" || file.role === "service" ? "bin" : file.role === "icon" || LEGAL(file.role) ? "resources" : "resources";
+    mkdirSync(path.join(stage, subdir), { recursive: true });
+    const installed = path.join(stage, subdir, file.name);
+    copyFileSync(sourceFile, installed);
+    // Tauri resolves externalBin artifacts by Rust target triple. Keep the
+    // portable role name too, then provide the required target-qualified alias.
+    if (file.role === "command" || file.role === "service") {
+      const base = file.name.replace(/\.exe$/i, "");
+      const suffix = manifest.platform === "win" ? `${base}-${manifest.targetTriple}.exe` : `${base}-${manifest.targetTriple}`;
+      const alias = path.join(stage, "bin", suffix);
+      copyFileSync(sourceFile, alias);
+      const adoptedSha256 = sha256(alias);
+      if (adoptedSha256 !== file.sha256) fail(`adopted alias hash mismatch: ${file.name}`);
+      adoptedFiles.push({ role: file.role, name: file.name, sealedSha256: file.sha256, adoptedName: `bin/${suffix}`, adoptedSha256 });
+    }
+  }
+  copyFileSync(path.join(source, "addon-manifest.json"), path.join(stage, "addon-manifest.json"));
+  // Directory rename is atomic on one filesystem. Move any previous add-on
+  // aside first, restore it if replacement fails, then clean it only after the
+  // new verified tree is in place.
+  const previous = `${destination}.previous-${process.pid}`;
+  mkdirSync(output, { recursive: true });
+  if (existsSync(destination)) renameSync(destination, previous);
+  try {
+    renameSync(stage, destination);
+  } catch (error) {
+    if (existsSync(previous)) renameSync(previous, destination);
+    throw error;
+  }
+  rmSync(previous, { recursive: true, force: true });
+  if (temporary) rmSync(temporary, { recursive: true, force: true });
+  const repoRoot = git(path.dirname(lockPath), ["rev-parse", "--show-toplevel"]);
+  const receipt = path.join(repoRoot, ".right-release", "addons", "adoptions", `${manifest.addon}-${manifest.platform}.json`);
+  mkdirSync(path.dirname(receipt), { recursive: true });
+  writeFileSync(receipt, `${JSON.stringify({ schema: 1, addon: manifest.addon, platform: manifest.platform, manifestSha256: entry.manifestSha256, manifestUrl: entry.manifestUrl, output: destination, files: adoptedFiles, adoptedAt: new Date().toISOString() }, null, 2)}\n`);
+  console.log(`right-release addon adopt: ${destination}`);
+  console.log(`receipt: ${receipt}`);
+}
+
+function verifyAdoptedSignature({ file, sourceFile, platform, sourceFixture }) {
+  if (!file.executable) return;
+  if (file.signing.contract === "test-fixture-v1" && sourceFixture && process.env.RIGHT_RELEASE_TEST_FIXTURE === "1") return;
+  if (platform === "mac") {
+    if (file.signing.contract !== "apple-developer-id-executable-v1") fail(`unexpected mac signing contract: ${file.name}`);
+    const output = command("codesign", ["-dv", "--verbose=4", sourceFile], path.dirname(sourceFile));
+    if (!/TeamIdentifier=6KLGD3LLKF/.test(output)) fail(`codesign team mismatch: ${file.name}`);
+    run("codesign", ["--verify", "--strict", "--verbose=2", sourceFile], path.dirname(sourceFile));
+  } else {
+    if (file.signing.contract !== "azure-artifact-signing-v1") fail(`unexpected Windows signing contract: ${file.name}`);
+    run(process.execPath, [SIGN_WINDOWS, "--verify-only", sourceFile], path.dirname(sourceFile));
+  }
+}
+
+function LEGAL(role) { return new Set(["license", "eula", "privacy", "third-party-notices"]).has(role); }
+function parse(args) { const value = { platform: process.platform === "win32" ? "win" : "mac", dryRun: false }; for (let i = 0; i < args.length; i += 1) { const key = args[i]; if (key === "--dry-run") value.dryRun = true; else if (["--config", "--platform", "--tier", "--lock", "--output", "--source"].includes(key)) value[key.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = args[++i]; else fail(`unknown argument: ${key}`); } return value; }
+function git(cwd, args) { return command("git", args, cwd).trim(); }
+function command(cmd, args, cwd) { const result = spawnSync(cmd, args, { cwd, encoding: "utf8", windowsHide: true }); if (result.status !== 0) throw new Error(`${cmd} ${args.join(" ")} failed: ${result.stderr || result.stdout}`); return `${result.stdout ?? ""}${result.stderr ?? ""}`; }
+function run(cmd, args, cwd) { command(cmd, args, cwd); }
+function wrangler(args, cwd) { return spawnSync("pnpm", ["dlx", "wrangler@4", ...args], { cwd, encoding: "utf8", windowsHide: true }); }
+function sha256(file) { return createHash("sha256").update(readFileSync(file)).digest("hex"); }
+function usage(code) { console.log("usage: right-release addon doctor|build|upload|adopt --platform mac|win ..."); process.exit(code); }
+function fail(message) { console.error(`right-release addon: ${message}`); process.exit(1); }

package/addon-command.test.mjs

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import test from "node:test";
+import { createAddonManifest, addonManifestSha256, canonicalAddonManifest, downloadImmutableAddOn } from "./addon-contract.mjs";
+
+const command = fileURLToPath(new URL("./addon-command.mjs", import.meta.url));
+function fixture() {
+  const root = mkdtempSync(path.join(os.tmpdir(), "right-addon-command-"));
+  mkdirSync(path.join(root, "legal")); mkdirSync(path.join(root, "assets"));
+  for (const name of ["LICENSE", "EULA.txt", "PRIVACY.md", "THIRD-PARTY-NOTICES.txt"]) writeFileSync(path.join(root, "legal", name), name);
+  writeFileSync(path.join(root, "assets", "tab.png"), "icon");
+  const files = [["command", "membrane", "out/membrane", true], ["service", "crypt-service", "out/crypt-service", true], ["icon", "membrane-tab-icon.png", "assets/tab.png", false], ["license", "LICENSE", "legal/LICENSE", false], ["eula", "EULA.txt", "legal/EULA.txt", false], ["privacy", "PRIVACY.md", "legal/PRIVACY.md", false], ["third-party-notices", "THIRD-PARTY-NOTICES.txt", "legal/THIRD-PARTY-NOTICES.txt", false]].map(([role, name, source, executable]) => ({ role, name, source, executable }));
+  writeFileSync(path.join(root, "right-addon.config.mjs"), `export default ${JSON.stringify({ schema: 1, kind: "headless-addon", addon: "membrane", version: "0.1.0", packageManager: "pnpm", checks: [], buildInputs: { include: ["right-addon.config.mjs"] }, consumer: { contract: "orthic-product-v1" }, targets: { mac: { targetTriple: "aarch64-apple-darwin", build: { cmd: "false", args: [] }, signing: { contract: "apple-developer-id-executable-v1", teamId: "6KLGD3LLKF" }, files }, win: { targetTriple: "x86_64-pc-windows-msvc", build: { cmd: "false", args: [] }, signing: { contract: "azure-artifact-signing-v1" }, files } } }, null, 2)};\n`);
+  execFileSync("git", ["init", "--initial-branch", "main"], { cwd: root }); execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: root }); execFileSync("git", ["config", "user.name", "Test"], { cwd: root }); execFileSync("git", ["add", "."], { cwd: root }); execFileSync("git", ["commit", "-m", "init"], { cwd: root });
+  return root;
+}
+test("add-on dry-run creates no release state and never executes build", () => {
+  const root = fixture(); const result = spawnSync(process.execPath, [command, "build", "--config", "right-addon.config.mjs", "--platform", "mac", "--dry-run"], { cwd: root, encoding: "utf8" });
+  assert.equal(result.status, 0, result.stderr); assert.match(result.stdout, /would run: false/); assert.equal(existsSync(path.join(root, ".right-release")), false);
+});
+
+test("local adoption verifies lock and stages portable plus Tauri-qualified binaries", async () => {
+  const root = fixture(); const config = (await import(`${pathToFileURL(path.join(root, "right-addon.config.mjs")).href}?test=${Date.now()}`)).default;
+  mkdirSync(path.join(root, "out")); writeFileSync(path.join(root, "out", "membrane"), "command"); writeFileSync(path.join(root, "out", "crypt-service"), "service");
+  const manifest = createAddonManifest({ config, root, platform: "mac", commit: "d".repeat(40), signing: { command: { contract: "test-fixture-v1", status: "verified" }, service: { contract: "test-fixture-v1", status: "verified" } } });
+  const sealed = path.join(root, "sealed"); mkdirSync(sealed);
+  for (const file of manifest.files) writeFileSync(path.join(sealed, file.name), readFileSync(path.join(root, config.targets.mac.files.find((entry) => entry.role === file.role).source)));
+  writeFileSync(path.join(sealed, "addon-manifest.json"), canonicalAddonManifest(manifest));
+  const digest = addonManifestSha256(manifest); const lock = path.join(root, "membrane.lock.json"); writeFileSync(lock, JSON.stringify({ targets: { mac: { manifestUrl: `https://example.test/membrane/addons/mac/sha256/${digest}/addon-manifest.json`, manifestSha256: digest } } }));
+  const output = path.join(root, "addons"); const unsigned = spawnSync(process.execPath, [command, "adopt", "--platform", "mac", "--lock", lock, "--output", `${output}-unsigned`, "--source", sealed], { cwd: root, encoding: "utf8", env: { ...process.env, RIGHT_RELEASE_TEST_FIXTURE: "" } });
+  assert.notEqual(unsigned.status, 0); assert.match(unsigned.stderr, /unexpected mac signing contract/);
+  const result = spawnSync(process.execPath, [command, "adopt", "--platform", "mac", "--lock", lock, "--output", output, "--source", sealed], { cwd: root, encoding: "utf8", env: { ...process.env, RIGHT_RELEASE_TEST_FIXTURE: "1" } });
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(readFileSync(path.join(output, "membrane", "bin", "membrane-aarch64-apple-darwin"), "utf8"), "command");
+  assert.equal(readFileSync(path.join(output, "membrane", "resources", "LICENSE"), "utf8"), "LICENSE");
+  const receipt = JSON.parse(readFileSync(path.join(root, ".right-release", "addons", "adoptions", "membrane-mac.json"), "utf8"));
+  assert.equal(receipt.manifestSha256, digest);
+  assert.deepEqual(receipt.files.map((file) => [file.role, file.sealedSha256, file.adoptedSha256]), [["command", manifest.files.find((file) => file.role === "command").sha256, manifest.files.find((file) => file.role === "command").sha256], ["service", manifest.files.find((file) => file.role === "service").sha256, manifest.files.find((file) => file.role === "service").sha256]]);
+});
+
+test("remote downloader accepts only immutable manifest plus file routes", async () => {
+  const root = fixture(); const config = (await import(`${pathToFileURL(path.join(root, "right-addon.config.mjs")).href}?remote=${Date.now()}`)).default;
+  mkdirSync(path.join(root, "out")); writeFileSync(path.join(root, "out", "membrane"), "command"); writeFileSync(path.join(root, "out", "crypt-service"), "service");
+  const manifest = createAddonManifest({ config, root, platform: "mac", commit: "e".repeat(40), signing: { command: { contract: "test-fixture-v1", status: "verified" }, service: { contract: "test-fixture-v1", status: "verified" } } });
+  const digest = addonManifestSha256(manifest); const base = `https://example.test/membrane/addons/mac/sha256/${digest}/`; const bytes = new Map([[`${base}addon-manifest.json`, Buffer.from(canonicalAddonManifest(manifest))], ...manifest.files.map((file) => [base + encodeURIComponent(file.name), readFileSync(path.join(root, config.targets.mac.files.find((entry) => entry.role === file.role).source))])]);
+  const destination = path.join(root, "remote"); mkdirSync(destination);
+  await downloadImmutableAddOn(`${base}addon-manifest.json`, destination, { fetchImpl: async (url) => ({ ok: bytes.has(url), status: bytes.has(url) ? 200 : 404, arrayBuffer: async () => bytes.get(url) }) });
+  assert.equal(readFileSync(path.join(destination, "crypt-service"), "utf8"), "service");
+});

package/addon-contract.mjs

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const ROLES = new Set(["command", "service", "icon", "license", "eula", "privacy", "third-party-notices"]);
+const LEGAL_ROLES = new Set(["license", "eula", "privacy", "third-party-notices"]);
+const PLATFORM = new Set(["mac", "win"]);
+
+export function validateAddonConfig(config, { root, platform, allowMissingExecutables = false }) {
+  if (!PLATFORM.has(platform)) throw new Error("add-on platform must be mac or win");
+  if (!config || config.schema !== 1 || config.kind !== "headless-addon") throw new Error("add-on config must use schema 1 headless-addon");
+  for (const key of ["addon", "version", "packageManager"]) if (typeof config[key] !== "string" || !SAFE_NAME.test(config[key])) throw new Error(`unsafe add-on ${key}`);
+  if (!Array.isArray(config.checks)) throw new Error("add-on checks must be an array");
+  validateBuildInputs(config.buildInputs);
+  const target = config.targets?.[platform];
+  if (!target?.targetTriple || !target?.build?.cmd || !Array.isArray(target.build.args)) throw new Error(`add-on ${platform} target requires targetTriple and build command`);
+  if (!target.signing?.contract) throw new Error(`add-on ${platform} target requires signing contract`);
+  if (platform === "mac" && target.signing.contract === "apple-developer-id-executable-v1" && !/^[A-Z0-9]{10}$/.test(target.signing.teamId ?? "")) throw new Error("mac add-on requires Developer ID teamId");
+  const files = resolveAddonFiles(config, root, platform);
+  const seenRoles = new Set();
+  const seenNames = new Set();
+  for (const file of files) {
+    if (!ROLES.has(file.role) || seenRoles.has(file.role)) throw new Error(`duplicate or unsafe add-on role: ${file.role}`);
+    if (!SAFE_NAME.test(file.name) || file.name.includes("..")) throw new Error(`unsafe add-on file name: ${file.name}`);
+    if (path.isAbsolute(file.source) || file.source.split(/[\\/]/).includes("..")) throw new Error(`unsafe add-on source: ${file.source}`);
+    if (seenNames.has(file.name)) throw new Error(`duplicate add-on file name: ${file.name}`);
+    if (!existsSync(path.resolve(root, file.source)) && !(allowMissingExecutables && file.executable === true)) throw new Error(`missing add-on file: ${file.source}`);
+    seenRoles.add(file.role); seenNames.add(file.name);
+  }
+  for (const role of ["command", "service", "icon", ...LEGAL_ROLES]) if (!seenRoles.has(role)) throw new Error(`missing required add-on role: ${role}`);
+  return { target, files };
+}
+
+export function resolveAddonFiles(config, root, platform) {
+  const configured = config.targets?.[platform]?.files ?? config.files;
+  if (!Array.isArray(configured)) throw new Error("add-on config requires files with role, name, and source");
+  return configured.map((file) => ({ ...file, executable: file.executable === true, source: String(file.source ?? "") }));
+}
+
+export function createAddonManifest({ config, root, platform, commit, signedAt = new Date().toISOString(), signing = {} }) {
+  const { target, files } = validateAddonConfig(config, { root, platform });
+  if (!/^[0-9a-f]{40}$/i.test(commit)) throw new Error("add-on commit must be a full Git SHA");
+  const manifestFiles = files.map((file) => {
+    const source = path.resolve(root, file.source);
+    const executable = file.executable === true;
+    if ((file.role === "command" || file.role === "service") && !executable) throw new Error(`executable role must declare executable: ${file.role}`);
+    const signature = signing[file.role] ?? (executable ? { contract: target.signing.contract, status: "verified" } : null);
+    if (executable && (!signature || signature.status !== "verified")) throw new Error(`unsigned executable role: ${file.role}`);
+    return { role: file.role, name: file.name, sha256: sha256(source), sizeBytes: statSync(source).size, executable, signing: signature };
+  });
+  const manifest = { schema: 1, kind: "headless-addon", addon: config.addon, version: config.version, commit, platform, targetTriple: target.targetTriple, consumer: config.consumer, files: manifestFiles, signedAt };
+  validateAddonManifest(manifest);
+  return manifest;
+}
+
+export function validateAddonManifest(manifest) {
+  const expected = ["schema", "kind", "addon", "version", "commit", "platform", "targetTriple", "consumer", "files", "signedAt"];
+  assertExactKeys(manifest, expected, "add-on manifest");
+  if (manifest.schema !== 1 || manifest.kind !== "headless-addon" || !SAFE_NAME.test(manifest.addon) || !SAFE_NAME.test(manifest.version)) throw new Error("invalid add-on manifest identity");
+  if (!PLATFORM.has(manifest.platform) || !/^[0-9a-f]{40}$/i.test(manifest.commit) || !Array.isArray(manifest.files)) throw new Error("invalid add-on manifest platform or files");
+  const roles = new Set(); const names = new Set();
+  for (const file of manifest.files) {
+    assertExactKeys(file, ["role", "name", "sha256", "sizeBytes", "executable", "signing"], "add-on file");
+    if (!ROLES.has(file.role) || roles.has(file.role) || !SAFE_NAME.test(file.name) || names.has(file.name)) throw new Error("duplicate or unsafe add-on manifest file");
+    if (!/^[0-9a-f]{64}$/i.test(file.sha256) || !Number.isSafeInteger(file.sizeBytes) || file.sizeBytes < 0 || typeof file.executable !== "boolean") throw new Error("invalid add-on file integrity");
+    if (file.executable && (!file.signing || file.signing.status !== "verified")) throw new Error(`unsigned executable role: ${file.role}`);
+    roles.add(file.role); names.add(file.name);
+  }
+  for (const role of ["command", "service", "icon", ...LEGAL_ROLES]) if (!roles.has(role)) throw new Error(`missing required add-on role: ${role}`);
+  return manifest;
+}
+
+export function canonicalAddonManifest(manifest) { validateAddonManifest(manifest); return `${JSON.stringify(manifest)}\n`; }
+export function addonManifestSha256(manifest) { return createHash("sha256").update(canonicalAddonManifest(manifest)).digest("hex"); }
+export function addonRoutes(manifest) {
+  const digest = addonManifestSha256(manifest);
+  const root = `${manifest.addon}/addons/${manifest.platform}/sha256/${digest}`;
+  return [...manifest.files.map((file) => ({ name: file.name, key: `${root}/${file.name}`, sha256: file.sha256, manifest: false })), { name: "addon-manifest.json", key: `${root}/addon-manifest.json`, sha256: digest, manifest: true }];
+}
+
+export async function downloadImmutableAddOn(manifestUrl, destination, { fetchImpl = fetch } = {}) {
+  if (!/^https:\/\//.test(manifestUrl) || !manifestUrl.endsWith("/addon-manifest.json") || /[?#]/.test(manifestUrl)) throw new Error("add-on lock manifestUrl must be an immutable HTTPS manifest URL");
+  const download = async (url, file) => {
+    const response = await fetchImpl(url, { cache: "no-store" });
+    if (!response.ok) throw new Error(`immutable add-on download failed: ${response.status} ${url}`);
+    writeFileSync(file, Buffer.from(await response.arrayBuffer()));
+  };
+  await download(manifestUrl, path.join(destination, "addon-manifest.json"));
+  const manifest = JSON.parse(readFileSync(path.join(destination, "addon-manifest.json"), "utf8"));
+  validateAddonManifest(manifest);
+  const base = manifestUrl.slice(0, -"addon-manifest.json".length);
+  for (const file of manifest.files) await download(`${base}${encodeURIComponent(file.name)}`, path.join(destination, file.name));
+}
+
+function validateBuildInputs(inputs) {
+  if (!Array.isArray(inputs?.include) || !inputs.include.length || inputs.include.some((entry) => typeof entry !== "string" || path.isAbsolute(entry) || entry.split(/[\\/]/).includes(".."))) throw new Error("add-on buildInputs.include must be safe and non-empty");
+}
+function sha256(file) { return createHash("sha256").update(readFileSync(file)).digest("hex"); }
+function assertExactKeys(value, keys, label) { if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).sort().join("\0") !== [...keys].sort().join("\0")) throw new Error(`${label} has unsupported fields`); }

package/addon-contract.test.mjs

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { addonManifestSha256, addonRoutes, createAddonManifest, validateAddonConfig, validateAddonManifest } from "./addon-contract.mjs";
+
+function fixture() {
+  const root = mkdtempSync(path.join(os.tmpdir(), "right-addon-contract-"));
+  mkdirSync(path.join(root, "bin")); mkdirSync(path.join(root, "assets")); mkdirSync(path.join(root, "legal"));
+  for (const [file, bytes] of [["bin/membrane", "membrane"], ["bin/crypt-service", "service"], ["assets/tab.png", "icon"], ["legal/LICENSE", "license"], ["legal/EULA.txt", "eula"], ["legal/PRIVACY.md", "privacy"], ["legal/THIRD-PARTY-NOTICES.txt", "notice"]]) writeFileSync(path.join(root, file), bytes);
+  const files = [
+    ["command", "membrane", "bin/membrane", true], ["service", "crypt-service", "bin/crypt-service", true], ["icon", "membrane-tab-icon.png", "assets/tab.png", false],
+    ["license", "LICENSE", "legal/LICENSE", false], ["eula", "EULA.txt", "legal/EULA.txt", false], ["privacy", "PRIVACY.md", "legal/PRIVACY.md", false], ["third-party-notices", "THIRD-PARTY-NOTICES.txt", "legal/THIRD-PARTY-NOTICES.txt", false],
+  ].map(([role, name, source, executable]) => ({ role, name, source, executable }));
+  return { root, config: { schema: 1, kind: "headless-addon", addon: "membrane", version: "0.1.0", packageManager: "pnpm", checks: ["test"], buildInputs: { include: ["right-addon.config.mjs"] }, consumer: { contract: "orthic-product-v1" }, targets: { mac: { targetTriple: "aarch64-apple-darwin", build: { cmd: "cargo", args: ["build"] }, signing: { contract: "apple-developer-id-executable-v1", teamId: "6KLGD3LLKF" }, files }, win: { targetTriple: "x86_64-pc-windows-msvc", build: { cmd: "cargo", args: ["build"] }, signing: { contract: "azure-artifact-signing-v1" }, files } } } };
+}
+
+test("add-on manifest has portable immutable identity and routes", () => {
+  const { root, config } = fixture();
+  const signing = { command: { contract: "test", status: "verified" }, service: { contract: "test", status: "verified" } };
+  const manifest = createAddonManifest({ config, root, platform: "mac", commit: "a".repeat(40), signedAt: "2026-08-11T00:00:00.000Z", signing });
+  assert.deepEqual(Object.keys(manifest), ["schema", "kind", "addon", "version", "commit", "platform", "targetTriple", "consumer", "files", "signedAt"]);
+  const digest = addonManifestSha256(manifest); const routes = addonRoutes(manifest);
+  assert.equal(routes.at(-1).manifest, true);
+  assert.match(routes[0].key, new RegExp(`^membrane/addons/mac/sha256/${digest}/`));
+  assert.ok(routes.slice(0, -1).every((route) => !route.manifest));
+});
+
+test("add-on contract rejects unsafe, incomplete, duplicate, and unsigned inputs", () => {
+  const { root, config } = fixture();
+  const broken = structuredClone(config); broken.targets.mac.files[0].source = "../escape";
+  assert.throws(() => validateAddonConfig(broken, { root, platform: "mac" }), /unsafe add-on source/);
+  const duplicate = structuredClone(config); duplicate.targets.mac.files[1].role = "command";
+  assert.throws(() => validateAddonConfig(duplicate, { root, platform: "mac" }), /duplicate/);
+  const signing = { command: { contract: "test", status: "verified" }, service: { contract: "test", status: "verified" } };
+  const manifest = createAddonManifest({ config, root, platform: "mac", commit: "b".repeat(40), signing });
+  manifest.files.find((file) => file.role === "command").signing = null;
+  assert.throws(() => validateAddonManifest(manifest), /unsigned executable/);
+});
+
+test("manifest excludes source and mutable transport fields", () => {
+  const { root, config } = fixture();
+  const manifest = createAddonManifest({ config, root, platform: "win", commit: "c".repeat(40), signing: { command: { contract: "test", status: "verified" }, service: { contract: "test", status: "verified" } } });
+  const text = JSON.stringify(manifest);
+  assert.doesNotMatch(text, /source|path|url|token/i);
+  assert.equal(readFileSync(path.join(root, "bin", "membrane"), "utf8"), "membrane");
+});

package/build-release.mjs

@@ -29,6 +29,17 @@ import { buildPathPrefix, collectPreflight, formatPreflight, preflightFailures }
 import { assertCleanSource } from "./source-gate.mjs";
 import { acquireHeavyWorkSlot, heavyCommandEnvironment, terminateProcessTree } from "./heavy-command.mjs";
 
+// Fingerprint of the pipeline code that can change the bytes we ship or the way
+// they are signed — deliberately NOT the package version, which moves for docs
+// and test-only edits and would force a cold Rust rebuild of every app each time.
+// These four files are the ones whose behaviour the cached target directory can
+// outlive.
+const PIPELINE_FINGERPRINT_SOURCES = ["release.mjs", "sign-windows.mjs", "tauri-bundle-marker.mjs", "nsis-payload.mjs"];
+const PIPELINE_FINGERPRINT = createHash("sha256")
+  .update(PIPELINE_FINGERPRINT_SOURCES.map((file) => `${file}:${createHash("sha256").update(readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), file))).digest("hex")}`).join("\n"))
+  .digest("hex")
+  .slice(0, 16);
+
 /** Assemble preflight inputs from the app's own files (mirrors release.mjs). */
 function buildPreflight({ config, configPath, appRoot, repoRoot, platform }) {
   let version;
@@ -88,6 +99,23 @@ let cacheLease;
 let heavySlot;
 let interrupted;
 
+// A dry-run is an inspection contract, not a partial build. It must finish
+// before locks, cache directories, receipts, dependency installation, or any
+// child build/sign process can exist.
+if (dryRun) {
+  const commit = git(invocationRoot, ["rev-parse", "HEAD"]);
+  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}?dry-run=${commit}`)).default;
+  if (!config?.app || !config?.version) fail("release config must expose app and version");
+  const target = config.targets?.[platform];
+  if (!target?.package) fail(`${config.app} has no ${platform} package command`);
+  console.log(`right-release build dry-run: ${config.app} ${config.version} ${platform}`);
+  console.log(`config: ${configPath}`);
+  console.log(`commit: ${commit}`);
+  process.exit(0);
+}
+
 for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
   process.once(signal, () => {
     if (child?.pid) killTree(child.pid);
@@ -124,8 +152,13 @@ try {
   const receiptRoot = path.resolve(process.env.RIGHT_RELEASE_STATE_ROOT ?? path.join(appRoot, ".right-release", "receipts"));
   const signingIdentity = platform === "win" ? {
     contract: target.signingContract ?? "<missing>",
+    // Pipeline code participates in cache identity. Without it, a fix to the
+    // signing or packaging logic leaves the previous logic's target directory
+    // eligible for reuse — which is how outputs from a known-bad pipeline
+    // outlived the change that was supposed to retire them.
+    pipeline: PIPELINE_FINGERPRINT,
     configSha256: hashFile(configPath),
-    receiptInputs: ["raw-exe", "installer"].map((phase) => path.join(receiptRoot, `windows-${phase}.json`)),
+    receiptInputs: ["raw-exe", "installer", "embedding"].map((phase) => path.join(receiptRoot, `windows-${phase}.json`)),
   } : null;
   if (signingIdentity) inputHashes[".right-release/signing-identity.json"] = hashFileText(JSON.stringify(signingIdentity));
   const cargoLock = requiredInputs.find((file) => /Cargo\.lock$/i.test(file));

package/build-release.test.mjs

@@ -1,10 +1,24 @@
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 
 const source = readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "build-release.mjs"), "utf8");
+const build = path.join(path.dirname(fileURLToPath(import.meta.url)), "build-release.mjs");
+
+test("general build dry-run is filesystem-pure and never starts its package command", () => {
+  const root = mkdtempSync(path.join(os.tmpdir(), "right-build-dry-run-"));
+  writeFileSync(path.join(root, "right-release.config.mjs"), "export default { app: 'fixture', version: '1.0.0', targets: { mac: { package: { cmd: 'false' } } } };\n");
+  for (const args of [["init", "--initial-branch", "main"], ["config", "user.email", "test@example.com"], ["config", "user.name", "Test"], ["add", "."], ["commit", "-m", "init"]]) execFileSync("git", args, { cwd: root });
+  const before = readdirSync(root).sort();
+  const result = spawnSync(process.execPath, [build, "--config", "right-release.config.mjs", "--platform", "mac", "--dry-run"], { cwd: root, encoding: "utf8" });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /build dry-run/);
+  assert.deepEqual(readdirSync(root).sort(), before);
+});
 
 test("macOS and Windows builds default to Cache V2 while explicit legacy mode remains available", () => {
   assert.match(source, /assertCleanSource/);

package/cargo-contract.mjs

@@ -85,6 +85,15 @@ function readCargoManifestDependencies(manifestPath, cargoHome, label) {
       windowsHide: true,
     },
   );
+  if (result.error) {
+    // spawnSync failed to launch the process at all (no exit code, no stderr) -
+    // a missing/unspawnable binary, not cargo rejecting the manifest. Reporting
+    // this as a version-contract violation sent a real diagnosis (a Windows
+    // rustup-proxy binary that can't be spawned from a non-console session)
+    // down the wrong path: it read as "fix your Cargo.toml" instead of "cargo
+    // could not be launched here".
+    throw new Error(`${label} could not launch ${cargoExecutable()} to read Cargo metadata: ${result.error.message}`);
+  }
   if (result.status !== 0) {
     throw new Error(`${label} Cargo metadata rejected manifest; RightKit dependencies must use exact crates.io versions: ${String(result.stderr ?? "").trim()}`);
   }

package/cli/right-release.mjs

@@ -61,6 +61,8 @@ if (first === "--version" || first === "-v") {
     process.exit(2);
   }
   run("model-promote.mjs", rest.slice(1));
+} else if (first === "addon") {
+  run("addon-command.mjs", args.slice(1));
 } else if (first === "lsclean") {
   runBinary("bash", [path.join(packageRoot, "lsclean.sh"), ...args.slice(1)]);
 } else if (first === "generate-dmg-background") {
@@ -133,6 +135,7 @@ Commands:
   publish swift [--scope <s>] [--url <u>] [--dry-run] Test, archive, scan, and publish RightKitSwift to a Swift registry
   model promote --authority heardright --config <file> [--dry-run]
                                                       Sign and promote one runtime/model artifact
+  addon doctor|build|upload|adopt <options>           Manage a signed headless add-on
   doctor [--platform mac|win]                        Inspect one app's release config
   doctor --all                                       Verify all Right Suite app release contracts
   suite-doctor                                       Verify all local Right Suite repositories