@rightkit/release 0.3.0 → 0.4.1

package/publish-swift.mjs

@@ -1,5 +1,5 @@
 // Publish RightKitSwift by the ONE Swift distribution contract: a plain semver git tag on this
-// repository (github.com/Orthic-Labs/rightkit), resolved by apps through the root Package.swift
+// repository (the checkout's own origin, github.com/bogusyogi/rightkit), resolved by apps through the root Package.swift
 // (docs/RIGHTKIT-SHARED-PACKAGES.md, Swift section). There is no mirror and no second repository.
 //
 // `right-release publish swift [--dry-run] [--evidence <file>] [--workspace <dir>]` verifies, in order:
@@ -19,7 +19,14 @@ import { spawnSync } from "./background-process.mjs";
 import { digestBytes } from "./publication-artifacts.mjs";
 import { enforcePublicationGate, defaultEvidencePath } from "./publication-gate.mjs";
 
-export const SWIFT_DISTRIBUTION_URL = "https://github.com/Orthic-Labs/rightkit";
+// The distribution URL is whatever repository this checkout's origin names (GITHUB_REPOSITORY when origin does not
+// parse); it is never a constant, so a repository move cannot leave a stale name in the success message.
+export function swiftDistributionUrl(origin, environment = process.env) {
+  const fromOrigin = /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/i.exec(String(origin ?? "").trim())?.[1];
+  const fromEnvironment = /^[\w.-]+\/[\w.-]+$/.test(environment?.GITHUB_REPOSITORY ?? "") ? environment.GITHUB_REPOSITORY : null;
+  const repository = fromOrigin ?? fromEnvironment;
+  return repository ? `https://github.com/${repository}` : String(origin ?? "").trim();
+}
 const DRIFT_TEST = path.join("scripts", "swift-root-manifest.test.mjs");
 
 export function parseSwiftPublishArgs(argv) {
@@ -125,7 +132,9 @@ export function runSwiftPublish(options, execute = spawnSync) {
   catch (error) { git(["tag", "-d", version], toplevel, execute); throw error; }
   const remote = git(["ls-remote", "--tags", "origin", `refs/tags/${version}`], toplevel, execute);
   if (!remote.startsWith(sha)) throw new Error(`origin does not show tag ${version} at ${sha}`);
-  out(`tagged ${version} at ${sha} on ${SWIFT_DISTRIBUTION_URL}`);
+  let origin = "";
+  try { origin = git(["config", "--get", "remote.origin.url"], toplevel, execute); } catch { /* the tag is already verified on origin; the name is cosmetic */ }
+  out(`tagged ${version} at ${sha} on ${swiftDistributionUrl(origin, options.environment)}`);
   return { name, version, commit: sha, published: true };
 }
 

package/publish-update.mjs

@@ -14,7 +14,7 @@ import { verifyPublicationRelease, PublicationError, assertArtifactUnchanged, di
 import { uploadVerifiedR2Artifact } from "./r2-verified-upload.mjs";
 import { verifyPlatformTrust } from "./github-release.mjs";
 import { admitInstalledQa } from "./release-qa-audit.mjs";
-import { assertAssetName, assertGitHubRepository, assertUpdaterKeyId, assertUpdaterPlatform, buildLatestJson, githubAssetUrl, githubTag, publishGitHubUpdaterRelease } from "./github-updater-release.mjs";
+import { assertAssetName, assertGitHubRepository, assertUpdaterKeyId, assertUpdaterPlatform, assertUpdaterSignature, buildLatestJson, githubAssetUrl, githubTag, publishGitHubUpdaterRelease } from "./github-updater-release.mjs";
 
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const API_BASE = process.env.RIGHTAPPS_API_URL || "https://api.spoares.com";
@@ -116,7 +116,20 @@ function git(args) {
 if (!githubLane && tier === "patch" && !installers.length) fail(`${config?.app ?? "app"} ${platform} patch has no installer.artifacts`);
 if ((githubLane || tier === "update") && !artifacts.length) fail(`${config?.app ?? "app"} ${platform} update has no updater.artifacts`);
 
-if (sealed) for (const artifact of artifacts) signatureFor(artifact);
+// Cryptographic gate before any upload: every sealed minisign signature must verify over the
+// exact final artifact bytes against the declared public key. No declared key means the
+// signature cannot be verified, so a sealed (real) publish fails closed; key-id pinning is
+// supplementary only. Integrator owns declaring distribution.updaterPublicKey in app configs
+// (suite key already pinned per-app as tauri plugins.updater.pubkey).
+const updaterPublicKey = config.distribution?.updaterPublicKey ?? config.distribution?.updaterPubkey ?? target?.updater?.pubkey ?? target?.updater?.publicKey;
+if (sealed) for (const artifact of artifacts) {
+  const signature = signatureFor(artifact);
+  if (!appInstallerKind) {
+    if (!updaterPublicKey) throw new PublicationError("PUBLICATION_SIGNATURE_UNVERIFIABLE", `no updater public key declared (distribution.updaterPublicKey); refusing to upload ${path.basename(artifact.file)} with an unverified signature`);
+    assertUpdaterSignature(assertArtifactUnchanged(verifiedArtifact(artifact.file)), signature, updaterPublicKey, `signature of ${path.basename(artifact.file)}`);
+    assertUpdaterKeyId(signature, config.distribution.updaterKeyId, `signature of ${path.basename(artifact.file)}`);
+  }
+}
 let releaseToken = null;
 if (!githubLane && !dryRun && (tier === "update" || artifacts.length > 0)) {
   try {

package/qa-build-features.mjs

@@ -12,17 +12,10 @@ import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { expandRecipeBuildCommands } from "./recipe-build.mjs";
 
-export const FORBIDDEN_FEATURES = Object.freeze(["devtools", "content-devtools", "qa-native", "qa-control", "dev-native", "dev-inspect",
-  // Per-app test-automation features (M20 owner gap): HeardRight `qa-shot`/`qa-tools`, ViewRight `dev-control`/`bench-native`.
-  "qa-shot", "qa-tools", "dev-control", "bench-native",
-  // D4 (M21/M23): rightkit-daemon `test-mode` compiles the override selectors; never in a release build.
-  "test-mode"]);
-// rightkit-qa 0.6.0 moved the embedded control server (the former rightkit-qa-driver `qa-control`) behind its `control`
-// feature. It emits the same QA_CONTROL_MARKER, so the binary layer refuses it unchanged; this is the source layer.
-export const QUALIFIED_FORBIDDEN_FEATURES = Object.freeze(["rightkit-qa/control", "rightkit-qa?/control"]);
-// The only forbidden features an allow-listed app may enable: rightkit-tauri-shell's `content-devtools` (and the Tauri
-// `devtools` it switches on). See devtools-policy.mjs; every other app is refused them.
-const DEVTOOLS_FEATURES = Object.freeze(["devtools", "content-devtools"]);
+const featureRegistry = JSON.parse(readFileSync(new URL("./release-switch-registry.json", import.meta.url), "utf8"));
+const DEVTOOLS_FEATURES = Object.freeze(featureRegistry.conditionalForbiddenFeatures["content-only"]);
+export const FORBIDDEN_FEATURES = Object.freeze([...featureRegistry.forbiddenFeatures.filter((name) => !name.includes("/")), ...DEVTOOLS_FEATURES]);
+export const QUALIFIED_FORBIDDEN_FEATURES = Object.freeze(featureRegistry.forbiddenFeatures.filter((name) => name.includes("/")));
 const FORBIDDEN_DEPENDENCY = "tauri-plugin-wdio-webdriver";
 const MANAGERS = new Set(["pnpm", "npm", "yarn", "bun", "npx"]);
 
@@ -36,7 +29,7 @@ export function isForbiddenFeature(item, { allowDevtools = false } = {}) {
   const name = featureName(text);
   if (allowDevtools && DEVTOOLS_FEATURES.includes(name)) return false;
   // `control` is too generic to forbid by bare name; rightkit-qa's dev-only server feature is refused when qualified.
-  if (QUALIFIED_FORBIDDEN_FEATURES.includes(text.replace(/\s+/g, ""))) return true;
+  if (QUALIFIED_FORBIDDEN_FEATURES.includes(text.replace(/\s+/g, "").replace("?/", "/"))) return true;
   return text === `dep:${FORBIDDEN_DEPENDENCY}` || FORBIDDEN_FEATURES.includes(name);
 }
 
@@ -154,6 +147,7 @@ export function parseCargoFeaturesAndDependencies(manifestText) {
 function dependencyInfo(spec) {
   const list = spec.match(/features\s*=\s*(\[)/);
   return {
+    package: spec.match(/package\s*=\s*["']([^"']+)["']/)?.[1],
     optional: /optional\s*=\s*true/.test(spec),
     features: list ? strings(balanced(spec, list.index + list[0].length - 1, "[", "]")) : [],
   };
@@ -162,6 +156,15 @@ function dependencyInfo(spec) {
 export function cargoManifestIssues(manifestText, label = "Cargo.toml", { allowDevtools = false } = {}) {
   const { features, dependencies } = parseCargoFeaturesAndDependencies(manifestText);
   const issues = [];
+  const canonicalFeature = (item) => {
+    const match = /^([^/]+?)(\?)?\/(.+)$/.exec(item);
+    return match ? `${dependencies.get(match[1])?.package ?? match[1]}/${match[3]}` : item;
+  };
+  for (const [alias, dep] of dependencies) {
+    if (dep.package && dep.package !== alias && !dep.optional) for (const feature of dep.features) {
+      if (isForbiddenFeature(`${dep.package ?? alias}/${feature}`, { allowDevtools })) issues.push(`${label}: dependency \`${alias}\` enables forbidden feature \`${dep.package ?? alias}/${feature}\``);
+    }
+  }
   const tauri = dependencies.get("tauri");
   if (!allowDevtools && tauri?.features.includes("devtools")) issues.push(`${label}: dependency \`tauri\` lists feature \`devtools\` unconditionally (inspector ships in release builds)`);
   // The crate was renamed from rightkit-control; apps still on the old published name must stay covered.
@@ -185,7 +188,7 @@ export function cargoManifestIssues(manifestText, label = "Cargo.toml", { allowD
     const item = stack.pop();
     if (reached.has(item)) continue;
     reached.add(item);
-    if (isForbiddenFeature(item, { allowDevtools })) issues.push(`${label}: default feature set reaches \`${item}\``);
+    if (isForbiddenFeature(canonicalFeature(item), { allowDevtools })) issues.push(`${label}: default feature set reaches \`${item}\``);
     if (features.has(item)) stack.push(...features.get(item));
   }
   return issues;

package/qa-contract.mjs

@@ -106,6 +106,33 @@ export function qaManifests(appRoot, { readdir = readdirSync } = {}) {
   return found.sort();
 }
 
+/**
+ * Native Apple UI-test targets under `appRoot`: an XcodeGen `project.yml` target of `type: bundle.ui-testing`,
+ * or an `.xcodeproj` whose `project.pbxproj` declares `com.apple.product-type.bundle.ui-testing`. An XCUITest
+ * target is the QA lane of a native iOS or macOS app, which has no package.json or Cargo.toml to pin RightKit QA in.
+ */
+export function nativeAppleUiTestLanes(appRoot, { readdir = readdirSync, readFile = readFileSync } = {}) {
+  const lanes = [];
+  const read = (file) => { try { return readFile(file, "utf8"); } catch { return ""; } };
+  const visit = (dir, depth) => {
+    let entries;
+    try { entries = readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      const relative = path.relative(appRoot, full).split(path.sep).join("/");
+      if (entry.isDirectory()) {
+        if (entry.name.endsWith(".xcodeproj")) {
+          if (read(path.join(full, "project.pbxproj")).includes("com.apple.product-type.bundle.ui-testing")) lanes.push(`native XCUITest lane (${relative})`);
+        } else if (depth < MAX_DEPTH && !SKIP_DIRS.test(entry.name) && relative !== "rightkit" && relative !== "tools/rightkit") visit(full, depth + 1);
+      } else if (entry.name === "project.yml" && /^\s*type:\s*bundle\.ui-testing\s*$/m.test(read(full))) {
+        lanes.push(`native XCUITest lane (${relative})`);
+      }
+    }
+  };
+  visit(appRoot, 0);
+  return [...new Set(lanes)].sort();
+}
+
 /** `[dependencies]`-style section header that holds dependencies (including target-specific ones). */
 const DEPENDENCY_HEADER = /^\[\s*(?:target\.[^\]]+\.)?(?:dev-|build-)?dependencies\s*\]/;
 const DEPENDENCY_TABLE_HEADER = /^\[\s*(?:target\.[^\]]+\.)?(?:dev-|build-)?dependencies\.([A-Za-z0-9_-]+)\s*\]/;
@@ -215,11 +242,12 @@ export function evaluateQaAdoption({ appRoot, repoRoot, app }, deps = {}) {
   }
   const label = app ?? "this app";
   const adopted = [...new Set(pins.filter((pin) => pin.name === NPM_QA || pin.name === CARGO_QA).map((pin) => pin.name))];
-  const lane = exists(path.join(appRoot, "right-qa.config.mjs")) ? ["native wdio lane (right-qa.config.mjs)", ...adopted] : adopted;
+  const nativeApple = deps.nativeAppleLanes ?? nativeAppleUiTestLanes(appRoot, deps);
+  const lane = [...(exists(path.join(appRoot, "right-qa.config.mjs")) ? ["native wdio lane (right-qa.config.mjs)"] : []), ...nativeApple, ...adopted];
   const refusals = [];
   const warnings = [];
   if (lane.length === 0) {
-    refusals.push(`RightKit QA is mandatory for every Orthic Labs app, and ${label} has no QA lane: no right-qa.config.mjs, no ${NPM_QA} in a package.json, no ${CARGO_QA} in a Cargo.toml${unreadable.length ? ` (unreadable: ${unreadable.join("; ")})` : ""}. Adopt it: add ${NPM_QA} to devDependencies (plus ${NPM_QA_CHROME} for a web UI) and/or ${CARGO_QA} to Cargo.toml [dev-dependencies], add the rightkit-qa floor run (smoke.launch, journey), see docs/ADOPTION.md, then run: node rightkit-drift.mjs --apply. Only a repository that is not an app is exempt (${QA_EXEMPTIONS_FILE}); an app cannot opt out`);
+    refusals.push(`RightKit QA is mandatory for every Orthic Labs app, and ${label} has no QA lane: no right-qa.config.mjs, no XCUITest target, no ${NPM_QA} in a package.json, no ${CARGO_QA} in a Cargo.toml${unreadable.length ? ` (unreadable: ${unreadable.join("; ")})` : ""}. Adopt it: add ${NPM_QA} to devDependencies (plus ${NPM_QA_CHROME} for a web UI) and/or ${CARGO_QA} to Cargo.toml [dev-dependencies], add the rightkit-qa floor run (smoke.launch, journey), see docs/ADOPTION.md, then run: node rightkit-drift.mjs --apply. Only a repository that is not an app is exempt (${QA_EXEMPTIONS_FILE}); an app cannot opt out`);
   }
   const lagging = pins
     .map((pin) => ({ ...pin, latest: pin.version && latestFor(versions, pin.ecosystem, pin.name) }))

package/qa-control-scan.mjs

@@ -379,6 +379,10 @@ export function assertNoQaControl(paths, label = "release", { requireBinary = fa
 // string that survives minification (an identifier that is also a string literal, a file/chunk name, a protocol or
 // a build-flag name). Source maps are scanned too: a map that names qaMock.ts proves the module was bundled.
 export const WEB_MOCK_MARKERS = Object.freeze([
+  { id: "platform-qa-selector", pattern: /__RIGHTKIT_QA_PLATFORM__/ },
+  { id: "platform-qa-environment", pattern: /\bRIGHTKIT_QA_PLATFORM\b/ },
+  { id: "platform-qa-entry", pattern: /(?:bootstrapQaPlatform|resolveQaPlatform|configureQaPlatform|@rightkit\/platform-ui\/qa)/ },
+
   { id: "browser-qa-fake", pattern: /browser-qa-fake/ },
   { id: "browser-mock-api", pattern: /browser-mock-api/ },
   { id: "browser-qa-mock-scheme", pattern: /browser-qa-mock:/ },
@@ -387,6 +391,10 @@ export const WEB_MOCK_MARKERS = Object.freeze([
   { id: "isBrowserQaMode", pattern: /isBrowserQaMode/ },
   { id: "MockDataSource", pattern: /MockDataSource/ },
   { id: "qa-build-flag", pattern: /\bVITE_[A-Z0-9_]*_QA\b/ },
+
+  // @rightkit/license/testing (M12): its sentinel value, and the subpath a bundle that kept the import still names.
+  { id: "license-testing-sentinel", pattern: /\bRIGHTKIT_LICENSE_TESTING_DO_NOT_SHIP\b/ },
+  { id: "license-testing-entry", pattern: /@rightkit\/license\/testing/ },
 ]);
 const WEB_EXTENSIONS = /\.(?:m?js|cjs|html?|css|map)$/i;
 

package/release-config.mjs

@@ -0,0 +1,330 @@
+// The release config contract (M24): `right-release.config.json`, a finite, versioned JSON schema read by dev, build, doctor, install
+// and upload alike. It is data. RightKit never imports, evaluates or converts an executable (`.mjs`, `.js`, `.cjs`, `.ts`) config: the
+// file name is judged BEFORE anything is opened or imported, including for `--dry-run`, so a legacy config cannot run a single line.
+//
+// Load order (build, dev, upload): resolve the primary checkout and the config path first, then `loadReleaseConfigSync` parses the JSON
+// strictly (no comments, no trailing commas, no duplicate keys), checks `schema: 1` and the finite top-level key set, expands the
+// typed templates below, and runs the M24 pipeline validation (`pipeline-config.mjs`) so a command that is not an admitted RightKit
+// invocation stops the run before the #340 preflight and before any recipe executes. A hash alone is never trusted: each effect
+// boundary (build, sign, upload) loads and validates again.
+//
+// Typed templates (the only computation a config may express):
+//   { "$fromJson": { "file": "src-tauri/tauri.conf.json", "pointer": "/version" } }   a string read from an app-relative JSON file
+//   { "$fromToml": { "file": "src-tauri/Cargo.toml", "path": "package.version" } }    a string read from an app-relative TOML file
+//   { "$json": <value> }                                                              JSON.stringify(<value>), for a JSON argument
+//   "{{app}}" "{{version}}" "{{home}}" "{{localAppData}}"                              replaced inside any string value
+// Anything else with braces is left alone, and an unknown {{token}} is an error.
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { collectConfigCommands, formatFindings, validateConfigPipeline } from "./pipeline-config.mjs";
+import { loadGeneratorRegistry } from "./pipeline-generators.mjs";
+
+export const RELEASE_CONFIG_FILE = "right-release.config.json";
+export const LEGACY_RELEASE_CONFIG_FILE = "right-release.config.mjs";
+export const RELEASE_CONFIG_SCHEMA = 1;
+export const MAX_CONFIG_BYTES = 1024 * 1024;
+export const LEGACY_EXECUTABLE_EXTENSIONS = Object.freeze([".mjs", ".js", ".cjs", ".ts", ".mts", ".cts", ".jsx", ".tsx"]);
+
+/** The complete set of top-level keys. A key outside it is refused: a new capability is a RightKit change, not an app extension. */
+export const TOP_LEVEL_KEYS = Object.freeze([
+  "$schema", "$comment", "schema", "app", "version", "channel", "distribution", "packageManager", "workdir", "targets", "development",
+  "deps", "checks", "buildInputs", "hostedWorkflows", "devtools", "releaseSwitches", "qa", "nativeAssembly", "legal", "web", "tests",
+  "sidecars", "releaseDependencies", "appStoreConnect", "storage", "cargoProfileExempt", "runtimeArtifacts",
+]);
+export const TEMPLATE_TOKENS = Object.freeze(["app", "version", "home", "localAppData"]);
+
+export class ReleaseConfigError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "ReleaseConfigError";
+    this.code = code;
+    Object.assign(this, details);
+  }
+}
+const fail = (code, message, details) => { throw new ReleaseConfigError(code, message, details); };
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * Judge a config file NAME. Throws for an executable config and for anything that is not `.json`. It touches no file: call it before
+ * opening, importing or even resolving a repository, so a legacy config is refused on every route (dry runs included).
+ */
+export function assertReleaseConfigFileName(file) {
+  if (typeof file !== "string" || !file.trim()) fail("RELEASE_CONFIG_NOT_JSON", "a release config path is required (right-release.config.json)");
+  const extension = path.extname(path.basename(file)).toLowerCase();
+  if (LEGACY_EXECUTABLE_EXTENSIONS.includes(extension)) {
+    fail("RELEASE_CONFIG_LEGACY_EXECUTABLE", `${file} is an executable release config (${extension}). RightKit never imports, evaluates or converts one; write ${RELEASE_CONFIG_FILE} (finite JSON schema, see the README section "Release config (JSON)") and delete the module.`, { file });
+  }
+  if (extension !== ".json") fail("RELEASE_CONFIG_NOT_JSON", `${file} is not a JSON release config; the only config file is ${RELEASE_CONFIG_FILE}`, { file });
+  return file;
+}
+
+/** A hint for a missing config: a legacy sibling is named (never opened). */
+function missingConfigMessage(file) {
+  const legacy = path.join(path.dirname(file), LEGACY_RELEASE_CONFIG_FILE);
+  return existsSync(legacy)
+    ? `release config not found: ${file}. A legacy executable config exists at ${legacy}; it is never imported or converted. Write ${RELEASE_CONFIG_FILE}.`
+    : `release config not found: ${file}`;
+}
+
+// ---- strict JSON ----------------------------------------------------------------------------------------------------------------
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+const NUMBER = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+const pointerKey = (key) => key.replaceAll("~", "~0").replaceAll("/", "~1");
+
+/** Parse JSON strictly and remember where every value starts: `{ value, offsets }` (offsets: JSON pointer -> character offset). */
+export function parseStrictJson(text) {
+  const offsets = new Map();
+  let pos = 0;
+  const error = (message) => { throw Object.assign(new SyntaxError(message), { offset: pos }); };
+  const skip = () => { while (pos < text.length && (text[pos] === " " || text[pos] === "\t" || text[pos] === "\n" || text[pos] === "\r")) pos += 1; };
+  const string = () => {
+    const start = pos;
+    pos += 1;
+    while (pos < text.length && text[pos] !== '"') {
+      if (text.charCodeAt(pos) < 0x20) error("a control character inside a string");
+      pos += text[pos] === "\\" ? 2 : 1;
+    }
+    if (text[pos] !== '"') error("an unterminated string");
+    pos += 1;
+    try { return JSON.parse(text.slice(start, pos)); } catch { pos = start; return error("an invalid string escape"); }
+  };
+  const literal = (word, result) => { if (!text.startsWith(word, pos)) error(`unexpected token`); pos += word.length; return result; };
+  const value = (pointer, depth) => {
+    if (depth > 64) error("nesting deeper than 64 levels");
+    skip();
+    offsets.set(pointer, pos);
+    const ch = text[pos];
+    if (ch === "{") return object(pointer, depth);
+    if (ch === "[") return array(pointer, depth);
+    if (ch === '"') return string();
+    if (ch === "t") return literal("true", true);
+    if (ch === "f") return literal("false", false);
+    if (ch === "n") return literal("null", null);
+    NUMBER.lastIndex = pos;
+    const match = NUMBER.exec(text);
+    if (!match || match.index !== pos) error("unexpected token");
+    pos += match[0].length;
+    return Number(match[0]);
+  };
+  const object = (pointer, depth) => {
+    const out = {};
+    pos += 1;
+    skip();
+    if (text[pos] === "}") { pos += 1; return out; }
+    for (;;) {
+      skip();
+      if (text[pos] !== '"') error("expected a string key");
+      const keyStart = pos;
+      const key = string();
+      if (FORBIDDEN_KEYS.has(key)) { pos = keyStart; error(`the key "${key}" is not allowed`); }
+      if (Object.prototype.hasOwnProperty.call(out, key)) { pos = keyStart; error(`duplicate key "${key}"`); }
+      skip();
+      if (text[pos] !== ":") error("expected ':'");
+      pos += 1;
+      out[key] = value(`${pointer}/${pointerKey(key)}`, depth + 1);
+      skip();
+      if (text[pos] === ",") { pos += 1; continue; }
+      if (text[pos] === "}") { pos += 1; return out; }
+      error("expected ',' or '}'");
+    }
+  };
+  const array = (pointer, depth) => {
+    const out = [];
+    pos += 1;
+    skip();
+    if (text[pos] === "]") { pos += 1; return out; }
+    for (;;) {
+      out.push(value(`${pointer}/${out.length}`, depth + 1));
+      skip();
+      if (text[pos] === ",") { pos += 1; continue; }
+      if (text[pos] === "]") { pos += 1; return out; }
+      error("expected ',' or ']'");
+    }
+  };
+  const result = value("", 0);
+  skip();
+  if (pos !== text.length) error("unexpected content after the JSON value");
+  return { value: result, offsets };
+}
+
+/** 1-based line of a JSON pointer in `text` (the nearest recorded ancestor when the exact pointer is not a source position). */
+export function lineOfPointer(text, offsets, pointer) {
+  let current = pointer;
+  while (current !== "" && !offsets.has(current)) current = current.slice(0, current.lastIndexOf("/"));
+  const offset = offsets.get(current) ?? 0;
+  let line = 1;
+  for (let i = 0; i < offset && i < text.length; i += 1) if (text[i] === "\n") line += 1;
+  return line;
+}
+
+// ---- templates ------------------------------------------------------------------------------------------------------------------
+function readInside(appRoot, relative, label, { readBytes, lstat }) {
+  if (typeof relative !== "string" || !relative.trim() || path.isAbsolute(relative) || path.win32.isAbsolute(relative) || /^[A-Za-z]:/.test(relative) || relative.replaceAll("\\", "/").split("/").includes("..")) {
+    fail("RELEASE_CONFIG_TEMPLATE", `${label}: file must be a relative path inside the app: ${JSON.stringify(relative)}`);
+  }
+  const absolute = path.resolve(appRoot, relative);
+  let info;
+  try { info = lstat(absolute); } catch { fail("RELEASE_CONFIG_TEMPLATE", `${label}: ${relative} does not exist`); }
+  if (info.isSymbolicLink() || !info.isFile()) fail("RELEASE_CONFIG_TEMPLATE", `${label}: ${relative} must be a regular file (no symlink)`);
+  if (info.size > MAX_CONFIG_BYTES) fail("RELEASE_CONFIG_TEMPLATE", `${label}: ${relative} is larger than ${MAX_CONFIG_BYTES} bytes`);
+  const bytes = readBytes(absolute);
+  return { bytes, sha256: createHash("sha256").update(bytes).digest("hex"), relative: relative.replaceAll("\\", "/") };
+}
+
+function jsonPointerGet(document, pointer, label) {
+  if (pointer === "") return document;
+  if (typeof pointer !== "string" || !pointer.startsWith("/")) fail("RELEASE_CONFIG_TEMPLATE", `${label}: pointer must be a JSON pointer such as /version`);
+  let current = document;
+  for (const raw of pointer.slice(1).split("/")) {
+    const key = raw.replaceAll("~1", "/").replaceAll("~0", "~");
+    if (!(isObject(current) || Array.isArray(current)) || !Object.prototype.hasOwnProperty.call(current, key)) fail("RELEASE_CONFIG_TEMPLATE", `${label}: ${pointer} is not in the file`);
+    current = current[key];
+  }
+  return current;
+}
+
+function scalarString(value, label) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return fail("RELEASE_CONFIG_TEMPLATE", `${label}: the referenced value must be a string or a number`);
+}
+
+/** Replace the typed templates in `node`. `context` carries the template values, the app root and the injectable file access. */
+function expand(node, context, label) {
+  if (typeof node === "string") {
+    return node.replace(/\{\{([A-Za-z][A-Za-z0-9]*)\}\}/g, (_, token) => {
+      if (!TEMPLATE_TOKENS.includes(token)) fail("RELEASE_CONFIG_TEMPLATE", `${label}: unknown template token {{${token}}} (allowed: ${TEMPLATE_TOKENS.map((t) => `{{${t}}}`).join(", ")})`);
+      const resolved = context.values[token];
+      if (typeof resolved !== "string" || resolved === "") fail("RELEASE_CONFIG_TEMPLATE", `${label}: {{${token}}} is not available${token === "localAppData" ? " (LOCALAPPDATA is not set)" : token === "version" ? " here (version cannot refer to itself)" : ""}`);
+      return resolved;
+    });
+  }
+  if (Array.isArray(node)) return node.map((item, index) => expand(item, context, `${label}/${index}`));
+  if (!isObject(node)) return node;
+  const keys = Object.keys(node);
+  if (keys.length === 1 && keys[0] === "$fromJson") {
+    const spec = node.$fromJson;
+    if (!isObject(spec) || Object.keys(spec).some((key) => key !== "file" && key !== "pointer") || typeof spec.file !== "string") fail("RELEASE_CONFIG_TEMPLATE", `${label}: $fromJson must be { file, pointer }`);
+    const read = readInside(context.appRoot, spec.file, `${label} $fromJson`, context);
+    let document;
+    try { document = JSON.parse(Buffer.from(read.bytes).toString("utf8")); } catch { fail("RELEASE_CONFIG_TEMPLATE", `${label}: ${spec.file} is not valid JSON`); }
+    context.inputs.set(read.relative, read.sha256);
+    return scalarString(jsonPointerGet(document, spec.pointer ?? "", `${label} $fromJson`), label);
+  }
+  if (keys.length === 1 && keys[0] === "$fromToml") {
+    const spec = node.$fromToml;
+    if (!isObject(spec) || Object.keys(spec).some((key) => key !== "file" && key !== "path") || typeof spec.file !== "string" || typeof spec.path !== "string") fail("RELEASE_CONFIG_TEMPLATE", `${label}: $fromToml must be { file, path }`);
+    const read = readInside(context.appRoot, spec.file, `${label} $fromToml`, context);
+    let document;
+    try { document = parseToml(Buffer.from(read.bytes).toString("utf8")); } catch { fail("RELEASE_CONFIG_TEMPLATE", `${label}: ${spec.file} is not valid TOML`); }
+    context.inputs.set(read.relative, read.sha256);
+    let current = document;
+    for (const key of spec.path.split(".")) {
+      if (!isObject(current) || !Object.prototype.hasOwnProperty.call(current, key)) fail("RELEASE_CONFIG_TEMPLATE", `${label}: ${spec.path} is not in ${spec.file}`);
+      current = current[key];
+    }
+    return scalarString(current, label);
+  }
+  if (keys.length === 1 && keys[0] === "$json") return JSON.stringify(expand(node.$json, context, `${label}/$json`));
+  const out = {};
+  for (const key of keys) {
+    if (key.startsWith("$") && !TOP_LEVEL_KEYS.includes(key)) fail("RELEASE_CONFIG_TEMPLATE", `${label}/${key}: "$" keys other than $fromJson, $fromToml and $json are reserved`);
+    out[key] = expand(node[key], context, `${label}/${pointerKey(key)}`);
+  }
+  return out;
+}
+
+// ---- shape ----------------------------------------------------------------------------------------------------------------------
+const SAFE_APP = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const SAFE_VERSION = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+
+/** Schema, finite key set and the identity fields. Throws RELEASE_CONFIG_SCHEMA / RELEASE_CONFIG_KEY. */
+export function validateReleaseConfigShape(config, { file = RELEASE_CONFIG_FILE, phase = "final" } = {}) {
+  if (!isObject(config)) fail("RELEASE_CONFIG_SCHEMA", `${file} must be a JSON object`, { file });
+  if (config.schema !== RELEASE_CONFIG_SCHEMA) fail("RELEASE_CONFIG_SCHEMA", `${file}: unsupported config schema ${JSON.stringify(config.schema ?? null)} (expected ${RELEASE_CONFIG_SCHEMA})`, { file });
+  const unknown = Object.keys(config).filter((key) => !TOP_LEVEL_KEYS.includes(key));
+  if (unknown.length) fail("RELEASE_CONFIG_KEY", `${file}: unknown top-level key(s): ${unknown.join(", ")}. The config schema is finite (allowed: ${TOP_LEVEL_KEYS.filter((key) => !key.startsWith("$")).join(", ")}); a new capability is a RightKit change.`, { file, unknown });
+  if (typeof config.app !== "string" || !SAFE_APP.test(config.app)) fail("RELEASE_CONFIG_SCHEMA", `${file}: app must be a safe name (letters, digits, . _ -)`, { file });
+  // Before template expansion a version may still be a { $fromJson | $fromToml } node or carry a {{token}}; the final check is strict.
+  const versionIsTemplate = phase === "raw" && (isObject(config.version) || (typeof config.version === "string" && config.version.includes("{{")));
+  if (config.version !== undefined && !versionIsTemplate && (typeof config.version !== "string" || !SAFE_VERSION.test(config.version))) fail("RELEASE_CONFIG_SCHEMA", `${file}: version must be a safe version string`, { file });
+  for (const key of ["targets", "development", "buildInputs", "distribution"]) {
+    if (config[key] !== undefined && !isObject(config[key])) fail("RELEASE_CONFIG_SCHEMA", `${file}: ${key} must be an object`, { file });
+  }
+  return config;
+}
+
+function packageScripts(appRoot, readText) {
+  try {
+    const parsed = JSON.parse(readText(path.join(appRoot, "package.json")));
+    return isObject(parsed?.scripts) ? parsed.scripts : undefined;
+  } catch { return undefined; }
+}
+
+/**
+ * Load, validate and expand a release config. Returns `{ config, configPath, appRoot, sha256, inputs, lineOf }`. Throws ReleaseConfigError
+ * (RELEASE_CONFIG_LEGACY_EXECUTABLE | _NOT_JSON | _NOT_FOUND | _INVALID_JSON | _SCHEMA | _KEY | _TEMPLATE | _M24). `validatePipeline: false`
+ * skips only the M24 command admission (the pipeline scanner reports those findings itself); nothing else is optional.
+ * File access, the generator registry, the environment and the home directory are injectable for tests.
+ */
+export function loadReleaseConfigSync(file, {
+  validatePipeline = true, registry, containment, env = process.env, homedir = () => os.homedir(),
+  readText = (target) => readFileSync(target, "utf8"), readBytes = (target) => readFileSync(target), lstat = lstatSync,
+} = {}) {
+  assertReleaseConfigFileName(file);
+  const configPath = path.resolve(file);
+  const appRoot = path.dirname(configPath);
+  let text;
+  try { text = readText(configPath); } catch { fail("RELEASE_CONFIG_NOT_FOUND", missingConfigMessage(configPath), { file: configPath }); }
+  if (Buffer.byteLength(text) > MAX_CONFIG_BYTES) fail("RELEASE_CONFIG_INVALID_JSON", `${configPath} is larger than ${MAX_CONFIG_BYTES} bytes`, { file: configPath });
+  if (text.charCodeAt(0) === 0xfeff) text = text.slice(1);
+  let parsed;
+  try { parsed = parseStrictJson(text); } catch (error) {
+    let line = 1;
+    for (let i = 0; i < (error.offset ?? 0) && i < text.length; i += 1) if (text[i] === "\n") line += 1;
+    fail("RELEASE_CONFIG_INVALID_JSON", `${configPath}:${line} is not valid strict JSON (${error.message}; no comments, trailing commas or duplicate keys)`, { file: configPath, line });
+  }
+  const raw = parsed.value;
+  validateReleaseConfigShape(raw, { file: configPath, phase: "raw" });
+  const inputs = new Map();
+  const base = { appRoot, inputs, readBytes, lstat, values: { home: homedir(), localAppData: env.LOCALAPPDATA ?? "", app: "", version: "" } };
+  base.values.app = expand(raw.app, { ...base }, "/app");
+  if (raw.version !== undefined) base.values.version = expand(raw.version, { ...base, values: { ...base.values, version: "" } }, "/version");
+  const config = expand(raw, base, "");
+  validateReleaseConfigShape(config, { file: configPath });
+  const sha256 = createHash("sha256").update(Buffer.from(text)).digest("hex");
+  if (validatePipeline) {
+    const findings = validateConfigPipeline(config, {
+      scripts: packageScripts(appRoot, readText),
+      registry: registry ?? loadGeneratorRegistry(),
+      appRoot,
+      containment,
+      readBytes,
+      lineOf: (pointer) => lineOfPointer(text, parsed.offsets, pointer),
+    });
+    if (findings.length) {
+      fail("RELEASE_CONFIG_M24", `${configPath} has ${findings.length} M24 pipeline finding(s); every command must be an admitted RightKit invocation:\n${formatFindings(findings, configPath).map((line) => `- ${line}`).join("\n")}`, { file: configPath, findings });
+    }
+  }
+  return {
+    config, configPath, appRoot, sha256,
+    inputs: [...inputs].map(([file, digest]) => ({ file, sha256: digest })),
+    lineOf: (pointer) => lineOfPointer(text, parsed.offsets, pointer),
+  };
+}
+
+/** The config object only (what `(await import(configPath)).default` used to be). */
+export async function loadReleaseConfig(file, options) {
+  return loadReleaseConfigSync(file, options).config;
+}
+
+/** `{ config, appRoot, configPath }` for the commands that need the app root beside the config. */
+export async function loadAppConfigFile(file = RELEASE_CONFIG_FILE, options) {
+  const loaded = loadReleaseConfigSync(file, options);
+  return { config: loaded.config, appRoot: loaded.appRoot, configPath: loaded.configPath };
+}
+
+export { collectConfigCommands };