@rightkit/release 0.6.16 → 0.6.20

package/test-command.mjs

@@ -30,6 +30,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { spawn } from "./background-process.mjs";
 import { carriedCargoMapOf, carriedLedgerIds, carriedOutputDirsSince } from "./carried-cargo.mjs";
+import { GATE_TARGET_DIRS_ENV } from "./qa-layout.mjs";
 import { CommandSpecError, loadAppConfig, resolveInvocation, validateStep } from "./command-spec.mjs";
 import { defaultReleaseConfigFile } from "./release-config.mjs";
 import { fsListRustFiles } from "./signing-files.mjs";
@@ -167,6 +168,11 @@ export function planTests(config, { suites = [], runner, passthrough = [], appRo
 }
 
 /** The refusal code of a planned `rightkit-qa journeys run` suite (GB-79). */
+/** RIGHTKIT_GATE_TARGET_DIRS: the absolute directories the gate pinned; none when unset or malformed. */
+function directOutputDirs(env) {
+  try { const dirs = JSON.parse(env[GATE_TARGET_DIRS_ENV] ?? "[]"); return Array.isArray(dirs) ? dirs.filter((d) => typeof d === "string" && path.isAbsolute(d)) : []; } catch { return []; }
+}
+
 export const QA_JOURNEYS_UNSUPPORTED = "RK_QA_JOURNEYS_PREBUILT_UNSUPPORTED";
 /** True when a suite step is `rightkit-qa journeys run ...` (by command or by node script name, extra args included). */
 export function qaJourneysRunStep(step, extraArgs = []) {
@@ -187,8 +193,10 @@ export function eventPrefix(config) {
  * Resolves `{ exitCode, results: [{ suite, exitCode, durationMs, skipped?, reason?, error? }] }`; a signal (cancellation) rejects.
  * A `sign` step (suite-signing.mjs) runs IN THIS PROCESS, never through `door` (it is no command and never a broker job); it signs what an earlier
  * suite built, named by that suite's verified carried receipts, and only a success sets RIGHTKIT_QA_APP_BINARY for the suites after it.
+ * On a direct host (no carrier) a suite's outputs are the Cargo output directories the gate pinned for the stage (RIGHTKIT_GATE_TARGET_DIRS).
+ * `within({ outputs, env })`, when given, runs once every suite passed and before the signed copies are removed; its result is returned as `within`.
  */
-export async function runSuites(plan, { appRoot, prefix = "test", env = process.env, spawnFn = spawn, log = console.log, errLog = console.error, door = buildLaunch, config = null, platform = process.platform, signDeps = {}, signStep = runSignStep, snapshotStage = Boolean(carriedCargoMapOf(env)?.map), qaCapability = (qa) => qaPrebuiltCapability(qa, { env }) } = {}) {
+export async function runSuites(plan, { appRoot, prefix = "test", env = process.env, spawnFn = spawn, log = console.log, errLog = console.error, door = buildLaunch, config = null, platform = process.platform, signDeps = {}, signStep = runSignStep, within = null, snapshotStage = Boolean(carriedCargoMapOf(env)?.map), qaCapability = (qa) => qaPrebuiltCapability(qa, { env }) } = {}) {
   const results = [];
   // One signing policy, enforced here whatever the config's format (the route probe reads JSON configs only; a legacy .mjs config is judged now): an
   // unsigned or ad hoc product build, or an identifier override, is refused before any suite runs (rightkit#1303). Mac and Dell only.
@@ -294,14 +302,16 @@ export async function runSuites(plan, { appRoot, prefix = "test", env = process.
       const durationMs = Date.now() - started;
       // Only a suite that passed hands its receipts to a sign step.
       if (exitCode === 0) {
-        const dirs = carriedOutputDirsSince(env, before);
+        const dirs = carriedCargoMapOf(env)?.map ? carriedOutputDirsSince(env, before) : directOutputDirs(env);
         for (const key of new Set([item.name, item.group])) outputs.set(key, [...new Set([...(outputs.get(key) ?? []), ...dirs])]);
       }
       log(JSON.stringify({ event: `${prefix}_suite_completed`, suite: item.name, exitCode, durationMs }));
       results.push({ suite: item.name, exitCode, durationMs, ...(failure ? { error: String(failure.message ?? failure) } : {}) });
       record(item, exitCode === 0 ? "passed" : "failed");
     }
-    return { exitCode: results.some((r) => r.skipped !== true && r.exitCode !== 0) || results.some((r) => r.skipped) ? firstFailure() : 0, results };
+    const exitCode = results.some((r) => r.skipped !== true && r.exitCode !== 0) || results.some((r) => r.skipped) ? firstFailure() : 0;
+    if (exitCode !== 0 || !within) return { exitCode, results };
+    return { exitCode, results, within: await within({ outputs, env: suiteEnv }) };
   } finally {
     // The signed copies live only as long as the run that signed them.
     for (const dir of signedDirs) { try { rmSync(dir, { recursive: true, force: true }); } catch { /* the managed root is pruned */ } }

package/tool-build.mjs

@@ -0,0 +1,156 @@
+// The gate's tool route: `rightkit-gate --to tool --unit cargo:rightkit-qa [--no-broker <exception-id>]`.
+//
+// Release QA runs only an ENROLLED rightkit-qa runner of the exact version an app's `qa.version` names (qa-runner.mjs). The unit stages cannot
+// make that binary: `--to compile|package --unit cargo:rightkit-qa` runs the unit's test plan and packs a .crate, and refuses a version that is
+// already on crates.io (local-publish.mjs); `cargo install` is denied (cargo-shapes.mjs). This route is the one sanctioned way to produce it:
+//
+//   1. the unit's class A check (the compile tier), exactly as a unit stage runs it;
+//   2. `cargo build --release --locked --bin <bin>` in the unit's own Cargo workspace of the selected commit's snapshot, through the same executor,
+//      cargo wrapper or carrier and target-directory binding as every other unit compile (unit-gate.mjs / bindUnitCargo). There is NO registry-version
+//      check: a tool build of a published version is the point of it, and it publishes nothing;
+//   3. the produced binary is enrolled (qa-runner.mjs `enrollQaRunner`): version = the crate's COMMITTED version, answered by the binary's own
+//      `--version`, a COPY recorded with its sha256 under the managed data root. The enrolled path and sha256 are printed so the owner can add the
+//      admission-policy entry (`right-release qa policy approve-runner`). Admission itself is unchanged and stays the owner's.
+//
+// `cargo:rightkit-credentials` takes the same route and is enrolled as the managed OS credential provider (credential-provider.mjs) that updater signing runs.
+// Only units named in TOOL_UNITS have this route. The route never uploads, signs or publishes, and it enrols only on a Mac or Windows host (the platforms
+// a runner is enrolled for: its bytes are executed here to read their version).
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { endRun, startRun } from "./gate-stages.mjs";
+import { runCargoSync } from "./managed-cargo.mjs";
+import { resolveManagedRoots } from "./managed-roots.mjs";
+import { CredentialProviderError, enrollCredentialProvider } from "./credential-provider.mjs";
+import { QaRunnerError, enrollQaRunner } from "./qa-runner.mjs";
+import { knownRedEntry, resolveUnit } from "./unit-gate.mjs";
+
+export const TOOL_STAGE = "tool";
+export const TOOL_REPORT_SCHEMA = "rightkit.tool-build-report/1";
+/** The units that have a tool route: the crate, the binary its manifest declares, and what the binary is enrolled as. */
+export const TOOL_UNITS = Object.freeze({
+  "cargo:rightkit-qa": Object.freeze({ crate: "rightkit-qa", bin: "rightkit-qa", enrols: "qa-runner" }),
+  "cargo:rightkit-credentials": Object.freeze({ crate: "rightkit-credentials", bin: "rightkit-credentials", enrols: "credential-provider" }),
+});
+const HOST_PLATFORM = Object.freeze({ darwin: "mac", win32: "win" });
+const BUILD_TIMEOUT_MS = 30 * 60 * 1000;
+
+export class ToolBuildError extends Error {
+  constructor(code, message) { super(`${code}: ${message}`); this.name = "ToolBuildError"; this.code = code; }
+}
+const refuse = (code, message) => { throw new ToolBuildError(code, message); };
+
+/** The cargo arguments of the build (no `cargo`): the one shape the broker admits as a compile and a stage grant carries (cargo-shapes.mjs). */
+export const toolBuildArgs = (bin) => ["build", "--release", "--locked", "--bin", bin];
+
+/**
+ * What `--to tool --unit <selector>` builds on `platform` (a `process.platform` value), decided before ownership, a snapshot or any process:
+ * `{ selector, crate, bin, enrols, cargoDir, argv, executable, runnerPlatform }`, or a typed ToolBuildError.
+ */
+export function toolPlan({ selector, platform }) {
+  const unit = Object.hasOwn(TOOL_UNITS, selector ?? "") ? TOOL_UNITS[selector] : null;
+  if (!unit) refuse("RK_TOOL_UNIT_UNSUPPORTED", `${JSON.stringify(selector ?? null)} has no tool route (${Object.keys(TOOL_UNITS).join(", ")}); \`--to tool\` builds only a unit named there`);
+  const runnerPlatform = HOST_PLATFORM[platform];
+  if (!runnerPlatform) refuse("RK_TOOL_HOST", `a ${unit.bin} runner is built and enrolled on a Mac or a Windows host (this is ${platform}): its bytes are executed there to read their version, and a runner is enrolled per platform`);
+  return { selector, ...unit, cargoDir: `crates/${unit.crate}`, argv: toolBuildArgs(unit.bin), executable: runnerPlatform === "win" ? `${unit.bin}.exe` : unit.bin, runnerPlatform };
+}
+
+/** The pinned target directory of the Cargo workspace that holds `cargoDir`: its own entry, else the nearest enclosing one (a crate that is a member of a parent workspace). Null when none is pinned. */
+export function pinnedTargetDir(targetDirs, cargoDir) {
+  for (let dir = cargoDir; ; dir = path.posix.dirname(dir)) {
+    if (typeof targetDirs?.[dir] === "string" && targetDirs[dir]) return targetDirs[dir];
+    if (dir === "." || dir === "/" || dir === "") return null;
+  }
+}
+
+const sha256OfFile = (file) => crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+
+/**
+ * The built binary under `outputDir` (the target directory: the carried receipt's `outputDir` on a broker host, the checkout's pinned target on a direct
+ * one): `<outputDir>/release/<executable>`, a regular file the build just wrote, never a link. Returns its path or throws.
+ */
+export function builtToolBinary({ outputDir, executable }) {
+  if (typeof outputDir !== "string" || !path.isAbsolute(outputDir)) refuse("RK_TOOL_NO_OUTPUT_DIR", `the build reported no absolute output directory (${JSON.stringify(outputDir ?? null)}); the produced binary cannot be located, so nothing was enrolled`);
+  const file = path.join(outputDir, "release", executable);
+  let meta;
+  try { meta = fs.lstatSync(file); } catch (error) { refuse("RK_TOOL_NO_BINARY", `the build succeeded but ${file} does not exist (${error.code ?? error.message}); nothing was enrolled`); }
+  if (meta.isSymbolicLink() || !meta.isFile()) refuse("RK_TOOL_NO_BINARY", `${file} is not a regular file; nothing was enrolled`);
+  return file;
+}
+
+/**
+ * Runs the tool route for one unit of the selected commit's snapshot. `root` is the snapshot, `commonDir` the checkout's git directory. `check(tier)`
+ * is the door's class A run and `stageGuard` its ledger verify around each stage (as runUnitGate takes them); `envExtra` is the Cargo binding
+ * (bindUnitCargo's env) and `targetDirs` its `{ [cargoDir]: checkout target directory }` for a direct host. Everything a test replaces is a parameter:
+ * `run` (the cargo call: managed-cargo's runCargoSync, which carries it through the broker or runs it direct), `enroll`, `resolve`, `dataRoot`.
+ * Returns the exit code (0, or 1 with the reason printed).
+ */
+export async function runUnitTool({
+  selector, root, commonDir, commit, tree, executor, env, platform, check, source = null, stageGuard = null, envExtra = {}, targetDirs = {},
+  resolve = resolveUnit, run = runCargoSync, enroll = enrollQaRunner, enrollProvider = enrollCredentialProvider, dataRoot = undefined, readKnownRed = null,
+  out = console.log, err = console.error, writeReport = null,
+}) {
+  let plan; let unit;
+  try {
+    plan = toolPlan({ selector, platform });
+    unit = resolve(selector, root);
+    const red = knownRedEntry({ unit, root, platform, ...(readKnownRed ? { readText: readKnownRed } : {}) });
+    if (red) refuse("RK_TOOL_KNOWN_RED", `${selector} is listed in ci/known-red.json for ${red.host} (${red.key}: ${red.reason}); a known-red unit is not built. Fix the defect and remove the entry first`);
+  } catch (error) { err(`rightkit-gate: BLOCKED: ${error.message}`); return 1; }
+  const report = { schema: TOOL_REPORT_SCHEMA, unit, commit, tree, executor: executor?.kind ?? null, stages: {} };
+  const save = () => { if (writeReport) writeReport(report); };
+  let stage = "check";
+  try {
+    if (stageGuard && !(await stageGuard.start("check"))) throw new Error("RK_CHECK_ERROR: the snapshot is not the commit's bytes plus the ledger before the check stage");
+    if (await check("compile") !== 0) throw new Error("class A check (compile tier) failed");
+    if (stageGuard && !(await stageGuard.end("check"))) throw new Error("RK_CHECK_ERROR: the check stage's result covers no known bytes");
+    report.stages.check = { ok: true }; save();
+    out(`rightkit-gate: [check] ${selector} passed`);
+
+    stage = TOOL_STAGE;
+    if (stageGuard && !(await stageGuard.start(TOOL_STAGE))) throw new Error(`RK_CHECK_ERROR: the snapshot is not the commit's bytes plus the ledger before the ${TOOL_STAGE} stage`);
+    const doorRun = startRun({ commonDir, commit, tree, stage: TOOL_STAGE });
+    let built;
+    try {
+      const childEnv = { ...env, ...envExtra, ...doorRun.env };
+      const cwd = path.join(root, ...plan.cargoDir.split("/"));
+      out(`rightkit-gate: [tool] ${selector}@${unit.version}: cargo ${plan.argv.join(" ")} (from ${plan.cargoDir}; executor ${executor?.kind ?? "?"})`);
+      const result = await run(plan.argv, { cwd, env: childEnv, encoding: "utf8", maxBuffer: 512 * 1024 * 1024, timeout: BUILD_TIMEOUT_MS, windowsHide: true });
+      if (result?.error || result?.status !== 0) {
+        throw new Error(`${selector}: cargo ${plan.argv.join(" ")} failed (${result?.error?.message ?? `exit ${result?.status}`})\nstdout:\n${String(result?.stdout ?? "").slice(-4000)}\nstderr:\n${String(result?.stderr ?? "").slice(-4000)}`);
+      }
+      // A carried (broker) call names the receipt's output directory; a direct call wrote the checkout target the gate pinned for this workspace.
+      built = builtToolBinary({ outputDir: result.outputDir ?? pinnedTargetDir(targetDirs, plan.cargoDir), executable: plan.executable });
+    } finally { endRun(doorRun); }
+    if (stageGuard && !(await stageGuard.end(TOOL_STAGE))) throw new Error(`RK_CHECK_ERROR: the ${TOOL_STAGE} stage's result covers no known bytes (a snapshot byte changed, a write is outside the ledger, or a cargo call did not complete)`);
+    const builtSha256 = sha256OfFile(built);
+    report.stages.tool = { ok: true, binary: built, binarySha256: builtSha256, version: unit.version }; save();
+    out(`rightkit-gate: [tool] built ${built} (sha256 ${builtSha256})`);
+
+    stage = "enrol";
+    let enrolled;
+    try {
+      const root_ = dataRoot ?? resolveManagedRoots({ env }).dataRoot;
+      enrolled = plan.enrols === "credential-provider"
+        ? enrollProvider({ dataRoot: root_, platform: plan.runnerPlatform, binary: built, version: unit.version })
+        : enroll({ dataRoot: root_, platform: plan.runnerPlatform, runner: built, version: unit.version });
+    } catch (error) {
+      if (error instanceof CredentialProviderError || error?.code?.startsWith?.("RK_CRED_PROVIDER_")) throw new Error(`${error.code}: ${error.message}\nthe built binary is ${built} (sha256 ${builtSha256}); a deliberate replacement of an enrolled version is \`node packages/release/credential-provider.mjs enroll --binary ${built} --version ${unit.version} --platform ${plan.runnerPlatform} --rotate\``);
+      if (error instanceof QaRunnerError || error?.code?.startsWith?.("RK_QA_RUNNER_")) throw new Error(`${error.code}: ${error.message}\nthe built binary is ${built} (sha256 ${builtSha256}); a deliberate replacement of an enrolled version is \`right-release qa runner enroll --runner ${built} --version ${unit.version} --platform ${plan.runnerPlatform} --rotate\``);
+      throw error;
+    }
+    // The copy that was recorded must be the very bytes that were built: a binary swapped between the digest and the copy is refused.
+    if (enrolled.entry.sha256 !== builtSha256) throw new Error(`RK_TOOL_DIGEST_DRIFT: the enrolled copy ${enrolled.runnerFile} has sha256 ${enrolled.entry.sha256}, the build produced ${builtSha256}; the binary changed while it was enrolled, so it is not trusted (enrol it again from a fresh build)`);
+    report.stages.enrol = { ok: true, runner: enrolled.runnerFile, sha256: enrolled.entry.sha256, version: enrolled.entry.version, platform: plan.runnerPlatform, record: enrolled.file, rotated: enrolled.rotated };
+    save();
+    out(`rightkit-gate: [tool] enrolled ${plan.bin} ${enrolled.entry.version} for ${plan.runnerPlatform}: ${enrolled.runnerFile} sha256 ${enrolled.entry.sha256} (record ${enrolled.file})`);
+    if (plan.enrols === "credential-provider") out("rightkit-gate: [tool] updater signing and the admission check resolve this enrolled provider (credential-provider.mjs); PATH is not used on a Mac or Windows host");
+    else out(`rightkit-gate: [tool] the owner admits it with: right-release qa policy approve-runner --runner ${enrolled.runnerFile} --version ${enrolled.entry.version} --platform ${plan.runnerPlatform} --set-by <name>`);
+    out(`rightkit-gate: [tool] ${selector} passed`);
+    return 0;
+  } catch (error) {
+    report.stages[stage] = { ok: false }; save();
+    err(`rightkit-gate: tool ${selector} stopped at ${stage}: ${error.message}`);
+    return 1;
+  }
+}

package/unit-gate.mjs

@@ -69,7 +69,12 @@ export function writeQualification({ report, artifact, unit, commit, tree, runti
     if (!/^[0-9a-f]{64}$/.test(artifact.contentSha256 ?? "")) throw new Error("release needs the qualified npm archive's content digest");
     content.contentSha256 = artifact.contentSha256;
     const excluded = exclusionsFor(unit.name);
-    if (excluded.length) {
+    if (excluded.length && executor?.kind === "direct") {
+      // A Linux direct origin neither builds nor signs the swap helper (publish.yml's build-swap/sign-swap do, hosted): its archive holds neither
+      // entry, and says so. The Mac rule below is unchanged.
+      if (!Array.isArray(artifact.contentExcluded) || artifact.contentExcluded.length) throw new Error(`a direct origin's ${unit.name} archive must hold neither ${excluded.join(" nor ")}`);
+      content.contentExcluded = [];
+    } else if (excluded.length) {
       if (!Array.isArray(artifact.contentExcluded) || [...artifact.contentExcluded].sort().join("\n") !== [...excluded].sort().join("\n")) throw new Error(`release needs the qualified ${unit.name} archive to hold ${excluded.join(" and ")}`);
       content.contentExcluded = [...artifact.contentExcluded].sort();
     }
@@ -348,6 +353,8 @@ export async function runUnitGate({ selector, to, root, commonDir, commit, tree,
   }
   // GB-29: a Linux origin has no managed volume; its scratch is the gate's own state directory (XDG state), never a Mac path.
   const scratch = platform === "win32" ? "D:\\scratch" : platform === "linux" ? path.join(env.XDG_STATE_HOME || path.join(env.HOME || "/tmp", ".local", "state"), "rightkit", "scratch") : "/Volumes/D/scratch";
+  // The Linux scratch is a gate-owned state directory that may not exist yet; the bundle itself is still created fresh (non-recursive) by the publisher.
+  if (platform === "linux") fs.mkdirSync(scratch, { recursive: true, mode: 0o700 });
   const bundle = path.join(scratch, `rk-unit-${randomBytes(12).toString("hex")}`);
   const argv = ["--local", unit.kind === "npm" ? "--package" : "--crate", unit.name, "--workspace", root, "--qualify-only", "--bundle", bundle];
   const runtimeDir = path.dirname(fileURLToPath(import.meta.url));
@@ -428,7 +435,7 @@ export async function runUnitGate({ selector, to, root, commonDir, commit, tree,
           // GB-29: the direct-origin qualification is written and verified exactly as the hosted side will. Dispatching it needs the publish workflow's `direct` admission input, which is the
           // reserved publication authorization (GC-T22): nothing is dispatched from a direct host until that input exists.
           const written = directQualification();
-          throw new Error(`RK_DIRECT_RELEASE_HELD: the direct-origin qualification ${written} was written and verified; the committed publish workflow admits \`broker\` only, and adding \`direct\` is the reserved publication authorization (GATE-CONTRACT GC-T22, GC-L01), so nothing was dispatched`);
+          throw new Error(`RK_DIRECT_RELEASE_HELD: the direct-origin qualification ${written} was written and verified; a direct host has no broker dispatch adapter, so dispatch publish.yml from main with admission=direct and this file as the qualification input (rightkit#1341); nothing was dispatched from here`);
         }
         requireBrokerHost(executor); // a direct host has no broker receipts to carry: refuse for that reason, not for the missing receipts
         const qualification = writeQualification({ report, artifact, unit, commit, tree, runtime, executor });

package/windows-identity-plan.mjs

@@ -0,0 +1,119 @@
+// The Windows package-identity (sparse MSIX) producer: the pure half. An app declares it in its release config as
+//
+//   windows: { identity: {
+//     manifest: "src-tauri/windows/identity/AppxManifest.xml",     // checked-in template; only Identity/@Version is stamped
+//     out: "src-tauri/windows/identity/dist",                       // gets <package> and external-assets/Assets/*; must lie under a declared compile input
+//     package: "HeardRight.Identity.msix",
+//     version: "0.1.33",                                            // optional; default is the config's `version` (3 or 4 numeric parts)
+//     assets: {
+//       files: [{ from: "src-tauri/icons/StoreLogo.png", to: "HeardRightStoreLogo.png" }, ...],   // into the package AND external-assets/Assets
+//       scaled: { svg: "src-tauri/icons/heardright-icon.svg", sizes: [16, 20, 24], name: "HeardRightSquare44x44Logo.targetsize-{size}_altform-unplated.png" },
+//     },
+//   } }
+//
+// The gate runs it (windows-identity.mjs) inside the door's snapshot before the compile, on Windows only. This module holds no I/O of its own
+// beyond config text matching: validation, version stamping, the step order, the expected package contents, and the write attribution.
+
+import path from "node:path";
+import { diffEntries } from "./stage-ledger.mjs";
+
+export const WINDOWS_IDENTITY_KEYS = Object.freeze(["manifest", "out", "package", "version", "assets"]);
+export const WINDOWS_IDENTITY_STEPS = Object.freeze(["stage-manifest", "stage-assets", "render-scaled", "makepri-config", "makepri-new", "pack", "unpack-roundtrip", "verify-roundtrip", "verify-pri", "sign", "cleanup"]);
+/** Scratch lives under `out` and is removed before the gate walks it. */
+export const WORK_DIR = ".identity-work";
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const posix = (v) => String(v).replaceAll("\\", "/");
+const insideApp = (v) => typeof v === "string" && v.trim() !== "" && !path.isAbsolute(v) && !/^[A-Za-z]:/.test(v) && !posix(v).split("/").includes("..");
+const flatName = (v, ext) => typeof v === "string" && /^[A-Za-z0-9._{}-]+$/.test(v) && v.toLowerCase().endsWith(ext) && !v.startsWith(".");
+
+/** Does this config text declare `windows.identity`? Text match like committedWebBuildConfigs: a `.mjs` config is code and is never imported by the gate. */
+export const declaresWindowsIdentity = (text) => /(^|[\s,{])["']?windows["']?\s*:\s*\{[^]*?["']?identity["']?\s*:\s*\{/.test(String(text));
+
+/** The release configs of `commit` under `appDir` that declare `windows.identity`, read from `base` (the commit's config decides, never the checkout's). */
+export function committedWindowsIdentityConfigs({ readFile, listConfigs, base }) {
+  return listConfigs.filter((f) => { try { return declaresWindowsIdentity(readFile(path.join(base, f))); } catch { return false; } });
+}
+
+/** `x.y.z` or `x.y.z.w` numeric (each <= 65535) to the four-part MSIX version; anything else (a prerelease suffix) is refused. */
+export function toMsixVersion(version) {
+  const parts = String(version ?? "").split(".");
+  if ((parts.length !== 3 && parts.length !== 4) || !parts.every((p) => /^\d{1,5}$/.test(p) && Number(p) <= 65535)) {
+    throw Object.assign(new Error(`version "${version}" is not 3 or 4 numeric segments (<=65535); cannot derive an MSIX package version (no prerelease or build suffix)`), { code: "RK_WINDOWS_IDENTITY" });
+  }
+  return (parts.length === 4 ? parts : [...parts, "0"]).join(".");
+}
+
+/** Stamp the real version into the template's `<Identity>` element only; returns `{ xml, name, publisher }`. */
+export function stampManifest(xml, msixVersion) {
+  const tag = String(xml).match(/<Identity\b[^>]*\/>/)?.[0];
+  if (!tag) throw Object.assign(new Error("the manifest has no <Identity ... /> element"), { code: "RK_WINDOWS_IDENTITY" });
+  if (!/\bVersion="[^"]*"/.test(tag)) throw Object.assign(new Error("the manifest <Identity> has no Version attribute"), { code: "RK_WINDOWS_IDENTITY" });
+  const name = tag.match(/\bName="([^"]+)"/)?.[1];
+  if (!name) throw Object.assign(new Error("the manifest <Identity> has no Name attribute"), { code: "RK_WINDOWS_IDENTITY" });
+  return { xml: String(xml).replace(tag, tag.replace(/\bVersion="[^"]*"/, `Version="${msixVersion}"`)), name, publisher: tag.match(/\bPublisher="([^"]*)"/)?.[1] ?? null };
+}
+
+/** The declared block, validated. Returns `{ problems, plan }` (plan null with problems). Paths stay app-relative posix. */
+export function planWindowsIdentity(config) {
+  const problems = [];
+  const block = config?.windows?.identity;
+  if (!isObject(block)) return { problems: ["the config declares no windows.identity"], plan: null };
+  if (isObject(config.windows)) for (const k of Object.keys(config.windows).filter((k) => k !== "identity")) problems.push(`windows has unknown key ${k} (allowed: identity)`);
+  for (const k of Object.keys(block).filter((k) => !WINDOWS_IDENTITY_KEYS.includes(k))) problems.push(`windows.identity has unknown key ${k} (allowed: ${WINDOWS_IDENTITY_KEYS.join(", ")})`);
+  if (!insideApp(block.manifest)) problems.push("windows.identity.manifest must be a relative path inside the app");
+  if (!insideApp(block.out)) problems.push("windows.identity.out must be a relative path inside the app");
+  if (!flatName(block.package, ".msix")) problems.push("windows.identity.package must be a flat .msix file name");
+  const version = block.version ?? config?.version;
+  let msixVersion = null;
+  try { msixVersion = toMsixVersion(version); } catch (e) { problems.push(`windows.identity version: ${e.message}`); }
+  const files = block.assets?.files;
+  if (!Array.isArray(files) || !files.length) problems.push("windows.identity.assets.files must list at least one { from, to } PNG");
+  const seen = new Set();
+  for (const [i, f] of (Array.isArray(files) ? files : []).entries()) {
+    if (!isObject(f) || !insideApp(f.from) || !flatName(f.to, ".png")) { problems.push(`windows.identity.assets.files[${i}] needs from (app-relative) and to (flat .png name)`); continue; }
+    if (seen.has(f.to.toLowerCase())) problems.push(`windows.identity.assets.files[${i}].to ${f.to} repeats`);
+    seen.add(f.to.toLowerCase());
+  }
+  const scaled = block.assets?.scaled;
+  if (scaled !== undefined) {
+    if (!isObject(scaled) || !insideApp(scaled.svg) || !Array.isArray(scaled.sizes) || !scaled.sizes.length || scaled.sizes.some((s) => !Number.isInteger(s) || s < 1 || s > 1024) || !flatName(scaled.name, ".png") || !String(scaled.name).includes("{size}")) {
+      problems.push("windows.identity.assets.scaled needs svg (app-relative), sizes (integers 1..1024) and name (flat .png containing {size})");
+    } else for (const s of scaled.sizes) if (seen.has(scaled.name.replace("{size}", s).toLowerCase())) problems.push(`windows.identity.assets.scaled name for size ${s} collides with a files entry`);
+  }
+  if (problems.length) return { problems, plan: null };
+  return {
+    problems,
+    plan: {
+      manifest: posix(block.manifest), out: posix(block.out).replace(/\/+$/, ""), package: block.package, msixVersion,
+      files: files.map((f) => ({ from: posix(f.from), to: f.to })),
+      scaled: scaled ? { svg: posix(scaled.svg), sizes: [...scaled.sizes], name: scaled.name } : null,
+    },
+  };
+}
+
+/** Every package-relative file the staged tree must contain (and the external Assets must mirror, minus the manifest and PRI). */
+export const scaledNames = (plan) => (plan.scaled ? plan.scaled.sizes.map((s) => plan.scaled.name.replace("{size}", String(s))) : []);
+export const assetNames = (plan) => [...plan.files.map((f) => f.to), ...scaledNames(plan)];
+export const expectedPackageFiles = (plan) => ["AppxManifest.xml", "resources.pri", ...assetNames(plan).map((n) => `Assets/${n}`)];
+/** The PRI resource URIs the manifest-backed (base) assets must resolve to: the taskbar resolves them, presence alone is not enough. */
+export const expectedPriUris = (plan, identityName) => plan.files.map((f) => `ms-resource://${identityName}/Files/Assets/${f.to}`);
+
+/** The ordered steps; `scaled` steps are omitted when no scaled renders are declared. */
+export const windowsIdentitySteps = (plan) => WINDOWS_IDENTITY_STEPS.filter((s) => s !== "render-scaled" || plan.scaled);
+
+/**
+ * Write attribution: everything the producer added or changed lies under its `out` (which must itself lie under a declared compile input),
+ * nothing was removed, and the package exists. `declared` and `out` are snapshot-relative posix paths; `out` is the producer's out dir.
+ */
+export function identityOutputProblems({ before, after, out, declared, packageFile }) {
+  const o = posix(out).replace(/\/+$/, "");
+  const roots = declared.map((x) => posix(x).replace(/\/+$/, ""));
+  const problems = [];
+  if (!roots.some((r) => o === r || o.startsWith(`${r}/`))) problems.push(`windows.identity.out ${o} lies under no declared compile input (declare it in .rightkit/compile-inputs.json)`);
+  const d = diffEntries(before, after);
+  for (const p of [...d.added, ...d.changed]) if (!(p === o || p.startsWith(`${o}/`))) problems.push(`${p} was written by the Windows identity build but lies outside its out ${o}`);
+  for (const p of d.removed) if (!(p === o || p.startsWith(`${o}/`))) problems.push(`${p} was removed by the Windows identity build but lies outside its out ${o}`);
+  if (packageFile && !after.some((e) => e.path === `${o}/${packageFile}`)) problems.push(`${o}/${packageFile} was not produced`);
+  return problems;
+}

package/windows-identity.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// `node windows-identity.mjs --config <file> [--json] [--dry-run]`: builds the app's Windows package-identity (sparse) MSIX from its release
+// config's `windows.identity` (windows-identity-plan.mjs), the producer the app's own build-windows-identity.mjs used to be. Run by the gate
+// inside the door's snapshot before the compile, on Windows only; under any other host it does nothing.
+//
+// Order (the archived script's, kept): stamp the manifest version into a staged copy; stage the asset PNGs into the package AND the external
+// Assets dir (a sparse package resolves its logo pixels from the install location); render the scaled variants from the SVG; makepri builds
+// resources.pri; makeappx packs with /nv (the identity package ships no executable by design); unpack round-trip; the PRI must index the
+// manifest-backed assets; then the package is signed through sign-windows.mjs, the one provisioned Azure Artifact Signing path. This module
+// never reads a credential, never authenticates, writes no signing receipt, and removes its scratch so only the package and external-assets remain.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { loadAppConfig } from "./command-spec.mjs";
+import { findWindowsSdkTool } from "./preflight.mjs";
+import { WORK_DIR, expectedPackageFiles, expectedPriUris, planWindowsIdentity, scaledNames, stampManifest, windowsIdentitySteps } from "./windows-identity-plan.mjs";
+import { webBuildDoorRefusal } from "./web-build.mjs";
+
+const SIGN_WINDOWS = path.join(path.dirname(fileURLToPath(import.meta.url)), "sign-windows.mjs");
+const fail = (message) => { throw Object.assign(new Error(message), { code: "RK_WINDOWS_IDENTITY" }); };
+
+/** The default SVG renderer: the app's own `@resvg/resvg-js` (resolved from the app root, never RightKit's). Returns a PNG Buffer. */
+export function appResvgRenderer(appRoot) {
+  const { Resvg } = createRequire(path.join(appRoot, "package.json"))("@resvg/resvg-js");
+  return (svg, size) => new Resvg(svg, { background: "rgba(0,0,0,0)", fitTo: { mode: "width", value: size } }).render().asPng();
+}
+
+/**
+ * Build the package. `deps` are injectable: `platform`, `run(cmd, args)`, `findTool`, `env`, `render(svg, size)`, `sign(file)`, `log`.
+ * Returns `{ skipped, steps, out, package, files }` (`files` app-relative posix). Skips (no writes) when the package already exists.
+ */
+export function buildWindowsIdentity({ plan, appRoot }, deps = {}) {
+  const { platform = process.platform, run = spawnSync, findTool = findWindowsSdkTool, env = process.env, render = null, log = (m) => console.error(`[windows-identity] ${m}`) } = deps;
+  const at = (p) => path.resolve(appRoot, p);
+  const outDir = at(plan.out);
+  const msix = path.join(outDir, plan.package);
+  const steps = windowsIdentitySteps(plan);
+  if (platform !== "win32") return { skipped: "not-windows", steps, out: plan.out, package: plan.package, files: [] };
+  if (existsSync(msix)) return { skipped: "present", steps, out: plan.out, package: plan.package, files: [] };
+  const tool = (name, envName) => { const p = env[envName] || findTool(name)?.toolPath; if (!p || !existsSync(p)) fail(`${name} not found; install the Windows SDK or set ${envName}`); return p; };
+  const makeappx = tool("makeappx.exe", "MAKEAPPX_PATH");
+  const makepri = tool("makepri.exe", "MAKEPRI_PATH");
+  const checked = (cmd, args, what) => { const r = run(cmd, args, { encoding: "utf8", windowsHide: true, timeout: 600000 }); if (r?.error || r?.status !== 0) fail(`${what} failed (${r?.error?.message ?? `exit ${r?.status}`}${r?.stderr ? `: ${String(r.stderr).trim()}` : ""})`); return r; };
+  const work = path.join(outDir, WORK_DIR);
+  const stage = path.join(work, "stage");
+  const external = path.join(outDir, "external-assets", "Assets");
+  try {
+    rmSync(work, { recursive: true, force: true });
+    mkdirSync(path.join(stage, "Assets"), { recursive: true });
+    rmSync(path.join(outDir, "external-assets"), { recursive: true, force: true });
+    mkdirSync(external, { recursive: true });
+    const manifestSource = at(plan.manifest);
+    if (!existsSync(manifestSource)) fail(`missing manifest ${plan.manifest}`);
+    const stamped = stampManifest(readFileSync(manifestSource, "utf8"), plan.msixVersion);
+    writeFileSync(path.join(stage, "AppxManifest.xml"), stamped.xml, "utf8");
+    log(`staged manifest ${stamped.name} Version="${plan.msixVersion}"`);
+    for (const f of plan.files) {
+      if (!existsSync(at(f.from))) fail(`missing asset ${f.from}`);
+      copyFileSync(at(f.from), path.join(stage, "Assets", f.to));
+      copyFileSync(at(f.from), path.join(external, f.to));
+    }
+    if (plan.scaled) {
+      if (!existsSync(at(plan.scaled.svg))) fail(`missing svg ${plan.scaled.svg}`);
+      const svg = readFileSync(at(plan.scaled.svg), "utf8");
+      const renderer = render ?? appResvgRenderer(appRoot);
+      for (const size of plan.scaled.sizes) {
+        const png = renderer(svg, size);
+        const name = plan.scaled.name.replace("{size}", String(size));
+        writeFileSync(path.join(stage, "Assets", name), png);
+        writeFileSync(path.join(external, name), png);
+      }
+    }
+    const priConfig = path.join(work, "priconfig.xml");
+    checked(makepri, ["createconfig", "/cf", priConfig, "/dq", "en-US", "/o"], "makepri createconfig");
+    checked(makepri, ["new", "/pr", stage, "/cf", priConfig, "/of", path.join(stage, "resources.pri"), "/o"], "makepri new");
+    if (!existsSync(path.join(stage, "resources.pri"))) fail("resources.pri was not produced; the taskbar icon would be blank");
+    rmSync(msix, { force: true });
+    checked(makeappx, ["pack", "/o", "/d", stage, "/nv", "/p", msix], "makeappx pack");
+    if (!existsSync(msix) || statSync(msix).size === 0) fail(`makeappx produced no package: ${msix}`);
+    const roundTrip = path.join(work, "roundtrip");
+    checked(makeappx, ["unpack", "/p", msix, "/d", roundTrip, "/o", "/nv"], "makeappx unpack round-trip");
+    const missing = expectedPackageFiles(plan).filter((rel) => !existsSync(path.join(roundTrip, ...rel.split("/"))));
+    if (missing.length) fail(`round-trip unpack of ${plan.package} is missing: ${missing.join(", ")}`);
+    const externalMissing = [...plan.files.map((f) => f.to), ...scaledNames(plan)].filter((n) => !existsSync(path.join(external, n)));
+    if (externalMissing.length) fail(`external Assets lacks files the PRI indexes: ${externalMissing.join(", ")}`);
+    const dump = path.join(work, "pri-dump.xml");
+    checked(makepri, ["dump", "/if", path.join(roundTrip, "resources.pri"), "/of", dump, "/o"], "makepri dump");
+    const dumpXml = readFileSync(dump, "utf8");
+    const unindexed = expectedPriUris(plan, stamped.name).filter((uri) => !dumpXml.includes(uri));
+    if (unindexed.length) fail(`packaged resources.pri does not index: ${unindexed.join(", ")}`);
+    // The one provisioned signer; it verifies after signing and exits non-zero on failure. No receipt file: nothing is written but the package.
+    (deps.sign ?? ((file) => checked(process.execPath, [SIGN_WINDOWS, file], "sign-windows")))(msix);
+    log(`signed ${plan.package}`);
+  } catch (error) {
+    rmSync(msix, { force: true }); // never leave an unchecked or unsigned package that a later run would take as present
+    throw error;
+  } finally { rmSync(work, { recursive: true, force: true }); }
+  const files = [`${plan.out}/${plan.package}`, ...[...plan.files.map((f) => f.to), ...scaledNames(plan)].map((n) => `${plan.out}/external-assets/Assets/${n}`)];
+  return { skipped: null, steps, out: plan.out, package: plan.package, files };
+}
+
+export function parseArgs(argv) {
+  const opts = { config: null, json: false, dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--config") { opts.config = argv[i + 1]; i += 1; if (!opts.config || opts.config.startsWith("--")) throw new Error("--config needs a value"); }
+    else if (argv[i] === "--json") opts.json = true;
+    else if (argv[i] === "--dry-run") opts.dryRun = true;
+    else throw new Error(`unknown windows-identity argument: ${argv[i]}`);
+  }
+  if (!opts.config) throw new Error("--config <file> is required");
+  return opts;
+}
+
+export async function main(argv = process.argv.slice(2), { env = process.env, platform = process.platform, spawnSyncFn = spawnSync, loadConfig = loadAppConfig, requireDoor, deps = {}, out = (s) => console.log(s) } = {}) {
+  const opts = parseArgs(argv);
+  const appRoot = path.dirname(path.resolve(opts.config));
+  // The door first (a .mjs config is code), then the platform: a non-Windows host builds nothing and says so.
+  const refusal = webBuildDoorRefusal({ appRoot, env, spawnSyncFn, ...(requireDoor ? { requireDoor } : {}) });
+  if (refusal) fail(refusal.replace("right-release web-build", "windows-identity"));
+  const result = (r) => { if (opts.json) out(JSON.stringify(r)); return 0; };
+  if (platform !== "win32") return result({ skipped: "not-windows", files: [] });
+  const { config } = await loadConfig(opts.config);
+  const { problems, plan } = planWindowsIdentity(config);
+  if (!plan) fail(problems.join("; "));
+  if (opts.dryRun) return result({ skipped: "dry-run", steps: windowsIdentitySteps(plan), out: plan.out, package: plan.package, files: [] });
+  return result(buildWindowsIdentity({ plan, appRoot }, { platform, env, ...deps }));
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().then((code) => { process.exitCode = code; }, (error) => {
+    console.error(`windows-identity: ${error.code ? `[${error.code}] ` : ""}${error.message}`);
+    process.exitCode = 1;
+  });
+}