@rightkit/release 0.2.151 → 0.2.153

package/crate-graph.mjs

@@ -0,0 +1,121 @@
+// Cargo manifest helpers for the release gates: package identity, workspace path-dependency
+// closure and Cargo.lock dependency closure. Pure TOML parsing (smol-toml); nothing shells out to cargo.
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parse } from "smol-toml";
+
+const DEP_TABLES = ["dependencies", "build-dependencies", "dev-dependencies"];
+
+/** Nearest ancestor (or self) directory whose Cargo.toml has a [workspace] table, or null. */
+export function findWorkspaceRoot(dir, { exists = existsSync, readFile = readFileSync } = {}) {
+  let current = path.resolve(dir);
+  for (;;) {
+    const manifest = path.join(current, "Cargo.toml");
+    if (exists(manifest)) {
+      try { if (parse(readFile(manifest, "utf8")).workspace) return current; } catch { /* unreadable: keep climbing */ }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/**
+ * `{ name, version, manifest }` from a crate's Cargo.toml, parsed (not pattern-matched).
+ * `version.workspace = true` resolves through the workspace root's `[workspace.package].version`.
+ * `version` is null when it cannot be resolved to a string.
+ */
+export function readCargoPackage(crateDir, deps = {}) {
+  const { exists = existsSync, readFile = readFileSync } = deps;
+  const manifest = parse(readFile(path.join(crateDir, "Cargo.toml"), "utf8"));
+  const pkg = manifest.package ?? {};
+  let version = pkg.version;
+  if (version && typeof version === "object" && version.workspace === true) {
+    const root = findWorkspaceRoot(crateDir, { exists, readFile });
+    version = root ? parse(readFile(path.join(root, "Cargo.toml"), "utf8")).workspace?.package?.version : undefined;
+  }
+  return { name: pkg.name ?? null, version: typeof version === "string" && version.trim() ? version : null, manifest };
+}
+
+function depTables(manifest, includeDev) {
+  const tables = [];
+  const take = (holder) => {
+    for (const key of DEP_TABLES) {
+      if (key === "dev-dependencies" && !includeDev) continue;
+      if (holder?.[key]) tables.push(holder[key]);
+    }
+  };
+  take(manifest);
+  for (const target of Object.values(manifest.target ?? {})) take(target);
+  return tables;
+}
+
+/**
+ * Absolute directories of the workspace crates `crateDir` depends on through `path` dependencies,
+ * transitively. Dev-dependencies count for the crate itself (benches and tests use them) and not for
+ * its dependencies. `{ workspace = true }` entries resolve through `[workspace.dependencies]`.
+ */
+export function pathDependencyDirs(crateDir, deps = {}) {
+  const { exists = existsSync, readFile = readFileSync } = deps;
+  const root = findWorkspaceRoot(crateDir, { exists, readFile });
+  const workspaceDeps = root ? (parse(readFile(path.join(root, "Cargo.toml"), "utf8")).workspace?.dependencies ?? {}) : {};
+  const found = new Set();
+  const visit = (dir, includeDev) => {
+    const manifestPath = path.join(dir, "Cargo.toml");
+    if (!exists(manifestPath)) return;
+    const manifest = parse(readFile(manifestPath, "utf8"));
+    for (const table of depTables(manifest, includeDev)) {
+      for (const spec of Object.values(table)) {
+        if (!spec || typeof spec !== "object" || spec.path === undefined) continue;
+        const target = path.resolve(dir, spec.path);
+        if (found.has(target) || target === path.resolve(crateDir)) continue;
+        found.add(target);
+        visit(target, false);
+      }
+      // Workspace-inherited path dependencies, keyed by dependency name.
+      for (const [name, spec] of Object.entries(table)) {
+        if (spec && typeof spec === "object" && spec.workspace === true && workspaceDeps[name]?.path !== undefined) {
+          const target = path.resolve(root, workspaceDeps[name].path);
+          if (found.has(target) || target === path.resolve(crateDir)) continue;
+          found.add(target);
+          visit(target, false);
+        }
+      }
+    }
+  };
+  visit(path.resolve(crateDir), true);
+  return [...found].sort();
+}
+
+const depName = (entry) => String(entry).split(" ")[0];
+
+/**
+ * Canonical [[package]] entries of Cargo.lock reachable from `name`: the crate, every workspace crate
+ * and every external crate in its dependency graph, with version, source, checksum and edges. Two
+ * lock files give equal closures exactly when nothing in that graph changed.
+ */
+export function lockClosure(lockText, name) {
+  const packages = parse(lockText).package ?? [];
+  const byName = new Map();
+  for (const entry of packages) {
+    if (!byName.has(entry.name)) byName.set(entry.name, []);
+    byName.get(entry.name).push(entry);
+  }
+  const seen = new Set();
+  const out = [];
+  const queue = [...(byName.get(name) ?? [])];
+  while (queue.length) {
+    const entry = queue.pop();
+    const key = `${entry.name}@${entry.version}@${entry.source ?? ""}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ name: entry.name, version: entry.version, source: entry.source ?? null, checksum: entry.checksum ?? null, dependencies: [...(entry.dependencies ?? [])].sort() });
+    for (const dependency of entry.dependencies ?? []) {
+      const parts = String(dependency).split(" ");
+      const candidates = byName.get(depName(dependency)) ?? [];
+      const matching = parts[1] ? candidates.filter((c) => c.version === parts[1]) : candidates;
+      queue.push(...(matching.length ? matching : candidates));
+    }
+  }
+  return out.sort((a, b) => `${a.name}@${a.version}@${a.source}`.localeCompare(`${b.name}@${b.version}@${b.source}`));
+}

package/development-signing.mjs

@@ -38,6 +38,14 @@ function readPlist(file, context) {
   catch { throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_CONFIG_INVALID", `Invalid plist JSON: ${file}`); }
 }
 
+/** CFBundleExecutable of a bundle, read through the same plutil path (and injectable runner) as every other plist here. */
+export function readBundleExecutable(bundle, { root, env = process.env, run = spawnSync }) {
+  const file = path.join(bundle, "Contents", "Info.plist");
+  const name = readPlist(file, { root, env, run }).CFBundleExecutable;
+  if (typeof name !== "string" || !name.trim() || /[\\/]/.test(name)) throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_CONFIG_INVALID", `Info.plist has no usable CFBundleExecutable: ${file}`);
+  return name.trim();
+}
+
 function decodeProfile(file, context) {
   const cms = checked("security", ["cms", "-D", "-i", file], context, "DEV_MAC_SIGNING_PROFILE_INVALID");
   // plutil JSON conversion rejects the date/data values in provisioning profiles.

package/development.mjs

@@ -9,7 +9,7 @@ import { assertReleaseExecutionAllowed } from "./execution-policy.mjs";
 import { acquireManagedRunLease, managedRuntimeClient, managedRuntimeCommand, runCargoSync } from "./managed-cargo.mjs";
 import { BUNDLE_MARKERS, bundleMarkerBuffer, readTauriBundleMarkers } from "./tauri-bundle-marker.mjs";
 import { installPortableDevelopment } from "./portable-development.mjs";
-import { signMacosDevelopmentBundle } from "./development-signing.mjs";
+import { readBundleExecutable, signMacosDevelopmentBundle } from "./development-signing.mjs";
 import { macosCodesignEnvironment } from "./codesign-environment.mjs";
 
 export const DEVELOPMENT_PROFILE = "release-iterate";
@@ -113,23 +113,56 @@ function install(descriptor, { root, platform, config, env, run, sinceMs = null
   rmSync(backup, { recursive: true, force: true });
   cpSync(app, staging, { recursive: true, verbatimSymlinks: true });
   let signing;
-  try { signing = signMacosDevelopmentBundle({ root, bundle: staging, descriptor, config, env, run }); }
-  catch (error) { rmSync(staging, { recursive: true, force: true }); throw error; }
+  let executableName;
+  try {
+    signing = signMacosDevelopmentBundle({ root, bundle: staging, descriptor, config, env, run });
+    executableName = readBundleExecutable(staging, { root, env, run });
+  } catch (error) { rmSync(staging, { recursive: true, force: true }); throw error; }
+  swapInstalledMacosBundle({ staging, destination, backup, executableName });
+  if (signing.provisioningProfile) signing.provisioningProfile = path.join(destination, "Contents", "embedded.provisionprofile");
+  console.log(`right-release dev: installed ${destination}; identity=${signing.identity}; TeamIdentifier=${signing.teamIdentifier}; profile=${signing.provisioningProfile ?? "none"}`);
+  return signing;
+}
+
+export class DevelopmentInstallError extends Error {
+  constructor(code, message) { super(message); this.name = "DevelopmentInstallError"; this.code = code; }
+}
+
+const NODE_FS = { existsSync, readFileSync, renameSync, rmSync, statSync };
+
+/**
+ * Move the signed staging bundle into place and verify it before the previous app's backup is removed: Info.plist exists and
+ * the installed main executable (`executableName`, the staged CFBundleExecutable read through plutil by the caller) exists with the same SHA-256 as the staged one. Any failure removes the
+ * new install, restores the backup and throws a DevelopmentInstallError (code DEV_INSTALL_VERIFICATION_FAILED,
+ * DEV_INSTALL_EXECUTABLE_MISSING or DEV_INSTALL_EXECUTABLE_MISMATCH). `fs` is the file-system seam (tests inject it).
+ */
+export function swapInstalledMacosBundle({ staging, destination, backup, executableName, fs = NODE_FS }) {
+  if (typeof executableName !== "string" || !executableName) throw new DevelopmentInstallError("DEV_INSTALL_VERIFICATION_FAILED", "swapInstalledMacosBundle requires the staged CFBundleExecutable name");
+  const executable = path.join("Contents", "MacOS", executableName);
+  const digest = (file) => createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+  let expected;
+  try { expected = digest(path.join(staging, executable)); }
+  catch (error) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw new DevelopmentInstallError("DEV_INSTALL_EXECUTABLE_MISSING", `staged app has no main executable ${executable}: ${staging} (${error.message})`);
+  }
   let backedUp = false;
   try {
-    if (existsSync(destination)) { renameSync(destination, backup); backedUp = true; }
-    renameSync(staging, destination);
-    if (!existsSync(path.join(destination, "Contents", "Info.plist"))) throw new Error(`installed app verification failed: ${destination}`);
-    if (backedUp) rmSync(backup, { recursive: true, force: true });
+    if (fs.existsSync(destination)) { fs.renameSync(destination, backup); backedUp = true; }
+    fs.renameSync(staging, destination);
+    if (!fs.existsSync(path.join(destination, "Contents", "Info.plist"))) throw new DevelopmentInstallError("DEV_INSTALL_VERIFICATION_FAILED", `installed app verification failed: ${destination}`);
+    const installed = path.join(destination, executable);
+    let actual;
+    try { actual = digest(installed); }
+    catch { throw new DevelopmentInstallError("DEV_INSTALL_EXECUTABLE_MISSING", `installed app verification failed: main executable ${executable} is missing in ${destination}`); }
+    if (actual !== expected) throw new DevelopmentInstallError("DEV_INSTALL_EXECUTABLE_MISMATCH", `installed app verification failed: ${executable} SHA-256 ${actual} does not match the staged ${expected}`);
+    if (backedUp) fs.rmSync(backup, { recursive: true, force: true });
   } catch (error) {
-    rmSync(destination, { recursive: true, force: true });
-    if (backedUp && existsSync(backup)) renameSync(backup, destination);
-    rmSync(staging, { recursive: true, force: true });
+    fs.rmSync(destination, { recursive: true, force: true });
+    if (backedUp && fs.existsSync(backup)) fs.renameSync(backup, destination);
+    fs.rmSync(staging, { recursive: true, force: true });
     throw error;
   }
-  if (signing.provisioningProfile) signing.provisioningProfile = path.join(destination, "Contents", "embedded.provisionprofile");
-  console.log(`right-release dev: installed ${destination}; identity=${signing.identity}; TeamIdentifier=${signing.teamIdentifier}; profile=${signing.provisioningProfile ?? "none"}`);
-  return signing;
 }
 
 export function resolveTauriArtifact(descriptor, { root, platform, env = process.env, runCargo = runCargoSync }) {

package/devtools-policy.json

@@ -0,0 +1,5 @@
+{
+  "schema": 1,
+  "note": "Owner's fixed design: every Right app has no access to DevTools; ViewRight alone may inspect the HTML content it opens, never its own UI or shell. Only an app listed here may declare devtools: \"content-only\" in its right-release config. Edit only on the owner's instruction.",
+  "contentOnlyApps": ["viewright"]
+}

package/devtools-policy.mjs

@@ -0,0 +1,119 @@
+// Release-side half of the DevTools policy (the runtime half is crates/rightkit-tauri-shell/src/devtools.rs).
+//
+// Owner's fixed design: every Right app has absolutely NO access to DevTools. The single exception is ViewRight,
+// which opens HTML documents and may inspect that opened content only, never its own UI or shell.
+//
+// Rules, applied to every release and update build before anything is built:
+//   - `devtools` is refused for every app (qa-build-features.mjs, qa-control-scan.mjs).
+//   - Exception: an app whose right-release config declares `devtools: "content-only"` AND is listed in
+//     devtools-policy.json (`contentOnlyApps`, today only `viewright`) AND whose Cargo manifest depends on
+//     rightkit-tauri-shell with the `content-devtools` feature (the only way to select DevToolsPolicy::ContentOnly)
+//     AND whose build.rs declares an application ACL manifest (without one Tauri lets local-origin content call
+//     every app command, so a content webview would not be IPC-isolated).
+//   - A manifest that turns on `content-devtools` without the declaration is refused as well.
+//   - The allowance is recorded in the release evidence (the sealed manifest, field `devtools`).
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseCargoFeaturesAndDependencies } from "./qa-build-features.mjs";
+
+// Keep identical to `CONTENT_ONLY_MARKER` in crates/rightkit-tauri-shell/src/devtools.rs and qa-control-scan.mjs.
+export const CONTENT_ONLY_MARKER = "RIGHTKIT-SHELL-DEVTOOLS-CONTENT-ONLY-COMPILED";
+export const DEVTOOLS_POLICY_FILE = path.join(path.dirname(fileURLToPath(import.meta.url)), "devtools-policy.json");
+const SHELL_CRATE = "rightkit-tauri-shell";
+// The crate was renamed from rightkit-shell; apps still on the old published name stay covered until they migrate.
+const SHELL_CRATES = [SHELL_CRATE, "rightkit-shell"];
+const SHELL_FEATURE = "content-devtools";
+
+export function readContentOnlyApps(file = DEVTOOLS_POLICY_FILE) {
+  const parsed = JSON.parse(readFileSync(file, "utf8"));
+  if (parsed.schema !== 1 || !Array.isArray(parsed.contentOnlyApps) || parsed.contentOnlyApps.some((a) => typeof a !== "string")) {
+    throw new Error(`${file}: expected { schema: 1, contentOnlyApps: [string] }`);
+  }
+  return Object.freeze([...parsed.contentOnlyApps]);
+}
+
+// "denied" | "content-only"; anything else is a configuration error.
+export function declaredDevtools(config) {
+  const value = config?.devtools;
+  if (value === undefined || value === null || value === "denied") return "denied";
+  if (value === "content-only") return "content-only";
+  throw new Error(`right-release config: devtools must be "denied" or "content-only", got ${JSON.stringify(value)}`);
+}
+
+// Does the manifest turn on rightkit-tauri-shell's content-devtools (directly or through an app feature it lists)?
+export function selectedContentDevtoolsCrate(manifestText) {
+  const { features, dependencies } = parseCargoFeaturesAndDependencies(manifestText);
+  for (const crate of SHELL_CRATES) {
+    const shell = dependencies.get(crate);
+    if (!shell) continue;
+    if (shell.features.includes(SHELL_FEATURE)) return crate;
+    // An app feature such as `content-devtools = ["rightkit-tauri-shell/content-devtools"]` or a `devtools` alias.
+    for (const items of features.values()) {
+      if (items.some((item) => item === `${crate}/${SHELL_FEATURE}` || item === `${crate}?/${SHELL_FEATURE}`)) return crate;
+    }
+  }
+  return null;
+}
+export function manifestSelectsContentDevtools(manifestText) {
+  return selectedContentDevtoolsCrate(manifestText) !== null;
+}
+
+function appManifestDeclared(buildRsText) {
+  return /\bAppManifest\b/.test(buildRsText) && /\.commands\s*\(/.test(buildRsText);
+}
+
+function readIfExists(file) {
+  return existsSync(file) ? readFileSync(file, "utf8") : null;
+}
+
+// Returns { mode: "denied" } or { mode: "content-only", app, allowListed, shellFeature, appAclManifest, evidence }.
+// Throws (a refusal) when the declaration and the allow-list or the sources disagree. `contentOnlyApps` is injectable
+// so a test can prove that any other app declaring the allowance is refused.
+export function resolveDevtoolsAllowance({ config, root, contentOnlyApps = readContentOnlyApps() }) {
+  const declared = declaredDevtools(config);
+  const app = config?.app;
+  const manifests = ["src-tauri/Cargo.toml", "Cargo.toml"].map((rel) => ({ rel, text: readIfExists(path.join(root, rel)) })).filter((m) => m.text !== null);
+  const selecting = manifests.filter((m) => manifestSelectsContentDevtools(m.text));
+  if (declared === "denied") {
+    if (selecting.length) {
+      throw new Error(`${app ?? "app"}: ${selecting.map((m) => m.rel).join(", ")} enables rightkit-tauri-shell \`${SHELL_FEATURE}\` but the right-release config does not declare devtools: "content-only"; no app ships DevTools without that declaration`);
+    }
+    return { mode: "denied" };
+  }
+  const problems = [];
+  if (typeof app !== "string" || !contentOnlyApps.includes(app)) {
+    problems.push(`app \`${app ?? "<unnamed>"}\` is not on the content-only DevTools allow-list (${contentOnlyApps.join(", ") || "empty"}); only ViewRight may inspect opened content, and no Right app may inspect its own UI or shell`);
+  }
+  if (selecting.length === 0) {
+    problems.push(`the Cargo manifest does not depend on ${SHELL_CRATE} with the \`${SHELL_FEATURE}\` feature, so rightkit-tauri-shell's DevToolsPolicy::ContentOnly cannot be selected`);
+  }
+  const shellCrate = selecting.length ? selectedContentDevtoolsCrate(selecting[0].text) : SHELL_CRATE;
+  const buildRs = readIfExists(path.join(root, "src-tauri", "build.rs")) ?? readIfExists(path.join(root, "build.rs"));
+  if (buildRs === null || !appManifestDeclared(buildRs)) {
+    problems.push("build.rs declares no application ACL manifest (tauri_build AppManifest with commands(..)); without one local content can call every app command");
+  }
+  if (problems.length) throw new Error(`devtools: "content-only" refused:\n- ${problems.join("\n- ")}`);
+  return {
+    mode: "content-only",
+    app,
+    allowListed: true,
+    shellFeature: `${shellCrate}/${SHELL_FEATURE}`,
+    appAclManifest: true,
+    marker: CONTENT_ONLY_MARKER,
+    evidence: `${app} is allow-listed for content-only DevTools (devtools-policy.json); ${selecting[0].rel} selects ${shellCrate}/${SHELL_FEATURE}; build.rs declares an application ACL manifest`,
+  };
+}
+
+// What the sealed manifest records.
+export function devtoolsEvidence(allowance) {
+  return allowance?.mode === "content-only"
+    ? { mode: "content-only", app: allowance.app, shellFeature: allowance.shellFeature, appAclManifest: true, marker: allowance.marker, evidence: allowance.evidence }
+    : { mode: "denied" };
+}
+
+// Re-checked at seal verification and upload: the manifest alone is not trusted, the allow-list is read again.
+export function sealedManifestAllowsContentDevtools(manifest, contentOnlyApps = readContentOnlyApps()) {
+  const devtools = manifest?.devtools;
+  return devtools?.mode === "content-only" && typeof manifest.app === "string" && devtools.app === manifest.app && contentOnlyApps.includes(manifest.app);
+}

package/direct-bootstrap.mjs

@@ -449,22 +449,28 @@ function Invoke-BoundedExe($Path, [string[]]$Arguments, [int]$TimeoutSeconds) {
     "  $StableBin = Split-Path $StableExe -Parent; $InstallRootResolved = [IO.Path]::GetFullPath($InstallRoot).TrimEnd([IO.Path]::DirectorySeparatorChar); $UserPath = [Environment]::GetEnvironmentVariable('Path','User'); $Kept = @($UserPath -split ';' | Where-Object { $Entry = $_.Trim(); $Entry -ne '' -and -not ($Entry.TrimEnd([IO.Path]::DirectorySeparatorChar).StartsWith(($InstallRootResolved + [IO.Path]::DirectorySeparatorChar), [StringComparison]::OrdinalIgnoreCase) -and -not $Entry.TrimEnd([IO.Path]::DirectorySeparatorChar).Equals($StableBin.TrimEnd([IO.Path]::DirectorySeparatorChar), [StringComparison]::OrdinalIgnoreCase)) }); $NewPath = ((@($StableBin) + $Kept) -join ';'); if ($NewPath -ne $UserPath) { [Environment]::SetEnvironmentVariable('Path', $NewPath, 'User') }",
     // Journal cleanup must succeed before discarding the prior pointer. If
     // cleanup fails, catch still has a rollback anchor to restore.
+    // Version directories are compared by NAME, never by full path, here and in the rollback below.
+    // A junction's stored target and the paths this script builds can spell one directory two ways
+    // (a Windows short name such as RUNNER~1, another junction on the way, a different root form),
+    // and a full-path comparison that misses would prune the prior version, skip the rollback
+    // activation, or remove the version the stable pointer is still on. Every version lives
+    // directly under the versions root, so its name identifies it.
     // Retention: after a healthy activation keep only the new version and the prior target (the
     // app's first-start probation may still roll back to it, then deletes it). Every other version
     // is removed; one a running process still holds fails the rename and is retried next install.
-    "  $KeepVersions = @([IO.Path]::GetFullPath($VersionRoot).TrimEnd([IO.Path]::DirectorySeparatorChar)); if ($PriorTarget) { $KeepVersions += [IO.Path]::GetFullPath([string]$PriorTarget).TrimEnd([IO.Path]::DirectorySeparatorChar) }; Get-ChildItem -LiteralPath $VersionsRoot -Directory -Force -ErrorAction SilentlyContinue | Where-Object { $Candidate = $_.FullName.TrimEnd([IO.Path]::DirectorySeparatorChar); -not ($KeepVersions | Where-Object { $_.Equals($Candidate, [StringComparison]::OrdinalIgnoreCase) }) } | ForEach-Object { try { $Doomed = Join-Path $VersionsRoot ('.prune-' + [guid]::NewGuid()); Rename-Item -LiteralPath $_.FullName -NewName (Split-Path -Leaf $Doomed) -ErrorAction Stop; Remove-Item -LiteralPath $Doomed -Recurse -Force -ErrorAction SilentlyContinue } catch { } }",
+    "  $KeepVersions = @([IO.Path]::GetFileName(([string]$VersionRoot).TrimEnd([IO.Path]::DirectorySeparatorChar))); if ($PriorTarget) { $KeepVersions += [IO.Path]::GetFileName(([string]$PriorTarget).TrimEnd([IO.Path]::DirectorySeparatorChar)) }; Get-ChildItem -LiteralPath $VersionsRoot -Directory -Force -ErrorAction SilentlyContinue | Where-Object { $Candidate = $_.Name; -not ($KeepVersions | Where-Object { $_.Equals($Candidate, [StringComparison]::OrdinalIgnoreCase) }) } | ForEach-Object { try { $Doomed = Join-Path $VersionsRoot ('.prune-' + [guid]::NewGuid()); Rename-Item -LiteralPath $_.FullName -NewName (Split-Path -Leaf $Doomed) -ErrorAction Stop; Remove-Item -LiteralPath $Doomed -Recurse -Force -ErrorAction SilentlyContinue } catch { } }",
     "  Remove-Item -Force $Journal; Remove-StableJunction $PreviousLink; Write-Output (" + psQuote(product + " ") + " + $Version + ' installed')",
     "} catch {",
     "  $InstallError = $_; $RollbackErrors = New-Object 'System.Collections.Generic.List[string]'",
     "  try { if ($Switched -or $PriorDetached) { Remove-StableJunction $Current }; if ($PriorDetached -and (Test-Path $PreviousLink)) { Rename-Item -LiteralPath $PreviousLink -NewName (Split-Path -Leaf $Current) } } catch { $RollbackErrors.Add($_.Exception.Message) }",
-    "  try { if ($PriorTarget -and (Test-Path $Current) -and $PriorCliCapable -and ([string](Get-Item -LiteralPath $Current).Target -eq [string]$PriorTarget)) { $PriorExe = Join-Path $Current " + psQuote(executablePath.replaceAll("/", "\\")) + "; $PriorActivationArgs = @(Expand-BootstrapArgs $ActivationArgsTemplate ([string]$PriorTarget) $PriorVersion); $PriorStatusArgs = @(Expand-BootstrapArgs $StatusArgsTemplate ([string]$PriorTarget) $PriorVersion); Invoke-BoundedExe $PriorExe $PriorActivationArgs 240 | Out-Null; if ($LASTEXITCODE -ne 0) { throw 'Rollback activation failed' }; $PriorHealthText = ((Invoke-BoundedExe $PriorExe $PriorStatusArgs 120) | Out-String).Trim(); if ($LASTEXITCODE -ne 0) { throw 'Rollback health failed' }; $PriorHealth = $PriorHealthText | ConvertFrom-Json; try { Assert-Health $PriorHealth $PriorVersion } catch { throw ('Prior health was not restored: ' + $_.Exception.Message) } } } catch { $RollbackErrors.Add($_.Exception.Message) }",
+    "  try { if ($PriorTarget -and (Test-Path $Current) -and $PriorCliCapable -and ([IO.Path]::GetFileName(([string](Get-Item -LiteralPath $Current).Target).TrimEnd([IO.Path]::DirectorySeparatorChar)) -eq [IO.Path]::GetFileName(([string]$PriorTarget).TrimEnd([IO.Path]::DirectorySeparatorChar)))) { $PriorExe = Join-Path $Current " + psQuote(executablePath.replaceAll("/", "\\")) + "; $PriorActivationArgs = @(Expand-BootstrapArgs $ActivationArgsTemplate ([string]$PriorTarget) $PriorVersion); $PriorStatusArgs = @(Expand-BootstrapArgs $StatusArgsTemplate ([string]$PriorTarget) $PriorVersion); Invoke-BoundedExe $PriorExe $PriorActivationArgs 240 | Out-Null; if ($LASTEXITCODE -ne 0) { throw 'Rollback activation failed' }; $PriorHealthText = ((Invoke-BoundedExe $PriorExe $PriorStatusArgs 120) | Out-String).Trim(); if ($LASTEXITCODE -ne 0) { throw 'Rollback health failed' }; $PriorHealth = $PriorHealthText | ConvertFrom-Json; try { Assert-Health $PriorHealth $PriorVersion } catch { throw ('Prior health was not restored: ' + $_.Exception.Message) } } } catch { $RollbackErrors.Add($_.Exception.Message) }",
     String.raw`  try {
     $CandidatePath = [IO.Path]::GetFullPath($VersionRoot).TrimEnd([IO.Path]::DirectorySeparatorChar)
     $VersionsPrefix = [IO.Path]::GetFullPath($VersionsRoot).TrimEnd([IO.Path]::DirectorySeparatorChar) + [IO.Path]::DirectorySeparatorChar
     $ActiveTarget = if (Test-Path -LiteralPath $Current) { [string](Get-Item -LiteralPath $Current).Target } else { $null }
     if ($ActiveTarget -and -not [IO.Path]::IsPathRooted($ActiveTarget)) { $ActiveTarget = Join-Path (Split-Path -Parent $Current) $ActiveTarget }
     if (-not $CandidatePath.StartsWith($VersionsPrefix, [StringComparison]::OrdinalIgnoreCase)) { throw 'Failed version cleanup escapes versions root' }
-    if ($ActiveTarget -and [IO.Path]::GetFullPath($ActiveTarget).TrimEnd([IO.Path]::DirectorySeparatorChar).Equals($CandidatePath, [StringComparison]::OrdinalIgnoreCase)) { throw 'Failed version is still active; preserved for recovery' }
+    if ($ActiveTarget -and [IO.Path]::GetFileName([IO.Path]::GetFullPath($ActiveTarget).TrimEnd([IO.Path]::DirectorySeparatorChar)).Equals([IO.Path]::GetFileName($CandidatePath), [StringComparison]::OrdinalIgnoreCase)) { throw 'Failed version is still active; preserved for recovery' }
     if (Test-Path -LiteralPath $CandidatePath) { Remove-Item -LiteralPath $CandidatePath -Recurse -Force }
   } catch { $RollbackErrors.Add($_.Exception.Message) }
   if ($RollbackErrors.Count) {

package/dmg-build.mjs

@@ -3,8 +3,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "./background-process.mjs";
 import { backgroundAlias, dmgDSStore } from "./dmg-layout.mjs";
+import { readDmgSpec } from "./dmg-spec.mjs";
 import { detachWithRetrySync } from "./hdiutil-detach.mjs";
 import { assertReleaseExecutionAllowed } from "./execution-policy.mjs";
+import { assertNoQaControl } from "./qa-control-scan.mjs";
 
 const fail = (code, message) => Object.assign(new Error(message), { code });
 const pair = (value, label, positive = false) => {
@@ -15,11 +17,20 @@ const pair = (value, label, positive = false) => {
   return numbers;
 };
 
-export function buildDmg({ app, out, volname, background, iconSize = 128, appPosition = [158, 231],
-  applicationsPosition = [492, 231], window = [660, 400], volumeIcon } = {},
+const definedOnly = (object) => Object.fromEntries(Object.entries(object).filter(([, value]) => value !== undefined));
+
+/** Layer explicit options over an appdmg-style spec file (`spec`); explicit values win. */
+export function resolveDmgOptions(input = {}) {
+  const { spec, ...explicit } = input;
+  return spec ? { ...readDmgSpec(spec, { app: explicit.app }), ...definedOnly(explicit) } : explicit;
+}
+
+export function buildDmg(input = {},
 { platform = process.platform, run = spawnSync, makeAlias = backgroundAlias,
   log = (event) => console.error(JSON.stringify(event)), sleep } = {}) {
   if (platform !== "darwin") throw fail("DMG_NATIVE_HOST_REQUIRED", "DMG creation requires macOS");
+  let { app, out, volname, background, iconSize = 128, appPosition = [158, 231],
+    applicationsPosition = [492, 231], window = [660, 400], windowPosition = [100, 100], volumeIcon } = resolveDmgOptions(input);
   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"))) {
@@ -30,7 +41,7 @@ export function buildDmg({ app, out, volname, background, iconSize = 128, appPos
   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);
+  window = pair(window, "--window", true); windowPosition = pair(windowPosition, "--window-position");
   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");
@@ -66,6 +77,9 @@ export function buildDmg({ app, out, volname, background, iconSize = 128, appPos
   try {
     mkdirSync(stage); mkdirSync(mount);
     command("/usr/bin/ditto", [app, path.join(stage, path.basename(app))]);
+    // The compressed DMG cannot be scanned afterwards: scan the staged payload before it is packed. An unreadable
+    // path or a finding fails; the "no binary at all" check lives in release.mjs, which knows the signed app.
+    assertNoQaControl([stage], "dmg staging");
     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)); }
@@ -84,7 +98,7 @@ export function buildDmg({ app, out, volname, background, iconSize = 128, appPos
     }
     const alias = relative ? makeAlias({ mount, volname, relative }) : undefined;
     writeFileSync(path.join(mount, ".DS_Store"), dmgDSStore({ appName: path.basename(app), iconSize,
-      appPosition, applicationsPosition, window, alias }));
+      appPosition, applicationsPosition, window, windowPosition, alias }));
     detach(); attached = false;
     command("/usr/bin/hdiutil", ["convert", rw, "-format", "UDZO", "-imagekey", "zlib-level=9", "-o", compressed]);
     command("/usr/bin/hdiutil", ["verify", compressed]);
@@ -107,7 +121,7 @@ export function buildDmg({ app, out, volname, background, iconSize = 128, appPos
 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"]]);
+    ["--icon-size", "iconSize"], ["--app-position", "appPosition"], ["--applications-position", "applicationsPosition"], ["--window", "window"], ["--window-position", "windowPosition"], ["--volume-icon", "volumeIcon"], ["--spec", "spec"]]);
   const options = {};
   for (let i = 1; i < args.length; i += 2) {
     const key = flags.get(args[i]);

package/dmg-layout.mjs

@@ -81,7 +81,7 @@ export function backgroundAlias({ mount, volname, relative, stat = statSync }) {
 
 /** 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 } = {}) {
+  applicationsPosition = [492, 231], window = [660, 400], windowPosition = [100, 100], 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,
@@ -90,7 +90,7 @@ export function dmgDSStore({ appName, iconSize = 128, appPosition = [158, 231],
   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]}}}` }));
