@rightkit/release 0.2.165 → 0.2.173

package/cargo-profile-contract.mjs

@@ -0,0 +1,183 @@
+// RightKit standard Cargo profile contract (Adrian, 2026-10-16; Astra-reviewed option C).
+//
+// Every app workspace-root Cargo.toml carries the tables of templates/cargo-profiles.toml verbatim:
+//   - [profile.dev] and [profile.dev.package."*"] equal the template (no missing, changed or extra keys),
+//   - panic = "unwind" in dev and release,
+//   - no [profile.release-iterate] (and nothing that inherits it),
+//   - no [profile.test] overrides (test inherits dev).
+// The same scan also flags the two source patterns the single dev profile makes wrong, because a dev
+// build now has debug_assertions on:
+//   - `cfg_attr(not(debug_assertions), windows_subsystem = ...)`: an installed dev app would open a
+//     console window on Windows. Set windows_subsystem = "windows" unconditionally.
+//   - an environment-variable override gated by cfg(debug_assertions): move it to the app's test-mode
+//     feature. Heuristic: a cfg(debug_assertions) attribute or cfg! within 12 lines before an env read.
+//     Suppress a reviewed site with a `rightkit-allow: debug-assertions-env` comment on the cfg line or
+//     the line above it.
+// The template file is the single source: this module reads it, it never copies the values.
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "smol-toml";
+import { findCargoManifests, isExcludedScanDirectory } from "./cargo-contract.mjs";
+
+export const CARGO_PROFILE_TEMPLATE = fileURLToPath(new URL("./templates/cargo-profiles.toml", import.meta.url));
+export const RETIRED_PROFILE = "release-iterate";
+const ENV_ALLOW_MARKER = "rightkit-allow: debug-assertions-env";
+const ENV_WINDOW_LINES = 12;
+// Never part of an app's shipped source: tests, examples, benches and vendored reference copies.
+const SOURCE_SKIP = new Set(["tests", "examples", "benches", "reference"]);
+const ENV_READ = /env::var|var_os|env::set_var|env::remove_var|\benv!\s*\(|option_env!|_env\(|env_var|env_nonempty/;
+const WINDOWS_SUBSYSTEM_GATED = /cfg_attr\s*\((?:(?!\]).)*?not\s*\(\s*debug_assertions\s*\)(?:(?!\]).)*?windows_subsystem/gs;
+
+export function loadCargoProfileTemplate(file = CARGO_PROFILE_TEMPLATE) {
+  const profile = parse(readFileSync(file, "utf8")).profile ?? {};
+  const { package: packages = {}, ...dev } = profile.dev ?? {};
+  return { dev, devPackageStar: packages["*"] ?? {}, releasePanic: profile.release?.panic };
+}
+
+const isTable = (value) => value && typeof value === "object" && !Array.isArray(value);
+const show = (value) => JSON.stringify(value);
+
+// Compare one table with the template: every template key must match, and no other key may exist.
+function compareTable(actual, expected, tableName, finding) {
+  if (!isTable(actual)) { finding("profile-missing", `${tableName} is missing`); return; }
+  for (const [key, value] of Object.entries(expected)) {
+    if (!(key in actual)) finding("profile-key", `${tableName} is missing ${key} = ${show(value)}`);
+    else if (actual[key] !== value) finding("profile-key", `${tableName} has ${key} = ${show(actual[key])}; the template requires ${show(value)}`);
+  }
+  for (const key of Object.keys(actual)) if (!(key in expected)) finding("profile-extra", `${tableName} has ${key}, which is not in the template`);
+}
+
+// Findings for one workspace-root manifest (already parsed).
+export function checkManifestProfiles(manifest, template, file) {
+  const findings = [];
+  const finding = (rule, message) => findings.push({ rule, file, message });
+  const profiles = isTable(manifest.profile) ? manifest.profile : {};
+  const dev = isTable(profiles.dev) ? profiles.dev : undefined;
+  const { package: devPackages, ...devRest } = dev ?? {};
+  // Subtables of [profile.dev] are checked separately below.
+  const devKeys = Object.fromEntries(Object.entries(devRest).filter(([, value]) => !isTable(value)));
+  compareTable(dev ? devKeys : undefined, template.dev, "[profile.dev]", finding);
+  compareTable(isTable(devPackages) ? devPackages["*"] : undefined, template.devPackageStar, '[profile.dev.package."*"]', finding);
+  if (isTable(devPackages)) for (const name of Object.keys(devPackages)) if (name !== "*") finding("profile-extra", `[profile.dev.package.${show(name)}] is not in the template`);
+  if (dev) for (const name of Object.keys(dev)) if (isTable(dev[name]) && name !== "package") finding("profile-extra", `[profile.dev.${name}] is not in the template`);
+  // [profile.dev] panic is checked with the rest of the dev table above.
+  if (profiles.release?.panic !== template.releasePanic) finding("panic", `[profile.release] panic must be ${show(template.releasePanic)} (found ${show(profiles.release?.panic)})`);
+  if (RETIRED_PROFILE in profiles) finding("retired-profile", `[profile.${RETIRED_PROFILE}] is retired; delete it and its package overrides`);
+  for (const [name, table] of Object.entries(profiles)) {
+    if (isTable(table) && table.inherits === RETIRED_PROFILE) finding("retired-profile", `[profile.${name}] inherits the retired ${RETIRED_PROFILE} profile`);
+  }
+  if ("test" in profiles) finding("profile-extra", "[profile.test] overrides are not allowed; test inherits dev");
+  return findings;
+}
+
+// Non-shipping workspaces: fixed prefixes plus the app's declared `cargoProfileExempt` directories.
+const NON_SHIPPING_PREFIXES = ["qa", "benchmarks"];
+const CARGO_PROFILE_EXEMPT_KEY = "cargoProfileExempt";
+const RELEASE_CONFIG = "right-release.config.mjs";
+const STRING_LITERAL = /"([^"\\\n]*)"|'([^'\\\n]*)'/g;
+
+// release.mjs imports the app's release config as an ES module. This scanner is synchronous and has only the
+// app root, so it reads the literal `cargoProfileExempt` array from the same file: every entry must be a plain
+// string literal naming a directory inside the app. Anything else is a finding, never silently ignored.
+export function readCargoProfileExempt(root) {
+  const file = path.join(root, RELEASE_CONFIG);
+  const findings = [];
+  if (!existsSync(file)) return { paths: [], findings };
+  const match = new RegExp(`\\b${CARGO_PROFILE_EXEMPT_KEY}\\s*:\\s*\\[([^\\]]*)\\]`).exec(readFileSync(file, "utf8"));
+  if (!match) return { paths: [], findings };
+  const body = match[1];
+  if (body.replace(STRING_LITERAL, "").replace(/[,\s]/g, "") !== "") {
+    findings.push({ rule: "invalid-exempt", file: RELEASE_CONFIG, message: `${CARGO_PROFILE_EXEMPT_KEY} must be an array of string literals` });
+  }
+  const paths = [];
+  for (const [, double, single] of body.matchAll(STRING_LITERAL)) {
+    const entry = double ?? single;
+    const normalized = path.posix.normalize(entry.replace(/\\/g, "/")).replace(/\/+$/, "");
+    if (normalized === "." || normalized === "" || path.posix.isAbsolute(normalized) || normalized.split("/").includes("..")) {
+      findings.push({ rule: "invalid-exempt", file: RELEASE_CONFIG, message: `${CARGO_PROFILE_EXEMPT_KEY} entry ${JSON.stringify(entry)} must be a relative directory inside the app` });
+    } else paths.push(normalized);
+  }
+  return { paths, findings };
+}
+
+const dirOf = (file) => path.posix.dirname(file);
+const isWithinDir = (dir, ancestor) => ancestor === "." || dir === ancestor || dir.startsWith(`${ancestor}/`);
+
+// The app's profile roots. Cargo reads profiles only from a workspace root, and a shipping app can ship binaries
+// from several independent workspaces, so every manifest with a top-level [workspace] table is a root, and so is
+// every standalone package manifest that no workspace contains. Only declared non-shipping directories are exempt:
+// the fixed qa/ and benchmarks/ prefixes plus `cargoProfileExempt`. Exempt workspaces still count as containers.
+export function findProfileRoots(root, manifests = findCargoManifests(root), declared = readCargoProfileExempt(root)) {
+  const parsed = [];
+  const findings = [...declared.findings];
+  for (const manifest of manifests) {
+    const file = path.relative(root, manifest).split(path.sep).join("/");
+    try { parsed.push({ manifest, file, toml: parse(readFileSync(manifest, "utf8")) }); }
+    catch (error) { findings.push({ rule: "invalid-toml", file, message: `is not valid TOML: ${error.message}` }); }
+  }
+  const exemptPrefixes = [...NON_SHIPPING_PREFIXES, ...declared.paths];
+  const isWorkspace = ({ toml }) => isTable(toml.workspace);
+  const roots = parsed.filter((entry) => {
+    if (exemptPrefixes.some((prefix) => entry.file.startsWith(`${prefix}/`))) return false;
+    if (isWorkspace(entry)) return true;
+    return !parsed.some((other) => other !== entry && isWorkspace(other) && isWithinDir(dirOf(entry.file), dirOf(other.file)));
+  });
+  return { roots, findings };
+}
+
+function* rustFiles(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (isExcludedScanDirectory(entry.name, path.basename(dir)) || SOURCE_SKIP.has(entry.name)) continue;
+      yield* rustFiles(full);
+    } else if (entry.isFile() && entry.name.endsWith(".rs")) yield full;
+  }
+}
+
+// Source patterns the single dev profile makes wrong (see the header). Returns findings with a line number.
+export function scanDebugAssertionSources(root) {
+  const findings = [];
+  for (const file of rustFiles(root)) {
+    const text = readFileSync(file, "utf8");
+    if (!text.includes("debug_assertions")) continue;
+    const label = path.relative(root, file).split(path.sep).join("/");
+    const lineAt = (index) => text.slice(0, index).split("\n").length;
+    for (const match of text.matchAll(WINDOWS_SUBSYSTEM_GATED)) {
+      findings.push({ rule: "windows-subsystem", file: label, line: lineAt(match.index), message: 'cfg_attr(not(debug_assertions), windows_subsystem = ...) opens a console for installed dev apps; set windows_subsystem = "windows" unconditionally' });
+    }
+    const lines = text.split("\n");
+    lines.forEach((line, index) => {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("//") || !line.includes("debug_assertions") || line.includes("windows_subsystem")) return;
+      if (!/#!?\[cfg|cfg!\s*\(/.test(line)) return;
+      if (line.includes(ENV_ALLOW_MARKER) || (lines[index - 1] ?? "").includes(ENV_ALLOW_MARKER)) return;
+      if (ENV_READ.test(lines.slice(index, index + ENV_WINDOW_LINES + 1).join("\n"))) {
+        findings.push({ rule: "debug-assertions-env", file: label, line: index + 1, message: "environment-variable override gated by cfg(debug_assertions); move it to the app's test-mode feature" });
+      }
+    });
+  }
+  return findings;
+}
+
+export function scanCargoProfileContract(root, { template = loadCargoProfileTemplate(), sources = true } = {}) {
+  const scanRoot = path.resolve(root);
+  const { roots, findings } = findProfileRoots(scanRoot);
+  for (const { toml, file } of roots) findings.push(...checkManifestProfiles(toml, template, file));
+  if (sources && existsSync(scanRoot)) findings.push(...scanDebugAssertionSources(scanRoot));
+  return findings;
+}
+
+export function formatCargoProfileFindings(findings, label) {
+  return findings.map(({ rule, file, line, message }) => `${label} ${file}${line ? `:${line}` : ""} [${rule}] ${message}`);
+}
+
+// Throws one error listing every finding for the app; returns 0 when the app conforms.
+export function assertCargoProfileContract(root, label = path.basename(path.resolve(root)), options) {
+  const findings = scanCargoProfileContract(root, options);
+  if (findings.length) {
+    throw new Error(`${label} breaks the RightKit Cargo profile contract (templates/cargo-profiles.toml):\n${formatCargoProfileFindings(findings, label).join("\n")}`);
+  }
+  return 0;
+}

