@rightkit/release 0.2.174 → 0.4.0

package/dist-scan.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// Fails when a built web bundle (vite `dist/`) carries dev, mock or fixture code (replaces per-app
+// checkReleaseBundle.mjs copies). Scans text files for forbidden marker strings and flags chunk file
+// names that match a forbidden name pattern. Read-only: it never writes, builds or follows a symlink.
+// Usage: right-release dist-scan --dist <dir> --forbid <string>... [--forbid-file <path>]
+//          [--forbid-name <regex>]... [--ext js,mjs,css,html,json,map]
+// A --forbid-file is JSON (`["a","b"]` or `{ "forbid": [...], "forbidNames": [...] }`) or plain text with
+// one marker per line (blank lines and `#` comments ignored).
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_EXTENSIONS = Object.freeze(["js", "mjs", "css", "html", "json", "map"]);
+export const DEFAULT_FORBIDDEN_NAMES = Object.freeze([/^(devSource|mockDataSource|fixtures)[-.]/]);
+
+export function parseForbidFile(text, name = "forbid file") {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+    let data;
+    try { data = JSON.parse(trimmed); } catch (error) { throw new Error(`${name}: invalid JSON (${error.message})`); }
+    const forbid = Array.isArray(data) ? data : data.forbid ?? [];
+    const forbidNames = Array.isArray(data) ? [] : data.forbidNames ?? [];
+    if (!Array.isArray(forbid) || !Array.isArray(forbidNames) || ![...forbid, ...forbidNames].every((s) => typeof s === "string" && s)) throw new Error(`${name}: entries must be non-empty strings`);
+    return { forbid, forbidNames };
+  }
+  return { forbid: trimmed.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith("#")), forbidNames: [] };
+}
+
+/** Scan `dist`. Returns { dist, files, scanned, markers, offenders: [{file, reason}] }. */
+export function scanDist(dist, { forbid = [], forbidNames = [], extensions = DEFAULT_EXTENSIONS } = {}) {
+  const root = resolve(dist);
+  if (!existsSync(root) || !statSync(root).isDirectory()) throw new Error(`No ${root}: build first.`);
+  const nameRes = [...DEFAULT_FORBIDDEN_NAMES, ...forbidNames.map((pattern) => {
+    try { return new RegExp(pattern); } catch (error) { throw new Error(`--forbid-name ${JSON.stringify(pattern)} is not a regular expression (${error.message})`); }
+  })];
+  const extRe = new RegExp(`\\.(${extensions.map((e) => e.replace(/[^\w]/g, "")).filter(Boolean).join("|")})$`);
+  const offenders = [];
+  let files = 0;
+  let scanned = 0;
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) { walk(path); continue; }
+      files += 1;
+      const rel = relative(root, path);
+      if (nameRes.some((re) => re.test(basename(path)))) offenders.push({ file: rel, reason: "forbidden chunk name" });
+      if (!extRe.test(path)) continue;
+      scanned += 1;
+      const text = readFileSync(path, "utf8");
+      for (const marker of forbid) if (text.includes(marker)) offenders.push({ file: rel, reason: `marker: ${marker}` });
+    }
+  };
+  walk(root);
+  return { dist: root, files, scanned, markers: forbid.length, offenders };
+}
+
+export function distScanFailed(result) {
+  return result.offenders.length > 0 || result.files === 0 || result.markers === 0;
+}
+
+const USAGE = "usage: right-release dist-scan --dist <dir> --forbid <string>... [--forbid-file <path>] [--forbid-name <regex>]... [--ext js,css,...]";
+
+export function parseArgs(argv) {
+  const out = { dist: null, forbid: [], forbidNames: [], extensions: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const value = () => { const v = argv[++i]; if (v === undefined || v.startsWith("--")) throw new Error(`${a} needs a value`); return v; };
+    if (a === "--dist") out.dist = value();
+    else if (a === "--forbid") out.forbid.push(value());
+    else if (a === "--forbid-name") out.forbidNames.push(value());
+    else if (a === "--ext") out.extensions = value().split(",").filter(Boolean);
+    else if (a === "--forbid-file") {
+      const file = value();
+      const parsed = parseForbidFile(readFileSync(file, "utf8"), file);
+      out.forbid.push(...parsed.forbid);
+      out.forbidNames.push(...parsed.forbidNames);
+    } else throw new Error(`unknown argument ${a}`);
+  }
+  if (!out.dist) throw new Error("--dist is required");
+  return out;
+}
+
+export function main(argv) {
+  let result;
+  try {
+    const args = parseArgs(argv);
+    if (args.forbid.length === 0) throw new Error("no --forbid markers given");
+    result = scanDist(args.dist, args);
+  } catch (error) {
+    console.error(`right-release dist-scan: ${error.message}\n${USAGE}`);
+    return 2;
+  }
+  if (distScanFailed(result)) {
+    console.error(`Release bundle contains forbidden code:\n${result.offenders.map((o) => `${o.file}: ${o.reason}`).join("\n") || `no files in ${result.dist}`}`);
+    return 1;
+  }
+  console.log(`Release bundle clean: ${result.markers} markers absent from ${result.dist} (${result.scanned} files scanned)`);
+  return 0;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) process.exit(main(process.argv.slice(2)));