+    SidebarWidth: 0, WindowBounds: `{{${windowPosition[0]}, ${windowPosition[1]}}, {${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,

package/dmg-spec.mjs

@@ -0,0 +1,97 @@
+// appdmg-style DMG spec (`dmg build --spec <file.json>`, `targets.mac.dmg.spec`) mapped onto the
+// headless hdiutil pipeline in dmg-build.mjs. Only fields the pipeline can render are accepted; any
+// other appdmg field fails with DMG_SPEC_UNSUPPORTED instead of being silently dropped.
+//
+// Supported:  title, icon (.icns volume icon), background (PNG/TIFF), icon-size,
+//             window.size {width,height}, window.position {x,y}, format "UDZO", filesystem "HFS+",
+//             contents: one `file` entry for the .app and one `link` entry to /Applications (x,y = icon centre).
+// Unsupported: background-color, code-sign (the release pipeline signs the DMG), license, other formats and
+//             filesystems, extra files or links, `position` entries, any unknown key.
+// Relative `background` / `icon` paths resolve against the spec file's directory.
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const fail = (message, code = "DMG_SPEC_INVALID") => Object.assign(new Error(message), { code });
+const unsupported = (message) => fail(message, "DMG_SPEC_UNSUPPORTED");
+const SPEC_KEYS = new Set(["title", "icon", "background", "icon-size", "window", "format", "filesystem", "contents"]);
+const UNSUPPORTED_KEYS = new Map([
+  ["background-color", "background-color is not rendered; use a background image"],
+  ["code-sign", "code-sign is not supported: right-release Developer ID signs the DMG in its own sign step"],
+  ["license", "license agreements are not supported"],
+]);
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const int = (value, label, { min = 0 } = {}) => {
+  if (!Number.isInteger(value) || value < min || value > 32767) throw fail(`${label} must be an integer ${min}..32767`);
+  return value;
+};
+
+/** Parse an appdmg-style spec object into buildDmg options. `app` (optional) is the .app path being packed. */
+export function parseDmgSpec(spec, { baseDir = process.cwd(), app } = {}) {
+  if (!isObject(spec)) throw fail("DMG spec must be a JSON object");
+  for (const key of Object.keys(spec)) {
+    if (UNSUPPORTED_KEYS.has(key)) throw unsupported(`DMG spec: ${UNSUPPORTED_KEYS.get(key)}`);
+    if (!SPEC_KEYS.has(key)) throw unsupported(`DMG spec: unsupported field ${JSON.stringify(key)}`);
+  }
+  const options = {};
+  if (spec.title !== undefined) {
+    if (typeof spec.title !== "string" || !spec.title) throw fail("DMG spec: title must be a non-empty string");
+    options.volname = spec.title;
+  }
+  const file = (value, label) => {
+    if (typeof value !== "string" || !value) throw fail(`DMG spec: ${label} must be a non-empty path string`);
+    return path.resolve(baseDir, value);
+  };
+  if (spec.icon !== undefined) options.volumeIcon = file(spec.icon, "icon");
+  if (spec.background !== undefined) options.background = file(spec.background, "background");
+  if (spec["icon-size"] !== undefined) options.iconSize = int(spec["icon-size"], "DMG spec: icon-size", { min: 16 });
+  if (spec.format !== undefined && spec.format !== "UDZO") throw unsupported(`DMG spec: format ${JSON.stringify(spec.format)} is not supported (the pipeline writes UDZO)`);
+  if (spec.filesystem !== undefined && spec.filesystem !== "HFS+") throw unsupported(`DMG spec: filesystem ${JSON.stringify(spec.filesystem)} is not supported (the pipeline writes HFS+)`);
+  if (spec.window !== undefined) {
+    if (!isObject(spec.window)) throw fail("DMG spec: window must be an object");
+    for (const key of Object.keys(spec.window)) if (!["size", "position"].includes(key)) throw unsupported(`DMG spec: unsupported field window.${key}`);
+    if (spec.window.size !== undefined) {
+      const { width, height, ...extra } = isObject(spec.window.size) ? spec.window.size : { width: undefined };
+      if (Object.keys(extra).length) throw unsupported(`DMG spec: unsupported field window.size.${Object.keys(extra)[0]}`);
+      options.window = [int(width, "DMG spec: window.size.width", { min: 1 }), int(height, "DMG spec: window.size.height", { min: 1 })];
+    }
+    if (spec.window.position !== undefined) {
+      const { x, y, ...extra } = isObject(spec.window.position) ? spec.window.position : { x: undefined };
+      if (Object.keys(extra).length) throw unsupported(`DMG spec: unsupported field window.position.${Object.keys(extra)[0]}`);
+      options.windowPosition = [int(x, "DMG spec: window.position.x"), int(y, "DMG spec: window.position.y")];
+    }
+  }
+  if (spec.contents !== undefined) {
+    if (!Array.isArray(spec.contents)) throw fail("DMG spec: contents must be an array");
+    const appName = app ? path.basename(app) : null;
+    spec.contents.forEach((item, index) => {
+      const label = `DMG spec: contents[${index}]`;
+      if (!isObject(item)) throw fail(`${label} must be an object`);
+      for (const key of Object.keys(item)) if (!["x", "y", "type", "path", "name"].includes(key)) throw unsupported(`${label}: unsupported field ${JSON.stringify(key)}`);
+      const point = [int(item.x, `${label}.x`), int(item.y, `${label}.y`)];
+      if (typeof item.path !== "string" || !item.path) throw fail(`${label}.path must be a non-empty string`);
+      if (item.type === "link") {
+        if (item.path !== "/Applications") throw unsupported(`${label}: only a link to /Applications is supported (got ${item.path})`);
+        if (options.applicationsPosition) throw fail(`${label}: duplicate /Applications link`);
+        options.applicationsPosition = point;
+      } else if (item.type === "file" || item.type === undefined) {
+        const name = item.name ?? path.basename(item.path);
+        if (!name.endsWith(".app")) throw unsupported(`${label}: only the .app can be a file entry (got ${item.path}); extra files are not supported`);
+        if (appName && name !== appName) throw fail(`${label}: names ${name} but the app being packed is ${appName}`);
+        if (options.appPosition) throw fail(`${label}: duplicate .app entry`);
+        options.appPosition = point;
+      } else if (item.type === "position") throw unsupported(`${label}: position entries are not supported`);
+      else throw fail(`${label}.type must be "file" or "link" (got ${JSON.stringify(item.type)})`);
+    });
+  }
+  return options;
+}
+
+/** Read and parse a spec file. */
+export function readDmgSpec(specPath, { app } = {}) {
+  const file = path.resolve(specPath);
+  let text;
+  try { text = readFileSync(file, "utf8"); } catch (error) { throw fail(`DMG spec not readable: ${file} (${error.code ?? error.message})`); }
+  let spec;
+  try { spec = JSON.parse(text); } catch { throw fail(`DMG spec is not valid JSON: ${file}`); }
+  return parseDmgSpec(spec, { baseDir: path.dirname(file), app });
+}

package/execution-policy.mjs

@@ -37,9 +37,25 @@ export function releaseExecutionPolicy(cwd = process.cwd()) {
   }
 }
 
+export const LOCAL_BUILD_FILE = ".rightkit-local-build.json";
+
+// Adrian's local-build opt-in (2026-10-14): a committed .rightkit-local-build.json naming this exact
+// repository allows local build, test and publish. Mirrors the build-control hook's check.
+function localBuildGranted(root) {
+  if (!root) return false;
+  try {
+    const grant = JSON.parse(readFileSync(path.join(root, LOCAL_BUILD_FILE), "utf8"));
+    if (grant?.allow !== "build-test-publish" || typeof grant.repository !== "string") return false;
+    const config = readFileSync(path.join(root, ".git", "config"), "utf8");
+    const origin = /\[remote "origin"\][^\[]*?url\s*=\s*(\S+)/i.exec(config)?.[1] ?? "";
+    const repo = /github\.com[:/]([^/]+\/[^/.\s]+?)(?:\.git)?\/?$/i.exec(origin)?.[1];
+    return !!repo && repo.toLowerCase() === grant.repository.toLowerCase();
+  } catch { return false; }
+}
+
 export function assertReleaseExecutionAllowed({ cwd = process.cwd(), environment = process.env, command = "build" } = {}) {
   const policy = releaseExecutionPolicy(cwd);
-  if (policy.compile === GITHUB_ACTIONS_ONLY && environment.GITHUB_ACTIONS !== "true") {
+  if (policy.compile === GITHUB_ACTIONS_ONLY && environment.GITHUB_ACTIONS !== "true" && !localBuildGranted(policy.root)) {
     throw Object.assign(new Error(`${command} is GitHub Actions only for ${policy.root}; push changes & use managed CI`), { code: GITHUB_ACTIONS_ONLY_ERROR });
   }
   return policy;