@rightkit/release 0.6.16 → 0.6.21

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;
+  });
+}