@rightkit/release 0.2.135 → 0.2.136

package/github-release.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { createHash } from "node:crypto";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import os from "node:os";
+import { readVerifiedArtifact, assertArtifactUnchanged, digestBytes, verifyArtifactFile } from "./publication-artifacts.mjs";
 import { spawnSync } from "./background-process.mjs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { verifySealedRelease } from "./release-state.mjs";
@@ -26,11 +28,20 @@ export function prepareGitHubRelease({ repoRoot, releaseId, platform, repo, stat
   mkdirSync(releaseState, { recursive: true });
   const manifestAsset = path.join(releaseState, `${sealed.manifest.app}-${sealed.manifest.version}-${platform}-release-manifest.json`);
   const checksumsAsset = path.join(releaseState, `${sealed.manifest.app}-${sealed.manifest.version}-${platform}-SHA256SUMS.txt`);
-  copyFileSync(sealed.manifestPath, manifestAsset);
-  writeFileSync(checksumsAsset, `${sealed.manifest.files.map((file) => `${file.sha256}  ${file.name}`).join("\n")}\n`);
+  const manifestBytes = Buffer.from(`${JSON.stringify(sealed.manifest, null, 2)}\n`);
+  const checksumsBytes = Buffer.from(`${sealed.manifest.files.map((file) => `${file.sha256}  ${file.name}`).join("\n")}\n`);
+  writeFileSync(manifestAsset, manifestBytes);
+  writeFileSync(checksumsAsset, checksumsBytes);
   const installer = path.join(sealed.sealedDir, installers[0].name);
   const assets = [...sealed.manifest.files.map((file) => path.join(sealed.sealedDir, file.name)), manifestAsset, checksumsAsset];
+  const publicationArtifacts = new Map(sealed.manifest.files.map((entry) => {
+    const file = path.join(sealed.sealedDir, entry.name);
+    return [file, verifyArtifactFile(file, entry)];
+  }));
+  publicationArtifacts.set(manifestAsset, readVerifiedArtifact(manifestAsset, { sha256: digestBytes(manifestBytes) }));
+  publicationArtifacts.set(checksumsAsset, readVerifiedArtifact(checksumsAsset, { sha256: digestBytes(checksumsBytes) }));
   return {
+    publicationArtifacts,
     sealed,
     installer,
     assets,
@@ -131,8 +142,7 @@ export function prepareGitHubDirectRelease({
     signaturePlatform: effectiveSignaturePlatform,
   };
   Object.defineProperty(plan, "signatureCommandRunner", { value: effectiveSignatureRunner, enumerable: false });
-  validateGitHubDirectReleasePlan(plan, { commandRunner: effectiveSignatureRunner, platform: effectiveSignaturePlatform });
-  return plan;
+  return validateGitHubDirectReleasePlan(plan, { commandRunner: effectiveSignatureRunner, platform: effectiveSignaturePlatform });
 }
 
 export const prepareGitHubPortableRelease = prepareGitHubDirectRelease;
@@ -153,16 +163,30 @@ export function validateGitHubDirectReleasePlan(plan, { commandRunner = plan?.si
     if (!existsSync(file) || !statSync(file).isFile()) throw new Error(`direct release payload missing: ${file}`);
   }
   if (statSync(signatureFile).size < 1) throw new Error("detached release manifest signature is missing");
-  const manifest = JSON.parse(readFileSync(manifestFile, "utf8"));
+  const manifestArtifact = readVerifiedArtifact(manifestFile, { sha256: plan.publicationArtifacts?.get(manifestFile)?.sha256 ?? sha256(manifestFile) });
+  const signatureArtifact = readVerifiedArtifact(signatureFile, { sha256: plan.publicationArtifacts?.get(signatureFile)?.sha256 ?? sha256(signatureFile) });
+  const manifest = JSON.parse(manifestArtifact.bytes);
   if (manifest.schemaVersion !== 1 || manifest.kind !== "rightkit-direct-release-manifest" || !STABLE_SEMVER_RE.test(manifest.version ?? "") || manifest.tag !== `v${manifest.version}`) {
     throw new Error("invalid direct release manifest");
   }
   if (plan.tag !== manifest.tag) throw new Error("direct GitHub release tag does not match manifest");
   if (manifest.signingKeyId !== RIGHTRELEASE_MANIFEST_SIGNER.id || manifest.signatureAlgorithm !== RIGHTRELEASE_MANIFEST_SIGNER.algorithm || manifest.signatureProvider !== RIGHTRELEASE_MANIFEST_SIGNER.provider || manifest.signatureProviderVersion !== RIGHTRELEASE_MANIFEST_SIGNER.providerVersion) throw new Error("direct release manifest signer contract is invalid");
-  verifyManifestCatalogSignature({ manifestPath: manifestFile, signaturePath: signatureFile, expectedSigner: plan.signer, commandRunner, platform });
+  // Catalog verification operates on snapshots of the exact captured authority bytes.
+  const snapshot = mkdtempSync(path.join(os.tmpdir(), "rightkit-direct-authority-"));
+  try {
+    const manifestSnapshot = path.join(snapshot, path.basename(manifestFile));
+    const signatureSnapshot = path.join(snapshot, path.basename(signatureFile));
+    writeFileSync(manifestSnapshot, manifestArtifact.bytes);
+    writeFileSync(signatureSnapshot, signatureArtifact.bytes);
+    verifyManifestCatalogSignature({ manifestPath: manifestSnapshot, signaturePath: signatureSnapshot, expectedSigner: plan.signer, commandRunner, platform });
+    readVerifiedArtifact(manifestSnapshot, manifestArtifact);
+    readVerifiedArtifact(signatureSnapshot, signatureArtifact);
+  } finally { rmSync(snapshot, { recursive: true, force: true }); }
+  assertArtifactUnchanged(manifestArtifact);
+  assertArtifactUnchanged(signatureArtifact);
   if (!SHA256.test(manifest.checksumsSha256 ?? "")) throw new Error("direct release checksums digest is missing");
-  if (sha256(checksumsFile) !== manifest.checksumsSha256) throw new Error("checksums.json is not manifest-bound");
-  const checksums = JSON.parse(readFileSync(checksumsFile, "utf8"));
+  const checksumsArtifact = readVerifiedArtifact(checksumsFile, { sha256: manifest.checksumsSha256 });
+  const checksums = JSON.parse(checksumsArtifact.bytes);
   if (checksums.schemaVersion !== 1 || checksums.algorithm !== "sha256" || !checksums.assets || typeof checksums.assets !== "object" || Array.isArray(checksums.assets)) {
     throw new Error("invalid direct release checksums");
   }
@@ -191,14 +215,18 @@ export function validateGitHubDirectReleasePlan(plan, { commandRunner = plan?.si
     addExpected({ name: asset.provenanceName, sha256: asset.provenanceSha256 }, "provenance");
     addExpected({ name: asset.sbomName, sha256: asset.sbomSha256 }, "SBOM");
   }
+  const publicationArtifacts = new Map([[manifestFile, manifestArtifact], [signatureFile, signatureArtifact], [checksumsFile, checksumsArtifact]]);
   for (const [name, evidence] of expected) {
     const file = payloadByName.get(name);
     if (!file) throw new Error(`direct release evidence is not attached: ${name}`);
     if (evidence.size !== undefined && (!Number.isSafeInteger(evidence.size) || evidence.size < 1 || statSync(file).size !== evidence.size)) throw new Error(`direct release archive size mismatch: ${name}`);
-    if (sha256(file) !== evidence.digest) throw new Error(`direct release payload hash mismatch: ${name}`);
+    publicationArtifacts.set(file, verifyArtifactFile(file, { sha256: evidence.digest, sizeBytes: evidence.size }));
     if (checksums.assets[name] !== evidence.digest) throw new Error(`direct release checksum mismatch: ${name}`);
   }
-  return { ...plan, manifest, checksums };
+  for (const file of payloadByName.values()) if (!publicationArtifacts.has(file)) throw new Error(`direct release payload lacks signed evidence: ${path.basename(file)}`);
+  const result = { ...plan, manifest, checksums, publicationArtifacts };
+  Object.defineProperty(result, "signatureCommandRunner", { value: commandRunner, enumerable: false });
+  return result;
 }
 
 export function repositoryFromRemote(repoRoot) {
@@ -218,17 +246,19 @@ export function prepareGitHubAddonRelease({ repoRoot, config, configRoot = repoR
   if (!existsSync(manifestPath)) throw new Error(`sealed add-on manifest not found: ${manifestPath}`);
   const manifest = validateAddonManifest(JSON.parse(readFileSync(manifestPath, "utf8")));
   if (manifest.addon !== config.addon || manifest.version !== config.version || manifest.platform !== platform || manifest.commit !== commit) throw new Error("sealed add-on identity mismatch");
+  const publicationArtifacts = new Map();
   const assets = manifest.files.map((file) => {
     const asset = path.join(sealedDir, file.name);
-    if (!existsSync(asset) || statSync(asset).size !== file.sizeBytes || sha256(asset) !== file.sha256) throw new Error(`sealed add-on file mismatch: ${file.name}`);
+    publicationArtifacts.set(asset, verifyArtifactFile(asset, file));
     return asset;
   });
   const digest = addonManifestSha256(manifest);
+  publicationArtifacts.set(manifestPath, readVerifiedArtifact(manifestPath, { sha256: digest }));
   const tag = `addon-${manifest.addon}-v${manifest.version}-${platform}-sha256-${digest}`;
   const stateDir = path.join(repoRoot, ".right-release", "state", "addons", manifest.addon, manifest.version, commit.slice(0, 8), platform, "github");
   mkdirSync(stateDir, { recursive: true });
   return {
-    kind: "addon", manifest, manifestPath, sealedDir, assets: [...assets, manifestPath], tag,
+    publicationArtifacts, kind: "addon", manifest, manifestPath, sealedDir, assets: [...assets, manifestPath], tag,
     title: `${manifest.addon} ${manifest.version} ${platform} add-on`,
     notes: [`Signed ${platform === "mac" ? "macOS" : "Windows"} add-on component set.`, "", `Build commit: \`${manifest.commit}\``, `Manifest SHA-256: \`${digest}\``].join("\n"),
     notesFile: path.join(stateDir, "release-notes.md"),
@@ -236,8 +266,13 @@ export function prepareGitHubAddonRelease({ repoRoot, config, configRoot = repoR
   };
 }
 
-export function publishGitHubRelease(plan, { repo, dryRun = false, run = runCommand, signatureCommandRunner = plan?.signatureCommandRunner ?? plan?.cmsCommandRunner, signaturePlatform = plan?.signaturePlatform ?? plan?.cmsPlatform ?? process.platform } = {}) {
-  if (plan.kind === "direct-release") validateGitHubDirectReleasePlan(plan, { commandRunner: signatureCommandRunner ?? spawnSync, platform: signaturePlatform });
+export function publishGitHubRelease(plan, { repo, dryRun = false, run = runCommand, signatureCommandRunner = plan?.signatureCommandRunner ?? plan?.cmsCommandRunner, signaturePlatform = plan?.signaturePlatform ?? plan?.cmsPlatform ?? process.platform, trustCommandRunner = spawnSync } = {}) {
+  if (plan.kind === "direct-release") plan = validateGitHubDirectReleasePlan(plan, { commandRunner: signatureCommandRunner ?? spawnSync, platform: signaturePlatform });
+  if (!(plan.publicationArtifacts instanceof Map) || plan.assets.some((file) => !plan.publicationArtifacts.has(file))) throw new Error("GitHub publication requires sealed or signed hash evidence for every asset");
+  for (const artifact of plan.publicationArtifacts.values()) {
+    if (artifact.bytes) assertArtifactUnchanged(artifact);
+    else verifyArtifactFile(artifact.file, artifact);
+  }
   const visibility = JSON.parse(run("gh", ["repo", "view", repo, "--json", "visibility"]));
   if (visibility.visibility !== "PUBLIC" && !(plan.kind !== "addon" && visibility.visibility === "PRIVATE")) {
     throw new Error(`GitHub releases require a public or private repository: ${repo}`);
@@ -246,16 +281,16 @@ export function publishGitHubRelease(plan, { repo, dryRun = false, run = runComm
     // Direct payloads are already sealed by the signed manifest contract. Do
     // not route them through desktop-installer trust checks.
   } else if (!dryRun) {
-    if (plan.kind === "addon") verifyAddonTrust(plan);
-    else verifyPlatformTrust(plan);
+    if (plan.kind === "addon") verifyAddonTrust(plan, trustCommandRunner);
+    else verifyPlatformTrust(plan, trustCommandRunner);
   }
   const existing = run("gh", ["release", "view", plan.tag, "--repo", repo, "--json", "tagName"], { allowFailure: true });
   if (dryRun) return { status: existing.ok ? plan.kind === "addon" ? "would-verify" : "would-update" : "would-create", tag: plan.tag, assets: plan.assets };
   if (existing.ok) {
-    const missing = plan.assets.filter((asset) => inspectRemoteAsset(plan.tag, repo, asset, run) === "missing");
+    const missing = plan.assets.filter((asset) => inspectRemoteAsset(plan.tag, repo, asset, run, plan.publicationArtifacts.get(asset)) === "missing");
     if (missing.length === 0) return { status: "already-verified", tag: plan.tag, assets: plan.assets, manifestUrl: plan.manifestUrl };
     run("gh", ["release", "upload", plan.tag, ...missing, "--repo", repo]);
-    for (const asset of plan.assets) verifyRemoteAsset(plan.tag, repo, asset, run);
+    for (const asset of plan.assets) verifyRemoteAsset(plan.tag, repo, asset, run, plan.publicationArtifacts.get(asset));
     return { status: "resumed-verified", tag: plan.tag, assets: plan.assets, manifestUrl: plan.manifestUrl };
   }
   if (!existing.ok) {
@@ -265,35 +300,35 @@ export function publishGitHubRelease(plan, { repo, dryRun = false, run = runComm
     rmSync(notesFile, { force: true });
   }
   run("gh", ["release", "upload", plan.tag, ...plan.assets, "--repo", repo]);
-  for (const asset of plan.assets) verifyRemoteAsset(plan.tag, repo, asset, run);
+  for (const asset of plan.assets) verifyRemoteAsset(plan.tag, repo, asset, run, plan.publicationArtifacts.get(asset));
   return { status: "verified", tag: plan.tag, assets: plan.assets, manifestUrl: plan.manifestUrl };
 }
 
-function verifyAddonTrust(plan) {
+function verifyAddonTrust(plan, commandRunner) {
   for (const file of plan.manifest.files.filter((entry) => entry.executable)) {
     const executable = path.join(plan.sealedDir, file.name);
     if (plan.manifest.platform === "mac") {
-      const output = runCombined("codesign", ["-dv", "--verbose=4", executable]);
+      const output = runCombined("codesign", ["-dv", "--verbose=4", executable], commandRunner);
       if (!/TeamIdentifier=6KLGD3LLKF/.test(output)) throw new Error(`codesign team mismatch: ${file.name}`);
-      runCommand("codesign", ["--verify", "--strict", "--verbose=2", executable]);
-    } else runCommand(process.execPath, [path.join(path.dirname(fileURLToPath(import.meta.url)), "sign-windows.mjs"), "--verify-only", executable]);
+      runCombined("codesign", ["--verify", "--strict", "--verbose=2", executable], commandRunner);
+    } else runCombined(process.execPath, [path.join(path.dirname(fileURLToPath(import.meta.url)), "sign-windows.mjs"), "--verify-only", executable], commandRunner);
   }
 }
 
-function verifyPlatformTrust(plan) {
+export function verifyPlatformTrust(plan, commandRunner = spawnSync) {
   if (plan.sealed.manifest.platform === "win") {
-    runCommand(process.execPath, [path.join(path.dirname(fileURLToPath(import.meta.url)), "sign-windows.mjs"), "--verify-only", plan.installer]);
+    runCombined(process.execPath, [path.join(path.dirname(fileURLToPath(import.meta.url)), "sign-windows.mjs"), "--verify-only", plan.installer], commandRunner);
     return;
   }
-  runCommand("spctl", ["--assess", "--type", "open", "--context", "context:primary-signature", "--verbose=2", plan.installer]);
-  runCommand("xcrun", ["stapler", "validate", plan.installer]);
+  runCombined("spctl", ["--assess", "--type", "open", "--context", "context:primary-signature", "--verbose=2", plan.installer], commandRunner);
+  runCombined("xcrun", ["stapler", "validate", plan.installer], commandRunner);
 }
 
-function verifyRemoteAsset(tag, repo, asset, run) {
-  if (inspectRemoteAsset(tag, repo, asset, run) !== "match") throw new Error(`GitHub release asset missing: ${path.basename(asset)}`);
+function verifyRemoteAsset(tag, repo, asset, run, evidence) {
+  if (inspectRemoteAsset(tag, repo, asset, run, evidence) !== "match") throw new Error(`GitHub release asset missing; inspect remote asset ${repo}/${tag}/${path.basename(asset)}`);
 }
 
-function inspectRemoteAsset(tag, repo, asset, run) {
+function inspectRemoteAsset(tag, repo, asset, run, evidence) {
   const verifyDir = `${path.dirname(asset)}/verify-${path.basename(asset)}`;
   rmSync(verifyDir, { recursive: true, force: true });
   mkdirSync(verifyDir, { recursive: true });
@@ -301,11 +336,12 @@ function inspectRemoteAsset(tag, repo, asset, run) {
   if (!result.ok) {
     rmSync(verifyDir, { recursive: true, force: true });
     if (/no assets match|not found/i.test(`${result.output ?? ""}\n${result.error ?? ""}`)) return "missing";
-    throw new Error(`cannot inspect GitHub release asset: ${path.basename(asset)}: ${result.error || result.output}`);
+    throw new Error(`cannot inspect remote asset ${repo}/${tag}/${path.basename(asset)}: ${result.error || result.output}`);
   }
   const downloaded = path.join(verifyDir, path.basename(asset));
-  if (!existsSync(downloaded) || sha256(downloaded) !== sha256(asset)) throw new Error(`GitHub release asset hash mismatch: ${path.basename(asset)}`);
-  rmSync(verifyDir, { recursive: true, force: true });
+  try { verifyArtifactFile(downloaded, evidence); }
+  catch { throw new Error(`GitHub release asset hash mismatch; remove remote asset ${repo}/${tag}/${path.basename(asset)}`); }
+  finally { rmSync(verifyDir, { recursive: true, force: true }); }
   return "match";
 }
 
@@ -323,8 +359,8 @@ function runCommand(command, args, { allowFailure = false, cwd } = {}) {
   return allowFailure ? { ok: true, output } : output;
 }
 
-function runCombined(command, args) {
-  const result = spawnSync(command, args, { encoding: "utf8", windowsHide: true });
+function runCombined(command, args, commandRunner = spawnSync) {
+  const result = commandRunner(command, args, { encoding: "utf8", windowsHide: true });
   if (result.status !== 0) throw new Error(`${command} ${args.join(" ")} failed: ${result.stderr?.trim() || `exit ${result.status}`}`);
   return `${result.stdout ?? ""}${result.stderr ?? ""}`;
 }
@@ -334,7 +370,8 @@ function usage(code) {
   process.exit(code);
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+const realOrSelf = (file) => { try { return realpathSync(file); } catch { return path.resolve(file); } };
+if (process.argv[1] && realOrSelf(process.argv[1]) === realOrSelf(fileURLToPath(import.meta.url))) {
   const args = process.argv.slice(2);
   const options = { platform: process.platform === "win32" ? "win" : "mac", releaseId: "", addon: "", repo: "", dryRun: false };
   for (let index = 0; index < args.length; index += 1) {

package/heavy-command.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, realpathSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawn, spawnSync } from "./background-process.mjs";
@@ -355,7 +355,8 @@ function spawnAttached(command, args, env, slot) {
   });
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === SELF) {
+const realOrSelf = (file) => { try { return realpathSync(file); } catch { return path.resolve(file); } };
+if (process.argv[1] && realOrSelf(process.argv[1]) === realOrSelf(fileURLToPath(import.meta.url))) {
   const args = process.argv.slice(2);
   const task = args[0] === "--watch-owner-base64"
     ? watchOwnedProcessTree(JSON.parse(Buffer.from(args[1] || "", "base64url").toString("utf8"))).then(() => 0)

package/install-app.mjs

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+// Sanctioned, non-intrusive local app install from a signed DMG (macOS).
+// Never uses a shell, osascript, AppleEvents, or foreground activation.
+import { execFile as nodeExecFile } from "./background-process.mjs";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const SIGTERM_WAIT_MS = 15_000;
+const POLL_MS = 250;
+
+export class InstallAppError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const VALUE_FLAGS = new Set(["--dmg", "--app-name", "--bundle-id", "--dest"]);
+const BOOL_FLAGS = new Set(["--relaunch", "--no-relaunch", "--json"]);
+
+export function parseArgs(argv) {
+  const opts = { dmg: null, appName: null, bundleId: null, dest: "/Applications", relaunch: null, json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i];
+    if (VALUE_FLAGS.has(flag)) {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("--")) throw new InstallAppError("usage", `${flag} requires a value`);
+      i += 1;
+      if (flag === "--dmg") opts.dmg = value;
+      else if (flag === "--app-name") opts.appName = value;
+      else if (flag === "--bundle-id") opts.bundleId = value;
+      else opts.dest = value;
+    } else if (BOOL_FLAGS.has(flag)) {
+      if (flag === "--json") opts.json = true;
+      else opts.relaunch = flag === "--relaunch";
+    } else {
+      throw new InstallAppError("usage", `unknown argument: ${flag}`);
+    }
+  }
+  if (argv.includes("--relaunch") && argv.includes("--no-relaunch")) throw new InstallAppError("usage", "--relaunch and --no-relaunch are mutually exclusive");
+  if (!opts.dmg) throw new InstallAppError("usage", "--dmg <path.dmg> is required");
+  if (!opts.dmg.toLowerCase().endsWith(".dmg")) throw new InstallAppError("usage", "--dmg must name a .dmg file");
+  if (opts.appName !== null && (!/^[^/\0]+\.app$/.test(opts.appName) || opts.appName === ".app" || opts.appName.includes(".."))) {
+    throw new InstallAppError("usage", "--app-name must be a bare bundle name ending in .app");
+  }
+  if (opts.bundleId !== null && !/^[A-Za-z0-9][A-Za-z0-9.-]*$/.test(opts.bundleId)) throw new InstallAppError("usage", "--bundle-id is not a valid bundle identifier");
+  if (!path.isAbsolute(opts.dest)) opts.dest = path.resolve(opts.dest);
+  opts.dmg = path.resolve(opts.dmg);
+  return opts;
+}
+
+// --- pure parsers ---------------------------------------------------------
+
+function xmlUnescape(text) {
+  return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+}
+
+// Minimal plist reader for hdiutil attach -plist output (dict/array/string/data/integer/true/false).
+export function parsePlist(xml) {
+  const cleaned = String(xml).replace(/<\?[\s\S]*?\?>/g, "").replace(/<!--[\s\S]*?-->/g, "").replace(/<!DOCTYPE[^>]*>/gi, "");
+  const tokens = [...cleaned.matchAll(/<(\/?)([a-zA-Z]+)(?:\s[^>]*?)?(\s*\/)?>|([^<]+)/g)];
+  let pos = 0;
+  const skipText = () => { while (pos < tokens.length && tokens[pos][4] !== undefined && tokens[pos][4].trim() === "") pos += 1; };
+  function readValue() {
+    skipText();
+    const t = tokens[pos];
+    if (!t || t[4] !== undefined || t[1]) throw new InstallAppError("plist", "malformed plist");
+    const name = t[2];
+    pos += 1;
+    if (t[3]) return name === "true" ? true : name === "false" ? false : "";
+    if (name === "dict") {
+      const out = {};
+      for (;;) {
+        skipText();
+        const n = tokens[pos];
+        if (!n) throw new InstallAppError("plist", "unterminated dict");
+        if (n[1] && n[2] === "dict") { pos += 1; return out; }
+        if (n[2] !== "key") throw new InstallAppError("plist", "expected key");
+        pos += 1;
+        const key = tokens[pos]?.[4] !== undefined ? xmlUnescape(tokens[pos++][4]) : "";
+        pos += 1; // </key>
+        out[key] = readValue();
+      }
+    }
+    if (name === "array") {
+      const out = [];
+      for (;;) {
+        skipText();
+        const n = tokens[pos];
+        if (!n) throw new InstallAppError("plist", "unterminated array");
+        if (n[1] && n[2] === "array") { pos += 1; return out; }
+        out.push(readValue());
+      }
+    }
+    let text = "";
+    if (tokens[pos]?.[4] !== undefined) { text = xmlUnescape(tokens[pos][4]); pos += 1; }
+    pos += 1; // closing tag
+    if (name === "integer") return Number(text);
+    if (name === "real") return Number(text);
+    return text;
+  }
+  while (pos < tokens.length && !(tokens[pos][2] === "plist" && !tokens[pos][1])) pos += 1;
+  if (pos >= tokens.length) throw new InstallAppError("plist", "no <plist> element");
+  pos += 1;
+  return readValue();
+}
+
+export function mountPointsFromAttach(plistXml) {
+  const parsed = parsePlist(plistXml);
+  const entities = parsed?.["system-entities"];
+  if (!Array.isArray(entities)) throw new InstallAppError("attach", "hdiutil attach output has no system-entities");
+  return entities.map((e) => e?.["mount-point"]).filter((m) => typeof m === "string" && m.length > 0);
+}
+
+export function parseTeamId(codesignDvvOutput) {
+  const match = /^TeamIdentifier=(.+)$/m.exec(codesignDvvOutput);
+  const value = match?.[1].trim();
+  return value && value !== "not set" ? value : null;
+}
+
+// Parse `ps -axo pid=,comm=` and return pids whose executable lives inside <app>/Contents/MacOS/.
+export function matchPids(psOutput, appBundlePath, { selfPid = process.pid } = {}) {
+  const prefix = `${appBundlePath.replace(/\/+$/, "")}/Contents/MacOS/`;
+  const pids = [];
+  for (const line of String(psOutput).split("\n")) {
+    const m = /^\s*(\d+)\s+(.+?)\s*$/.exec(line);
+    if (!m) continue;
+    const pid = Number(m[1]);
+    if (pid === selfPid || pid <= 1) continue;
+    if (m[2].startsWith(prefix)) pids.push(pid);
+  }
+  return pids;
+}
+
+export function trashName(appName, now = new Date()) {
+  const stamp = now.toISOString().replace(/[:T]/g, "-").replace(/\..*$/, "");
+  const base = appName.replace(/\.app$/, "");
+  return `${base} ${stamp}.app`;
+}
+
+// --- orchestration --------------------------------------------------------
+
+const realExecFile = (cmd, args) => new Promise((resolve, reject) => {
+  nodeExecFile(cmd, args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => {
+    if (error) { error.stdout = stdout; error.stderr = stderr; reject(error); } else resolve({ stdout, stderr });
+  });
+});
+
+function errText(error) {
+  return `${error?.stderr || ""}${error?.stdout || ""}`.trim() || error?.message || String(error);
+}
+
+export async function installApp(opts, deps = {}) {
+  const {
+    execFile = realExecFile,
+    platform = process.platform,
+    fsImpl = fs,
+    home = os.homedir(),
+    now = () => new Date(),
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    kill = (pid, sig) => process.kill(pid, sig),
+    emit = () => {},
+    tmpdir = os.tmpdir(),
+  } = deps;
+  const event = (name, data = {}) => emit({ event: name, ...data });
+  const run = (cmd, args) => execFile(cmd, args);
+  let mountRoot = null;
+  let mounted = false;
+  let mountPoint = null;
+  let failedStage = "start";
+
+  const detach = async () => {
+    if (!mounted) return;
+    mounted = false;
+    try { await run("/usr/bin/hdiutil", ["detach", mountPoint]); }
+    catch { try { await run("/usr/bin/hdiutil", ["detach", "-force", mountPoint]); } catch { /* best effort */ } }
+    try { fsImpl.rmSync(mountRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+  };
+
+  try {
+    if (platform !== "darwin") throw new InstallAppError("unsupported", `install-app is not implemented on ${platform}`);
+    event("start", { dmg: opts.dmg, dest: opts.dest });
+    if (!fsImpl.existsSync(opts.dmg)) throw new InstallAppError("dmg-missing", `DMG not found: ${opts.dmg}`);
+    if (!fsImpl.existsSync(opts.dest)) throw new InstallAppError("dest-missing", `destination not found: ${opts.dest}`);
+
+    failedStage = "attach";
+    mountRoot = fsImpl.mkdtempSync(path.join(tmpdir, "right-install-app-"));
+    const attached = await run("/usr/bin/hdiutil", ["attach", "-nobrowse", "-readonly", "-noautoopen", "-mountrandom", mountRoot, "-plist", opts.dmg]);
+    const mounts = mountPointsFromAttach(attached.stdout);
+    if (mounts.length === 0) throw new InstallAppError("attach", "DMG attached but exposed no mount point");
+    mountPoint = mounts[0];
+    mounted = true;
+
+    let sourceApp = null;
+    for (const mp of mounts) {
+      const apps = fsImpl.readdirSync(mp).filter((n) => n.endsWith(".app"));
+      if (opts.appName) { if (apps.includes(opts.appName)) { sourceApp = path.join(mp, opts.appName); break; } }
+      else if (apps.length === 1) { sourceApp = path.join(mp, apps[0]); break; }
+      else if (apps.length > 1) throw new InstallAppError("ambiguous-app", `DMG contains multiple apps (${apps.join(", ")}); pass --app-name`);
+    }
+    if (!sourceApp) throw new InstallAppError("app-not-found", opts.appName ? `${opts.appName} not found in DMG` : "no .app found in DMG");
+    const appName = path.basename(sourceApp);
+    const installed = path.join(opts.dest, appName);
+    const hadInstalled = fsImpl.existsSync(installed);
+
+    // Verify the mounted app before touching anything installed.
+    failedStage = "verify";
+    const newTeam = await verifyBundle(run, sourceApp, { assess: true, staple: true });
+    const newBundleId = await readBundleId(run, sourceApp);
+    if (opts.bundleId && newBundleId !== opts.bundleId) throw new InstallAppError("bundle-id-mismatch", `DMG app bundle id ${newBundleId} != --bundle-id ${opts.bundleId}`);
+    let installedTeam = null;
+    if (hadInstalled) {
+      const installedBundleId = await readBundleId(run, installed);
+      if (installedBundleId !== newBundleId) throw new InstallAppError("bundle-id-mismatch", `DMG app bundle id ${newBundleId} != installed bundle id ${installedBundleId}`);
+      try { installedTeam = await teamIdOf(run, installed); } catch { installedTeam = null; }
+      if (installedTeam && installedTeam !== newTeam) throw new InstallAppError("team-id-changed", `refusing team change: installed ${installedTeam}, DMG ${newTeam}`);
+    }
+    const bundleId = opts.bundleId || newBundleId;
+    event("verified", { app: appName, bundleId, teamId: newTeam, replacing: hadInstalled });
+
+    // Quit running instance without UI.
+    failedStage = "quit";
+    const wasRunning = hadInstalled ? (await findPids(run, installed)).length > 0 : false;
+    const quit = hadInstalled ? await quitApp(run, kill, sleep, installed) : { pids: [], killed: [] };
+    event("quit", { wasRunning, pids: quit.pids, forced: quit.killed });
+
+    // Replace.
+    failedStage = "replace";
+    let trashed = null;
+    if (hadInstalled) {
+      const trashDir = path.join(home, ".Trash");
+      fsImpl.mkdirSync(trashDir, { recursive: true });
+      trashed = path.join(trashDir, trashName(appName, now()));
+      await moveAside(run, fsImpl, installed, trashed);
+    }
+    try {
+      await run("/usr/bin/ditto", [sourceApp, installed]);
+    } catch (error) {
+      try { fsImpl.rmSync(installed, { recursive: true, force: true }); } catch { /* ignore */ }
+      let restored = false;
+      if (trashed) { try { await moveAside(run, fsImpl, trashed, installed); restored = true; } catch { /* reported below */ } }
+      throw new InstallAppError("ditto-failed", `ditto failed (${errText(error)}); ${trashed ? (restored ? "previous app restored" : `RESTORE FAILED, previous app is at ${trashed}`) : "no previous app to restore"}`);
+    }
+    event("replaced", { installed, previous: trashed });
+    await detach();
+
+    // Re-verify installed copy.
+    failedStage = "reverify";
+    await verifyBundle(run, installed, { assess: true, staple: false });
+
+    // Relaunch hidden and in the background only.
+    const relaunch = opts.relaunch === null ? wasRunning : opts.relaunch;
+    if (relaunch) {
+      failedStage = "relaunch";
+      await run("/usr/bin/open", ["-g", "-j", "-b", bundleId]);
+      event("relaunched", { bundleId });
+    }
+    const result = { ok: true, app: appName, installed, bundleId, teamId: newTeam, previous: trashed, relaunched: relaunch };
+    event("done", result);
+    return result;
+  } catch (error) {
+    const reason = error instanceof InstallAppError ? error.message : errText(error);
+    event("failed", { stage: failedStage, code: error.code || "error", reason });
+    if (!(error instanceof InstallAppError)) throw new InstallAppError("error", reason);
+    throw error;
+  } finally {
+    await detach();
+  }
+}
+
+async function verifyBundle(run, app, { assess, staple }) {
+  const step = async (code, cmd, args) => {
+    try { return await run(cmd, args); }
+    catch (error) { throw new InstallAppError(code, `${code} failed for ${app}: ${errText(error)}`); }
+  };
+  await step("codesign-verify", "/usr/bin/codesign", ["--verify", "--deep", "--strict", app]);
+  const team = await teamIdOf(run, app);
+  if (!team) throw new InstallAppError("team-id-missing", `${app} has no Team ID (ad-hoc or unsigned)`);
+  await step("codesign-requirement", "/usr/bin/codesign", ["-dr", "-", app]);
+  if (assess) await step("spctl-assess", "/usr/sbin/spctl", ["--assess", "--type", "execute", app]);
+  if (staple) await step("stapler-validate", "/usr/bin/xcrun", ["stapler", "validate", app]);
+  return team;
+}
+
+async function teamIdOf(run, app) {
+  const out = await run("/usr/bin/codesign", ["-dvv", app]);
+  return parseTeamId(`${out.stderr || ""}\n${out.stdout || ""}`);
+}
+
+async function readBundleId(run, app) {
+  let out;
+  try { out = await run("/usr/bin/plutil", ["-convert", "json", "-o", "-", path.join(app, "Contents", "Info.plist")]); }
+  catch (error) { throw new InstallAppError("info-plist", `cannot read Info.plist of ${app}: ${errText(error)}`); }
+  const id = JSON.parse(out.stdout)?.CFBundleIdentifier;
+  if (typeof id !== "string" || !id) throw new InstallAppError("info-plist", `no CFBundleIdentifier in ${app}`);
+  return id;
+}
+
+async function findPids(run, app) {
+  const ps = await run("/bin/ps", ["-axo", "pid=,comm="]);
+  return matchPids(ps.stdout, app);
+}
+
+async function quitApp(run, kill, sleep, app) {
+  const pids = await findPids(run, app);
+  const send = (pid, sig) => { try { kill(pid, sig); } catch (e) { if (e.code !== "ESRCH") throw e; } };
+  for (const pid of pids) send(pid, "SIGTERM");
+  let waited = 0;
+  let remaining = pids.length ? await findPids(run, app) : [];
+  while (remaining.length && waited < SIGTERM_WAIT_MS) {
+    await sleep(POLL_MS);
+    waited += POLL_MS;
+    remaining = await findPids(run, app);
+  }
+  for (const pid of remaining) send(pid, "SIGKILL");
+  if (remaining.length) await sleep(POLL_MS);
+  return { pids, killed: remaining };
+}
+
+async function moveAside(run, fsImpl, from, to) {
+  try {
+    fsImpl.renameSync(from, to);
+  } catch (error) {
+    if (error.code !== "EXDEV") throw error;
+    await run("/usr/bin/ditto", [from, to]);
+    fsImpl.rmSync(from, { recursive: true, force: true });
+  }
+}
+
+export async function main(argv = process.argv.slice(2), io = {}) {
+  const stdout = io.stdout || ((s) => console.log(s));
+  const stderr = io.stderr || ((s) => console.error(s));
+  let opts;
+  try { opts = parseArgs(argv); }
+  catch (error) {
+    stderr(`right-release install-app: ${error.message}`);
+    stderr("usage: right-release install-app --dmg <path.dmg> [--app-name Pulse.app] [--bundle-id dev.orthic.pulse] [--dest /Applications] [--relaunch|--no-relaunch] [--json]");
+    return 2;
+  }
+  const emit = (e) => {
+    if (opts.json) { stdout(JSON.stringify({ schema: 1, ts: new Date().toISOString(), ...e })); return; }
+    const { event, ...rest } = e;
+    if (event === "failed") stderr(`install-app: failed at ${rest.stage}: ${rest.reason}`);
+    else stdout(`install-app: ${event}${Object.keys(rest).length ? ` ${JSON.stringify(rest)}` : ""}`);
+  };
+  try {
+    await installApp(opts, { ...io.deps, emit });
+    return 0;
+  } catch (error) {
+    return error.code === "unsupported" ? 3 : 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().then((code) => { process.exitCode = code; });
+}