@rightkit/release 0.2.135 → 0.2.137

package/codesign-environment.mjs

@@ -20,8 +20,21 @@ export function macosCodesignEnvironment(env = process.env, { platform = process
   if (platform !== "darwin") return env;
   const route = detect({ env }).guiRunner ? "agent" : "direct";
   const script = codesignShimScript({ route, node });
+  const automationScript = `#!/bin/sh\nexec ${quote(node)} ${quote(fileURLToPath(new URL("./osascript-guard.mjs", import.meta.url)))} "$@"\n`;
+  // Tauri's script invokes /usr/bin/osascript, bypassing PATH. Its env-bash
+  // shebang & app-side `bash bundle_dmg.sh` calls both traverse this wrapper.
+  const bashScript = `#!/bin/sh\nlayout_script=\nskip_layout=0\nfor arg in "$@"; do
+  case "$arg" in
+    */bundle_dmg.sh|bundle_dmg.sh) layout_script="$arg" ;;
+    --skip-jenkins) skip_layout=1 ;;
+  esac
+done
+if [ -n "$layout_script" ] && [ "$skip_layout" = 0 ]; then
+  exec ${quote(node)} ${quote(fileURLToPath(new URL("./osascript-guard.mjs", import.meta.url)))} --caller "$layout_script"
+fi
+exec /bin/bash "$@"\n`;
   // Immutable wrappers avoid races between GUI & SSH builds or package versions.
-  const identity = createHash("sha256").update(script).digest("hex").slice(0, 24);
+  const identity = createHash("sha256").update(script).update(automationScript).update(bashScript).digest("hex").slice(0, 24);
   const bin = path.join(resolveManagedRoot({ env }), "signing", "codesign-bin", identity);
   ensurePrivateDirectory(bin, { io });
   const file = path.join(bin, "codesign");
@@ -29,6 +42,17 @@ export function macosCodesignEnvironment(env = process.env, { platform = process
     privatePath(file, 0o700, { io });
     if (io.readFileSync(file, "utf8") !== script) throw new Error("Managed codesign shim content changed");
   } else io.writeFileSync(file, script, { mode: 0o700, flag: "wx" });
+  const automationFile = path.join(bin, "osascript");
+  if (io.existsSync(automationFile)) {
+    privatePath(automationFile, 0o700, { io });
+    if (io.readFileSync(automationFile, "utf8") !== automationScript) throw new Error("Managed osascript guard content changed");
+  } else io.writeFileSync(automationFile, automationScript, { mode: 0o700, flag: "wx" });
+  const bashFile = path.join(bin, "bash");
+  if (io.existsSync(bashFile)) {
+    privatePath(bashFile, 0o700, { io });
+    if (io.readFileSync(bashFile, "utf8") !== bashScript) throw new Error("Managed bash guard content changed");
+  } else io.writeFileSync(bashFile, bashScript, { mode: 0o700, flag: "wx" });
   // Keep every other shim (especially managed Cargo) in its original order.
-  return { ...env, PATH: [bin, ...(env.PATH ?? "").split(path.delimiter).filter((entry) => entry !== bin)].join(path.delimiter) };
+  return { ...env, CI: "true", TAURI_BUNDLER_DMG_IGNORE_CI: "false",
+    PATH: [bin, ...(env.PATH ?? "").split(path.delimiter).filter((entry) => entry !== bin)].join(path.delimiter) };
 }

package/codesign-shim.mjs

@@ -35,7 +35,8 @@ export async function runCodesignShim(argv, { cwd = process.cwd(), env = process
   return result;
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+const realOrSelf = (file) => { try { return fs.realpathSync(file); } catch { return path.resolve(file); } };
+if (process.argv[1] && realOrSelf(process.argv[1]) === realOrSelf(fileURLToPath(import.meta.url))) {
   try {
     // Only the managed shell wrapper invokes this entry: session detection was
     // already performed by right-release before selecting its wrapper directory.

package/committed-source.mjs

@@ -35,7 +35,7 @@ function gitEnv(env = process.env, platform = process.platform) {
 }
 
 function runGit(root, args, { encoding = "buffer", maxBuffer = 4 * 1024 * 1024, timeout = COMMAND_TIMEOUT_MS, runner = spawnSync, env = gitEnv(), input } = {}) {
-  const result = runner(nativeGitPath(), ["-C", root, "--no-replace-objects", "-c", "core.fsmonitor=false", "-c", `core.hooksPath=${os.devNull}`, ...args], {
+  const result = runner(nativeGitPath(), ["-C", root, "--no-replace-objects", "-c", "core.fsmonitor=false", "-c", `core.hooksPath=${os.devNull}`, "-c", `safe.directory=${root}`, ...args], {
     encoding, env, windowsHide: true, maxBuffer, timeout, ...(input ? { input } : {}),
   });
   if (result?.error || result?.status !== 0) throw new Error(`committed ownership: git ${args[0] ?? "command"} failed${result?.error?.code ? ` (${result.error.code})` : ""}`);
@@ -118,7 +118,7 @@ function acquire(root, { expectedCommit, expectedTree, requiredPaths = [], runne
   const text = (args) => runGit(root, args, { encoding: "utf8", runner, env }).trim();
   const repositoryRoot = path.resolve(text(["rev-parse", "--show-toplevel"]));
   const pathPrefix = text(["rev-parse", "--show-prefix"]).replaceAll("\\", "/");
-  const originResult = runner(nativeGitPath(), ["-C", repositoryRoot, "--no-replace-objects", "-c", "core.fsmonitor=false", "-c", `core.hooksPath=${os.devNull}`, "config", "--get", "remote.origin.url"], {
+  const originResult = runner(nativeGitPath(), ["-C", repositoryRoot, "--no-replace-objects", "-c", "core.fsmonitor=false", "-c", `core.hooksPath=${os.devNull}`, "-c", `safe.directory=${repositoryRoot}`, "config", "--get", "remote.origin.url"], {
     encoding: "utf8", env, windowsHide: true, maxBuffer: 4 * 1024 * 1024, timeout: COMMAND_TIMEOUT_MS,
   });
   const origin = originResult?.status === 0 ? String(originResult.stdout).trim() : null;
@@ -132,7 +132,7 @@ function acquire(root, { expectedCommit, expectedTree, requiredPaths = [], runne
   const rows = parseTree(runGit(root, ["ls-tree", "-r", "-z", "--full-tree", tree], { encoding: "buffer", maxBuffer: MAX_TREE_BYTES, timeout: COMMAND_TIMEOUT_MS, runner, env }), objectFormat);
   const wanted = new Set(requiredPaths.filter(validatePath));
   const shouldRead = (row) => row.type === "blob" && row.mode !== "120000" && (
-    wanted.has(row.rel) || ["Cargo.toml", "package.json", "Package.swift", "ownership-exceptions.json"].includes(path.posix.basename(row.rel)) ||
+    wanted.has(row.rel) || ["Cargo.toml", "package.json", "Package.swift", "ownership-exceptions.json", "Cargo.lock", "pnpm-lock.yaml", "package-lock.json", "npm-shrinkwrap.json", "yarn.lock"].includes(path.posix.basename(row.rel)) ||
     /\.(?:rs|ts|tsx|js|mjs|cjs|jsx|swift|m|mm|c|cc|cpp|h|py|go|kt|java|cs)$/i.test(row.rel)
   );
   const candidates = rows.filter(shouldRead);

package/development.mjs

@@ -1,8 +1,9 @@
+import { discoverBrokerSocket, resolveManagedRoots } from './managed-roots.mjs';
 import { spawnSync } from "./background-process.mjs";
 import { createHash } from "node:crypto";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
 import { assertReleaseExecutionAllowed } from "./execution-policy.mjs";
 import { acquireManagedRunLease, managedRuntimeClient, runCargoSync } from "./managed-cargo.mjs";
@@ -27,16 +28,14 @@ export function developmentEnvironment(env = process.env) {
   delete result.CARGO_INCREMENTAL;
   const client = managedRuntimeClient(result);
   if (client) {
-    const managedRoot = result.RIGHTKIT_MANAGED_ROOT ?? result.RIGHTKIT_EXTERNAL_ROOT
-      ?? (process.platform === "win32" ? "D:\\.rightkit-managed" : process.platform === "darwin" ? "/Volumes/D/.rightkit-managed" : undefined);
-    const agentBin = managedRoot && path.join(managedRoot, "agent-bin");
+    const { agentBin } = resolveManagedRoots({ env: result });
     if (agentBin && existsSync(agentBin)) {
       const pathKey = Object.keys(result).find((key) => key.toLowerCase() === "path") ?? "PATH";
       result[pathKey] = [agentBin, result[pathKey]].filter(Boolean).join(path.delimiter);
     }
     // Same default as the agent-bin `rightkit` shim: children that run the managed client directly
     // (resolveCommand("rightkit"), build scripts) must not lose the broker endpoint.
-    const socket = managedRoot && path.join(managedRoot, "broker.sock");
+    const socket = discoverBrokerSocket(result);
     if (!result.RIGHTKIT_BUILD_BROKER_SOCKET && socket && existsSync(socket)) result.RIGHTKIT_BUILD_BROKER_SOCKET = socket;
   }
   return result;
@@ -212,7 +211,7 @@ export function resolveCommand(command, args, { root, env = process.env } = {})
   if (command === "rightkit") {
     const client = managedRuntimeClient(env);
     if (!client) throw new Error("installed RightKit runtime client is unavailable for development command");
-    const socket = path.join(path.dirname(path.dirname(path.dirname(path.dirname(client)))), "broker.sock");
+    const socket = discoverBrokerSocket(env);
     const childEnv = !env.RIGHTKIT_BUILD_BROKER_SOCKET && existsSync(socket) ? { ...env, RIGHTKIT_BUILD_BROKER_SOCKET: socket } : undefined;
     return { command: process.execPath, args: [client, ...args], ...(childEnv ? { env: childEnv } : {}) };
   }
@@ -282,6 +281,7 @@ export async function main(args = process.argv.slice(2)) {
   return result;
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+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))) {
   main().catch((error) => { console.error(`right-release dev: ${error.code ? `[${error.code}] ` : ""}${error.message}`); process.exitCode = 1; });
 }

package/direct-bootstrap.mjs

@@ -1,5 +1,6 @@
+import { readVerifiedArtifact } from "./publication-artifacts.mjs";
 import { createHash } from "node:crypto";
-import { mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, rmSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { spawnSync } from "./background-process.mjs";
 import { RIGHTRELEASE_MANIFEST_SIGNER, signReleaseManifestWithAzure } from "./sign-release-manifest.mjs";
@@ -539,7 +540,8 @@ export function planBootstrapPublication({ product, bootstrapVersion, scriptPath
   if (stableKey !== `${product}/install.ps1`) throw new Error("bootstrap stable key must be product/install.ps1");
   const script = statSync(scriptPath);
   if (!script.isFile() || script.size < 1 || script.size > MAX_BOOTSTRAP_BYTES || scriptPath.split(/[\\/]/).at(-1) !== "install.ps1") throw new Error("bootstrap must be one small install.ps1 file");
-  const validation = validatePowerShellBootstrap(readFileSync(scriptPath, "utf8"), { product });
+  const scriptBytes = readFileSync(scriptPath);
+  const validation = validatePowerShellBootstrap(scriptBytes.toString("utf8"), { product });
   if (!validation.valid) throw new Error("bootstrap script violates generated RightRelease contract: " + validation.errors.join("; "));
   const versionedKey = `${product}/versions/${bootstrapVersion}/install.ps1`;
   return {
@@ -549,7 +551,7 @@ export function planBootstrapPublication({ product, bootstrapVersion, scriptPath
     stableKey,
     versionedKey,
     scriptPath: resolve(scriptPath),
-    sha256: sha256File(scriptPath),
+    sha256: createHash("sha256").update(scriptBytes).digest("hex"),
   };
 }
 
@@ -567,16 +569,24 @@ export function createWranglerR2Client({ commandRunner = spawnSync, wranglerRunn
 
 export function publishBootstrapPlan(plan, r2, { verificationPath }) {
   validateBootstrapPublicationPlan(plan);
-  r2.put(plan.bucket, plan.versionedKey, plan.scriptPath);
-  r2.get(plan.bucket, plan.versionedKey, verificationPath);
-  if (sha256File(verificationPath) !== plan.sha256) throw new Error("immutable bootstrap remote verification failed");
-  r2.put(plan.bucket, plan.stableKey, plan.scriptPath);
-  r2.get(plan.bucket, plan.stableKey, verificationPath);
-  if (sha256File(verificationPath) !== plan.sha256) throw new Error("stable bootstrap remote verification failed");
+  readVerifiedArtifact(plan.scriptPath, { sha256: plan.sha256 });
+  for (const [label, key] of [["immutable", plan.versionedKey], ["stable", plan.stableKey]]) {
+    try { r2.put(plan.bucket, key, plan.scriptPath); }
+    catch { throw new Error(`bootstrap upload failed; inspect remote key ${plan.bucket}/${key}`); }
+    // A successful readback must materialize fresh bytes, never reuse prior output.
+    rmSync(verificationPath, { force: true });
+    try {
+      r2.get(plan.bucket, key, verificationPath);
+      readVerifiedArtifact(verificationPath, { sha256: plan.sha256 });
+    } catch {
+      throw new Error(`${label} bootstrap remote verification failed; remove remote key ${plan.bucket}/${key}`);
+    }
+  }
   return { ...plan, verified: true };
 }
 
 export function validateBootstrapPublicationPlan(plan) {
+  if (!/^[a-f0-9]{64}$/.test(plan?.sha256 ?? "")) throw new Error("bootstrap publication hash evidence is required");
   if (!plan || !/^[a-z][a-z0-9-]+$/.test(plan.product ?? "")) throw new Error("bootstrap publication product is invalid");
   if (!VERSION.test(plan.bootstrapVersion ?? "")) throw new Error("bootstrap publication version is invalid");
   if (plan.bucket !== "rightapps-downloads") throw new Error("bootstrap publication bucket is not branded public R2");

package/dmg-build.mjs

@@ -0,0 +1,117 @@
+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { backgroundAlias, dmgDSStore } from "./dmg-layout.mjs";
+import { assertReleaseExecutionAllowed } from "./execution-policy.mjs";
+
+const fail = (code, message) => Object.assign(new Error(message), { code });
+const pair = (value, label, positive = false) => {
+  const numbers = Array.isArray(value) ? value : String(value).split(",").map(Number);
+  if (numbers.length !== 2 || numbers.some((n) => !Number.isInteger(n) || n < (positive ? 1 : 0) || n > 32767)) {
+    throw fail("DMG_INVALID_OPTIONS", `${label} requires ${positive ? "positive" : "nonnegative"} x,y integers <=32767`);
+  }
+  return numbers;
+};
+
+export function buildDmg({ app, out, volname, background, iconSize = 128, appPosition = [158, 231],
+  applicationsPosition = [492, 231], window = [660, 400], volumeIcon } = {},
+{ platform = process.platform, run = spawnSync, makeAlias = backgroundAlias,
+  log = (event) => console.error(JSON.stringify(event)) } = {}) {
+  if (platform !== "darwin") throw fail("DMG_NATIVE_HOST_REQUIRED", "DMG creation requires macOS");
+  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"))) {
+    throw fail("DMG_INVALID_OPTIONS", `expected .app bundle with Contents/Info.plist: ${app}`);
+  }
+  if (!out.endsWith(".dmg") || out.startsWith(`${app}${path.sep}`)) throw fail("DMG_INVALID_OPTIONS", "--out must be a .dmg outside app bundle");
+  if (/[\0\r\n/:]/.test(volname) || Buffer.byteLength(volname) > 255) throw fail("DMG_INVALID_OPTIONS", "invalid volume name");
+  iconSize = Number(iconSize);
+  if (!Number.isInteger(iconSize) || iconSize < 16 || iconSize > 512) throw fail("DMG_INVALID_OPTIONS", "--icon-size must be 16..512");
+  appPosition = pair(appPosition, "--app-position"); applicationsPosition = pair(applicationsPosition, "--applications-position");
+  window = pair(window, "--window", true);
+  if (volumeIcon) {
+    volumeIcon = path.resolve(volumeIcon);
+    if (!existsSync(volumeIcon) || !statSync(volumeIcon).isFile() || !/\.icns$/i.test(volumeIcon)) throw fail("DMG_INVALID_OPTIONS", "--volume-icon must be an .icns file");
+  }
+  if (background) {
+    background = path.resolve(background);
+    // Existing Right Suite backgrounds include TIFF; accept PNG & TIFF without conversion.
+    if (!statSync(background).isFile() || !/\.(png|tiff?)$/i.test(background)) throw fail("DMG_INVALID_OPTIONS", "background must be PNG or TIFF");
+    if (/\.png$/i.test(background) && !readFileSync(background).subarray(0, 8).equals(Buffer.from("89504e470d0a1a0a", "hex"))) {
+      throw fail("DMG_INVALID_OPTIONS", "invalid PNG signature");
+    }
+  }
+  for (let cursor = out; cursor !== path.dirname(cursor); cursor = path.dirname(cursor)) {
+    if (existsSync(cursor) && lstatSync(cursor).isSymbolicLink()) throw fail("DMG_INVALID_OPTIONS", `output must not traverse symlink: ${cursor}`);
+  }
+  assertReleaseExecutionAllowed({ cwd: app, command: "right-release dmg build" });
+  mkdirSync(path.dirname(out), { recursive: true });
+  const work = mkdtempSync(path.join(path.dirname(out), ".rightkit-dmg-")), stage = path.join(work, "stage"), mount = path.join(work, "mount");
+  const rw = path.join(work, "writable.dmg"), compressed = path.join(work, "compressed.dmg");
+  let attached = false, attaching = false;
+  const command = (tool, args) => {
+    const result = run(tool, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], shell: false, timeout: 300000 });
+    if (result.error || result.status !== 0) throw fail("DMG_COMMAND_FAILED", `${tool} ${args[0]} failed: ${result.error?.message ?? result.stderr ?? result.status}`);
+    return result;
+  };
+  log({ event: "dmg-build-started", app, out, volname });
+  try {
+    mkdirSync(stage); mkdirSync(mount);
+    command("/usr/bin/ditto", [app, path.join(stage, path.basename(app))]);
+    symlinkSync("/Applications", path.join(stage, "Applications"));
+    const relative = background ? path.join(".background", path.basename(background)) : null;
+    if (relative) { mkdirSync(path.join(stage, ".background")); copyFileSync(background, path.join(stage, relative)); }
+    // Include layout headroom in hdiutil's source-folder size estimate. Alias
+    // CNIDs become available only after mounting, when this reservation is replaced.
+    writeFileSync(path.join(stage, ".DS_Store"), Buffer.alloc(64 * 1024));
+    command("/usr/bin/hdiutil", ["create", "-fs", "HFS+", "-format", "UDRW", "-volname", volname, "-srcfolder", stage, rw]);
+    attaching = true;
+    command("/usr/bin/hdiutil", ["attach", "-readwrite", "-nobrowse", "-noautoopen", "-mountpoint", mount, rw]);
+    attached = true; attaching = false;
+    if (volumeIcon) {
+      // Custom volume icon: .VolumeIcon.icns at the root plus the volume's kHasCustomIcon (0x0400) Finder flag.
+      copyFileSync(volumeIcon, path.join(mount, ".VolumeIcon.icns"));
+      const finderInfo = Buffer.alloc(32); finderInfo.writeUInt16BE(0x0400, 8);
+      command("/usr/bin/xattr", ["-wx", "com.apple.FinderInfo", finderInfo.toString("hex"), mount]);
+    }
+    const alias = relative ? makeAlias({ mount, volname, relative }) : undefined;
+    writeFileSync(path.join(mount, ".DS_Store"), dmgDSStore({ appName: path.basename(app), iconSize,
+      appPosition, applicationsPosition, window, alias }));
+    command("/usr/bin/hdiutil", ["detach", mount]); attached = false;
+    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" };
+  } catch (error) {
+    log({ event: "dmg-build-failed", out, code: error.code ?? "DMG_BUILD_FAILED", message: error.message });
+    throw error;
+  } finally {
+    if (attached || attaching) {
+      try { command("/usr/bin/hdiutil", ["detach", "-force", mount]); attached = false; attaching = false; }
+      catch (error) { log({ event: "dmg-cleanup-failed", mount, work, message: error.message }); }
+    }
+    // Never recurse through a mount that failed to detach.
+    if (!attached && !attaching) rmSync(work, { recursive: true, force: true });
+  }
+}
+
+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"], ["--volume-icon", "volumeIcon"]]);
+  const options = {};
+  for (let i = 1; i < args.length; i += 2) {
+    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];
+  }
+  return options;
+}
+
+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))) {
+  try { buildDmg(parseDmgArguments(process.argv.slice(2))); }
+  catch (error) { console.error(`right-release dmg: [${error.code ?? "DMG_BUILD_FAILED"}] ${error.message}`); process.exitCode = 1; }
+}

package/dmg-layout.mjs

@@ -0,0 +1,123 @@
+// Finder records follow dmgbuild's ds_store/mac_alias formats. No Finder IPC.
+// https://github.com/dmgbuild/ds_store/tree/main/src/ds_store
+// https://github.com/dmgbuild/mac_alias/blob/main/src/mac_alias/alias.py
+import { statSync } from "node:fs";
+import path from "node:path";
+
+const u32 = (n) => { const b = Buffer.alloc(4); b.writeUInt32BE(n); return b; };
+const u16 = (n) => { const b = Buffer.alloc(2); b.writeUInt16BE(n); return b; };
+const utf16 = (s) => Buffer.from(s, "utf16le").swap16();
+const uint = (n, size) => { const b = Buffer.alloc(size); b.writeUIntBE(n, 0, size); return b; };
+
+// Small binary-plist encoder for Finder view dictionaries (strings, data, real,
+// integer, boolean). Object references & offset widths are computed per plist.
+export function finderPlist(value) {
+  const objects = [];
+  function add(v, key) {
+    const id = objects.length;
+    objects.push(null);
+    if (Buffer.isBuffer(v)) objects[id] = { kind: 0x40, bytes: v, length: v.length };
+    else if (typeof v === "string") objects[id] = { kind: 0x60, bytes: utf16(v), length: v.length };
+    else if (typeof v === "boolean") objects[id] = { bytes: Buffer.from([v ? 9 : 8]) };
+    else if (typeof v === "number") {
+      if (!Number.isFinite(v)) throw new TypeError("non-finite plist value");
+      const bytes = Buffer.alloc(9);
+      if (["viewOptionsVersion", "backgroundType", "SidebarWidth"].includes(key)) {
+        bytes[0] = 0x13; bytes.writeBigInt64BE(BigInt(v), 1);
+      } else { bytes[0] = 0x23; bytes.writeDoubleBE(v, 1); }
+      objects[id] = { bytes };
+    } else {
+      const entries = Object.entries(v);
+      objects[id] = { kind: 0xd0, length: entries.length,
+        refs: [...entries.map(([k]) => add(k)), ...entries.map(([k, val]) => add(val, k))] };
+    }
+    return id;
+  }
+  const root = add(value), refSize = objects.length < 256 ? 1 : 2;
+  const prefix = (kind, length) => length < 15 ? Buffer.from([kind | length])
+    : Buffer.concat([Buffer.from([kind | 15, 0x12]), u32(length)]);
+  const chunks = objects.map((o) => o.kind == null ? o.bytes : Buffer.concat([
+    prefix(o.kind, o.length), o.refs ? Buffer.concat(o.refs.map((ref) => uint(ref, refSize))) : o.bytes,
+  ]));
+  let offset = 8;
+  const offsets = chunks.map((chunk) => { const start = offset; offset += chunk.length; return start; });
+  const offsetSize = offset < 256 ? 1 : offset < 65536 ? 2 : 4;
+  const trailer = Buffer.alloc(32);
+  trailer[6] = offsetSize; trailer[7] = refSize;
+  trailer.writeBigUInt64BE(BigInt(objects.length), 8);
+  trailer.writeBigUInt64BE(BigInt(root), 16);
+  trailer.writeBigUInt64BE(BigInt(offset), 24);
+  return Buffer.concat([Buffer.from("bplist00"), ...chunks, ...offsets.map((n) => uint(n, offsetSize)), trailer]);
+}
+
+/** Carbon Alias v2, with mounted HFS+ CNIDs, dates, Unicode & volume-relative paths. */
+export function backgroundAlias({ mount, volname, relative, stat = statSync }) {
+  const target = path.join(mount, relative), file = stat(target), volume = stat(mount), folder = stat(path.dirname(target));
+  const macDate = (s) => Math.floor(s.birthtimeMs / 1000 + 2082844800);
+  const header = Buffer.alloc(150);
+  header.writeUInt16BE(2, 6); // version; kind=file
+  const pascal = (text, offset, size) => {
+    const bytes = Buffer.from(text.replaceAll(":", "/"));
+    header[offset] = Math.min(bytes.length, size - 1); bytes.copy(header, offset + 1, 0, size - 1);
+  };
+  pascal(volname, 10, 28); header.writeUInt32BE(macDate(volume), 38);
+  header.write("H+", 42, "ascii");
+  header.writeUInt32BE(folder.ino, 46); pascal(path.basename(target), 50, 64);
+  header.writeUInt32BE(file.ino, 114); header.writeUInt32BE(macDate(file), 118);
+  header.writeInt16BE(-1, 130); header.writeInt16BE(-1, 132);
+  const tag = (code, bytes) => Buffer.concat([u16(code), u16(bytes.length), bytes, ...(bytes.length % 2 ? [Buffer.alloc(1)] : [])]);
+  const unicode = (s) => Buffer.concat([u16(s.length), utf16(s)]);
+  const highDate = (s) => { const b = Buffer.alloc(8); b.writeBigUInt64BE(BigInt(Math.floor((s.birthtimeMs / 1000 + 2082844800) * 65536))); return b; };
+  const carbonPath = `${volname}:${relative.split(path.sep).map((s) => s.replaceAll(":", "/")).join(":\0")}`;
+  const bytes = Buffer.concat([header, tag(0, Buffer.from(path.basename(path.dirname(target)))),
+    tag(16, highDate(volume)), tag(17, highDate(file)), tag(1, u32(folder.ino)), tag(2, Buffer.from(carbonPath)),
+    tag(14, unicode(path.basename(target))), tag(15, unicode(volname)),
+    tag(18, Buffer.from(`/${relative.split(path.sep).join("/")}`)), tag(19, Buffer.from(mount)),
+    Buffer.from([255, 255, 0, 0])]);
+  if (bytes.length > 32767) throw new RangeError("background alias too large");
+  bytes.writeUInt16BE(bytes.length, 4);
+  return bytes;
+}
+
+/** One sorted B-tree leaf in a valid Bud1 allocator, sufficient for DMG layout. */
+export function dmgDSStore({ appName, iconSize = 128, appPosition = [158, 231],
+  applicationsPosition = [492, 231], window = [660, 400], alias } = {}) {
+  const entries = [];
+  const add = (name, code, type, bytes) => entries.push({ name, code, bytes: Buffer.concat([
+    u32(name.length), utf16(name), Buffer.from(code + type), ...(type === "blob" ? [u32(bytes.length)] : []), bytes,
+  ]) });
+  add(".", "vSrn", "long", u32(1));
+  add(".", "icvl", "type", Buffer.from("icnv"));
+  add(".", "bwsp", "blob", finderPlist({ ShowStatusBar: false, ShowToolbar: false, ShowTabView: false,
+    ShowPathbar: false, ShowSidebar: false, ContainerShowSidebar: false, PreviewPaneVisibility: false,
+    SidebarWidth: 0, WindowBounds: `{{100, 100}, {${window[0]}, ${window[1]}}}` }));
+  add(".", "icvp", "blob", finderPlist({ viewOptionsVersion: 1, backgroundType: alias ? 2 : 0,
+    backgroundColorRed: 1, backgroundColorGreen: 1, backgroundColorBlue: 1,
+    gridOffsetX: 0, gridOffsetY: 0, gridSpacing: 100, arrangeBy: "none", showIconPreview: true,
+    showItemInfo: false, labelOnBottom: true, textSize: 16, iconSize,
+    scrollPositionX: 0, scrollPositionY: 0, ...(alias ? { backgroundImageAlias: alias } : {}) }));
+  for (const [name, point] of [[appName, appPosition], ["Applications", applicationsPosition]]) {
+    add(name, "Iloc", "blob", Buffer.concat([u32(point[0]), u32(point[1]), u32(0xffffffff), u32(0xffff0000)]));
+  }
+  entries.sort((a, b) => a.name.toLowerCase() < b.name.toLowerCase() ? -1
+    : a.name.toLowerCase() > b.name.toLowerCase() ? 1 : a.code < b.code ? -1 : 1);
+  const leafData = Buffer.concat([u32(0), u32(entries.length), ...entries.map((e) => e.bytes)]);
+  const pagePower = Math.max(12, Math.ceil(Math.log2(leafData.length))), pageSize = 2 ** pagePower;
+  if (pagePower > 20) throw new RangeError("DMG layout too large");
+  // Larger leaf starts at its own aligned boundary; unused buddies remain free.
+  const leafOffset = pageSize, file = Buffer.alloc(leafOffset + pageSize + 4);
+  Buffer.concat([u32(1), Buffer.from("Bud1"), u32(2048), u32(2048), u32(2048),
+    Buffer.from("0000100c000000870000200b00000000", "hex")]).copy(file);
+  const root = Buffer.alloc(2048); let pos = 0;
+  const write = (bytes) => { bytes.copy(root, pos); pos += bytes.length; };
+  write(u32(3)); write(u32(0)); write(u32(2048 | 11)); write(u32(32 | 5)); write(u32(leafOffset | pagePower));
+  pos = 1032; write(u32(1)); write(Buffer.from([4])); write(Buffer.from("DSDB")); write(u32(1));
+  for (let power = 0; power < 32; power++) {
+    const free = power >= 6 && power <= 10 || power >= 12 && power !== pagePower && power <= 30;
+    write(u32(free ? 1 : 0)); if (free) write(u32(2 ** power));
+  }
+  root.copy(file, 2052);
+  Buffer.concat([u32(2), u32(0), u32(entries.length), u32(1), u32(pageSize)]).copy(file, 36);
+  leafData.copy(file, leafOffset + 4);
+  return file;
+}