@rightkit/release 0.4.0 → 0.5.0

package/pipeline-admission.mjs

@@ -0,0 +1,375 @@
+// M24 R1 (invocation admission) and the R2 hook-string rules.
+//
+// A command that a release config, a package alias or a framework hook asks RightKit to run is admitted only as one COMPLETE approved
+// invocation: an exact executable and an argument vector that matches a typed entry below. There is no shell, so there is nothing to
+// quote: an operator, an environment injection, a substitution or a chained second command in any string is refused outright, and
+// `pnpm exec` runs only an approved installed runtime. Aliases (`pnpm run x`, `pnpm x`) are followed through package.json with a
+// depth bound; a cycle, an unknown alias or any unadmitted step anywhere in the chain blocks the whole invocation. Caller strings and
+// process identity never establish "official" origin: a step carries no origin field (an unknown key is refused), and only the
+// executable and arguments are judged.
+//
+// Everything here is a pure function over the step and an optional `scripts` map; it reads no file and runs nothing. The scanner
+// (`pipeline-scan.mjs`) supplies the app's package.json scripts and the shared-generator registry.
+import path from "node:path";
+import { classifyTokens, commandBaseName } from "./pipeline-tools.mjs";
+
+export class PipelineAdmissionError extends Error {
+  constructor(code, message, findings = []) {
+    super(message);
+    this.name = "PipelineAdmissionError";
+    this.code = code;
+    this.findings = findings;
+  }
+}
+
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const refuse = (code, reason) => ({ admitted: false, code, reason });
+const admit = (id, via, extra = {}) => ({ admitted: true, id, via, ...extra });
+
+export const MAX_ALIAS_DEPTH = 8;
+export const MAX_COMMAND_TIMEOUT_MS = 6 * 60 * 60 * 1000;
+
+/** Keys a command step may carry. `env` and `nodeOptions` are environment injection; there is no `shell`, `origin` or `official` key. */
+export const STEP_ALLOWED_KEYS = Object.freeze(["cmd", "node", "args", "cwd", "timeoutMs", "name", "nodeFlags"]);
+const ENV_INJECTION_KEYS = new Set(["env", "nodeOptions", "envFile", "shell"]);
+
+/** Operators, redirects, substitutions and variable expansion: anything a shell or a script runner could re-interpret. */
+const SHELL_META = /[\0\r\n]|&&|\|\||[;|<>`]|\$\(|\$\{|\$[A-Za-z_]|%[A-Za-z_][A-Za-z0-9_]*%|\^\^/;
+export const hasShellMeta = (text) => SHELL_META.test(String(text));
+
+/** right-release subcommands a config may invoke (the CLI's own commands; unknown names are refused). */
+export const OWNER_SUBCOMMANDS = Object.freeze(new Set([
+  "release", "build", "package", "publish", "upload", "deps", "publish-update", "hardening", "harden", "hardeningscan", "sign-windows",
+  "sign-updater", "sign-dev-artifact", "sign-qa-bundle", "sign-candidate", "engine-locate", "stage-sidecar", "init", "pe", "icons", "recipe-build",
+  "signing-agent", "create-mac-updater", "mirror-root-artifact", "test", "web-build", "license-notices", "toolchain", "github",
+  "cargo-target", "qa", "ownership", "ownership-approval", "ownership-report", "ownership-mandatory", "adoption-evidence", "swift-package", "bundle-scan",
+  "check-release-dependencies", "dist-scan", "identity-scan", "apple-profile-create", "ios-credentials", "dev", "doctor", "hooks",
+  "suite-doctor", "cache", "disk", "install-app", "dmg", "apple", "inventory", "model", "addon", "lsclean", "generate-dmg-background",
+  "pipeline",
+]));
+
+/** right-release subcommands that start another pipeline run: a generator or a framework hook may never run one (R2, R4). */
+export const PIPELINE_DISPATCH_SUBCOMMANDS = Object.freeze(new Set([
+  "release", "build", "package", "publish", "upload", "publish-update", "github", "dev", "install-app", "recipe-build", "sign-windows",
+  "sign-updater", "sign-dev-artifact", "sign-candidate", "create-mac-updater", "swift-package", "dmg", "addon", "apple",
+]));
+
+const INTERPRETERS = new Set(["bash", "sh", "zsh", "dash", "fish", "ksh", "csh", "tcsh", "cmd", "powershell", "pwsh", "python", "python3", "py", "ruby", "perl", "php", "osascript", "wsl", "env", "sudo", "xargs", "wscript", "cscript", "deno", "bun"]);
+const PACKAGE_MANAGERS = new Set(["npm", "npx", "yarn", "corepack", "pnpx"]);
+const PNPM_BUILTINS = new Set(["add", "install", "i", "remove", "rm", "uninstall", "update", "up", "upgrade", "exec", "run", "run-script", "dlx", "publish", "pack", "rebuild", "store", "config", "link", "ln", "unlink", "list", "ls", "outdated", "audit", "why", "root", "bin", "create", "deploy", "patch", "patch-commit", "import", "init", "licenses", "prune", "fetch", "env", "setup", "self-update", "completion", "approve-builds", "dedupe", "doctor", "server", "cache", "recursive", "-r", "--filter", "-F", "--version", "-v", "--help", "-h"]);
+/** pnpm subcommands that run a package.json script of the same name. */
+const PNPM_SCRIPT_SHORTHANDS = new Set(["test", "t", "start", "stop", "restart"]);
+const CARGO_SUBCOMMANDS = new Set(["build", "check", "test", "clippy", "fmt", "metadata", "tree", "doc", "bench", "about", "fetch", "vendor"]);
+const NODE_FLAG = /^(?:--disable-warning=[A-Za-z0-9_-]+|--no-experimental-webstorage|--no-warnings|--max-old-space-size=\d{3,6})$/;
+const SAFE_VALUE = /^[A-Za-z0-9._:/@=+,#-]+$/;
+const TRIPLE = /^[A-Za-z0-9_]+(?:-[A-Za-z0-9_.]+){1,4}$/;
+const PROFILE = /^[a-z][a-z0-9_-]*$/;
+const LEGACY_CONFIG = /\.(?:[cm]?js|[cm]?ts)$/i;
+
+function relativeInside(value) {
+  if (typeof value !== "string" || !value.trim() || path.isAbsolute(value) || path.win32.isAbsolute(value) || /^[A-Za-z]:/.test(value)) return null;
+  const normalized = value.replaceAll("\\", "/").replace(/^(?:\.\/)+/, "");
+  return normalized.split("/").includes("..") || normalized === "" ? null : normalized;
+}
+
+/**
+ * Split one command line into tokens (quotes group, a backslash escapes outside single quotes). Returns `{ tokens }` or
+ * `{ error }`; an unquoted operator is an error, so a chained second command can never be hidden in the text.
+ */
+export function tokenizeCommandLine(text) {
+  const input = String(text);
+  if (/[\0\r\n]/.test(input)) return { error: "a command line may not contain a newline or NUL" };
+  const tokens = [];
+  let current = "";
+  let started = false;
+  let quote = null;
+  for (let i = 0; i < input.length; i += 1) {
+    const ch = input[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+      else if (ch === "\\" && quote === '"' && (input[i + 1] === '"' || input[i + 1] === "\\")) { current += input[i + 1]; i += 1; }
+      else current += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { quote = ch; started = true; continue; }
+    if (/\s/.test(ch)) { if (started) { tokens.push(current); current = ""; started = false; } continue; }
+    if (/[;|&<>`()]/.test(ch) || (ch === "$" && /[({A-Za-z_]/.test(input[i + 1] ?? ""))) return { error: `the operator or substitution "${ch}" is not allowed in an admitted command` };
+    current += ch;
+    started = true;
+  }
+  if (quote) return { error: "unterminated quote" };
+  if (started) tokens.push(current);
+  return { tokens };
+}
+
+function shellSafeArgs(args, label) {
+  const bad = args.find((arg) => hasShellMeta(arg));
+  return bad === undefined ? null : refuse("R1-operators", `${label}: argument ${JSON.stringify(bad)} contains an operator, substitution, environment reference or newline`);
+}
+
+/** Validate a step's shape and return `{ cmd, args, cwd }` (a `node` step becomes `cmd: "node"`), or a refusal. */
+export function normalizeStep(step) {
+  if (!isObject(step)) return refuse("R1-shape", "a command must be an object { cmd, args? }");
+  for (const key of Object.keys(step)) {
+    if (ENV_INJECTION_KEYS.has(key)) return refuse("R1-env-injection", `the "${key}" key injects environment or a shell and is not allowed in an admitted command`);
+    if (!STEP_ALLOWED_KEYS.includes(key)) return refuse("R1-shape", `unknown command key "${key}" (allowed: ${STEP_ALLOWED_KEYS.join(", ")}); a caller-supplied origin or identity is never accepted`);
+  }
+  if (step.cmd !== undefined && step.node !== undefined) return refuse("R1-shape", "a command sets both cmd and node");
+  const argList = step.args === undefined ? [] : step.args;
+  if (!Array.isArray(argList) || argList.some((arg) => typeof arg !== "string")) return refuse("R1-shape", "args must be a list of strings");
+  if (argList.some((arg) => /[\0\r\n]/.test(arg))) return refuse("R1-operators", "an argument contains a newline or NUL");
+  if (step.cwd !== undefined && relativeInside(step.cwd) === null) return refuse("R1-cwd", `cwd must be relative and stay inside the app: ${JSON.stringify(step.cwd)}`);
+  if (step.timeoutMs !== undefined && !(Number.isInteger(step.timeoutMs) && step.timeoutMs > 0 && step.timeoutMs <= MAX_COMMAND_TIMEOUT_MS)) return refuse("R1-shape", "timeoutMs must be a positive integer of at most six hours");
+  if (step.nodeFlags !== undefined && (!Array.isArray(step.nodeFlags) || step.nodeFlags.some((flag) => typeof flag !== "string" || !NODE_FLAG.test(flag)))) return refuse("R1-node-flags", "nodeFlags allow only --disable-warning=<id>, --no-experimental-webstorage, --no-warnings and --max-old-space-size=<n>");
+  if (step.node !== undefined) {
+    if (typeof step.node !== "string") return refuse("R1-shape", "node must be an app-relative script path");
+    return { cmd: "node", args: [...(step.nodeFlags ?? []), step.node, ...argList], cwd: step.cwd, nodeScript: true };
+  }
+  if (step.nodeFlags !== undefined) return refuse("R1-node-flags", "nodeFlags apply only to a node script step");
+  if (typeof step.cmd !== "string" || !step.cmd.trim()) return refuse("R1-shape", "cmd must be a non-empty string");
+  return { cmd: step.cmd, args: argList, cwd: step.cwd };
+}
+
+/** The approved installed runtimes a `pnpm exec` (or `node node_modules/...`) may start. */
+const flagTable = (spec) => (rest, label) => {
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    const flag = arg.includes("=") && arg.startsWith("--") ? arg.slice(0, arg.indexOf("=")) : arg;
+    const kind = spec[flag];
+    if (kind === undefined) return refuse("R1-option", `${label}: option ${JSON.stringify(arg)} is not an approved option`);
+    if (kind === "none") { if (arg !== flag) return refuse("R1-option", `${label}: ${flag} takes no value`); continue; }
+    const value = arg !== flag ? arg.slice(flag.length + 1) : rest[(i += 1)];
+    if (value === undefined) return refuse("R1-option", `${label}: ${flag} needs a value`);
+    if (kind === "value" && !SAFE_VALUE.test(value)) return refuse("R1-option", `${label}: ${flag} value ${JSON.stringify(value)} is not a plain token`);
+    if (kind === "triple" && !TRIPLE.test(value)) return refuse("R1-option", `${label}: ${flag} must name a target triple`);
+    if (kind === "profile" && !PROFILE.test(value)) return refuse("R1-option", `${label}: ${flag} must name a Cargo profile`);
+    if (kind === "path" && relativeInside(value) === null) return refuse("R1-option", `${label}: ${flag} must be a relative path inside the app`);
+    if (kind === "int" && !/^\d{1,3}$/.test(value)) return refuse("R1-option", `${label}: ${flag} must be a small integer`);
+  }
+  return null;
+};
+
+const TAURI_COMMANDS = new Set(["build", "bundle", "dev", "info"]);
+const TAURI_OPTIONS = flagTable({
+  "--target": "triple", "--bundles": "value", "--no-sign": "none", "--no-bundle": "none", "--ci": "none", "--verbose": "none", "-v": "none",
+  "--debug": "none", "-d": "none", "--features": "value", "--config": "config", "-c": "config",
+});
+const TAURI_PASSTHROUGH = flagTable({ "--profile": "profile", "--locked": "none", "--features": "value", "--no-default-features": "none", "--jobs": "int", "--frozen": "none", "--offline": "none" });
+
+/** `--config <json | path>`: an inline override may set only the typed keys below, and each hook inside it passes R2. */
+export function validateTauriConfigOverride(text, options = {}, label = "tauri --config") {
+  const value = String(text).trim();
+  if (!value.startsWith("{")) {
+    const normalized = relativeInside(value);
+    if (normalized === null || !/\.json$/i.test(normalized)) return refuse("R2-tauri-config", `${label} must be inline JSON or a relative .json file: ${JSON.stringify(value)}`);
+    return null;
+  }
+  let parsed;
+  try { parsed = JSON.parse(value); } catch { return refuse("R2-tauri-config", `${label} is not valid JSON`); }
+  if (!isObject(parsed)) return refuse("R2-tauri-config", `${label} must be a JSON object`);
+  for (const key of Object.keys(parsed)) if (key !== "build" && key !== "bundle") return refuse("R2-tauri-config", `${label}: top-level key "${key}" is not allowed (identity and bundle id belong to RightKit; allowed: build, bundle)`);
+  const build = parsed.build ?? {};
+  if (!isObject(build)) return refuse("R2-tauri-config", `${label}.build must be an object`);
+  for (const [key, entry] of Object.entries(build)) {
+    if (["beforeDevCommand", "beforeBuildCommand", "beforeBundleCommand"].includes(key)) {
+      const result = admitTauriHook(entry, options, `${label}.build.${key}`);
+      if (result) return result;
+    } else if (!["frontendDist", "devUrl"].includes(key)) return refuse("R2-tauri-config", `${label}.build.${key} is not allowed`);
+  }
+  const bundle = parsed.bundle ?? {};
+  if (!isObject(bundle)) return refuse("R2-tauri-config", `${label}.bundle must be an object`);
+  for (const [key, entry] of Object.entries(bundle)) {
+    if (key === "createUpdaterArtifacts") { if (typeof entry !== "boolean" && entry !== "v1Compatible") return refuse("R2-tauri-config", `${label}.bundle.createUpdaterArtifacts must be a boolean`); }
+    else if (key === "windows") { if (!isObject(entry) || Object.keys(entry).some((k) => k !== "signCommand" || entry[k] !== null)) return refuse("R3-tauri-sign-hook", `${label}.bundle.windows may only set signCommand to null: a sign hook is not allowed`); }
+    else if (key === "macOS") { if (!isObject(entry) || Object.keys(entry).some((k) => k !== "signingIdentity" || entry[k] !== "-")) return refuse("R3-tauri-sign-hook", `${label}.bundle.macOS may only set signingIdentity to "-" (ad hoc): signing belongs to RightKit`); }
+    else return refuse("R2-tauri-config", `${label}.bundle.${key} is not allowed`);
+  }
+  return null;
+}
+
+/** A Tauri `before*Command` value: a string or `{ script, cwd }`; one admitted command, no chain. */
+export function admitTauriHook(entry, options = {}, label = "tauri hook") {
+  const script = typeof entry === "string" ? entry : isObject(entry) && typeof entry.script === "string" ? entry.script : null;
+  if (script === null) return refuse("R2-tauri-hook", `${label} must be a command string or { script, cwd }`);
+  if (isObject(entry) && entry.cwd !== undefined && relativeInside(entry.cwd) === null) return refuse("R2-tauri-hook", `${label}.cwd must stay inside the app`);
+  if (script.trim() === "") return null;
+  const result = admitHookString(script, options);
+  return result.admitted ? null : refuse(result.code, `${label}: ${result.reason}`);
+}
+
+function admitTauri(rest, options, label) {
+  const sub = rest[0];
+  if (sub === "signer" || sub === "icon" || sub === "init" || sub === "add" || sub === "migrate") return refuse("R3-tauri-subcommand", `${label}: tauri ${sub} is not an admitted pipeline command`);
+  if (!TAURI_COMMANDS.has(sub) && sub !== "--version" && sub !== "-V") return refuse("R1-option", `${label}: tauri subcommand ${JSON.stringify(sub)} is not admitted`);
+  if (sub === "--version" || sub === "-V") return rest.length === 1 ? admit("tauri-version", "runtime") : refuse("R1-option", `${label}: --version takes no further arguments`);
+  const dash = rest.indexOf("--");
+  const own = dash >= 0 ? rest.slice(1, dash) : rest.slice(1);
+  const pass = dash >= 0 ? rest.slice(dash + 1) : [];
+  // `--config` values carry JSON that the generic flag table cannot judge: validate them here, then check the remaining flags.
+  const plain = [];
+  for (let i = 0; i < own.length; i += 1) {
+    if (own[i] === "--config" || own[i] === "-c" || own[i].startsWith("--config=")) {
+      const value = own[i].startsWith("--config=") ? own[i].slice("--config=".length) : own[(i += 1)];
+      if (value === undefined) return refuse("R1-option", `${label}: --config needs a value`);
+      const problem = validateTauriConfigOverride(value, options, `${label} --config`);
+      if (problem) return problem;
+    } else plain.push(own[i]);
+  }
+  const problem = TAURI_OPTIONS(plain.map((arg) => arg), label);
+  if (problem) return problem;
+  const passProblem = TAURI_PASSTHROUGH(pass, `${label} --`);
+  if (passProblem) return passProblem;
+  return admit(`tauri-${sub}`, "runtime");
+}
+
+const VITE_OPTIONS = flagTable({ "--config": "path", "-c": "path", "--outDir": "path", "--base": "value", "--emptyOutDir": "none" });
+
+/** `pnpm exec <bin>` and `node node_modules/...` runtimes. */
+function admitRuntime(bin, rest, options, label) {
+  switch (bin) {
+    case "right-release": return admitRightRelease(rest, label);
+    case "tauri": return admitTauri(rest, options, label);
+    case "vite": return rest[0] === "build" ? (VITE_OPTIONS(rest.slice(1), label) ?? admit("vite-build", "runtime")) : rest.length === 1 && rest[0] === "--version" ? admit("vite-version", "runtime") : refuse("R1-option", `${label}: only vite build and vite --version are admitted`);
+    case "tsc": return shellSafeArgs(rest, label) ?? admit("tsc", "runtime");
+    case "vitest": return rest[0] === "run" || (rest.length === 1 && rest[0] === "--version") ? (shellSafeArgs(rest, label) ?? admit("vitest", "runtime")) : refuse("R1-option", `${label}: only vitest run is admitted`);
+    case "eslint": return shellSafeArgs(rest, label) ?? admit("eslint", "runtime");
+    default: return refuse("R1-runtime", `${label}: "${bin}" is not an approved installed runtime for pnpm exec`);
+  }
+}
+
+function admitRightRelease(args, label) {
+  const sub = args[0];
+  if (!OWNER_SUBCOMMANDS.has(sub)) return refuse("R1-owner-subcommand", `${label}: right-release ${JSON.stringify(sub ?? "")} is not a known RightKit command`);
+  const meta = shellSafeArgs(args, label);
+  if (meta) return meta;
+  for (let i = 1; i < args.length; i += 1) {
+    const value = args[i] === "--config" ? args[i + 1] : args[i].startsWith("--config=") ? args[i].slice("--config=".length) : null;
+    if (value !== null && value !== undefined && LEGACY_CONFIG.test(value)) return refuse("R1-legacy-config", `${label}: ${value} is a legacy executable config; RightKit reads only right-release.config.json`);
+  }
+  return admit(`right-release-${sub}`, "owner");
+}
+
+const NODE_MODULE_ENTRIES = Object.freeze({
+  "node_modules/typescript/bin/tsc": "tsc",
+  "node_modules/typescript/lib/tsc.js": "tsc",
+  "node_modules/vite/bin/vite.js": "vite",
+  "node_modules/vitest/vitest.mjs": "vitest",
+  "node_modules/@tauri-apps/cli/tauri.js": "tauri",
+  "node_modules/@rightkit/release/cli/right-release.mjs": "right-release",
+});
+
+function admitNode(args, options, label) {
+  let index = 0;
+  while (index < args.length && args[index].startsWith("-")) {
+    if (!NODE_FLAG.test(args[index])) return refuse("R1-interpreter", `${label}: node option ${JSON.stringify(args[index])} is not admitted (no -e, --eval, --import or --require)`);
+    index += 1;
+  }
+  const script = relativeInside(args[index]);
+  if (script === null) return refuse("R1-interpreter", `${label}: node needs a script path inside the app`);
+  const rest = args.slice(index + 1);
+  const runtime = NODE_MODULE_ENTRIES[script];
+  if (runtime) return admitRuntime(runtime, rest, options, label);
+  const generator = options.admitGenerator?.({ script, args: rest, cwd: options.cwd });
+  if (generator?.admitted) return admit(generator.id, "generator", { generator: generator.id });
+  return refuse(generator?.code ?? "R4-unregistered-generator", `${label}: ${script} is app code, not an admitted shared generator${generator?.reason ? ` (${generator.reason})` : ""}`);
+}
+
+const PNPM_INSTALL_FLAGS = new Set(["--frozen-lockfile", "--ignore-scripts", "--prefer-offline", "--offline"]);
+
+function admitPnpm(args, options, label, chain) {
+  const sub = args[0];
+  if (sub === undefined) return refuse("R1-pnpm", `${label}: pnpm needs a subcommand`);
+  if (sub === "exec") {
+    const bin = args[1];
+    if (bin === undefined || bin.startsWith("-")) return refuse("R1-pnpm-exec", `${label}: pnpm exec needs an installed runtime name first (no shell mode or option before it)`);
+    return admitRuntime(bin, args.slice(2), options, `${label} exec ${bin}`);
+  }
+  if (sub === "install" || sub === "i") {
+    const flags = args.slice(1);
+    if (flags.some((flag) => !PNPM_INSTALL_FLAGS.has(flag)) || !flags.includes("--frozen-lockfile")) return refuse("R1-pnpm", `${label}: pnpm install is admitted only as install --frozen-lockfile [--ignore-scripts]`);
+    return admit("pnpm-install", "runtime");
+  }
+  if (sub === "run" || sub === "run-script") {
+    const name = args[1];
+    if (name === undefined || name.startsWith("-")) return refuse("R1-pnpm", `${label}: pnpm run needs a script name first`);
+    const meta = shellSafeArgs(args.slice(2), label);
+    if (meta) return meta;
+    return admitAlias(name, options, chain);
+  }
+  if (PNPM_SCRIPT_SHORTHANDS.has(sub)) {
+    const meta = shellSafeArgs(args.slice(1), label);
+    return meta ?? admitAlias(sub === "t" ? "test" : sub, options, chain);
+  }
+  if (PNPM_BUILTINS.has(sub)) return refuse("R1-pnpm", `${label}: pnpm ${sub} is not an admitted pipeline command`);
+  const meta = shellSafeArgs(args.slice(1), label);
+  return meta ?? admitAlias(sub, options, chain);
+}
+
+/** Follow a package.json alias (and its pre/post hooks): every step must be admitted; a cycle or an unknown name blocks. */
+export function admitAlias(name, options = {}, chain = []) {
+  const scripts = options.scripts;
+  if (!isObject(scripts)) return refuse("R1-alias-unresolved", `package script "${name}" cannot be resolved (no package.json scripts were supplied); an unknown reachable owner blocks`);
+  if (chain.includes(name)) return refuse("R1-alias-cycle", `package script alias cycle: ${[...chain, name].join(" -> ")}`);
+  if (chain.length >= MAX_ALIAS_DEPTH) return refuse("R1-alias-depth", `package script alias chain deeper than ${MAX_ALIAS_DEPTH}: ${[...chain, name].join(" -> ")}`);
+  if (typeof scripts[name] !== "string") return refuse("R1-alias-unknown", `package script "${name}" does not exist`);
+  const next = [...chain, name];
+  for (const hook of [`pre${name}`, name, `post${name}`]) {
+    if (scripts[hook] === undefined) continue;
+    if (typeof scripts[hook] !== "string") return refuse("R1-alias-unknown", `package script "${hook}" is not a string`);
+    // The hook name joins the chain so `prebuild: pnpm run build` is a cycle, not an unbounded descent.
+    const result = admitHookString(scripts[hook], options, hook === name ? next : [...next, hook]);
+    if (!result.admitted) return refuse(result.code, `script "${hook}": ${result.reason}`);
+  }
+  return admit(`alias:${name}`, "alias", { chain: next });
+}
+
+/** One command line (a package script, a Tauri hook, a workflow step, an Xcode phase): a single admitted command, no chain. */
+export function admitHookString(text, options = {}, chain = []) {
+  const tokenized = tokenizeCommandLine(text);
+  if (tokenized.error) return refuse("R1-operators", tokenized.error);
+  if (!tokenized.tokens.length) return refuse("R1-shape", "an empty command line");
+  const [cmd, ...args] = tokenized.tokens;
+  return admitInvocation({ cmd, args }, { ...options, aliasChain: chain });
+}
+
+/**
+ * R1: is this one step an approved invocation? Returns `{ admitted: true, id, via }` or `{ admitted: false, code, reason }`.
+ * `options`: `scripts` (package.json scripts, for alias traversal), `stage` (reported only), `label` (message prefix),
+ * `admitGenerator({ script, args, cwd })` (the shared-generator registry check; absent means no generator is admitted).
+ */
+export function admitInvocation(step, options = {}) {
+  const label = options.label ?? "command";
+  const normalized = normalizeStep(step);
+  if (normalized.admitted === false) return normalized;
+  const { cmd, args, cwd } = normalized;
+  const chain = options.aliasChain ?? [];
+  if (/^\.[\\/]gradlew(?:\.bat)?$/i.test(cmd)) return admitGradle(args, options, label);
+  if (!/^[A-Za-z0-9._@+-]+$/.test(cmd)) return refuse("R1-executable", `${label}: executable ${JSON.stringify(cmd)} must be a bare name (a path, a space or an operator makes it app-owned code)`);
+  const name = commandBaseName(cmd);
+  const inner = { ...options, cwd };
+  const tool = classifyTokens([name, ...args]);
+  if (tool) return refuse("R3-pipeline-tool", `${label}: ${tool.tool} is a ${tool.stage} tool; build, sign, notarize, package and upload run only inside RightKit`);
+  if (name === "right-release") return admitRightRelease(args, label);
+  if (name === "pnpm") return admitPnpm(args, inner, label, chain);
+  if (name === "node") return admitNode(args, inner, label);
+  if (name === "rightkit") {
+    if (args[0] !== "cargo" || !CARGO_SUBCOMMANDS.has(args[1])) return refuse("R1-managed-client", `${label}: only rightkit cargo ${[...CARGO_SUBCOMMANDS].join("|")} is admitted`);
+    return shellSafeArgs(args, label) ?? admit(`rightkit-cargo-${args[1]}`, "managed-cargo");
+  }
+  if (name === "cargo" || name === "rustc" || name === "rustdoc") return refuse("R1-bare-cargo", `${label}: run Cargo through the managed client (rightkit cargo ...), never bare ${name}`);
+  if (name === "tauri") return refuse("R1-direct-tauri", `${label}: run the Tauri CLI as pnpm exec tauri ..., or through right-release; a bare tauri is not an approved installed runtime`);
+  if (PACKAGE_MANAGERS.has(name)) return refuse("R1-package-manager", `${label}: ${name} is not allowed; the workspace uses pnpm`);
+  if (INTERPRETERS.has(name)) return refuse("R1-interpreter", `${label}: ${name} runs script text or a script file the app owns; only an admitted shared generator may do that`);
+  return refuse("R1-unknown-executable", `${label}: ${JSON.stringify(cmd)} is not an admitted RightKit step; unknown pipeline ownership blocks`);
+}
+
+const GRADLE_ARG = /^(?::?[A-Za-z][A-Za-z0-9:_-]*|--(?:no-daemon|stacktrace|offline|no-build-cache|warning-mode=(?:all|summary|none|fail)|console=plain)|-P[A-Za-z][A-Za-z0-9._]*=[A-Za-z0-9._:/-]+)$/;
+function admitGradle(args, options, label) {
+  const stage = options.stage ?? "";
+  if (!["android-build", "dev-build"].includes(stage)) return refuse("R1-executable", `${label}: ./gradlew is admitted only as the Android build (targets.android.gradle) or an Android dev build`);
+  if (!args.length || args.some((arg) => !GRADLE_ARG.test(arg))) return refuse("R1-option", `${label}: gradle arguments must be plain tasks and approved flags`);
+  const task = args.find((arg) => !arg.startsWith("-"));
+  if (!task) return refuse("R1-option", `${label}: gradle needs a task`);
+  if (/(?<![A-Za-z])(?:publish|upload|sign)(?![a-z])/.test(args.filter((arg) => !arg.startsWith("-")).join(" "))) return refuse("R3-pipeline-tool", `${label}: a gradle publish, upload or sign task is a release effect that belongs to RightKit`);
+  return admit("gradle-build", "runtime");
+}