package/dmg-build.mjs

@@ -7,6 +7,10 @@ import { readDmgSpec } from "./dmg-spec.mjs";
 import { detachWithRetrySync } from "./hdiutil-detach.mjs";
 import { assertReleaseExecutionAllowed } from "./execution-policy.mjs";
 import { assertNoQaControl } from "./qa-control-scan.mjs";
+import { signMacosEntries, validateCodesignIdentifier } from "./mac-sign-core.mjs";
+import { MACOS_PORTABLE_SIGNING_CONTRACT } from "./macos-signing-contract.mjs";
+import { resolveMacosDeveloperIdIdentity } from "./macos-signing-identity.mjs";
+import { runMacCodesignCommands } from "./macos-signing-session.mjs";
 
 const fail = (code, message) => Object.assign(new Error(message), { code });
 const pair = (value, label, positive = false) => {
@@ -25,12 +29,44 @@ export function resolveDmgOptions(input = {}) {
   return spec ? { ...readDmgSpec(spec, { app: explicit.app }), ...definedOnly(explicit) } : explicit;
 }
 
+/**
+ * Developer ID sign a finished disk image (#646): secure timestamp, no hardened runtime (a disk image has none), an
+ * optional stable `--identifier`, strict verification, and an optional signing receipt (the sign-macos.mjs shape) so a
+ * later notarize step can bind to it. It never notarizes or uploads. Developer ID only: no ad hoc or Apple Development fallback.
+ */
+export function signBuiltDmg({ file, identifier, receipt }) {
+  const identity = resolveMacosDeveloperIdIdentity();
+  const files = signMacosEntries([{ file, hardenedRuntime: false, options: [], ...(identifier ? { identifier } : {}) }], {
+    identity,
+    signOne: (codesignArgs) => runMacCodesignCommands([codesignArgs])[0],
+    inspect: (tool, args) => {
+      const result = spawnSync(tool, args, { encoding: "utf8" });
+      const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+      if (result.status !== 0) throw new Error(`${tool} ${args.join(" ")} failed: ${output.trim()}`);
+      return output;
+    },
+  });
+  if (receipt) {
+    mkdirSync(path.dirname(receipt), { recursive: true });
+    writeFileSync(receipt, `${JSON.stringify({ schema: 1, signingContract: MACOS_PORTABLE_SIGNING_CONTRACT, identity, files }, null, 2)}\n`);
+  }
+  return files;
+}
+
+/**
+ * Build the branded DMG; with `sign: true` (CLI `--sign`) it is then Developer ID signed (`identifier`, `signReceipt`
+ * optional) and a signing failure removes the unsigned image so nothing downstream can pick it up. `signDmg` is injectable.
+ */
 export function buildDmg(input = {},
 { platform = process.platform, run = spawnSync, makeAlias = backgroundAlias,
-  log = (event) => console.error(JSON.stringify(event)), sleep } = {}) {
+  log = (event) => console.error(JSON.stringify(event)), sleep, signDmg = signBuiltDmg } = {}) {
   if (platform !== "darwin") throw fail("DMG_NATIVE_HOST_REQUIRED", "DMG creation requires macOS");
   let { app, out, volname, background, iconSize = 128, appPosition = [158, 231],
-    applicationsPosition = [492, 231], window = [660, 400], windowPosition = [100, 100], volumeIcon } = resolveDmgOptions(input);
+    applicationsPosition = [492, 231], window = [660, 400], windowPosition = [100, 100], volumeIcon,
+    sign = false, identifier, signReceipt } = resolveDmgOptions(input);
+  if (identifier !== undefined && !sign) throw fail("DMG_INVALID_OPTIONS", "--identifier needs --sign");
+  if (signReceipt !== undefined && !sign) throw fail("DMG_INVALID_OPTIONS", "--receipt needs --sign");
+  if (identifier !== undefined) { try { validateCodesignIdentifier(identifier, "--identifier"); } catch (error) { throw fail("DMG_INVALID_OPTIONS", error.message); } }
   if (!app || !out || !volname) throw fail("DMG_INVALID_OPTIONS", "--app, --out & --volname are required");
   app = path.resolve(app); out = path.resolve(out);
   if (!app.endsWith(".app") || !statSync(app).isDirectory() || !existsSync(path.join(app, "Contents", "Info.plist"))) {
@@ -103,8 +139,18 @@ export function buildDmg(input = {},
     command("/usr/bin/hdiutil", ["convert", rw, "-format", "UDZO", "-imagekey", "zlib-level=9", "-o", compressed]);
     command("/usr/bin/hdiutil", ["verify", compressed]);
     renameSync(compressed, out);
-    log({ event: "dmg-build-completed", out, format: "UDZO" });
-    return { out, format: "UDZO" };
+    let signed;
+    if (sign) {
+      // Developer ID sign the finished image. A failure removes the unsigned image: nothing downstream may pick it up.
+      try { signed = signDmg({ file: out, ...(identifier ? { identifier } : {}), ...(signReceipt ? { receipt: path.resolve(signReceipt) } : {}) }); }
+      catch (error) {
+        rmSync(out, { force: true });
+        throw fail("DMG_SIGN_FAILED", `signing ${out} failed (the unsigned image was removed): ${error.message}`);
+      }
+      log({ event: "dmg-signed", out, ...(identifier ? { identifier } : {}) });
+    }
+    log({ event: "dmg-build-completed", out, format: "UDZO", signed: Boolean(sign) });
+    return { out, format: "UDZO", ...(sign ? { signed: true, signing: signed } : {}) };
   } catch (error) {
     log({ event: "dmg-build-failed", out, code: error.code ?? "DMG_BUILD_FAILED", message: error.message });
     throw error;
@@ -122,8 +168,11 @@ export function parseDmgArguments(args) {
   if (args[0] !== "build") throw fail("DMG_INVALID_OPTIONS", "expected dmg build");
   const flags = new Map([["--app", "app"], ["--out", "out"], ["--volname", "volname"], ["--background", "background"],
     ["--icon-size", "iconSize"], ["--app-position", "appPosition"], ["--applications-position", "applicationsPosition"], ["--window", "window"], ["--window-position", "windowPosition"], ["--volume-icon", "volumeIcon"], ["--spec", "spec"]]);
+  flags.set("--identifier", "identifier"); flags.set("--receipt", "signReceipt");
   const options = {};
   for (let i = 1; i < args.length; i += 2) {
+    // `--sign` is the one value-less flag: Developer ID sign the finished image (#646).
+    if (args[i] === "--sign") { if (options.sign !== undefined) throw fail("DMG_INVALID_OPTIONS", "invalid option: --sign"); options.sign = true; i -= 1; continue; }
     const key = flags.get(args[i]);
     if (!key || options[key] !== undefined || !args[i + 1] || args[i + 1].startsWith("--")) throw fail("DMG_INVALID_OPTIONS", `invalid option: ${args[i]}`);
     options[key] = args[i + 1];

package/github-updater-release.mjs

@@ -1,11 +1,12 @@
 // GitHub Releases lane of `right-release publish-update` (Orthic-Labs/rightkit#237).
 //
 // The updater artifacts and their minisign signatures are the ones the r2-rightapps lane already uses: they are
-// signed once by `sign-updater.mjs` with the suite updater key (the same TAURI_SIGNING_PRIVATE_KEY / key file as
-// every other app), sealed, and re-verified by `verifyPublicationRelease`. This module only turns the same
+// signed once by `sign-updater.mjs` with the suite updater key (loaded from the OS credential store, never a
+// key file), sealed, and re-verified by `verifyPublicationRelease`. This module only turns the same
 // `platforms` map the r2 lane builds ({ <platform>: { signature, url } }) into a Tauri v2 static `latest.json`
 // and uploads it, with the bundles and their `.sig` files, as assets of the GitHub release `v<version>`, so
 // `https://github.com/<owner>/<repo>/releases/latest/download/latest.json` resolves. It adds no key and no trust root.
+import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { PublicationError, digestBytes, readVerifiedArtifact, verifyArtifactFile } from "./publication-artifacts.mjs";
@@ -58,13 +59,75 @@ export function githubLatestJsonUrl(repo) {
  * [2-byte algorithm][8-byte key id, little endian][64-byte signature].
  */
 export function updaterSignatureKeyId(signatureText) {
+  return parseMinisignSignature(signatureText)?.keyId ?? null;
+}
+
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+function parseMinisignSignature(signatureText) {
+  try {
+    const decode = (text) => {
+      if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(text)) throw new Error("invalid base64");
+      const bytes = Buffer.from(text, "base64");
+      if (bytes.toString("base64") !== text) throw new Error("invalid base64");
+      return bytes;
+    };
+    const envelope = decode(String(signatureText).trim());
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(envelope);
+    const lines = text.split(/\r?\n/);
+    if (lines.at(-1) === "") lines.pop();
+    if (lines.length !== 4 || !lines[2].startsWith("trusted comment: ")) return null;
+    const raw = decode(lines[1]);
+    const globalSignature = decode(lines[3]);
+    if (globalSignature.length !== 64) return null;
+    if (raw.length !== 74) return null;
+    const algorithm = raw.subarray(0, 2).toString("latin1");
+    if (algorithm !== "Ed" && algorithm !== "ED") return null;
+    return { algorithm, keyId: Buffer.from(raw.subarray(2, 10)).reverse().toString("hex").toUpperCase(), signature: raw.subarray(10), globalSignature, trustedComment: Buffer.from(lines[2].slice(17), "utf8") };
+  } catch { return null; }
+}
+
+function parseMinisignPublicKey(publicKeyText) {
+  const text = String(publicKeyText ?? "").trim();
   try {
-    const lines = Buffer.from(String(signatureText).trim(), "base64").toString("utf8").split(/\r?\n/);
+    const lines = Buffer.from(text, "base64").toString("utf8").split(/\r?\n/);
     const raw = Buffer.from(lines[1] ?? "", "base64");
-    if (raw.length !== 74 || raw[0] !== 0x45 || (raw[1] !== 0x64 && raw[1] !== 0x44)) return null;
-    return Buffer.from(raw.subarray(2, 10)).reverse().toString("hex").toUpperCase();
-  } catch {
-    return null;
+    if (raw.length === 42 && ["Ed", "ED"].includes(raw.subarray(0, 2).toString("latin1"))) {
+      return { keyId: Buffer.from(raw.subarray(2, 10)).reverse().toString("hex").toUpperCase(), key: raw.subarray(10) };
+    }
+  } catch { /* fall through to raw forms */ }
+  try {
+    const raw = Buffer.from(text, "base64");
+    if (raw.length === 42 && ["Ed", "ED"].includes(raw.subarray(0, 2).toString("latin1"))) return { keyId: Buffer.from(raw.subarray(2, 10)).reverse().toString("hex").toUpperCase(), key: raw.subarray(10) };
+    if (raw.length === 32) return { keyId: null, key: raw };
+  } catch { /* invalid below */ }
+  return null;
+}
+
+/**
+ * Cryptographic minisign (Ed25519) verification over the EXACT artifact bytes. `Ed` signatures
+ * cover the bytes directly; `ED` signatures cover their BLAKE2b-512 prehash. Returns false (never
+ * throws) for any malformed signature/key, key-id mismatch, or bad signature.
+ */
+export function verifyMinisignSignature(bytes, signatureText, publicKeyText) {
+  const sig = parseMinisignSignature(signatureText);
+  const pub = parseMinisignPublicKey(publicKeyText);
+  if (!sig || !pub || (pub.keyId && pub.keyId !== sig.keyId)) return false;
+  try {
+    const data = sig.algorithm === "ED" ? createHash("blake2b512").update(bytes).digest() : Buffer.from(bytes);
+    const key = createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, pub.key]), format: "der", type: "spki" });
+    return cryptoVerify(null, data, key, sig.signature)
+      && cryptoVerify(null, Buffer.concat([sig.signature, sig.trustedComment]), key, sig.globalSignature);
+  } catch { return false; }
+}
+
+/**
+ * Require a cryptographically valid minisign signature over `bytes` under the declared public key.
+ * The key-id check (`assertUpdaterKeyId`) is supplementary only; this is the seal/upload gate.
+ */
+export function assertUpdaterSignature(bytes, signatureText, publicKeyText, label = "updater signature") {
+  if (!verifyMinisignSignature(bytes, signatureText, publicKeyText)) {
+    throw new PublicationError("PUBLICATION_SIGNATURE_INVALID", `${label} does not cryptographically verify over the exact artifact bytes under the declared updater public key`);
   }
 }
 

