@rightkit/release 0.2.173 → 0.3.0

package/in-place-install.mjs

@@ -4,8 +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. Rollback is a persistent `<name>.previous` beside it (rename it back). Nothing ever runs
- * from `.previous` or from the staging copy.
+ * 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.
  */
 export const PREVIOUS_SUFFIX = ".previous";
 export const STAGING_SUFFIX = ".staging";
@@ -20,12 +22,19 @@ const exists = (fs, file) => {
 };
 
 /**
- * Swap `staging` into `destination`: the old destination becomes `previous` (replacing any older `.previous`),
- * then `verify(destination)` runs. Any failure removes the new copy and renames `previous` back, so the fixed
- * path is never left empty. Renames only: no copy, no new path.
+ * 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 `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.
  */
 export function swapInPlace({ staging, destination, previous = previousPathOf(destination), 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;
   try {
@@ -45,12 +54,28 @@ export function swapInPlace({ staging, destination, previous = previousPathOf(de
   return { destination, previous: movedAside ? previous : null };
 }
 
-/** Copy one file to its fixed path in place: temp sibling, then rename, keeping `<file>.previous`. Returns the path. */
+function replaceWithoutBackup({ staging, destination, verify, fs }) {
+  if (staging === destination) throw new Error("swapInPlace needs distinct staging and destination paths");
+  try {
+    if (exists(fs, destination)) fs.rmSync(destination, { recursive: true, force: true });
+    fs.renameSync(staging, destination);
+    verify(destination);
+  } catch (error) {
+    try { fs.rmSync(destination, { recursive: true, force: true }); } catch { /* keep the original error */ }
+    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.
+  try { fs.rmSync(previousPathOf(destination), { recursive: true, force: true }); } catch { /* best effort */ }
+  return { destination, previous: null };
+}
+
+/** Copy one dev or QA file to its fixed path in place: temp sibling, then rename. NO backup of the old file. Returns the path. */
 export function replaceFileInPlace(from, destination, { fs = nodeFs } = {}) {
   fs.mkdirSync(path.dirname(destination), { recursive: true });
   const staging = stagingPathOf(destination);
   fs.rmSync(staging, { force: true });
   fs.copyFileSync(from, staging);
-  swapInPlace({ staging, destination });
+  swapInPlace({ staging, destination, previous: null, fs });
   return destination;
 }

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

@@ -5,15 +5,23 @@ import { spawnSync } from "./background-process.mjs";
 import { previousPathOf } from "./in-place-install.mjs";
 
 /**
- * `right-release install-app --installer <Setup.exe> --dest <install folder> --exe <App.exe>` on Windows (Orthic-Labs/rightkit#258).
+ * `right-release install-app --installer <Setup.exe> --dest <install folder> --exe <App.exe> [--payload <file>]... [--payload-manifest <json>]` on Windows (Orthic-Labs/rightkit#258).
  *
  * The same rule as the macOS install: the app is installed and updated IN PLACE at one fixed folder (`--dest`, the
- * folder the NSIS installer already owns, for example `%LOCALAPPDATA%\Programs\Pulse`). Rollback is one
- * `<dest>.previous` beside it (a copy of the folder as it was; replaced on each install; nothing runs from it), never a
- * versioned, digest or per-run folder. The silent installer is pinned to the fixed folder with `/D=` so it cannot choose another one.
+ * folder the NSIS installer already owns, for example `%LOCALAPPDATA%\Programs\Pulse`). The silent installer is pinned to the
+ * fixed folder with `/D=` so it cannot choose another one.
  *
- * Why a copy and not a rename: a running app holds its folder open on Windows, so a rename fails; the installer closes
- * the app and updates the same path in place instead. A failed install copies `<dest>.previous` back over `<dest>`.
+ * DATA SAFETY (Orthic-Labs/rightkit#348): the install folder can also hold USER DATA (CodeRight keeps coderight.db, its WAL,
+ * state and models in `%LOCALAPPDATA%\CodeRight`). So this module NEVER copies, restores, removes or overwrites the whole
+ * install folder. Rollback is PAYLOAD-ONLY, from an explicit allowlist of the files the installer itself writes:
+ *   - the allowlist is `--payload <relative file>` (repeatable) and/or `--payload-manifest <json file>` (`{ "files": [...] }` or a bare array)
+ *     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);
+ *   - 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`.
+ * 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 {
   constructor(code, message) { super(message); this.name = "InstallAppWindowsError"; this.code = code; }
@@ -26,6 +34,40 @@ export function windowsInstallArguments(dest) {
 
 const sha256 = (fs, file) => createHash("sha256").update(fs.readFileSync(file)).digest("hex");
 
+const SEGMENT_BAD = /[<>:"|?*\0]/;
+
+/** One allowlist entry as a normalized `a/b/c` relative file path, or a usage error. */
+function normalizePayloadEntry(entry) {
+  if (typeof entry !== "string" || !entry.trim()) throw new InstallAppWindowsError("usage", "a payload entry must be a non-empty relative file path");
+  if (path.win32.isAbsolute(entry) || path.posix.isAbsolute(entry) || /^[A-Za-z]:/.test(entry)) throw new InstallAppWindowsError("usage", `payload entry ${JSON.stringify(entry)} must be relative to --dest, not absolute`);
+  const segments = entry.split(/[\\/]/);
+  if (segments.some((segment) => segment === "" || segment === "." || segment === ".." || SEGMENT_BAD.test(segment))) {
+    throw new InstallAppWindowsError("usage", `payload entry ${JSON.stringify(entry)} must be a plain relative file path (no directories, wildcards, "..", or empty segments)`);
+  }
+  return segments.join("/");
+}
+
+/** The payload allowlist: `--exe`, `--payload` entries and a `--payload-manifest` file, normalized and de-duplicated. Empty when nothing is declared. */
+export function resolvePayloadAllowlist({ exe, payload = [], payloadManifest = null }, { fs = nodeFs } = {}) {
+  const declared = [...(Array.isArray(payload) ? payload : [payload])];
+  if (payloadManifest) {
+    let parsed;
+    try { parsed = JSON.parse(String(fs.readFileSync(payloadManifest, "utf8"))); }
+    catch (error) { throw new InstallAppWindowsError("usage", `--payload-manifest ${payloadManifest} cannot be read as JSON: ${error.message}`); }
+    const files = Array.isArray(parsed) ? parsed : parsed?.files;
+    if (!Array.isArray(files)) throw new InstallAppWindowsError("usage", `--payload-manifest ${payloadManifest} must be a JSON array of relative files, or { "files": [...] }`);
+    declared.push(...files);
+  }
+  // `--exe` alone is the minimal allowlist: the executable is always backed up and restored; data files never are.
+  const normalized = [...new Set([exe, ...declared].map(normalizePayloadEntry))];
+  const lower = new Set();
+  for (const entry of normalized) {
+    if (lower.has(entry.toLowerCase())) throw new InstallAppWindowsError("usage", `payload entry ${JSON.stringify(entry)} is listed twice (Windows paths are case-insensitive)`);
+    lower.add(entry.toLowerCase());
+  }
+  return normalized.sort();
+}
+
 export function installAppWindows(opts, { platform = process.platform, fs = nodeFs, run = spawnSync, event = () => {} } = {}) {
   if (platform !== "win32") throw new InstallAppWindowsError("unsupported", `the Windows installer mode runs on win32, not ${platform}`);
   const { installer, dest, exe } = opts;
@@ -33,31 +75,80 @@ export function installAppWindows(opts, { platform = process.platform, fs = node
   if (!dest || !path.win32.isAbsolute(dest) || path.win32.parse(dest).root === dest) throw new InstallAppWindowsError("usage", "--dest must be the fixed absolute install folder, not a drive root");
   if (!exe || exe !== path.win32.basename(exe)) throw new InstallAppWindowsError("usage", "--exe must be the bare executable name inside --dest");
   if (!fs.existsSync(installer)) throw new InstallAppWindowsError("installer-missing", `installer not found: ${installer}`);
+  const allowlist = resolvePayloadAllowlist({ exe, payload: opts.payload, payloadManifest: opts.payloadManifest }, { fs });
   const previous = previousPathOf(dest);
   const installed = path.win32.join(dest, exe);
   const hadInstall = fs.existsSync(dest);
-  event("start", { installer, dest, replacing: hadInstall });
-  if (hadInstall) {
-    // One rollback copy, replaced on every install.
+  const inDest = (relative) => path.win32.join(dest, ...relative.split("/"));
+  const inPrevious = (relative) => path.win32.join(previous, ...relative.split("/"));
+  const isFile = (file) => { try { return (fs.lstatSync ?? fs.statSync).call(fs, file).isFile(); } catch { return false; } };
+  // lstat every segment from dest down to the file; a symlink or junction anywhere in the chain is refused. A missing segment ends the walk.
+  const assertNoLinks = (relative) => {
+    const lstat = fs.lstatSync ?? fs.statSync;
+    let current = dest;
+    for (const segment of [null, ...relative.split("/")]) {
+      if (segment !== null) current = path.win32.join(current, segment);
+      let stat;
+      try { stat = lstat.call(fs, current); } catch { return; }
+      if (stat.isSymbolicLink?.() || stat.isReparsePoint?.()) throw new InstallAppWindowsError("usage", `${current} is a symlink or junction; refusing to back up, restore or remove payload entry ${relative} through it`);
+    }
+  };
+  event("start", { installer, dest, replacing: hadInstall, payloadFiles: allowlist.length });
+
+  // Backup: ONLY the allowlisted files that exist now, into `<dest>.previous`. The rest of --dest (user data) is never copied.
+  const backedUp = [];
+  const absentBefore = [];
+  let backupMade = false;
+  if (hadInstall && allowlist.length > 0) {
+    for (const relative of allowlist) {
+      const file = inDest(relative);
+      assertNoLinks(relative);
+      if (!fs.existsSync(file)) { absentBefore.push(relative); continue; }
+      if (!isFile(file)) throw new InstallAppWindowsError("usage", `payload entry ${relative} is not a regular file in ${dest}; refusing to back it up or roll it back`);
+      backedUp.push(relative);
+    }
+    // One payload-only rollback copy, replaced on every install (this also clears a whole-folder copy an older RightKit left).
     fs.rmSync(previous, { recursive: true, force: true });
-    fs.cpSync(dest, previous, { recursive: true });
-    event("previous-kept", { previous });
+    for (const relative of backedUp) {
+      fs.mkdirSync(path.win32.dirname(inPrevious(relative)), { recursive: true });
+      fs.copyFileSync(inDest(relative), inPrevious(relative));
+    }
+    backupMade = true;
+    event("previous-kept", { previous, files: backedUp.length, payloadOnly: true });
   }
+  // 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 = [];
   const restore = () => {
-    if (!hadInstall || !fs.existsSync(previous)) return false;
-    fs.cpSync(previous, dest, { recursive: true, force: true });
+    if (!backupMade) return false;
+    for (const relative of backedUp) {
+      try {
+        assertNoLinks(relative);
+        fs.mkdirSync(path.win32.dirname(inDest(relative)), { recursive: true });
+        fs.copyFileSync(inPrevious(relative), inDest(relative));
+      } catch (error) { restoreFailures.push(`${relative}: ${error.message}`); }
+    }
+    for (const relative of absentBefore) {
+      try {
+        assertNoLinks(relative);
+        const file = inDest(relative);
+        if (fs.existsSync(file) && isFile(file)) fs.rmSync(file, { force: true });
+      } catch (error) { restoreFailures.push(`${relative}: ${error.message}`); }
+    }
     return true;
   };
+  const failureNote = () => (restoreFailures.length ? `; ROLLBACK INCOMPLETE, ${restoreFailures.length} file(s) failed: ${restoreFailures.join(" | ")}` : "");
+  const noRollback = "nothing was installed before, so nothing was rolled back and no other file in the install folder was touched";
   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 ${dest} from ${previous}` : "nothing was installed before"}`);
+    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()}`);
   }
   // 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 from ${previous}` : "nothing was installed before"}`);
+    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()}`);
   }
-  event("replaced", { installed, previous: hadInstall ? previous : null, sha256: sha256(fs, installed) });
-  return { ok: true, installed, previous: hadInstall ? previous : null };
+  event("replaced", { installed, previous: backupMade ? previous : null, sha256: sha256(fs, installed) });
+  return { ok: true, installed, previous: backupMade ? previous : null };
 }

package/install-app.mjs

@@ -22,11 +22,11 @@ export class InstallAppError extends Error {
   }
 }
 
-const VALUE_FLAGS = new Set(["--dmg", "--zip", "--app", "--app-name", "--bundle-id", "--dest", "--installer", "--exe"]);
+const VALUE_FLAGS = new Set(["--dmg", "--zip", "--app", "--app-name", "--bundle-id", "--dest", "--installer", "--exe", "--payload", "--payload-manifest"]);
 const BOOL_FLAGS = new Set(["--relaunch", "--no-relaunch", "--json", "--dev", "--recover"]);
 
 export function parseArgs(argv) {
-  const opts = { dmg: null, zip: null, app: null, installer: null, exe: null, dev: false, appName: null, bundleId: null, dest: "/Applications", relaunch: null, json: false, recover: false };
+  const opts = { dmg: null, zip: null, app: null, installer: null, exe: null, payload: [], payloadManifest: null, dev: false, appName: null, bundleId: null, dest: "/Applications", relaunch: null, json: false, recover: false };
   for (let i = 0; i < argv.length; i += 1) {
     const flag = argv[i];
     if (VALUE_FLAGS.has(flag)) {
@@ -40,6 +40,8 @@ export function parseArgs(argv) {
       else if (flag === "--bundle-id") opts.bundleId = value;
       else if (flag === "--installer") opts.installer = value;
       else if (flag === "--exe") opts.exe = value;
+      else if (flag === "--payload") opts.payload.push(value);
+      else if (flag === "--payload-manifest") opts.payloadManifest = value;
       else opts.dest = value;
     } else if (BOOL_FLAGS.has(flag)) {
       if (flag === "--json") opts.json = true;
@@ -51,11 +53,13 @@ export function parseArgs(argv) {
     }
   }
   if (opts.installer !== null) {
-    // Windows: run the sealed NSIS installer in place at one fixed folder, keeping <dest>.previous.
+    // Windows: run the sealed NSIS installer in place at one fixed folder; rollback is payload-only (--payload / --payload-manifest), never the whole folder.
     if (opts.dmg !== null || opts.zip !== null || opts.app !== null || opts.recover || opts.dev) throw new InstallAppError("usage", "--installer cannot be combined with --dmg, --zip, --app, --dev or --recover");
     if (!argv.includes("--dest") || opts.exe === null) throw new InstallAppError("usage", "--installer requires --dest <fixed install folder> and --exe <App.exe>");
+    if (opts.payloadManifest !== null) opts.payloadManifest = path.resolve(opts.payloadManifest);
     return opts;
   }
+  if (opts.payload.length > 0 || opts.payloadManifest !== null) throw new InstallAppError("usage", "--payload and --payload-manifest only apply to --installer (the Windows install)");
   if (argv.includes("--relaunch") && argv.includes("--no-relaunch")) throw new InstallAppError("usage", "--relaunch and --no-relaunch are mutually exclusive");
   const inputs = [opts.dmg, opts.zip, opts.app].filter((v) => v !== null).length;
   if (opts.recover) {
@@ -278,6 +282,31 @@ async function keepPreviousBundle(run, fsImpl, bundle, installed) {
   return previous;
 }
 
+// Exclusive per-destination install lock: a lock file beside the installed apps, created O_EXCL. A lock whose pid is dead is
+// stale and taken over once. Held across recovery, staging, journal mutation and cleanup so two installers never share the
+// fixed staging/journal paths.
+const LOCK_NAME = ".rightkit-install.lock";
+// Locks this process currently holds. A lock naming our own pid that is not in this set was leaked (a simulated or
+// aborted install in this process), so it is stale exactly like a dead pid's.
+const heldLocks = new Set();
+function acquireInstallLock({ dest, fsImpl, pid, isAlive }) {
+  const lock = path.join(dest, LOCK_NAME);
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      fsImpl.writeFileSync(lock, JSON.stringify({ pid }), { flag: "wx" });
+      heldLocks.add(lock);
+      return () => { heldLocks.delete(lock); try { fsImpl.rmSync(lock, { force: true }); } catch { /* best effort */ } };
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw new InstallAppError("lock-failed", `cannot create install lock ${lock}: ${errText(error)}`);
+      let holder = null;
+      try { holder = JSON.parse(fsImpl.readFileSync(lock, "utf8")).pid; } catch { holder = null; }
+      if (Number.isInteger(holder) && isAlive(holder) && !(holder === pid && !heldLocks.has(lock))) throw new InstallAppError("install-locked", `another install holds ${lock} (pid ${holder})`);
+      try { fsImpl.rmSync(lock, { force: true }); } catch { /* retry decides */ }
+    }
+  }
+  throw new InstallAppError("install-locked", `could not take install lock ${lock}`);
+}
+
 // Deterministic roll-forward/back of any interrupted install journal in `dest`. Idempotent.
 export async function recoverInstalls({ dest, appName = null, run, fsImpl, home, now, event, sleep, isAlive = defaultIsAlive, selfPid = process.pid, swapPaths = createSwapPaths() }) {
   let names = [];
@@ -311,7 +340,8 @@ export async function recoverInstalls({ dest, appName = null, run, fsImpl, home,
           let ok = j.phase === "verified";
           if (!ok) { try { await verifyBundle(run, j.installed, { assess: !j.dev, staple: false }); ok = true; } catch { ok = false; } }
           if (ok) {
-            try { await keepPreviousBundle(run, fsImpl, j.staged, j.installed); action = "rolled-forward"; }
+            // A dev journal (from an older RightKit) never keeps the old bundle: the staged path is cleared below.
+            try { if (!j.dev) await keepPreviousBundle(run, fsImpl, j.staged, j.installed); action = "rolled-forward"; }
             catch { action = "rolled-forward-previous-pending"; keepJournal = true; keepStaged = true; }
           } else {
             swapBack(swapPaths, fsImpl, j.staged, j.installed); // staged now holds the bad new bundle
@@ -325,7 +355,7 @@ export async function recoverInstalls({ dest, appName = null, run, fsImpl, home,
         let ok = j.phase === "verified";
         if (!ok) { try { await verifyBundle(run, j.installed, { assess: !j.dev, staple: false }); ok = true; } catch { ok = false; } }
         if (ok) {
-          try { await keepPreviousBundle(run, fsImpl, j.backup, j.installed); action = "rolled-forward"; }
+          try { if (j.dev) rm(j.backup); else await keepPreviousBundle(run, fsImpl, j.backup, j.installed); action = "rolled-forward"; }
           catch { action = "rolled-forward-previous-pending"; keepJournal = true; }
         } else {
           rm(j.installed);
@@ -352,7 +382,10 @@ export async function recoverInstalls({ dest, appName = null, run, fsImpl, home,
 export async function recoverApp(opts, deps = {}) {
   const { execFile = realExecFile, fsImpl = fs, home = os.homedir(), now = () => new Date(), sleep = (ms) => new Promise((r) => setTimeout(r, ms)), emit = () => {}, isAlive, platform = process.platform, env = process.env, swapPaths = createSwapPaths({ env }) } = deps;
   if (platform !== "darwin") throw new InstallAppError("unsupported", `install-app is not implemented on ${platform}`);
-  const results = await recoverInstalls({ dest: opts.dest, appName: opts.appName, run: (c, a) => execFile(c, a), fsImpl, home, now, event: (name, data = {}) => emit({ event: name, ...data }), sleep, isAlive, swapPaths });
+  const release = acquireInstallLock({ dest: opts.dest, fsImpl, pid: process.pid, isAlive: isAlive ?? defaultIsAlive });
+  let results;
+  try { results = await recoverInstalls({ dest: opts.dest, appName: opts.appName, run: (c, a) => execFile(c, a), fsImpl, home, now, event: (name, data = {}) => emit({ event: name, ...data }), sleep, isAlive, swapPaths }); }
+  finally { release(); }
   emit({ event: "recover-done", dest: opts.dest, recovered: results.length });
   return { ok: true, recovered: results };
 }
@@ -384,6 +417,8 @@ export async function installApp(opts, deps = {}) {
   let mountPoint = null;
   let failedStage = "start";
   let swap = null; // set once the journal exists; tracks which renames happened
+  let releaseLock = () => {};
+  let devOldRemoved = false; // a dev install removed the old bundle; nothing can put it back
 
   const removeQuiet = (p) => { if (p) { try { fsImpl.rmSync(p, { recursive: true, force: true }); } catch { /* best effort */ } } };
   // Undo an unfinished swap using renames only. Sync on purpose so a signal handler can run it.
@@ -422,6 +457,7 @@ export async function installApp(opts, deps = {}) {
         await detach();
         cleanupExtract();
       } catch { /* exiting anyway */ }
+      releaseLock();
       exit(128 + (os.constants.signals[sig] || 0));
     })();
   };
@@ -449,6 +485,7 @@ export async function installApp(opts, deps = {}) {
     if (!fsImpl.existsSync(inputPath)) throw new InstallAppError(`${inputKind}-missing`, `${inputKind.toUpperCase()} not found: ${inputPath}`);
     if (!fsImpl.existsSync(opts.dest)) throw new InstallAppError("dest-missing", `destination not found: ${opts.dest}`);
 
+    releaseLock = acquireInstallLock({ dest: opts.dest, fsImpl, pid, isAlive });
     await recoverInstalls({ dest: opts.dest, appName: opts.appName, run, fsImpl, home, now, event, sleep, isAlive, selfPid: pid, swapPaths });
 
     let sourceApp = null;
@@ -505,9 +542,11 @@ export async function installApp(opts, deps = {}) {
     // Stage a verified copy on the destination volume so the swap is rename(2) only.
     failedStage = "stage";
     const base = appName.replace(/\.app$/, "");
-    // Staging is never run from: it is verified, then renamed into place. The rollback copy is the fixed `<installed>.previous`.
-    const staged = path.join(opts.dest, `.${base}.rightkit-install-${pid}.app`);
-    const backup = hadInstalled ? previousPathOf(installed) : null;
+    // Staging is never run from: it is verified, then renamed into place. Its name is fixed per app (no per-pid sibling), like the
+    // journal beside it; the rollback copy is the fixed `<installed>.previous`.
+    const staged = path.join(opts.dest, `.${base}.rightkit-install.app`);
+    // Dev installs keep NO old copy of any kind (Orthic-Labs/rightkit#348): the old bundle is removed, never moved to `.previous`.
+    const backup = hadInstalled && !dev ? previousPathOf(installed) : null;
     const journal = journalPathFor(opts.dest, appName);
     const journalData = { schema: 1, appName, pid, phase: "staging", dev, installed, backup, staged, mount: mountPoint, mountRoot };
     removeQuiet(staged);
@@ -543,6 +582,17 @@ export async function installApp(opts, deps = {}) {
       writeJournal(fsImpl, journal, { ...jd, phase: "swapping", swap: swapMode });
       fsImpl.renameSync(staged, installed);
       swap.stagedIn = true;
+    } else if (dev) {
+      // Dev: remove the old bundle, then rename the verified staged copy over the fixed path. No backup, no exchange (an exchange
+      // would park the old bundle at the staged path). A failure from here leaves the path absent or partial: reinstall from an older DMG.
+      swapMode = "replace";
+      swap.mode = "two-rename";
+      jd = { ...journalData, swap: "two-rename", backup: null };
+      writeJournal(fsImpl, journal, { ...jd, phase: "swapping" });
+      devOldRemoved = true;
+      fsImpl.rmSync(installed, { recursive: true, force: true });
+      fsImpl.renameSync(staged, installed);
+      swap.stagedIn = true;
     } else {
       jd = { ...journalData, swap: "atomic", backup: null, stagedIno: fsImpl.statSync(staged).ino };
       writeJournal(fsImpl, journal, { ...jd, phase: "swapping" });
@@ -586,6 +636,8 @@ export async function installApp(opts, deps = {}) {
     }
     if (!oldBundle || kept !== previousPathOf(installed)) { if (!oldBundle) removeQuiet(journal); }
     else removeQuiet(journal);
+    // A stale `.previous` from an older RightKit must not survive a dev install either.
+    if (dev) removeQuiet(previousPathOf(installed));
     swap = null;
     event("replaced", { installed, previous: kept, swap: swapMode });
 
@@ -601,7 +653,11 @@ export async function installApp(opts, deps = {}) {
     return result;
   } catch (error) {
     rollbackSwap();
-    const reason = error instanceof InstallAppError ? error.message : errText(error);
+    let reason = error instanceof InstallAppError ? error.message : errText(error);
+    if (dev && devOldRemoved) {
+      reason = `${reason}; the dev install keeps no old copy, so the failed install was removed: reinstall from an older DMG`;
+      if (error instanceof InstallAppError) error.message = reason;
+    }
     event("failed", { stage: failedStage, code: error.code || "error", reason });
     if (!(error instanceof InstallAppError)) throw new InstallAppError("error", reason);
     throw error;
@@ -610,6 +666,7 @@ export async function installApp(opts, deps = {}) {
     rollbackSwap();
     await detach();
     cleanupExtract();
+    releaseLock();
   }
 }
 
@@ -708,7 +765,7 @@ export async function main(argv = process.argv.slice(2), io = {}) {
     stderr(`right-release install-app: ${error.message}`);
     stderr("usage: right-release install-app (--dmg <path.dmg> | --dev (--zip <path.zip> | --app <path.app> | --dmg <path.dmg>)) [--app-name Pulse.app] [--bundle-id dev.orthic.pulse] [--dest /Applications] [--relaunch|--no-relaunch] [--json]");
     stderr("       right-release install-app --recover [--dest /Applications] [--app-name Pulse.app] [--json]");
-    stderr("       right-release install-app --installer <Setup.exe> --dest <fixed install folder> --exe <App.exe> [--json]   (Windows: in place, keeps <dest>.previous)");
+    stderr("       right-release install-app --installer <Setup.exe> --dest <fixed install folder> --exe <App.exe> [--payload <file>]... [--payload-manifest <json>] [--json]   (Windows: in place; payload-only rollback, never the whole folder)");
     stderr("  --dev installs a Developer ID-signed, NOT notarized build (skips spctl/stapler, clears quarantine on the new bundle).");
     return 2;
   }