package/pipeline-config.mjs

@@ -0,0 +1,100 @@
+// M24: every command a release config hands to RightKit is judged here, before anything runs.
+//
+// A release config is data. The places where it can name an executable are the dev build and install commands, the package, signing
+// and publish hooks, the recipe `prepare` / `postBuild` lists, the native assembly hooks, the sidecar `command` entries and the web
+// build steps. `collectConfigCommands` finds every object that carries `cmd` or `node` under those roots (so a command hidden in a
+// new key is still seen), and `validateConfigPipeline` runs R1 admission on each one (R2 inside Tauri `--config` overrides, R4 for a
+// `node` generator). Each finding names its JSON pointer, its line in the config file, its pipeline stage and who owns the step.
+// `tests` and `qa` are not pipeline commands (M20, M21) and are not walked.
+import { admitHookString, admitInvocation } from "./pipeline-admission.mjs";
+import { makeGeneratorAdmitter } from "./pipeline-generators.mjs";
+
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const escapePointer = (key) => String(key).replaceAll("~", "~0").replaceAll("/", "~1");
+
+/** Config roots that can carry a command. Everything else (checks, buildInputs, legal, distribution, qa, tests) is typed data. */
+export const PIPELINE_CONFIG_ROOTS = Object.freeze(["development", "targets", "nativeAssembly", "sidecars", "web"]);
+/** The only keys of a command object that can change what runs; every other key on the node is typed host metadata. */
+const COMMAND_KEYS = ["cmd", "node", "args", "cwd", "timeoutMs", "nodeFlags", "env", "nodeOptions", "envFile", "shell"];
+
+/** The pipeline stage a command pointer belongs to. */
+export function stageOfPointer(pointer) {
+  const parts = pointer.split("/").slice(1);
+  if (parts[0] === "development") {
+    if (parts[3] === "install") return "dev-install";
+    return "dev-build";
+  }
+  if (parts[0] === "targets") {
+    if (parts[2] === "gradle") return "android-build";
+    if (["winPackage", "macPackage", "iosPackage"].includes(parts[2])) return "recipe-prepare";
+    const hook = parts[2];
+    if (hook === "prePackage") return "build";
+    if (hook === "package") return "package";
+    if (hook === "postSign") return "post-sign";
+    if (hook === "publish" || hook === "upload") return "publish";
+    return "build";
+  }
+  if (parts[0] === "nativeAssembly") return "native-assembly";
+  if (parts[0] === "sidecars") return "sidecar-stage";
+  if (parts[0] === "web") return "web-build";
+  return "pipeline";
+}
+
+/** Every command node under the pipeline roots: `[{ pointer, stage, step }]`, plus string-form hooks (`nativeAssembly.finalizer`). */
+export function collectConfigCommands(config) {
+  const found = [];
+  const visit = (node, pointer, depth) => {
+    if (depth > 32) return;
+    if (Array.isArray(node)) { node.forEach((item, index) => visit(item, `${pointer}/${index}`, depth + 1)); return; }
+    if (!isObject(node)) return;
+    if (typeof node.cmd === "string" || typeof node.node === "string") {
+      const step = {};
+      for (const key of COMMAND_KEYS) if (key in node) step[key] = node[key];
+      found.push({ pointer, stage: stageOfPointer(pointer), step });
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (key === "args" || key === "nodeFlags" || key === "env") continue;
+      visit(value, `${pointer}/${escapePointer(key)}`, depth + 1);
+    }
+  };
+  for (const root of PIPELINE_CONFIG_ROOTS) if (config?.[root] !== undefined) visit(config[root], `/${root}`, 0);
+  if (typeof config?.nativeAssembly?.finalizer === "string") found.push({ pointer: "/nativeAssembly/finalizer", stage: "native-assembly", string: config.nativeAssembly.finalizer });
+  return found;
+}
+
+const UNKNOWN_CODE = /(?:unknown|unresolved|cycle|depth|unregistered|containment)/;
+/** Who owns a refused step: `unknown` when ownership could not be established (it blocks), else the app that wrote it. */
+export const ownershipOfCode = (code) => (UNKNOWN_CODE.test(code) ? "unknown" : "app-owned");
+export const ruleOfCode = (code) => String(code).split("-")[0];
+
+/**
+ * Judge every command in a release config. `options`: `scripts` (the app's package.json scripts), `registry` + `appRoot` (the shared
+ * generator registry for a `node` step), `lineOf(pointer)` (config line numbers), `containment`, `readBytes`, `readText` (injectable).
+ * Returns the findings; an empty list means every command is an admitted RightKit invocation.
+ */
+export function validateConfigPipeline(config, options = {}) {
+  const findings = [];
+  const app = typeof config?.app === "string" ? config.app : "";
+  const admitGenerator = options.registry && options.appRoot
+    ? makeGeneratorAdmitter({ registry: options.registry, app, appRoot: options.appRoot, ...(options.containment ? { containment: options.containment } : {}), ...(options.readBytes ? { readBytes: options.readBytes } : {}), ...(options.readText ? { readText: options.readText } : {}) })
+    : undefined;
+  for (const entry of collectConfigCommands(config)) {
+    const common = { scripts: options.scripts, stage: entry.stage, label: entry.pointer, admitGenerator };
+    const result = entry.string !== undefined ? admitHookString(entry.string, common) : admitInvocation(entry.step, common);
+    if (result.admitted) continue;
+    findings.push({
+      rule: ruleOfCode(result.code),
+      code: result.code,
+      pointer: entry.pointer,
+      line: options.lineOf ? options.lineOf(entry.pointer) : 1,
+      stage: entry.stage,
+      ownership: ownershipOfCode(result.code),
+      message: result.reason,
+    });
+  }
+  return findings;
+}
+
+export function formatFindings(findings, file = "right-release.config.json") {
+  return findings.map((finding) => `${file}:${finding.line} [${finding.code}] ${finding.stage} (${finding.ownership}) ${finding.pointer}: ${finding.message}`);
+}