package/icon-pack.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// App icon packers (bogusyogi/rightkit#675): assemble a Windows ICO or a macOS ICNS from per-size PNG frames, so
+// hand-tuned small frames (16/24/32/48) are kept exactly as drawn instead of being down-scaled from one master.
+//   right-release icons ico  --out <file.ico>  --frame <PNG>... [--dir <folder of <size>.png>]
+//   right-release icons icns --out <file.icns> --frame <PNG>... [--dir <folder of <size>.png>]
+// Every frame must be a square PNG; its size comes from its IHDR, never from the file name. ICO frames are stored
+// as PNG (Vista+), sizes 1..256. ICNS accepts 16, 32, 64, 128, 256, 512 and 1024. Pure Buffer work, any host.
+// Rendering a master image to PNG frames and DMG background art stay with the app's design source
+// (dmg background: generate-dmg-background.py).
+import { readFileSync, readdirSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+export const ICNS_TYPES = Object.freeze({ 16: "icp4", 32: "icp5", 64: "icp6", 128: "ic07", 256: "ic08", 512: "ic09", 1024: "ic10" });
+function fail(message, code = "ICON_INVALID") { throw Object.assign(new Error(message), { code }); }
+
+/** Read the pixel size of a square PNG from its IHDR. */
+export function pngSize(bytes, label = "frame") {
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  if (buf.length < 33 || !buf.subarray(0, 8).equals(PNG_MAGIC) || buf.toString("latin1", 12, 16) !== "IHDR") fail(`${label} is not a PNG`);
+  const width = buf.readUInt32BE(16), height = buf.readUInt32BE(20);
+  if (width !== height) fail(`${label} must be square, got ${width}x${height}`);
+  // Walk the chunk list: IHDR first (13 bytes), at least one IDAT, IEND last with nothing after it.
+  if (buf.readUInt32BE(8) !== 13) fail(`${label} has a malformed IHDR chunk`);
+  let at = 8, idat = false, iend = false, first = true;
+  while (at < buf.length) {
+    if (at + 12 > buf.length) fail(`${label} is a truncated PNG`);
+    const length = buf.readUInt32BE(at), type = buf.toString("latin1", at + 4, at + 8);
+    if (at + 12 + length > buf.length) fail(`${label} is a truncated PNG`);
+    if (iend) fail(`${label} has data after IEND`);
+    if (first && type !== "IHDR") fail(`${label} is not a PNG`);
+    first = false;
+    if (type === "IDAT") idat = true;
+    if (type === "IEND") iend = true;
+    at += 12 + length;
+  }
+  if (!idat) fail(`${label} has no image data (IDAT)`);
+  if (!iend) fail(`${label} is missing IEND`);
+  const depth = buf[24], colorType = buf[25];
+  if (depth !== 8 || colorType !== 6) fail(`${label} must be 8-bit RGBA (color type 6, bit depth 8), got bit depth ${depth}, color type ${colorType}`);
+  return width;
+}
+
+function normalizeFrames(frames, { min = 1, max = 1024, only = null } = {}) {
+  if (!Array.isArray(frames) || frames.length === 0) fail("at least one PNG frame is required", "ICON_USAGE");
+  const bySize = new Map();
+  for (const frame of frames) {
+    const bytes = Buffer.isBuffer(frame) ? frame : Buffer.from(frame);
+    const size = pngSize(bytes);
+    if (size < min || size > max || (only && !only.includes(size))) fail(`unsupported frame size ${size}${only ? ` (allowed: ${only.join(", ")})` : ` (allowed ${min}..${max})`}`);
+    if (bySize.has(size)) fail(`duplicate ${size}x${size} frame`);
+    bySize.set(size, bytes);
+  }
+  return [...bySize.entries()].sort((a, b) => a[0] - b[0]);
+}
+
+/** @param {Buffer[]} frames PNG buffers, one per size (1..256). @returns {Buffer} ICO file. */
+export function packIco(frames) {
+  const sorted = normalizeFrames(frames, { max: 256 });
+  const header = Buffer.alloc(6 + 16 * sorted.length);
+  header.writeUInt16LE(0, 0); header.writeUInt16LE(1, 2); header.writeUInt16LE(sorted.length, 4);
+  let offset = header.length;
+  sorted.forEach(([size, png], i) => {
+    const at = 6 + i * 16;
+    header[at] = size === 256 ? 0 : size; header[at + 1] = size === 256 ? 0 : size;
+    header.writeUInt16LE(1, at + 4); header.writeUInt16LE(32, at + 6);
+    header.writeUInt32LE(png.length, at + 8); header.writeUInt32LE(offset, at + 12);
+    offset += png.length;
+  });
+  return Buffer.concat([header, ...sorted.map(([, png]) => png)]);
+}
+
+/** @param {Buffer[]} frames PNG buffers (16, 32, 64, 128, 256, 512, 1024). @returns {Buffer} ICNS file. */
+export function packIcns(frames) {
+  const sorted = normalizeFrames(frames, { only: Object.keys(ICNS_TYPES).map(Number) });
+  const chunks = sorted.map(([size, png]) => {
+    const head = Buffer.alloc(8);
+    head.write(ICNS_TYPES[size], 0, "latin1"); head.writeUInt32BE(png.length + 8, 4);
+    return Buffer.concat([head, png]);
+  });
+  const total = 8 + chunks.reduce((n, c) => n + c.length, 0);
+  const head = Buffer.alloc(8);
+  head.write("icns", 0, "latin1"); head.writeUInt32BE(total, 4);
+  return Buffer.concat([head, ...chunks]);
+}
+
+function parseArgs(argv) {
+  const [kind, ...rest] = argv;
+  const opts = { kind, out: null, frames: [], dirs: [] };
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i], value = rest[i + 1];
+    if (!["--out", "--frame", "--dir"].includes(arg)) fail(`unknown icons argument: ${arg}`, "ICON_USAGE");
+    if (value === undefined || value.startsWith("--")) fail(`${arg} needs a value`, "ICON_USAGE");
+    i += 1;
+    if (arg === "--out") opts.out = value; else if (arg === "--frame") opts.frames.push(value); else opts.dirs.push(value);
+  }
+  if (!["ico", "icns"].includes(kind) || !opts.out) fail("usage: right-release icons ico|icns --out <file> --frame <PNG>... [--dir <folder>]", "ICON_USAGE");
+  for (const dir of opts.dirs) for (const name of readdirSync(dir).filter((n) => n.toLowerCase().endsWith(".png")).sort()) opts.frames.push(path.join(dir, name));
+  return opts;
+}
+
+export function main(argv = process.argv.slice(2), out = console) {
+  try {
+    const opts = parseArgs(argv);
+    const frames = opts.frames.map((file) => readFileSync(file));
+    const bytes = opts.kind === "ico" ? packIco(frames) : packIcns(frames);
+    mkdirSync(path.dirname(path.resolve(opts.out)), { recursive: true });
+    writeFileSync(opts.out, bytes);
+    out.log(JSON.stringify({ out: opts.out, kind: opts.kind, frames: opts.frames.length, bytes: bytes.length }));
+    return 0;
+  } catch (error) {
+    out.error(error.message);
+    return error.code === "ICON_USAGE" ? 2 : 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) process.exit(main());

package/in-place-install.mjs

@@ -4,10 +4,10 @@ import path from "node:path";
 /**
  * The one install rule for every app, helper and dev or QA binary (Adrian, 2026-10-17: "No new id, no new folder"):
  * macOS and Windows tie privacy grants to the path and the code identity, so an install or update replaces the
- * copy at ONE fixed path. Release installs may keep a persistent `<name>.previous` beside it (rename it back).
- * Dev and QA installs NEVER keep an old copy (Orthic-Labs/rightkit#348: "when installing dev, old copy must never be
- * backedup"): they pass `previous: null` to `swapInPlace`, or use `replaceFileInPlace`, which has no backup at all.
- * Nothing ever runs from `.previous` or from the staging copy.
+ * copy at ONE fixed path. NO install keeps a retained `<name>.previous` copy (D01/#771): a `previous` path passed
+ * to `swapInPlace` is only a TRANSIENT park for the old copy while the new one is verified; it is deleted on
+ * success and, on failure, the parked copy is renamed back and the park path is gone. Nothing ever runs from
+ * `.previous` or from the staging copy. A stale `<destination>.previous` left by an older RightKit is removed.
  */
 export const PREVIOUS_SUFFIX = ".previous";
 export const STAGING_SUFFIX = ".staging";
@@ -24,16 +24,16 @@ const exists = (fs, file) => {
 /**
  * Swap `staging` into `destination`, then `verify(destination)` runs.
  *
- * With a `previous` path (release): the old destination becomes `previous` (replacing any older `.previous`). Any
- * failure removes the new copy and renames `previous` back, so the fixed path is never left empty. Renames only.
- * @returns {{destination: string, previous: string|null}} previous is null when nothing was installed before.
+ * With a `previous` path: the old destination is parked there ONLY until verification passes, then deleted
+ * (never retained as a rollback copy). Any failure removes the new copy and renames the parked copy back,
+ * so the fixed path is never left empty and no `.previous` remains either way. Renames only.
+ * @returns {{destination: string, previous: null}} previous is always null: no copy is retained.
  *
- * With `previous: null` (dev and QA, NO backup of any kind): the old destination is removed and `staging` is renamed
- * over the fixed path; a stale `<destination>.previous` left by an older RightKit is removed too. Any failure removes
- * the new (absent or partial) copy and the staging copy and rethrows; the old copy is NOT restored, the user reinstalls
- * from an older build. `previous` is always null in the result.
+ * With `previous: null` (NO park of any kind): the old destination is removed and `staging` is renamed
+ * over the fixed path. Any failure removes the new (absent or partial) copy and the staging copy and
+ * rethrows; the old copy is NOT restored, the user reinstalls from an older build.
  */
-export function swapInPlace({ staging, destination, previous = previousPathOf(destination), verify = () => {}, fs = nodeFs }) {
+export function swapInPlace({ staging, destination, previous = null, verify = () => {}, fs = nodeFs }) {
   if (previous === null) return replaceWithoutBackup({ staging, destination, verify, fs });
   if (previous === destination || staging === destination || staging === previous) throw new Error("swapInPlace needs three distinct paths");
   let movedAside = false;
@@ -51,7 +51,10 @@ export function swapInPlace({ staging, destination, previous = previousPathOf(de
     try { fs.rmSync(staging, { recursive: true, force: true }); } catch { /* best effort */ }
     throw error;
   }
-  return { destination, previous: movedAside ? previous : null };
+  // Verified: the transient park (and any stale retained copy) is deleted, never kept.
+  try { if (movedAside) fs.rmSync(previous, { recursive: true, force: true }); } catch { /* best effort */ }
+  try { fs.rmSync(previousPathOf(destination), { recursive: true, force: true }); } catch { /* best effort */ }
+  return { destination, previous: null };
 }
 
 function replaceWithoutBackup({ staging, destination, verify, fs }) {
@@ -65,7 +68,7 @@ function replaceWithoutBackup({ staging, destination, verify, fs }) {
     try { fs.rmSync(staging, { recursive: true, force: true }); } catch { /* best effort */ }
     throw error;
   }
-  // No old copy may survive a dev install, including one an older RightKit left behind.
+  // No old copy may survive an install, including one an older RightKit left behind.
   try { fs.rmSync(previousPathOf(destination), { recursive: true, force: true }); } catch { /* best effort */ }
   return { destination, previous: null };
 }

package/init-command.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// `right-release init --name <App Name> --id <reverse.dns.bundle.id> [--slug <lowercase>] [--dir <root>] [--dry-run]`
+// (bogusyogi/rightkit#385): renames the desktop app template into a real app, in place. Ports PostRight's
+// crates/tools/src/init.rs. The template identity (`RightApp`, `rightapp`, `RIGHTAPP`, `app.rightsuite.rightapp`)
+// is rewritten in text files; nothing else is touched and no gate or build is run.
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SKIP_DIRS = new Set(["node_modules", "target", ".git", "dist", "gen"]);
+export const TEXT_EXT = new Set(["json", "toml", "mjs", "ts", "tsx", "rs", "md", "html", "css", "yaml", "yml", "sh"]);
+// Assembled so this file is not rewritten into the new identity when the template is renamed.
+const TITLE = ["Right", "App"].join("");
+const LOWER = ["right", "app"].join("");
+const UPPER = ["RIGHT", "APP"].join("");
+const TEMPLATE_ID = `app.rightsuite.${LOWER}`;
+const SELF = path.basename(fileURLToPath(import.meta.url));
+
+export const INIT_USAGE = "usage: right-release init --name <Product Name> --id <reverse.dns.bundle.id> [--slug <lowercase>] [--dir <root>] [--dry-run]";
+
+export function parseInitArgs(argv) {
+  const opts = { name: undefined, id: undefined, slug: undefined, dir: ".", dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (["--name", "--id", "--slug", "--dir"].includes(arg)) {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("--")) throw new Error(`${arg} needs a value\n${INIT_USAGE}`);
+      opts[arg.slice(2)] = value;
+      i += 1;
+    } else if (arg === "--dry-run") opts.dryRun = true;
+    else throw new Error(`unknown init argument: ${arg}\n${INIT_USAGE}`);
+  }
+  if (!opts.name || !opts.id) throw new Error(INIT_USAGE);
+  return opts;
+}
+
+/** Validate and derive the identity. `slug` defaults to the lowercased name without spaces. */
+export function resolveIdentity({ name, id, slug }) {
+  const resolvedSlug = slug ?? name.replaceAll(" ", "").toLowerCase();
+  if (!/^[A-Za-z][A-Za-z0-9 ]*$/.test(name)) throw new Error(`name must be letters, digits and spaces starting with a letter: ${name}\n${INIT_USAGE}`);
+  if (!/^[a-z][a-z0-9]*$/.test(resolvedSlug)) throw new Error(`slug must be lowercase letters and digits starting with a letter: ${resolvedSlug}\n${INIT_USAGE}`);
+  if (!/^[A-Za-z][A-Za-z0-9-]*(\.[A-Za-z][A-Za-z0-9-]*)+$/.test(id)) throw new Error(`id must be a reverse-DNS bundle id with at least two segments: ${id}\n${INIT_USAGE}`);
+  const warnings = [];
+  if (name.replaceAll(" ", "").toLowerCase() !== resolvedSlug) {
+    warnings.push(`--name "${name}" lowercased is not slug "${resolvedSlug}"; check productName and installer names.`);
+  }
+  if (!id.toLowerCase().endsWith(`.${resolvedSlug}`)) {
+    warnings.push(`--id "${id}" does not end in .${resolvedSlug}; check the bundle id.`);
+  }
+  return { name, id, slug: resolvedSlug, warnings };
+}
+
+export function walkTextFiles(dir, out = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) walkTextFiles(full, out);
+    } else if (entry.isFile() && TEXT_EXT.has(path.extname(entry.name).slice(1))) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/** Rewrite the template identity in one string; the bundle id first, then the three spellings. */
+export function renameText(text, { name, id, slug }) {
+  return text
+    .replaceAll(TEMPLATE_ID, id)
+    .replaceAll(UPPER, slug.toUpperCase())
+    .replaceAll(TITLE, name)
+    .replaceAll(LOWER, slug);
+}
+
+/** Rename the template under `root`. Returns the identity and the changed file paths (relative, sorted). */
+export function initTemplate(root, options) {
+  const identity = resolveIdentity(options);
+  const changed = [];
+  for (const file of walkTextFiles(root)) {
+    if (path.basename(file) === SELF) continue;
+    let before;
+    try {
+      before = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    const after = renameText(before, identity);
+    if (after === before) continue;
+    if (!options.dryRun) writeFileSync(file, after);
+    changed.push(path.relative(root, file).split(path.sep).join("/"));
+  }
+  return { ...identity, changed: changed.sort() };
+}
+
+export function runInitCommand(argv, io = { stdout: console.log, stderr: console.error }) {
+  const opts = parseInitArgs(argv);
+  const result = initTemplate(path.resolve(opts.dir), opts);
+  for (const warning of result.warnings) io.stderr(`warning: ${warning}`);
+  io.stdout(`right-release init${opts.dryRun ? " --dry-run" : ""}: ${result.changed.length} file(s) ${opts.dryRun ? "would change" : "changed"}`);
+  for (const file of result.changed) io.stdout(`  ${file}`);
+  return result;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    runInitCommand(process.argv.slice(2));
+  } catch (error) {
+    console.error(`right-release init: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/install-app-windows.mjs

@@ -18,9 +18,11 @@ import { previousPathOf } from "./in-place-install.mjs";
  *     plus the `--exe` file; entries are relative regular files inside `--dest`, no directories, wildcards, `..` or drive paths;
  *   - with NO declared payload the allowlist is just the `--exe` file (always backed up and restored; nothing else is);
  *   - no path segment from `--dest` down to an allowlisted file may be a symlink or junction (reparse point); one is refused before backup and before restore or removal;
- *   - the backup is `<dest>.previous`, holding only the allowlisted files that existed before (replaced on each install; nothing runs from it);
+ *   - the TRANSIENT backup is `<dest>.previous`, holding only the allowlisted files that existed before; it is
+ *     deleted after a successful install and after a failure restore, so no copy is ever retained (D01);
  *   - a failed install restores only allowlisted files that existed before and removes only allowlisted files the failed run newly wrote;
- *     it never touches any other file in `--dest`.
+ *     it never touches any other file in `--dest`; a stale `<dest>.previous` is cleaned allowlist-scope only,
+ *     never as a whole install directory.
  * Dev installs do not pass through this module: they keep no backup at all (see development.mjs, install-app.mjs --dev).
  */
 export class InstallAppWindowsError extends Error {
@@ -114,8 +116,20 @@ export function installAppWindows(opts, { platform = process.platform, fs = node
       fs.copyFileSync(inDest(relative), inPrevious(relative));
     }
     backupMade = true;
-    event("previous-kept", { previous, files: backedUp.length, payloadOnly: true });
+    event("previous-parked", { previous, files: backedUp.length, payloadOnly: true, transient: true });
   }
+  // Delete the transient park. Ours (backupMade) is exactly the allowlisted scope we just created; a stale
+  // park from an older RightKit is cleaned allowlist-entry by allowlist-entry, never as a whole directory.
+  const cleanupPrevious = () => {
+    try {
+      if (backupMade) { fs.rmSync(previous, { recursive: true, force: true }); return; }
+      for (const relative of allowlist) {
+        const file = inPrevious(relative);
+        if (fs.existsSync(file) && isFile(file)) fs.rmSync(file, { force: true });
+      }
+      try { fs.rmdirSync(previous); } catch { /* non-empty or absent: leave it */ }
+    } catch { /* best effort; never mask the install result */ }
+  };
   // Roll back the payload and nothing else: restore allowlisted files that existed, remove allowlisted files this run newly wrote.
   // Each file is restored independently; failures are collected and reported together, never masking the installer error.
   const restoreFailures = [];
@@ -142,13 +156,16 @@ export function installAppWindows(opts, { platform = process.platform, fs = node
   const result = run(installer, windowsInstallArguments(dest), { stdio: "inherit", windowsHide: true, shell: false });
   if (result.status !== 0) {
     const restored = restore();
-    throw new InstallAppWindowsError("installer-failed", `installer exited ${result.status ?? "abnormally"}${result.error ? `: ${result.error.message}` : ""}; ${restored ? `restored the ${backedUp.length} payload file(s) of ${dest} from ${previous}; no other file was touched` : noRollback}${failureNote()}`);
+    cleanupPrevious();
+    throw new InstallAppWindowsError("installer-failed", `installer exited ${result.status ?? "abnormally"}${result.error ? `: ${result.error.message}` : ""}; ${restored ? `restored the ${backedUp.length} payload file(s) of ${dest} from the transient backup (now deleted); no other file was touched` : noRollback}${failureNote()}; reinstall from the release installer if the app does not launch`);
   }
   // The installer must have updated the fixed folder: the executable is at the same path as before, not in a new folder.
   if (!fs.existsSync(installed) || fs.statSync(installed).size === 0) {
     const restored = restore();
-    throw new InstallAppWindowsError("path-changed", `the installer did not place ${exe} at the fixed path ${installed}; ${restored ? `restored the ${backedUp.length} payload file(s) from ${previous}; no other file was touched` : noRollback}${failureNote()}`);
+    cleanupPrevious();
+    throw new InstallAppWindowsError("path-changed", `the installer did not place ${exe} at the fixed path ${installed}; ${restored ? `restored the ${backedUp.length} payload file(s) from the transient backup (now deleted); no other file was touched` : noRollback}${failureNote()}; reinstall from the release installer if the app does not launch`);
   }
-  event("replaced", { installed, previous: backupMade ? previous : null, sha256: sha256(fs, installed) });
-  return { ok: true, installed, previous: backupMade ? previous : null };
+  cleanupPrevious();
+  event("replaced", { installed, previous: null, sha256: sha256(fs, installed) });
+  return { ok: true, installed, previous: null };
 }