@rightkit/release 0.2.173 → 0.3.0

package/mirror-root-artifact.mjs

@@ -1,11 +1,24 @@
 #!/usr/bin/env node
-import { copyFileSync, lstatSync, mkdirSync, realpathSync, renameSync, rmSync, statSync } from "node:fs";
+// Two forms:
+//   right-release mirror-root-artifact --file <artifact> --package-root <dir> [--name <filename>]
+//   right-release mirror-root-artifact --config <right-release.config.mjs> --platform mac|win [--package-root <dir>]
+// The config form mirrors every entry of `targets.<platform>.mirror`, a list of `"<app-relative file>"` or
+// `{ file, name?, pruneSuffix? }`. `pruneSuffix` (for example "-setup.exe") then removes the other files with that suffix
+// from the managed directory, so it holds exactly the current artifact. Run it as `targets.<platform>.postSign`.
+// Output goes only to RIGHT_RELEASE_ARTIFACT_DIR (outside the repository); it never writes into the repository root.
+import { copyFileSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync } from "node:fs";
 import { execFileSync } from "./background-process.mjs";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
 const args = parseArgs(process.argv.slice(2));
-if (!args.file || !args.packageRoot) {
-  console.error("Usage: right-release mirror-root-artifact --file <artifact> --package-root <dir> [--name <filename>]");
+const usage = "Usage: right-release mirror-root-artifact (--file <artifact> --package-root <dir> [--name <filename>] | --config <file> --platform mac|win [--package-root <dir>])";
+if (!args.config && (!args.file || !args.packageRoot)) {
+  console.error(usage);
+  process.exit(2);
+}
+if (args.config && (!args.platform || args.file)) {
+  console.error(usage);
   process.exit(2);
 }
 if (!process.env.RIGHT_RELEASE_ARTIFACT_DIR) {
@@ -13,33 +26,68 @@ if (!process.env.RIGHT_RELEASE_ARTIFACT_DIR) {
   process.exit(2);
 }
 
-const packageRoot = realpathSync(path.resolve(args.packageRoot));
-const source = path.resolve(packageRoot, args.file);
-const name = args.name || path.basename(source);
+let entries;
+let rootArg = args.packageRoot;
+if (args.config) {
+  const configPath = path.resolve(args.config);
+  const loaded = await import(pathToFileURL(configPath).href);
+  const config = loaded.default ?? loaded.config ?? loaded;
+  const declared = config?.targets?.[args.platform]?.mirror;
+  if (!Array.isArray(declared) || declared.length === 0) {
+    console.error(`right-release mirror-root-artifact: targets.${args.platform}.mirror declares no files in ${args.config}`);
+    process.exit(2);
+  }
+  entries = declared.map((item) => (typeof item === "string" ? { file: item } : item));
+  for (const entry of entries) {
+    const unknown = entry && typeof entry === "object" ? Object.keys(entry).filter((key) => !["file", "name", "pruneSuffix"].includes(key)) : ["(not an object)"];
+    if (typeof entry?.file !== "string" || !entry.file.trim() || unknown.length || path.isAbsolute(entry.file) || entry.file.replaceAll("\\", "/").split("/").includes("..")) {
+      console.error(`right-release mirror-root-artifact: each mirror entry is an app-relative file or { file, name?, pruneSuffix? }: ${JSON.stringify(entry)}`);
+      process.exit(2);
+    }
+  }
+  rootArg ??= path.dirname(configPath);
+} else {
+  entries = [{ file: args.file, name: args.name }];
+}
+
+const packageRoot = realpathSync(path.resolve(rootArg));
 const managedOutput = path.resolve(process.env.RIGHT_RELEASE_ARTIFACT_DIR);
 const repoRoot = path.resolve(git(packageRoot, "rev-parse", "--show-toplevel"));
 if (inside(managedOutput, repoRoot)) {
   console.error(`right-release mirror-root-artifact: managed output must be outside repository: ${managedOutput}`);
   process.exit(2);
 }
-if (name !== path.basename(name) || !/^[A-Za-z0-9][A-Za-z0-9._+-]{0,159}$/.test(name)) {
-  console.error(`right-release mirror-root-artifact: unsafe artifact name: ${name}`);
-  process.exit(2);
-}
-assertSafePath(source);
-if (!statSync(source).isFile()) {
-  console.error(`right-release mirror-root-artifact: source is not a regular file: ${source}`);
-  process.exit(2);
-}
-const destinations = new Set([path.join(managedOutput, name)]);
+const safeName = (name) => name === path.basename(name) && /^[A-Za-z0-9][A-Za-z0-9._+-]{0,159}$/.test(name);
 
-for (const destination of destinations) {
-  if (path.resolve(destination) === source) continue;
-  atomicCopy(source, destination);
+for (const entry of entries) {
+  const source = path.resolve(packageRoot, entry.file);
+  const name = entry.name || path.basename(source);
+  if (!safeName(name)) {
+    console.error(`right-release mirror-root-artifact: unsafe artifact name: ${name}`);
+    process.exit(2);
+  }
+  if (entry.pruneSuffix !== undefined && (typeof entry.pruneSuffix !== "string" || !/^[A-Za-z0-9._+-]{1,40}$/.test(entry.pruneSuffix) || !name.endsWith(entry.pruneSuffix))) {
+    console.error(`right-release mirror-root-artifact: pruneSuffix must be a plain suffix of the artifact name: ${entry.pruneSuffix}`);
+    process.exit(2);
+  }
+  assertSafePath(source);
+  if (!statSync(source).isFile()) {
+    console.error(`right-release mirror-root-artifact: source is not a regular file: ${source}`);
+    process.exit(2);
+  }
+  const destination = path.join(managedOutput, name);
+  if (path.resolve(destination) !== source) atomicCopy(source, destination);
+  if (entry.pruneSuffix) {
+    for (const stale of readdirSync(managedOutput)) {
+      if (stale !== name && stale.endsWith(entry.pruneSuffix) && safeName(stale)) {
+        assertSafePath(path.join(managedOutput, stale));
+        rmSync(path.join(managedOutput, stale), { force: true });
+      }
+    }
+  }
+  console.log(`right-release: managed artifact -> ${destination}`);
 }
 
-console.log(`right-release: managed artifact -> ${[...destinations][0]}`);
-
 function git(cwd, ...commandArgs) {
   return execFileSync("git", commandArgs, { cwd, encoding: "utf8" }).trim();
 }

package/npm-license-notices.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+// `right-release license-notices npm [--config <file>] [--output <file>] [--product-name <name>] [--check]`: writes the
+// third-party npm license appendix (one HTML file) for an app's production dependency closure, from
+// `pnpm licenses list --prod --json`, the installed packages' own LICENSE / COPYING / NOTICE files, and the lockfile hash.
+//
+//   legal: { npmNotices: { output: "legal/THIRD_PARTY_NPM_LICENSES.html", productName: "ViewRight", exclude: ["@rightkit/"] } }
+//
+// `output` and `productName` may also come from `--output` / `--product-name`. `exclude` is a list of package-name prefixes left
+// out (default `["@rightkit/"]`). A package that ships no license file gets the standard published text for its declared SPDX
+// license (MIT or ISC), labelled as a fallback; any other license without a file is an error, never invented text.
+// The page records the app version, the sha256 of `pnpm-lock.yaml` and `generated-by=right-release license-notices npm`, so the
+// same inputs always produce the same bytes. `--check` writes nothing and exits 1 when the file on disk differs.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { CommandSpecError, loadAppConfig, relativeInside } from "./command-spec.mjs";
+
+const fail = (message) => { throw new CommandSpecError(message); };
+
+// Generic published SPDX text, used ONLY when an installed package ships no license file of its own.
+export const SPDX_FALLBACK_TEXT = {
+  MIT: `Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.`,
+  ISC: `Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.`,
+};
+
+export const escapeHtml = (value) => String(value)
+  .replaceAll("&", "&amp;")
+  .replaceAll("<", "&lt;")
+  .replaceAll(">", "&gt;")
+  .replaceAll('"', "&quot;");
+
+/** Flatten `pnpm licenses list --json` (license -> entries) into a sorted list, minus excluded name prefixes. */
+export function collectNpmPackages(groups, exclude = ["@rightkit/"]) {
+  return Object.entries(groups)
+    .flatMap(([license, entries]) => entries.map((entry) => ({ ...entry, license })))
+    .filter((entry) => !exclude.some((prefix) => entry.name.startsWith(prefix)))
+    .sort((a, b) => `${a.name}@${a.versions.join(",")}`.localeCompare(`${b.name}@${b.versions.join(",")}`));
+}
+
+/**
+ * Render the appendix. `readNames(dir)` lists a package directory and `readText(file)` reads one file (both injectable).
+ * Returns `{ html, packageCount, fallbackCount }`.
+ */
+export function renderNpmNotices({ productName, version, lockHash, packages, readNames = (dir) => readdirSync(dir), readText = (file) => readFileSync(file, "utf8") }) {
+  let fallbackCount = 0;
+  const sections = packages.map((entry) => {
+    const packageRoot = entry.paths[0];
+    const files = readNames(packageRoot).filter((name) => /^(?:license|copying|notice)(?:[._-]|$)/i.test(name)).sort();
+    let texts;
+    if (files.length) {
+      texts = files.map((name) => `<h3>${escapeHtml(name)}</h3><pre>${escapeHtml(readText(path.join(packageRoot, name)))}</pre>`).join("\n");
+    } else {
+      const fallback = SPDX_FALLBACK_TEXT[entry.license];
+      if (!fallback) {
+        fail(`${entry.name} ${entry.versions.join(", ")} has no packaged license/notice file and no SPDX fallback text for declared license "${entry.license}"; bundle the file or extend SPDX_FALLBACK_TEXT`);
+      }
+      fallbackCount += 1;
+      texts = `<h3>No packaged license file found</h3><p><em>This package's installed npm distribution does not include a LICENSE/COPYING/NOTICE file. The text below is the standard published license text for its declared SPDX license (${escapeHtml(entry.license)}), not package-specific content.</em></p><pre>${escapeHtml(fallback)}</pre>`;
+    }
+    return `<section><h2>${escapeHtml(entry.name)} ${escapeHtml(entry.versions.join(", "))}</h2><p>Declared license: ${escapeHtml(entry.license)}</p>${texts}</section>`;
+  });
+  const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>${escapeHtml(productName)} npm third-party licenses</title></head><body>
+<h1>${escapeHtml(productName)} npm third-party licenses</h1>
+<p>Build provenance: ${escapeHtml(productName)} ${escapeHtml(version)}; inputs: pnpm-lock.yaml sha256=${lockHash}; generated-by=right-release license-notices npm</p>
+${sections.join("\n")}
+</body></html>\n`;
+  return { html, packageCount: packages.length, fallbackCount };
+}
+
+/** Resolve options from config + flags. */
+export function resolveNoticeOptions(config, flags = {}) {
+  const declared = config?.legal?.npmNotices ?? {};
+  if (typeof declared !== "object" || declared === null || Array.isArray(declared)) fail("legal.npmNotices must be an object");
+  const unknown = Object.keys(declared).filter((key) => !["output", "productName", "exclude"].includes(key));
+  if (unknown.length) fail(`legal.npmNotices has unknown key(s): ${unknown.join(", ")} (allowed: output, productName, exclude)`);
+  const output = flags.output ?? declared.output;
+  const productName = flags.productName ?? declared.productName;
+  const exclude = declared.exclude ?? ["@rightkit/"];
+  if (output === undefined) fail("no output file: set legal.npmNotices.output or pass --output");
+  relativeInside(output, "legal.npmNotices.output");
+  if (typeof productName !== "string" || !productName.trim()) fail("no product name: set legal.npmNotices.productName or pass --product-name");
+  if (!Array.isArray(exclude) || exclude.some((prefix) => typeof prefix !== "string")) fail("legal.npmNotices.exclude must be a list of name prefixes");
+  if ((config?.packageManager ?? "pnpm") !== "pnpm") fail(`license-notices npm supports pnpm apps only (config.packageManager is ${config.packageManager})`);
+  return { output, productName, exclude };
+}
+
+/** Generate (or check) the appendix for the app at `appRoot`. `spawnSyncFn` is injectable. */
+export function generateNpmNotices({ appRoot, config, flags = {}, check = false, spawnSyncFn = spawnSync }) {
+  const { output, productName, exclude } = resolveNoticeOptions(config, flags);
+  const version = JSON.parse(readFileSync(path.join(appRoot, "package.json"), "utf8")).version;
+  const result = spawnSyncFn("pnpm", ["licenses", "list", "--prod", "--json"], {
+    cwd: appRoot,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    shell: process.platform === "win32",
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) fail(result.stderr || "pnpm licenses list failed");
+  const packages = collectNpmPackages(JSON.parse(result.stdout), exclude);
+  const lockHash = createHash("sha256").update(readFileSync(path.join(appRoot, "pnpm-lock.yaml"))).digest("hex");
+  const { html, packageCount, fallbackCount } = renderNpmNotices({ productName, version, lockHash, packages });
+  const target = path.join(appRoot, output);
+  if (check) {
+    const current = existsSync(target) ? readFileSync(target, "utf8") : null;
+    return { target, packageCount, fallbackCount, upToDate: current === html };
+  }
+  mkdirSync(path.dirname(target), { recursive: true });
+  writeFileSync(target, html);
+  return { target, packageCount, fallbackCount, upToDate: true };
+}
+
+export function parseNoticeArgs(argv) {
+  const opts = { config: "right-release.config.mjs", output: undefined, productName: undefined, check: false };
+  const rest = argv[0] === "npm" ? argv.slice(1) : argv;
+  if (argv[0] !== "npm") throw new Error("expected: license-notices npm");
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === "--config" || arg === "--output" || arg === "--product-name") {
+      const value = rest[i + 1];
+      if (!value || value.startsWith("--")) throw new Error(`${arg} needs a value`);
+      opts[arg === "--product-name" ? "productName" : arg.slice(2)] = value;
+      i += 1;
+    } else if (arg === "--check") opts.check = true;
+    else throw new Error(`unknown license-notices argument: ${arg}`);
+  }
+  return opts;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const opts = parseNoticeArgs(argv);
+  const { config, appRoot } = await loadAppConfig(opts.config);
+  const outcome = generateNpmNotices({ appRoot, config, flags: { output: opts.output, productName: opts.productName }, check: opts.check });
+  if (opts.check) {
+    if (!outcome.upToDate) {
+      console.error(`right-release license-notices: ${outcome.target} is out of date; run right-release license-notices npm`);
+      return 1;
+    }
+    console.log(`${outcome.target} is up to date (${outcome.packageCount} package notices)`);
+    return 0;
+  }
+  console.log(`wrote ${outcome.packageCount} package notices (${outcome.fallbackCount} used an SPDX fallback text)`);
+  return 0;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().then((code) => { process.exitCode = code; }, (error) => {
+    console.error(`right-release license-notices: ${error.code ? `[${error.code}] ` : ""}${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/ownership-dependency-allowlist.json

@@ -791,6 +791,7 @@
       "repositoryIdentity": "https://github.com/bogusyogi/postright",
       "dependencies": [
         "cargo:jiff",
+        "cargo:serde",
         "cargo:serde_json",
         "cargo:tauri",
         "cargo:tauri-build",

package/ownership.mjs

@@ -156,7 +156,31 @@ function resolveLocalPath(root, sourceFile, pathValue, coverage, display, invent
   } catch { coverage.push({ path: display, status: "unscanned", reason: `${reasonPrefix}-path-unresolved${detail ? `:${detail}` : ""}` }); }
 }
 
-function parseCargo(parsed, file, out, workspace, root, coverage, inventory) {
+// A Git dependency pinned by a full 40-hex `rev` is immutable. When its URL is third-party it is equivalent to a registry
+// dependency and is not a gap (Orthic-Labs/rightkit#677). A first-party URL (Orthic-Labs, bogusyogi, or an org listed in
+// ownership-repositories.json) stays an unscanned fatal gap because first-party code must be scanned. A branch, a tag, a
+// short rev or no rev is always an unscanned coverage gap.
+const FULL_GIT_REV = /^[0-9a-f]{40}$/i;
+export const PINNED_GIT_DEPENDENCY = "pinned-git-dependency";
+const FIRST_PARTY_GIT_ORGS = new Set(["github.com/orthic-labs", "github.com/bogusyogi"]);
+const gitHostOrg = (url) => {
+  const text = String(url).trim();
+  const match = /^(?:[a-z][a-z0-9+.-]*:\/\/)?(?:[^@/\s]+@)?([^/:\s]+)[/:]+([^/\s]+)/i.exec(text);
+  return match ? `${match[1]}/${match[2]}`.toLowerCase() : null;
+};
+let configuredFirstParty;
+function firstPartyGitOrgs() {
+  if (configuredFirstParty) return configuredFirstParty;
+  const orgs = new Set(FIRST_PARTY_GIT_ORGS);
+  try {
+    const config = JSON.parse(readFileSync(new URL("./ownership-repositories.json", import.meta.url), "utf8"));
+    for (const repo of config.repositories ?? []) { const key = gitHostOrg(repo.repositoryIdentity ?? ""); if (key) orgs.add(key); }
+  } catch { /* the built-in first-party orgs still apply */ }
+  return (configuredFirstParty = orgs);
+}
+export const isFirstPartyGitUrl = (url) => { const key = gitHostOrg(url); return key === null || firstPartyGitOrgs().has(key); };
+
+function parseCargo(parsed, file, out, workspace, root, coverage, inventory, covered = []) {
   const pathSpec = (pathValue, sourceFile, display) => {
     resolveLocalPath(root, sourceFile, pathValue, coverage, display, inventory);
   };
@@ -176,7 +200,15 @@ function parseCargo(parsed, file, out, workspace, root, coverage, inventory) {
       if (!raw || typeof raw !== "string" && (typeof raw !== "object" || Array.isArray(raw)) || features.some((x) => typeof x !== "string") || requirement !== null && typeof requirement !== "string") throw new Error(`malformed dependency declaration: ${alias}`);
       addDependency(out, "cargo", name, file, { alias: name === alias ? null : alias, section: `${prefix}${section}`, requirement, features, defaultFeatures: spec["default-features"] ?? inherited["default-features"] ?? null, source, resolvedVersion: null, local: !!pathValue || !!git });
       if (pathValue) pathSpec(pathValue, spec.path ? file : path.posix.join(workspace.dir ?? ".", "Cargo.toml"), file);
-      if (git) coverage.push({ path: file, status: "unscanned", reason: `git-dependency-source:${name}` });
+      if (git) {
+        const rev = spec.rev ?? inherited.rev;
+        const moving = [spec.branch, inherited.branch, spec.tag, inherited.tag].some((value) => value !== undefined);
+        if (typeof git === "string" && typeof rev === "string" && FULL_GIT_REV.test(rev) && !moving && !isFirstPartyGitUrl(git)) {
+          // Immutable third-party source, not a gap: kept out of `coverage` (every coverage row blocks the gate) and reported on
+          // `deps.covered`. `scanned: false` records that the source is pinned, not examined.
+          covered.push({ path: file, status: PINNED_GIT_DEPENDENCY, reason: `git-dependency-source:${name}`, fingerprint: `${git}@${rev.toLowerCase()}`, scanned: false });
+        } else coverage.push({ path: file, status: "unscanned", reason: `git-dependency-source:${name}` });
+      }
     }
     for (const [target, value] of Object.entries(table.target ?? {})) addTable(value, `${prefix}target.'${target}'.`);
   };
@@ -375,7 +407,7 @@ function resolveDependencyVersions(appRoot, inventory, deps, coverage, contentDi
 }
 
 function dependenciesFromInventory(appRoot, inventory) {
-  const deps = [], coverage = [], contentDigests = [];
+  const deps = [], coverage = [], contentDigests = [], covered = [];
   // Workspace inheritance is loaded before member manifests.
   const manifestNames = new Set(["Cargo.toml", "package.json", "Package.swift"]);
   const manifests = inventory.files.filter((x) => manifestNames.has(path.posix.basename(x.rel)));
@@ -419,7 +451,7 @@ function dependenciesFromInventory(appRoot, inventory) {
     if (base === "Cargo.toml") {
       const dir = path.posix.dirname(rel);
       const workspace = workspaces.filter((x) => x.dir === "." || dir === x.dir || dir.startsWith(`${x.dir}/`)).sort((a, b) => b.dir.length - a.dir.length)[0] ?? { dir: ".", deps: {} };
-      try { parseCargo(parseToml(text), rel, deps, workspace, appRoot, coverage, inventory); }
+      try { parseCargo(parseToml(text), rel, deps, workspace, appRoot, coverage, inventory, covered); }
       catch { coverage.push({ path: rel, status: "unscanned", reason: "invalid-cargo-toml" }); }
     }
     else if (base === "package.json") {
@@ -453,6 +485,7 @@ function dependenciesFromInventory(appRoot, inventory) {
   resolveDependencyVersions(appRoot, inventory, deps, coverage, contentDigests);
   Object.defineProperty(deps, "coverage", { value: coverage, enumerable: false });
   Object.defineProperty(deps, "contentDigests", { value: contentDigests, enumerable: false });
+  Object.defineProperty(deps, "covered", { value: covered, enumerable: false });
   Object.defineProperty(deps, "manifests", { value: files, enumerable: false });
   return deps;
 }

package/package-recipe-targets.mjs

@@ -4,7 +4,10 @@
 // marker patch before signing, raw-EXE and installer Authenticode, the NSIS embedding verification, Developer ID
 // signing of the .app and its nested code, app notarization before packing, the signed DMG and its notarization.
 // The standalone recipes (win-package-recipe.mjs, mac-package-recipe.mjs) hold the same steps for direct callers.
+import { existsSync } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveTargetRoot as cargoResolveTargetRoot } from "./cargo-target.mjs";
 import { validateWinPackage, WinPackageConfigError } from "./win-package-recipe.mjs";
 
 export class PackageRecipeTargetError extends Error {
@@ -21,40 +24,166 @@ const withoutRecipe = (target) => {
   return rest;
 };
 const QUIET_TAURI_ENV = { TAURI_SIGNING_PRIVATE_KEY: "", TAURI_SIGNING_PRIVATE_KEY_PASSWORD: "" };
+const RECIPE_BUILD = fileURLToPath(new URL("./recipe-build.mjs", import.meta.url));
+const CREATE_MAC_UPDATER = fileURLToPath(new URL("./create-mac-updater.mjs", import.meta.url));
+const PROFILE = /^[a-z][a-z0-9_-]*$/;
+
+function relativeInside(value, label) {
+  if (typeof value !== "string" || !value.trim()) fail(`${label} must be a non-empty relative path`);
+  const normalized = value.replaceAll("\\", "/");
+  if (path.isAbsolute(value) || /^[A-Za-z]:/.test(value) || normalized.split("/").includes("..")) fail(`${label} must be relative and stay inside the app: ${value}`);
+  return normalized;
+}
+
+/** `prepare` / `postBuild`: a list of { cmd, args?, cwd? } argv commands (no shell). */
+function commandList(value, label) {
+  if (!Array.isArray(value)) fail(`${label} must be an array of { cmd, args?, cwd? }`);
+  return value.map((item, index) => {
+    const where = `${label}[${index}]`;
+    if (!isObject(item)) fail(`${where} must be an object`);
+    const unknown = Object.keys(item).filter((key) => !["cmd", "args", "cwd"].includes(key));
+    if (unknown.length) fail(`${where} has unknown key(s): ${unknown.join(", ")} (allowed: cmd, args, cwd)`);
+    if (typeof item.cmd !== "string" || !item.cmd.trim()) fail(`${where}.cmd must be a non-empty string`);
+    if (item.args !== undefined && (!Array.isArray(item.args) || item.args.some((arg) => typeof arg !== "string"))) fail(`${where}.args must be a list of strings`);
+    return { cmd: item.cmd, args: [...(item.args ?? [])], ...(item.cwd === undefined ? {} : { cwd: relativeInside(item.cwd, `${where}.cwd`) }) };
+  });
+}
+
+/** The keys shared by winPackage and macPackage: profile, tauriConfig, prepare (and postBuild where allowed). */
+function buildExtras(spec, label, { postBuild }) {
+  if (spec.profile !== undefined && (typeof spec.profile !== "string" || !PROFILE.test(spec.profile))) fail(`${label}.profile must be a Cargo profile name`);
+  const tauriConfig = spec.tauriConfig === undefined ? undefined : relativeInside(spec.tauriConfig, `${label}.tauriConfig`);
+  if (tauriConfig && !/\.json$/i.test(tauriConfig)) fail(`${label}.tauriConfig must be a .json file`);
+  return {
+    profile: spec.profile,
+    tauriConfig,
+    prepare: spec.prepare === undefined ? [] : commandList(spec.prepare, `${label}.prepare`),
+    postBuild: !postBuild || spec.postBuild === undefined ? [] : commandList(spec.postBuild, `${label}.postBuild`),
+  };
+}
+
+/** Tauri v2 passes Cargo flags after `--`; the profile also decides where Tauri looks for the built binary. */
+const profileArgs = (extras) => (extras.profile ? ["--", "--profile", extras.profile] : []);
+/** The build command also takes `--jobs N` (Cargo parallelism), after the same `--`. */
+const buildCargoArgs = (extras, jobs) => {
+  const flags = [...(extras.profile ? ["--profile", extras.profile] : []), ...(jobs ? ["--jobs", String(jobs)] : [])];
+  return flags.length ? ["--", ...flags] : [];
+};
+const configArgs = (extras, appRoot, cwd) => (extras.tauriConfig ? ["--config", path.relative(path.resolve(appRoot, cwd), path.resolve(appRoot, extras.tauriConfig)).split(path.sep).join("/")] : []);
+
+/**
+ * release.mjs runs ONE prePackage command: node recipe-build.mjs runs the built-in cleanup, prepare, the Tauri build,
+ * the artifact stability poll and postBuild in order. `cleanup` and `stability` are recipe-build plan sections.
+ */
+function recipeBuildCommand({ extras, build, env, cleanup, stability, timeoutMs }) {
+  const steps = [
+    ...extras.prepare.map((step) => ({ phase: "prepare", ...step })),
+    { phase: "build", cmd: build.cmd, args: build.args, cwd: build.cwd },
+    ...extras.postBuild.map((step) => ({ phase: "postBuild", ...step })),
+  ];
+  const plan = { version: 1, steps, ...(cleanup ? { cleanup } : {}), ...(stability ? { stability } : {}) };
+  return { cmd: process.execPath, args: [RECIPE_BUILD, "--plan", JSON.stringify(plan)], env, ...(timeoutMs ? { timeoutMs } : {}) };
+}
+
+const DEFAULT_WIN_TIMEOUT_MS = 20 * 60 * 1000;
+const positiveInt = (value) => Number.isInteger(value) && value > 0;
+
+/**
+ * Managed Cargo target roots. Artifact paths in a target are declared (and default) under `<cargo dir>/target/...`.
+ * With `cargoTargetRoot` (true: <tauriCwd>/src-tauri/Cargo.toml; or an app-relative Cargo.toml path) or CARGO_TARGET_DIR set
+ * (default manifest), `cargo metadata`'s target_directory is resolved and every declared path under the default
+ * `<cargo dir>/target/` is moved to the real directory. release.mjs needs app-relative paths with no `..`, so a target
+ * directory outside the app fails closed (use RIGHT_RELEASE_ARTIFACT_DIR for copies, see the docs).
+ */
+function targetRootMapper({ spec, appRoot, cwd, env, resolveTargetRoot, label }) {
+  const explicit = spec.cargoTargetRoot;
+  if (explicit !== undefined && explicit !== true && explicit !== false && typeof explicit !== "string") fail(`${label}.cargoTargetRoot must be true or an app-relative Cargo.toml path`);
+  const envDir = typeof env.CARGO_TARGET_DIR === "string" && env.CARGO_TARGET_DIR.trim() !== "";
+  if (explicit === false || (!explicit && !envDir)) return (declared) => declared;
+  const manifestRel = typeof explicit === "string" ? relativeInside(explicit, `${label}.cargoTargetRoot`) : path.posix.join(cwd === "." ? "" : cwd, "src-tauri", "Cargo.toml");
+  const manifest = path.resolve(appRoot, manifestRel);
+  if (typeof explicit !== "string" && explicit !== true && !existsSync(manifest)) return (declared) => declared;
+  let targetDir;
+  try { targetDir = resolveTargetRoot(manifest); } catch (error) { fail(`${label}: cannot resolve the Cargo target directory (${error.message})`); }
+  const prefix = path.posix.join(path.posix.dirname(manifestRel).replace(/^\.$/, ""), "target");
+  return (declared) => {
+    const normalized = String(declared).replaceAll("\\", "/");
+    if (!normalized.startsWith(`${prefix}/`)) return declared;
+    const moved = path.resolve(targetDir, normalized.slice(prefix.length + 1));
+    const relative = path.relative(appRoot, moved).split(path.sep).join("/");
+    if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative) || /^[A-Za-z]:/.test(relative)) {
+      fail(`${label}: the Cargo target directory ${targetDir} is outside the app, so ${declared} cannot be addressed by an app-relative path; point CARGO_TARGET_DIR inside the app or declare the artifact paths yourself`);
+    }
+    return relative;
+  };
+}
+
+function winPrePackage({ extras, cwd, appRoot, triple, jobs, timeoutMs, cleanup, stability }) {
+  const args = ["exec", "tauri", "build", "--no-bundle", "--target", triple, ...configArgs(extras, appRoot, cwd), ...buildCargoArgs(extras, jobs)];
+  return recipeBuildCommand({ extras, build: { cmd: "pnpm", args, cwd }, env: QUIET_TAURI_ENV, cleanup, stability, timeoutMs });
+}
 
 /** `targets.win.winPackage` → prePackage (`tauri build --no-bundle`) and package (`tauri bundle --bundles nsis`). */
-export function expandWinPackageTarget(target, { appRoot, config = {} }) {
+export function expandWinPackageTarget(target, { appRoot, config = {}, env = process.env, resolveTargetRoot = cargoResolveTargetRoot }) {
   if (!target?.winPackage) return withoutRecipe(target);
   if (target.prePackage !== undefined) fail("targets.win.winPackage replaces prePackage; remove the prePackage script");
   if (target.winPackage.sidecars !== undefined) fail("targets.win.winPackage.sidecars is not supported in a right-release target: declare sidecars through externalBin or mediaSidecar, which release.mjs signs with the raw EXE");
+  if (!isObject(target.winPackage)) fail("targets.win.winPackage must be an object");
+  const { profile: _p, tauriConfig: _t, prepare: _pr, postBuild, jobs, timeoutMs, cleanStale, cargoTargetRoot: _c, ...coreSpec } = target.winPackage;
+  if (postBuild !== undefined) fail("targets.win.winPackage.postBuild is not supported: release.mjs signs the raw EXE between the build and the bundle; use prepare");
+  if (jobs !== undefined && !positiveInt(jobs)) fail("targets.win.winPackage.jobs must be a positive integer (Cargo --jobs)");
+  if (timeoutMs !== undefined && !positiveInt(timeoutMs)) fail("targets.win.winPackage.timeoutMs must be a positive integer (milliseconds)");
+  if (cleanStale !== undefined && typeof cleanStale !== "boolean") fail("targets.win.winPackage.cleanStale must be a boolean");
+  const extras = buildExtras(target.winPackage, "targets.win.winPackage", { postBuild: false });
   let plan;
-  try { plan = validateWinPackage({ appRoot, config, target }); } catch (error) {
+  try { plan = validateWinPackage({ appRoot, config, target: { ...target, winPackage: coreSpec } }); } catch (error) {
     if (error instanceof WinPackageConfigError) fail(`targets.win.winPackage: ${(error.issues ?? [error.message]).join("; ")}`);
     throw error;
   }
   if (target.signingContract !== undefined && target.signingContract !== "windows-raw-exe-authenticode-before-nsis-v1") fail(`targets.win.winPackage builds an NSIS installer; signingContract must be windows-raw-exe-authenticode-before-nsis-v1, got ${target.signingContract}`);
   const cwd = rel(plan.appRoot, plan.tauriCwd) || ".";
   const override = { bundle: { createUpdaterArtifacts: false, windows: { nsis: { installMode: plan.perMachine ? "perMachine" : "currentUser" } } } };
+  const mapPath = targetRootMapper({ spec: target.winPackage, appRoot: plan.appRoot, cwd, env, resolveTargetRoot, label: "targets.win.winPackage" });
+  const rawExe = mapPath(rel(plan.appRoot, plan.rawExe));
+  const installerFile = mapPath(rel(plan.appRoot, plan.installerFile));
+  // Stale outputs are removed before the build, and the raw EXE is polled until it stops changing after it.
+  const cleanup = cleanStale === false ? undefined : { remove: [rawExe, installerFile] };
+  const timeout = timeoutMs ?? DEFAULT_WIN_TIMEOUT_MS;
   // `recipe` is set only here: a hand-written one is dropped so it can never select a recipe path.
   const { winPackage, recipe: _ignoredWin, ...rest } = target;
   return {
     ...rest,
     signingContract: "windows-raw-exe-authenticode-before-nsis-v1",
-    prePackage: { cmd: "pnpm", args: ["exec", "tauri", "build", "--no-bundle", "--target", plan.triple], cwd, env: QUIET_TAURI_ENV },
-    package: { cmd: "pnpm", args: ["exec", "tauri", "bundle", "--bundles", "nsis", "--target", plan.triple, "--config", JSON.stringify(override)], cwd, env: QUIET_TAURI_ENV },
-    sign: { ...(target.sign ?? {}), prePackageFiles: [rel(plan.appRoot, plan.rawExe)], files: [rel(plan.appRoot, plan.installerFile)] },
+    prePackage: winPrePackage({ extras, cwd, appRoot: plan.appRoot, triple: plan.triple, jobs, timeoutMs: timeout, cleanup, stability: { files: [rawExe] } }),
+    package: { cmd: "pnpm", args: ["exec", "tauri", "bundle", "--bundles", "nsis", "--target", plan.triple, ...configArgs(extras, plan.appRoot, cwd), "--config", JSON.stringify(override), ...profileArgs(extras)], cwd, env: QUIET_TAURI_ENV, timeoutMs: timeout },
+    sign: { ...(target.sign ?? {}), prePackageFiles: [rawExe], files: [installerFile] },
     recipe: { kind: "winPackage", productName: plan.productName, updater: plan.updater },
   };
 }
 
-const MAC_KEYS = new Set(["universal", "tauriCwd", "features"]);
+const MAC_KEYS = new Set(["universal", "triple", "tauriCwd", "features", "profile", "tauriConfig", "prepare", "postBuild", "cleanup", "cargoTargetRoot", "updater"]);
+const MAC_TRIPLES = ["aarch64-apple-darwin", "x86_64-apple-darwin"];
+const MAC_CLEANUP_KEYS = new Set(["staleApps", "staleDmgVolumes", "lsclean"]);
+
+function macCleanupSpec(value) {
+  if (value === undefined) return {};
+  if (!isObject(value)) fail("targets.mac.macPackage.cleanup must be an object");
+  const unknown = Object.keys(value).filter((key) => !MAC_CLEANUP_KEYS.has(key));
+  if (unknown.length) fail(`targets.mac.macPackage.cleanup has unknown key(s): ${unknown.join(", ")} (allowed: ${[...MAC_CLEANUP_KEYS].join(", ")})`);
+  for (const key of MAC_CLEANUP_KEYS) if (value[key] !== undefined && typeof value[key] !== "boolean") fail(`targets.mac.macPackage.cleanup.${key} must be a boolean`);
+  return value;
+}
 
 /**
  * `targets.mac.macPackage` → prePackage (`tauri build --bundles app`, universal by default), the .app as the
  * Developer ID signing set, app notarization before packing, and right-release's own signed DMG from the stapled app.
  * The app path and DMG path are `notarize.app` and `notarize.file`; DMG branding is `targets.mac.dmg`.
+ * Architecture: `triple` (an explicit arch triple) beats `universal`; `universal: false` means this host's arch.
+ * `cleanup` runs built-in steps in recipe-build before the build (stale DMG volumes, stale .app bundles, lsregister).
+ * `updater: true | "<app-relative .tar.gz>"` emits the Tauri updater tarball and its signature from the signed, stapled .app:
+ * it prepends a `create-mac-updater` command to `postSign` (default output `<App>.app.tar.gz` beside the app's working root).
  */
-export function expandMacPackageTarget(target, { appRoot }) {
+export function expandMacPackageTarget(target, { appRoot, env = process.env, resolveTargetRoot = cargoResolveTargetRoot }) {
   if (!target?.macPackage) return withoutRecipe(target);
   const spec = target.macPackage;
   if (!isObject(spec)) fail("targets.mac.macPackage must be an object");
@@ -66,30 +195,65 @@ export function expandMacPackageTarget(target, { appRoot }) {
   if (target.dmg === false) fail("targets.mac.macPackage always builds a DMG; remove dmg: false");
   if (spec.universal !== undefined && typeof spec.universal !== "boolean") fail("targets.mac.macPackage.universal must be a boolean");
   if (spec.features !== undefined && (!Array.isArray(spec.features) || spec.features.some((f) => typeof f !== "string" || !/^[A-Za-z0-9_,:-]+$/.test(f)))) fail("targets.mac.macPackage.features must be Cargo feature names");
+  if (spec.triple !== undefined && !MAC_TRIPLES.includes(spec.triple)) fail(`targets.mac.macPackage.triple must be one of ${MAC_TRIPLES.join(", ")}`);
   const cwd = spec.tauriCwd ?? ".";
   if (typeof cwd !== "string" || path.isAbsolute(cwd) || cwd.split(/[\\/]/).includes("..")) fail("targets.mac.macPackage.tauriCwd must be a relative path inside the app");
+  const cleanupSpec = macCleanupSpec(spec.cleanup);
+  if (spec.updater !== undefined && spec.updater !== true && spec.updater !== false && typeof spec.updater !== "string") fail("targets.mac.macPackage.updater must be true or an app-relative .tar.gz path");
+  if (typeof spec.updater === "string" && !/\.tar\.gz$/i.test(relativeInside(spec.updater, "targets.mac.macPackage.updater"))) fail("targets.mac.macPackage.updater must end in .tar.gz");
   // Tauri's universal-apple-darwin target builds both slices and lipos them itself.
-  const triple = spec.universal === false ? (process.arch === "arm64" ? "aarch64-apple-darwin" : "x86_64-apple-darwin") : "universal-apple-darwin";
+  const triple = spec.triple ?? (spec.universal === false ? (process.arch === "arm64" ? "aarch64-apple-darwin" : "x86_64-apple-darwin") : "universal-apple-darwin");
+  if (spec.triple !== undefined) {
+    const wrong = [...MAC_TRIPLES, "universal-apple-darwin"].find((other) => other !== triple && target.notarize.app.replaceAll("\\", "/").split("/").includes(other));
+    if (wrong) fail(`targets.mac.macPackage.triple is ${triple} but notarize.app is under ${wrong}; the built .app lives in the ${triple} directory`);
+  }
   const override = { bundle: { createUpdaterArtifacts: false, macOS: { signingIdentity: null } } };
-  const args = ["exec", "tauri", "build", "--target", triple, "--bundles", "app", "--no-sign", "--config", JSON.stringify(override)];
+  const extras = buildExtras(spec, "targets.mac.macPackage", { postBuild: true });
+  const args = ["exec", "tauri", "build", "--target", triple, "--bundles", "app", "--no-sign", ...configArgs(extras, appRoot, cwd), "--config", JSON.stringify(override)];
   if (spec.features?.length) args.push("--features", spec.features.join(","));
-  const prePackageFiles = target.sign?.prePackageFiles ?? [target.notarize.app];
-  if (!prePackageFiles.some((entry) => (typeof entry === "string" ? entry : entry?.file) === target.notarize.app)) fail("targets.mac.macPackage: sign.prePackageFiles must include notarize.app");
+  args.push(...profileArgs(extras));
+  const mapPath = targetRootMapper({ spec, appRoot, cwd, env, resolveTargetRoot, label: "targets.mac.macPackage" });
+  const app = mapPath(target.notarize.app);
+  const entryFile = (entry) => (typeof entry === "string" ? entry : entry?.file);
+  const declaredFiles = target.sign?.prePackageFiles ?? [target.notarize.app];
+  if (!declaredFiles.some((entry) => entryFile(entry) === target.notarize.app)) fail("targets.mac.macPackage: sign.prePackageFiles must include notarize.app");
+  const prePackageFiles = declaredFiles.map((entry) => (typeof entry === "string" ? mapPath(entry) : { ...entry, file: mapPath(entry.file) }));
+  // Built-in cleanup before the build: the bundle dir is where a stale .app lives; DMG volumes are named after the product.
+  const appPosix = app.replaceAll("\\", "/");
+  const productName = path.posix.basename(appPosix, ".app");
+  const volumes = [...new Set([productName, ...(isObject(target.dmg) && typeof target.dmg.volname === "string" ? [target.dmg.volname] : [])])];
+  const cleanup = cleanupSpec.staleApps || cleanupSpec.staleDmgVolumes || cleanupSpec.lsclean
+    ? {
+      ...(cleanupSpec.staleDmgVolumes ? { dmgVolumes: volumes } : {}),
+      ...(cleanupSpec.staleApps || cleanupSpec.lsclean ? { apps: { dir: path.posix.dirname(appPosix), remove: cleanupSpec.staleApps === true, unregister: cleanupSpec.lsclean === true } } : {}),
+    }
+    : undefined;
+  const wrapped = extras.prepare.length || extras.postBuild.length || cleanup;
   const { macPackage, recipe: _ignoredMac, ...rest } = target;
+  // The updater tarball is made from the signed .app, so it runs in postSign, ahead of any postSign the app declares.
+  const updaterOutput = spec.updater === true ? `${productName}.app.tar.gz` : typeof spec.updater === "string" ? relativeInside(spec.updater, "targets.mac.macPackage.updater") : undefined;
+  const postSign = updaterOutput === undefined ? {} : {
+    postSign: [
+      { cmd: process.execPath, args: [CREATE_MAC_UPDATER, "--app", app, "--output", updaterOutput] },
+      ...(target.postSign === undefined ? [] : Array.isArray(target.postSign) ? target.postSign : [target.postSign]),
+    ],
+  };
   return {
     ...rest,
-    prePackage: { cmd: "pnpm", args, cwd, env: QUIET_TAURI_ENV },
+    ...postSign,
+    prePackage: wrapped ? recipeBuildCommand({ extras, build: { cmd: "pnpm", args, cwd }, env: QUIET_TAURI_ENV, cleanup }) : { cmd: "pnpm", args, cwd, env: QUIET_TAURI_ENV },
     sign: { ...(target.sign ?? {}), prePackageFiles },
-    notarize: { ...target.notarize, appBeforePackage: true },
+    notarize: { ...target.notarize, app, appBeforePackage: true },
     dmg: isObject(target.dmg) ? target.dmg : {},
     recipe: { kind: "macPackage", universal: triple === "universal-apple-darwin" },
   };
 }
 
 /** Expand whichever declarative package key the target carries. */
-export function expandPackageRecipeTarget(target, { platform, appRoot, config }) {
-  if (platform === "win") return expandWinPackageTarget(target, { appRoot, config });
-  if (platform === "mac") return expandMacPackageTarget(target, { appRoot, config });
+export function expandPackageRecipeTarget(target, { platform, appRoot, config, env, resolveTargetRoot }) {
+  const injected = { ...(env ? { env } : {}), ...(resolveTargetRoot ? { resolveTargetRoot } : {}) };
+  if (platform === "win") return expandWinPackageTarget(target, { appRoot, config, ...injected });
+  if (platform === "mac") return expandMacPackageTarget(target, { appRoot, config, ...injected });
   if (target?.winPackage || target?.macPackage) fail(`winPackage / macPackage are not valid on ${platform}`);
   return target;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/release",
-  "version": "0.2.173",
+  "version": "0.3.0",
   "description": "Portable release CLI/SDK with fail-closed public GitHub Releases and private R2 + RightApps distribution.",
   "license": "MIT OR Apache-2.0",
   "type": "module",