package/pipeline-generators.json

@@ -0,0 +1,4 @@
+{
+  "schema": 1,
+  "generators": []
+}

package/pipeline-generators.mjs

@@ -0,0 +1,137 @@
+// M24 R4: the typed shared-generator registry.
+//
+// Product-source generation (an icon pass, a schema codegen, an engine stage) may sit inside a pipeline only as an explicitly admitted
+// shared step. Each registry entry binds one generator to its script, its executable dependency closure (every file the script loads),
+// its interpreter, its exact argument vector and its I/O limits, by sha256. An app cannot register one: the registry is a RightKit file
+// (`pipeline-generators.json`), so a new capability is a RightKit change. An admitted generator can reach no network and perform no
+// signing, installation or upload; the registry refuses an entry that claims otherwise, and the static check below refuses a
+// generator source that names a pipeline tool or dispatches RightKit again (a generator may never start another pipeline).
+//
+// Static review is NOT a sandbox. The process, network and output limits are enforced by native containment, which this package does
+// not yet implement for any platform: `detectContainment` reports it unsupported, and an unsupported containment REFUSES the
+// generator (the target stays unqualified) instead of running it unconfined. Callers inject a real containment to admit one.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { dispatchesRightKit, scanTextForPipelineTools, segmentTokens, splitSegments } from "./pipeline-tools.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const GENERATOR_REGISTRY_FILE = "pipeline-generators.json";
+export const GENERATOR_INTERPRETERS = Object.freeze(["node"]);
+const SHA256 = /^[0-9a-f]{64}$/;
+const ID = /^[a-z][a-z0-9-]{1,63}$/;
+const APP = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const ENTRY_KEYS = ["id", "app", "interpreter", "script", "scriptSha256", "args", "closure", "inputs", "outputs", "limits", "network"];
+const LIMIT_KEYS = ["maxOutputBytes", "maxProcesses", "timeoutMs"];
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+export class GeneratorRegistryError extends Error {
+  constructor(message) { super(message); this.name = "GeneratorRegistryError"; this.code = "RK_GENERATOR_REGISTRY"; }
+}
+const bad = (message) => { throw new GeneratorRegistryError(message); };
+
+function relativePath(value, label) {
+  if (typeof value !== "string" || !value.trim() || path.isAbsolute(value) || path.win32.isAbsolute(value) || /^[A-Za-z]:/.test(value) || value.includes("\\")) bad(`${label} must be a forward-slash relative path`);
+  const parts = value.replace(/^(?:\.\/)+/, "").split("/");
+  if (parts.includes("..") || parts.includes("") || parts.includes(".")) bad(`${label} must stay inside the app: ${value}`);
+  return parts.join("/");
+}
+
+/** Validate one registry entry; returns the normalised entry. */
+export function validateGeneratorEntry(entry, label = "generator") {
+  if (!isObject(entry)) bad(`${label} must be an object`);
+  const unknown = Object.keys(entry).filter((key) => !ENTRY_KEYS.includes(key));
+  if (unknown.length) bad(`${label} has unknown key(s): ${unknown.join(", ")}`);
+  if (typeof entry.id !== "string" || !ID.test(entry.id)) bad(`${label}.id must be a lowercase id`);
+  if (typeof entry.app !== "string" || !APP.test(entry.app)) bad(`${label}.app must name the registered app`);
+  if (!GENERATOR_INTERPRETERS.includes(entry.interpreter)) bad(`${label}.interpreter must be one of ${GENERATOR_INTERPRETERS.join(", ")}`);
+  const script = relativePath(entry.script, `${label}.script`);
+  if (typeof entry.scriptSha256 !== "string" || !SHA256.test(entry.scriptSha256)) bad(`${label}.scriptSha256 must be a lowercase sha256`);
+  if (!Array.isArray(entry.args) || entry.args.some((arg) => typeof arg !== "string" || /[\0\r\n]/.test(arg))) bad(`${label}.args must be the exact argument vector (a list of strings)`);
+  if (!Array.isArray(entry.closure)) bad(`${label}.closure must list every executable dependency of the script (an empty list for none)`);
+  const closure = entry.closure.map((item, index) => {
+    if (!isObject(item) || Object.keys(item).some((key) => key !== "path" && key !== "sha256")) bad(`${label}.closure[${index}] must be { path, sha256 }`);
+    if (typeof item.sha256 !== "string" || !SHA256.test(item.sha256)) bad(`${label}.closure[${index}].sha256 must be a lowercase sha256`);
+    return { path: relativePath(item.path, `${label}.closure[${index}].path`), sha256: item.sha256 };
+  });
+  for (const key of ["inputs", "outputs"]) {
+    if (!Array.isArray(entry[key]) || entry[key].length === 0) bad(`${label}.${key} must be a non-empty list of app-relative globs (the I/O limit)`);
+    for (const [index, glob] of entry[key].entries()) {
+      if (typeof glob !== "string" || glob.includes("..") || path.isAbsolute(glob) || /^[A-Za-z]:/.test(glob) || glob.includes("\\")) bad(`${label}.${key}[${index}] must be an app-relative forward-slash glob`);
+    }
+  }
+  if (!isObject(entry.limits) || Object.keys(entry.limits).some((key) => !LIMIT_KEYS.includes(key))) bad(`${label}.limits must be an object with ${LIMIT_KEYS.join(", ")}`);
+  for (const key of LIMIT_KEYS) if (!Number.isInteger(entry.limits[key]) || entry.limits[key] <= 0) bad(`${label}.limits.${key} must be a positive integer`);
+  if (entry.network !== false) bad(`${label}.network must be false: an admitted generator reaches no network, and cannot sign, install or upload`);
+  return { ...entry, script, closure, args: [...entry.args], inputs: [...entry.inputs], outputs: [...entry.outputs] };
+}
+
+/** Load and validate the registry. A missing or malformed file throws: the shipped registry always exists (empty means no generator is admitted). */
+export function loadGeneratorRegistry(file = path.join(here, GENERATOR_REGISTRY_FILE), { readText = (target) => readFileSync(target, "utf8") } = {}) {
+  let parsed;
+  try { parsed = JSON.parse(readText(file)); } catch (error) { bad(`the generator registry ${file} cannot be read: ${error.message}`); }
+  if (!isObject(parsed) || parsed.schema !== 1 || !Array.isArray(parsed.generators)) bad(`${file} must be { schema: 1, generators: [...] }`);
+  const seen = new Set();
+  const generators = parsed.generators.map((entry, index) => {
+    const valid = validateGeneratorEntry(entry, `generators[${index}]`);
+    if (seen.has(valid.id)) bad(`generators[${index}] repeats the id ${valid.id}`);
+    seen.add(valid.id);
+    return valid;
+  });
+  return { schema: 1, generators };
+}
+
+/** Native containment for a generator (no network, bounded output and processes). None is implemented yet: report it, never fake it. */
+export function detectContainment({ platform = process.platform } = {}) {
+  return { supported: false, mechanism: null, reason: `no native containment (network-, output- and process-restricted) is implemented for ${platform}; the generator is refused and the target stays unqualified` };
+}
+
+const sha256File = (file, readBytes) => createHash("sha256").update(readBytes(file)).digest("hex");
+
+/** Static refusals on a generator file's text: a pipeline tool, or RightKit dispatched again. */
+export function generatorSourceProblems(text, label) {
+  const problems = [];
+  for (const hit of scanTextForPipelineTools(text, { kind: "code" })) problems.push(`${label}:${hit.line} runs ${hit.tool} (${hit.stage}); a generator cannot sign, install or upload`);
+  for (const [index, line] of String(text).split(/\r?\n/).entries()) {
+    for (const literal of line.matchAll(/["'`]([^"'`\n]{1,200})["'`]/g)) {
+      const tokens = segmentTokens(splitSegments(literal[1])[0] ?? "");
+      if (tokens.length && dispatchesRightKit(tokens)) problems.push(`${label}:${index + 1} dispatches RightKit; a generator cannot start another pipeline`);
+    }
+  }
+  return problems;
+}
+
+/**
+ * Is `node <script> <args...>` an admitted generator for `app`? Returns `{ admitted: true, id }` or `{ admitted: false, code, reason }`.
+ * Revalidates the files at the moment of the call (a hash recorded earlier is not enough). All file access and the containment
+ * probe are injectable.
+ */
+export function admitGeneratorScript({ registry, app, appRoot, script, args = [], containment = detectContainment, readBytes = (file) => readFileSync(file), readText = (file) => readFileSync(file, "utf8") }) {
+  const refuse = (code, reason) => ({ admitted: false, code, reason });
+  const entries = (registry?.generators ?? []).filter((entry) => entry.app === app && entry.script === script);
+  if (entries.length === 0) return refuse("R4-unregistered-generator", `no registered generator for ${app} runs ${script}; apps cannot self-register, a new generator is a RightKit change`);
+  const entry = entries.find((candidate) => candidate.args.length === args.length && candidate.args.every((arg, index) => arg === args[index]));
+  if (!entry) return refuse("R4-arguments", `${script}: the argument vector differs from the registered one; only the exact registered arguments are admitted`);
+  const contained = containment();
+  if (!contained?.supported) return refuse("R4-containment-unsupported", contained?.reason ?? "native containment is not available");
+  const files = [{ path: entry.script, sha256: entry.scriptSha256 }, ...entry.closure];
+  for (const file of files) {
+    const absolute = path.resolve(appRoot, file.path);
+    let digest;
+    try { digest = sha256File(absolute, readBytes); } catch { return refuse("R4-missing-file", `${file.path} (registered for ${entry.id}) cannot be read`); }
+    if (digest !== file.sha256) return refuse("R4-digest-mismatch", `${file.path} does not match the registered digest for ${entry.id}; the generator changed after review`);
+    if (/\.(?:[cm]?js|ts)$/i.test(file.path)) {
+      let text;
+      try { text = readText(absolute); } catch { return refuse("R4-missing-file", `${file.path} cannot be read`); }
+      const problems = generatorSourceProblems(text, file.path);
+      if (problems.length) return refuse("R4-forbidden-effect", problems.join("; "));
+    }
+  }
+  return { admitted: true, id: entry.id, interpreter: entry.interpreter, limits: entry.limits, containment: contained.mechanism };
+}
+
+/** The `admitGenerator` option for `admitInvocation`, bound to one app. */
+export function makeGeneratorAdmitter({ registry, app, appRoot, ...injected }) {
+  return ({ script, args }) => admitGeneratorScript({ registry, app, appRoot, script, args, ...injected });
+}