package/cargo-target.mjs

@@ -9,6 +9,14 @@
 // (see cargo-contract.mjs) remains a separate, cache-policy-only decision:
 // whether Cache V2's lease/slot/prune/floor machinery should run at all, not
 // where the target directory lives.
+//
+// NOT A STABLE PATH. On a broker-managed host the directory this reports is
+// `<managed>/rightkit-build-control/ws/<hash>/g/<generation>/target`, and the generation
+// changes over time; `cargo-guard` uses a hashed `dev-targets/<project>-<hash>` folder.
+// Both are build output only. Nothing may run from them: macOS ties privacy grants to the
+// path an app runs from. Dev and QA binaries are copied in place to a fixed staged path
+// (`development.targets.<platform>.stage`, `stage-binary.mjs`; rightkit-qa's
+// `.rightkit-qa-bin` stash) and run from there.
 import { realpathSync } from "node:fs";
 import { execFileSync } from "./background-process.mjs";
 import { runCargoSync } from "./managed-cargo.mjs";

package/cli/right-release.mjs

@@ -18,6 +18,10 @@ const commands = new Map([
   ["hardeningscan", "hardeningscan.mjs"],
   ["sign-windows", "sign-windows.mjs"],
   ["sign-updater", "sign-updater.mjs"],
+  ["sign-dev-artifact", "sign-dev-artifact.mjs"],
+  ["sign-candidate", "sign-candidate.mjs"],
+  ["engine-locate", "engine-locator.mjs"],
+  ["stage-sidecar", "stage-sidecar-command.mjs"],
   ["signing-agent", "signing-agent-command.mjs"],
   ["create-mac-updater", "create-mac-updater.mjs"],
   ["mirror-root-artifact", "mirror-root-artifact.mjs"],
@@ -31,6 +35,7 @@ const commands = new Map([
   ["swift-package", "swift-package-command.mjs"],
   ["bundle-scan", "runtime-bundle-scan.mjs"],
   ["identity-scan", "packaged-app-identity.mjs"],
+  ["apple-profile-create", "apple-profile-create.mjs"],
 ]);
 
 const args = process.argv.slice(2);
@@ -177,12 +182,16 @@ function printHelp() {
   console.log(`right-release <command> [options]
 
 Commands:
+  stage-sidecar [--config <file>] [--target <triple>] [--json]  Stage declarative sidecars into src-tauri/binaries (Tauri externalBin naming)
   dmg build --app <.app> --out <dmg> --volname <name> [--background <png>] [--spec <appdmg.json>]
             [--icon-size N] [--app-position x,y] [--applications-position x,y] [--window w,h] [--window-position x,y]
                                                       Build branded UDZO image without Finder
   install-app --dmg <path.dmg> [--app-name Pulse.app] [--bundle-id <id>] [--dest /Applications]
               [--relaunch|--no-relaunch] [--json]
                                                       Verify a signed DMG, quit, replace & relaunch hidden; no UI, no osascript (macOS)
+                                                      The replaced app stays beside the fixed path as <App>.app.previous
+  install-app --installer <Setup.exe> --dest <fixed install folder> --exe <App.exe> [--json]
+                                                      Windows: run the installer in place at the fixed folder, keep <dest>.previous
   build [--platform mac|win] [--skip-checks] [--resume-from <phase>]
                                                       Resume macOS at prepackage, sign, package, post-sign, or harden
   dev --platform win|mac [--config <path>] [--dry-run] [--build-only]
@@ -191,6 +200,12 @@ Commands:
                                                       Stage SwiftPM app; build+sign MSIX (Windows) or assemble+sign+notarize .app (macOS); never uploads
   bundle-scan [--allow-name <basename>]... <bundle-root>...
                                                       Fail when a bundle carries Node/Python runtimes or script sources
+  sign-dev-artifact --artifact <dir> --manifest <sign.json> [--metadata <payload.json>] [--evidence <path>] [--dry-run]
+                                                      Developer ID sign an existing CI dev artifact per file with fixed identifiers; never builds, notarizes or publishes (macOS)
+  sign-candidate --platform win|mac --artifact <dir> --candidate-receipt <receipt.json> --out <binding.json> [--manifest <sign.json>] [--publisher <subject>] [--dry-run]
+                                                      Sign the exact unsigned candidate bytes (sha256 checked against the candidate receipt) instead of rebuilding; writes a candidate-sha -> signed-sha binding receipt
+  engine-locate --engine cutright|genright [--sha256 <hex>] [--json]
+                                                      Print the verified path of the installed CutRight/GenRight engine (fixed route, signature and identity checked, no override)
   identity-scan --target <path> [--identifier <id>] [--team <OU>] [--cdhash <hex>] [--arch <arch>]...
                                                       Assert codesign Identifier/Team/cdhash/lipo archs; reject ad-hoc
   upload --release <id> --platform mac|win --tier patch|update
@@ -232,10 +247,7 @@ Commands:
   ownership trust-sync                               Advance this host's protected trust to the committed key log
   ownership trust-sync --check                       Read-only: say whether a sync would ask for approval, and for what (exit 3 if so)
   ownership trust-compare [--json]                   Print this host's protected-trust digest (Mac is the reference)
-  ownership-approval --draft <input.json> [--out <draft.json>]
-                                                      Draft an exception for native owner approval
-  ownership-approval --verify <signed.json> --context <scan.json>
-                                                      Verify exact signed exception coverage
+  ownership-approval                                 Retired no-op: exceptions are plain entries in the repo exceptions file, edited directly and reviewed through git
   ownership-report --workspace <dir> [--markdown <file>] [--json-out <file>]
                                                       Report cross-app ownership & pending requests
   ownership-mandatory [--workspace <dir>] [--app <name>]... [--amendment v2.1] [--enforce] [--json]

package/committed-source.mjs

@@ -133,7 +133,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", "Package.resolved", "ownership-exceptions.json", "Cargo.lock", "pnpm-lock.yaml", "package-lock.json", "npm-shrinkwrap.json", "yarn.lock"].includes(path.posix.basename(row.rel)) ||
+    wanted.has(row.rel) || ["Cargo.toml", "package.json", "Package.swift", "Package.resolved", "ownership-exceptions.json", "pnpm-workspace.yaml", "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/dev-artifact-refresh.mjs

@@ -0,0 +1,176 @@
+// Declarative metadata refresh for right-release sign-dev-artifact (Orthic-Labs/rightkit#257).
+//
+// Signing changes bytes, so a JSON file that records a digest of signed bytes goes stale. The sign manifest declares, per value, which
+// JSON pointer of which file is recomputed from which artifact path:
+//
+//   { "schema": 1, "refreshRoot": "<dir inside the artifact>", "entries": [...],
+//     "refresh": [ { "file": "share/app/release.json", "pointer": "/runtime/sha256", "compute": "sha256-file", "of": "bin/app" } ] }
+//
+// `file` and `of` are relative to `refreshRoot` (default: the artifact root). Computes:
+//   sha256-file       hex sha256 of the bytes of `of`
+//   sha256-tree-v1    hex sha256 over the regular files below the directory `of`: sorted by relative POSIX path (UTF-8 bytes), each
+//                     contributing path bytes, 0x00, the length as 8 big-endian bytes, then the file bytes. Symlinks and
+//                     non-regular files are refused.
+//   verify-sha256-file  does not write: refuses unless the value at the pointer already equals the sha256 of `of` (a digest that must
+//                     survive signing unchanged)
+// Optional per operation: `format` (a template with one `{value}`, applied to the computed digest, for locator strings that embed it) and
+// `currentMatches` (a regular expression the CURRENT string value must match before it is overwritten, so a value of another kind, such as
+// a signed attestation locator, is refused instead of replaced).
+//
+// Ordering is enforced, never reordered: every operation runs after the manifest entries it reads (the entries equal to or below `of`)
+// are signed and before the first entry that contains a file the refresh writes, so the bundle holding refreshed files is signed last
+// over their final bytes. An operation may not read a file a later operation writes. JSON is rewritten in place keeping key order, and a
+// file the serializer cannot reproduce byte for byte (apart from the edited value) is refused rather than reformatted.
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { assertInsideOnDisk, contained, fail, isWithin, toPosix } from "./dev-artifact-support.mjs";
+
+export const REFRESH_COMPUTES = Object.freeze(["sha256-file", "sha256-tree-v1", "verify-sha256-file"]);
+const OPERATION_KEYS = new Set(["file", "pointer", "compute", "of", "format", "currentMatches"]);
+
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+/** Digest of the regular files below `root` (see the header). Refuses symlinks and anything that is not a regular file or directory. */
+export function sha256TreeV1(root) {
+  const files = [];
+  const visit = (directory) => {
+    for (const name of readdirSync(directory)) {
+      const absolute = path.join(directory, name);
+      const info = lstatSync(absolute);
+      if (info.isSymbolicLink()) fail("SIGN_DEV_ARTIFACT_REFRESH_TREE_INVALID", `refresh tree contains a symlink: ${toPosix(path.relative(root, absolute))}`);
+      if (info.isDirectory()) visit(absolute);
+      else if (info.isFile()) files.push({ relative: toPosix(path.relative(root, absolute)), absolute });
+      else fail("SIGN_DEV_ARTIFACT_REFRESH_TREE_INVALID", `refresh tree contains a non-regular file: ${toPosix(path.relative(root, absolute))}`);
+    }
+  };
+  if (!lstatSync(root).isDirectory()) fail("SIGN_DEV_ARTIFACT_REFRESH_TREE_INVALID", `sha256-tree-v1 needs a directory: ${root}`);
+  visit(root);
+  files.sort((a, b) => Buffer.compare(Buffer.from(a.relative), Buffer.from(b.relative)));
+  const digest = createHash("sha256");
+  for (const { relative, absolute } of files) {
+    const bytes = readFileSync(absolute);
+    const length = Buffer.alloc(8);
+    length.writeBigUInt64BE(BigInt(bytes.length));
+    digest.update(Buffer.from(relative)).update(Buffer.from([0])).update(length).update(bytes);
+  }
+  return digest.digest("hex");
+}
+
+const decodePointer = (pointer) => pointer.slice(1).split("/").map((token) => token.replace(/~1/g, "/").replace(/~0/g, "~"));
+
+/** Parse and validate `refresh` and `refreshRoot` of a raw sign manifest. Returns { root, operations } with absolute paths. */
+export function readRefreshPlan(raw, artifact) {
+  if (raw.refresh === undefined && raw.refreshRoot === undefined) return { root: artifact, operations: [] };
+  if (!Array.isArray(raw.refresh) || raw.refresh.length === 0) fail("SIGN_DEV_ARTIFACT_REFRESH_INVALID", "sign manifest refresh must be a non-empty array of operations");
+  const root = raw.refreshRoot === undefined ? artifact : contained(artifact, raw.refreshRoot, "sign manifest refreshRoot");
+  const operations = raw.refresh.map((item, index) => {
+    const label = `sign manifest refresh[${index}]`;
+    if (!item || typeof item !== "object" || Array.isArray(item)) fail("SIGN_DEV_ARTIFACT_REFRESH_INVALID", `${label} must be an object`);
+    for (const key of Object.keys(item)) if (!OPERATION_KEYS.has(key)) fail("SIGN_DEV_ARTIFACT_REFRESH_INVALID", `${label} has an unknown field: ${key}`);
+    if (!REFRESH_COMPUTES.includes(item.compute)) fail("SIGN_DEV_ARTIFACT_REFRESH_INVALID", `${label}.compute must be one of ${REFRESH_COMPUTES.join(", ")}`);
+    if (typeof item.pointer !== "string" || !item.pointer.startsWith("/") || /~(?![01])/.test(item.pointer)) fail("SIGN_DEV_ARTIFACT_REFRESH_INVALID", `${label}.pointer must be a JSON pointer starting with "/"`);
+    if (item.format !== undefined && (typeof item.format !== "string" || item.format.split("{value}").length !== 2)) fail("SIGN_DEV_ARTIFACT_REFRESH_INVALID", `${label}.format must be a string with exactly one {value}`);
+    if (item.format !== undefined && item.compute === "verify-sha256-file") fail("SIGN_DEV_ARTIFACT_REFRESH_INVALID", `${label}.format does not apply to verify-sha256-file`);
+    let currentMatches;
+    if (item.currentMatches !== undefined) {
+      if (typeof item.currentMatches !== "string" || item.currentMatches.length > 200) fail("SIGN_DEV_ARTIFACT_REFRESH_INVALID", `${label}.currentMatches must be a short regular expression string`);
+      try { currentMatches = new RegExp(item.currentMatches); } catch { fail("SIGN_DEV_ARTIFACT_REFRESH_INVALID", `${label}.currentMatches is not a valid regular expression`); }
+    }
+    return {
+      index, artifact, file: contained(root, item.file, `${label}.file`), of: contained(root, item.of, `${label}.of`),
+      pointer: item.pointer, compute: item.compute, format: item.format, currentMatches, writes: item.compute !== "verify-sha256-file",
+      declared: { file: item.file, pointer: item.pointer, compute: item.compute, of: item.of },
+    };
+  });
+  return { root, operations };
+}
+
+/**
+ * Split the manifest entries around the refresh and enforce the ordering rules. Returns `{ before, after }`: the entries to sign
+ * before the refresh runs and the entries (the first one containing a refreshed file, and everything after it) to sign after it.
+ * Also refuses a payload metadata file that sits inside a signed entry, since refreshing it after that entry is signed would break
+ * the signature. `entries` carry absolute `file` paths.
+ */
+export function planRefresh(entries, operations, metadataFile) {
+  const insideSigned = entries.find((entry) => isWithin(entry.file, metadataFile));
+  if (insideSigned) {
+    fail("SIGN_DEV_ARTIFACT_METADATA_IN_SIGNED_ENTRY", `payload metadata ${path.basename(metadataFile)} lies inside the signed entry ${path.basename(insideSigned.file)}, and refreshing its hashes after signing would break that signature. Keep the payload metadata outside every signed bundle (for example at the artifact root).`);
+  }
+  if (operations.length === 0) return { before: entries, after: [] };
+  const written = operations.filter((operation) => operation.writes).map((operation) => operation.file);
+  const firstContaining = entries.findIndex((entry) => written.some((file) => isWithin(entry.file, file)));
+  const split = firstContaining < 0 ? entries.length : firstContaining;
+  for (const operation of operations) {
+    entries.forEach((entry, index) => {
+      if (isWithin(operation.of, entry.file) && index >= split) {
+        fail("SIGN_DEV_ARTIFACT_REFRESH_ORDER", `refresh reads ${toPosix(path.relative(path.dirname(operation.of), entry.file)) || path.basename(entry.file)}, which is signed after the bundle holding the refreshed files; list it before that bundle so its final bytes are read`);
+      }
+    });
+    operations.forEach((later) => {
+      if (later.index > operation.index && later.writes && isWithin(operation.of, later.file)) {
+        fail("SIGN_DEV_ARTIFACT_REFRESH_ORDER", `refresh[${operation.index}] reads a file that refresh[${later.index}] writes later; list the writer first`);
+      }
+    });
+  }
+  for (const operation of operations) {
+    if (!existsSync(operation.of)) fail("SIGN_DEV_ARTIFACT_MISSING", `refresh input is missing: ${operation.declared.of}`);
+    if (!existsSync(operation.file)) fail("SIGN_DEV_ARTIFACT_MISSING", `refresh file is missing: ${operation.declared.file}`);
+  }
+  return { before: entries.slice(0, split), after: entries.slice(split) };
+}
+
+function readJson(file, label) {
+  const text = readFileSync(file, "utf8");
+  let value;
+  try { value = JSON.parse(text); } catch { fail("SIGN_DEV_ARTIFACT_REFRESH_JSON_INVALID", `${label} is not readable JSON`); }
+  const indent = /^\{\n( +)"/.exec(text)?.[1].length ?? 2;
+  const newline = text.endsWith("\n") ? "\n" : "";
+  const serialize = (candidate) => `${JSON.stringify(candidate, null, indent)}${newline}`;
+  if (serialize(value) !== text) fail("SIGN_DEV_ARTIFACT_REFRESH_JSON_FORMAT", `${label} is not formatted the way this tool writes JSON (${indent}-space indent, key order kept), so refreshing it would reformat more than the edited value; refusing`);
+  return { value, serialize };
+}
+
+function locate(root, pointer, label) {
+  const tokens = decodePointer(pointer);
+  let container = root;
+  for (const token of tokens.slice(0, -1)) {
+    if (container === null || typeof container !== "object" || !Object.hasOwn(container, token)) fail("SIGN_DEV_ARTIFACT_REFRESH_POINTER_MISSING", `${label}: pointer ${pointer} does not exist; the refresh only updates values that are already there`);
+    container = container[token];
+  }
+  const key = tokens.at(-1);
+  if (container === null || typeof container !== "object" || Array.isArray(container) || !Object.hasOwn(container, key)) fail("SIGN_DEV_ARTIFACT_REFRESH_POINTER_MISSING", `${label}: pointer ${pointer} does not exist; the refresh only updates values that are already there`);
+  return { container, key };
+}
+
+/**
+ * Run the operations in order. Returns one record per operation: `{ file, pointer, compute, of, before, after, changed }`
+ * (`verified: true` and no change for verify-sha256-file). Writes atomically, one operation at a time.
+ */
+export function applyRefresh(operations, root) {
+  return operations.map((operation) => {
+    const label = `${operation.declared.file} ${operation.pointer}`;
+    // A link can appear after the plan was read: check every path again on disk right before it is read or written.
+    assertInsideOnDisk(operation.artifact, operation.of, `${label} input`);
+    assertInsideOnDisk(operation.artifact, operation.file, `${label} file`);
+    const digest = operation.compute === "sha256-tree-v1" ? sha256TreeV1(operation.of) : sha256(readFileSync(operation.of));
+    const { value, serialize } = readJson(operation.file, operation.declared.file);
+    const { container, key } = locate(value, operation.pointer, label);
+    const before = container[key];
+    if (typeof before !== "string") fail("SIGN_DEV_ARTIFACT_REFRESH_POINTER_INVALID", `${label} is not a string value`);
+    const record = { file: toPosix(path.relative(root, operation.file)), pointer: operation.pointer, compute: operation.compute, of: toPosix(path.relative(root, operation.of)), before };
+    if (operation.compute === "verify-sha256-file") {
+      if (before !== digest) fail("SIGN_DEV_ARTIFACT_REFRESH_VERIFY_FAILED", `${label} records ${before}, but ${operation.declared.of} is now ${digest}; this digest must survive signing unchanged`);
+      return { ...record, after: before, changed: false, verified: true };
+    }
+    if (operation.currentMatches && !operation.currentMatches.test(before)) fail("SIGN_DEV_ARTIFACT_REFRESH_UNRECOMPUTABLE", `${label} is ${JSON.stringify(before)}, which does not match ${operation.currentMatches}; it is not a value this refresh can recompute, so it is left alone and signing stops`);
+    const after = operation.format === undefined ? digest : operation.format.replace("{value}", digest);
+    container[key] = after;
+    const staging = `${operation.file}.refresh`;
+    assertInsideOnDisk(operation.artifact, staging, `${label} staging file`);
+    rmSync(staging, { force: true }); // removes a stale file or a planted link itself, never what a link points at
+    writeFileSync(staging, serialize(value), { flag: "wx" });
+    renameSync(staging, operation.file);
+    return { ...record, after, changed: after !== before };
+  });
+}

package/dev-artifact-support.mjs

@@ -0,0 +1,61 @@
+// Shared by sign-dev-artifact.mjs and dev-artifact-refresh.mjs (Orthic-Labs/rightkit#257): the typed error and the path helpers.
+import { lstatSync, realpathSync } from "node:fs";
+import path from "node:path";
+
+export class SignDevArtifactError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "SignDevArtifactError";
+    this.code = code;
+  }
+}
+
+export const fail = (code, message) => { throw new SignDevArtifactError(code, message); };
+export const toPosix = (value) => value.split(path.sep).join("/");
+
+/** True when `child` is `parent` or lies below it. Both absolute. */
+export const isWithin = (parent, child) => child === parent || child.startsWith(parent + path.sep);
+
+/**
+ * Refuse `absolute` unless every existing component between `base` and it stays inside `base` on disk. Each component is lstat'ed; a
+ * symlink (or junction) must resolve, through realpath, to a location inside the real `base`, and a dangling or unreadable one is
+ * refused. A path whose tail does not exist yet is judged by its existing prefix. Call it again immediately before every read or
+ * write, since a link can appear after the lexical check. Returns `absolute`.
+ */
+export function assertInsideOnDisk(base, absolute, label) {
+  let realBase;
+  try { realBase = realpathSync(base); } catch { fail("SIGN_DEV_ARTIFACT_PATH_INVALID", `${label}: the artifact directory cannot be resolved: ${base}`); }
+  let current = path.resolve(base);
+  const parts = path.relative(current, absolute).split(path.sep).filter(Boolean);
+  for (const part of parts) {
+    current = path.join(current, part);
+    let info;
+    try {
+      info = lstatSync(current);
+    } catch (error) {
+      if (error.code === "ENOENT" || error.code === "ENOTDIR") return absolute;
+      fail("SIGN_DEV_ARTIFACT_PATH_INVALID", `${label}: cannot inspect ${toPosix(path.relative(base, current))} (${error.code ?? error.message})`);
+    }
+    if (!info.isSymbolicLink()) continue;
+    let real;
+    try { real = realpathSync(current); } catch { fail("SIGN_DEV_ARTIFACT_PATH_ESCAPE", `${label}: ${toPosix(path.relative(base, current))} is a symlink that does not resolve`); }
+    if (!isWithin(realBase, real)) fail("SIGN_DEV_ARTIFACT_PATH_ESCAPE", `${label}: ${toPosix(path.relative(base, current))} is a symlink that leaves the artifact directory`);
+  }
+  return absolute;
+}
+
+/**
+ * A path relative to `base` that stays inside it: no absolute path, no `..`, not empty, and not `base` itself (so "." and "a/.."
+ * are refused). Lexical first, then every existing component is checked on disk (see assertInsideOnDisk), so a symlink inside the
+ * artifact cannot redirect outside it. Returns the absolute path.
+ */
+export function contained(base, relative, label) {
+  if (typeof relative !== "string" || !relative || path.isAbsolute(relative) || path.win32.isAbsolute(relative) || relative.split(/[\\/]/).includes("..")) {
+    fail("SIGN_DEV_ARTIFACT_PATH_INVALID", `${label} must be a relative path inside the artifact directory: ${JSON.stringify(relative)}`);
+  }
+  const absolute = path.resolve(base, relative);
+  if (absolute === path.resolve(base) || !isWithin(path.resolve(base), absolute)) {
+    fail("SIGN_DEV_ARTIFACT_PATH_INVALID", `${label} must name a path below the artifact directory, not the directory itself: ${JSON.stringify(relative)}`);
+  }
+  return assertInsideOnDisk(base, absolute, label);
+}