@rightkit/release 0.2.174 → 0.4.0

package/target-distribution.mjs

@@ -0,0 +1,5 @@
+// The distribution an upload uses for one platform. An app that ships desktop and mobile has a different store per
+// platform, so `targets.<platform>.distribution` wins; the top-level `distribution` is the single-store fallback.
+export function targetDistribution(config, platform) {
+  return config?.targets?.[platform]?.distribution ?? config?.distribution;
+}

package/test-command.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+// `right-release test [--config <file>] [--suite <name>[,<name>]]... [--runner <name>] [--list] [--json] [-- <args>]`
+// runs the app's declared test suites from `right-release.config.mjs`, one after another, and stops at the first failure.
+//
+//   tests: {
+//     eventPrefix: "e2e",                       // optional; events are `<prefix>_suite_started` / `<prefix>_suite_completed`
+//     runners: {                                // optional named bases a suite or a `--runner` call builds on
+//       vitest: { node: "node_modules/vitest/vitest.mjs", nodeFlags: ["--no-experimental-webstorage"], nodeOptions: ["--no-experimental-webstorage"] },
+//     },
+//     suites: [
+//       { name: "unit", runner: "vitest", args: ["run", "--project", "unit"] },
+//       { name: "runtime-config", node: "scripts/test-runtime-config-e2e.test.mjs", nodeFlags: ["--test"] },
+//       // Expands to journeys-1, journeys-2, ...: the listed journeys run `chunk` at a time in separate processes.
+//       { name: "journeys", node: "scripts/qa-browser-functional.mjs", args: ["--keep-going"],
+//         journeys: { file: "scripts/qa-e2e-journeys.json", key: "journeys", chunk: 12, flag: "--journey" } },
+//     ],
+//   }
+//
+// A step is `{ cmd | node, args?, cwd?, env?, nodeFlags?, nodeOptions? }` (see command-spec.mjs); a suite adds `name`,
+// optionally `runner` (its arguments and flags are appended to the runner's) and `journeys`. Everything runs without a shell
+// from the app root. `--suite journeys` selects every chunk of that group. `--runner vitest -- run --project unit` runs
+// the runner once with the arguments after `--` (the watch or one-off case); `-- <args>` after `--suite` is allowed when
+// exactly one suite is selected. Exit code: 0 when every selected suite passed, else the failing suite's exit code.
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { spawn } from "./background-process.mjs";
+import { CommandSpecError, loadAppConfig, resolveInvocation, validateStep } from "./command-spec.mjs";
+
+const fail = (message) => { throw new CommandSpecError(message); };
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const PREFIX = /^[a-z][a-z0-9_]*$/;
+const uniq = (...lists) => [...new Set(lists.flatMap((list) => list ?? []))];
+
+export function parseTestArgs(argv) {
+  const opts = { config: "right-release.config.mjs", suites: [], runner: undefined, list: false, json: false, passthrough: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--") { opts.passthrough = argv.slice(i + 1); break; }
+    if (arg === "--config" || arg === "--suite" || arg === "--runner") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("--")) throw new Error(`${arg} needs a value`);
+      if (arg === "--suite") opts.suites.push(...value.split(",").filter(Boolean));
+      else opts[arg.slice(2)] = value;
+      i += 1;
+    } else if (arg === "--list") opts.list = true;
+    else if (arg === "--json") opts.json = true;
+    else throw new Error(`unknown test argument: ${arg}`);
+  }
+  return opts;
+}
+
+function mergeRunner(runner, entry) {
+  const { name: _name, runner: _runner, journeys: _journeys, ...own } = entry;
+  return {
+    ...runner,
+    ...own,
+    args: [...(runner?.args ?? []), ...(own.args ?? [])],
+    nodeFlags: uniq(runner?.nodeFlags, own.nodeFlags),
+    nodeOptions: uniq(runner?.nodeOptions, own.nodeOptions),
+    env: { ...(runner?.env ?? {}), ...(own.env ?? {}) },
+    // A suite that names its own executable replaces the runner's, whichever form each uses.
+    ...(runner?.node !== undefined && own.cmd !== undefined ? { node: undefined } : {}),
+    ...(runner?.cmd !== undefined && own.node !== undefined ? { cmd: undefined } : {}),
+  };
+}
+
+function expandJourneys(spec, label, appRoot) {
+  if (!isObject(spec)) fail(`${label}.journeys must be an object`);
+  const unknown = Object.keys(spec).filter((key) => !["file", "key", "chunk", "flag"].includes(key));
+  if (unknown.length) fail(`${label}.journeys has unknown key(s): ${unknown.join(", ")} (allowed: file, key, chunk, flag)`);
+  if (typeof spec.file !== "string" || !spec.file.trim()) fail(`${label}.journeys.file must be a relative JSON path`);
+  if (!Number.isInteger(spec.chunk) || spec.chunk < 1) fail(`${label}.journeys.chunk must be a positive integer`);
+  if (typeof spec.flag !== "string" || !spec.flag.startsWith("--")) fail(`${label}.journeys.flag must be a flag such as --journey`);
+  let data;
+  try { data = JSON.parse(readFileSync(path.resolve(appRoot, spec.file), "utf8")); }
+  catch (error) { fail(`${label}.journeys.file cannot be read: ${error.message}`); }
+  const list = (spec.key ?? "journeys") === "" ? data : data?.[spec.key ?? "journeys"];
+  if (!Array.isArray(list) || list.some((item) => typeof item !== "string" || item.includes(","))) fail(`${label}.journeys: ${spec.file} must hold a list of names without commas under "${spec.key ?? "journeys"}"`);
+  const chunks = [];
+  for (let index = 0; index < list.length; index += spec.chunk) chunks.push(list.slice(index, index + spec.chunk));
+  return chunks.map((names) => [spec.flag, names.join(",")]);
+}
+
+/**
+ * The ordered suites a run would execute: `[{ name, group, step, extraArgs }]`. `step` is merged with its runner and
+ * validated; journey chunks are already expanded. Pure apart from reading a declared journeys file.
+ */
+export function planTests(config, { suites = [], runner, passthrough = [], appRoot }) {
+  const tests = config?.tests;
+  if (!isObject(tests)) fail("the config declares no tests");
+  const unknown = Object.keys(tests).filter((key) => !["suites", "runners", "eventPrefix"].includes(key));
+  if (unknown.length) fail(`tests has unknown key(s): ${unknown.join(", ")} (allowed: suites, runners, eventPrefix)`);
+  const runners = tests.runners ?? {};
+  if (!isObject(runners)) fail("tests.runners must be an object");
+  for (const [name, spec] of Object.entries(runners)) {
+    if (!NAME.test(name)) fail(`tests.runners.${name}: names use letters, digits, . _ -`);
+    validateStep(spec, `tests.runners.${name}`);
+  }
+  if (runner !== undefined) {
+    if (!runners[runner]) fail(`unknown runner: ${runner} (declared: ${Object.keys(runners).join(", ") || "none"})`);
+    if (suites.length) fail("use --runner or --suite, not both");
+    const step = mergeRunner(runners[runner], {});
+    return [{ name: runner, group: runner, step, extraArgs: [...passthrough] }];
+  }
+  if (!Array.isArray(tests.suites) || tests.suites.length === 0) fail("tests.suites must be a non-empty list");
+  const planned = [];
+  const seen = new Set();
+  tests.suites.forEach((entry, index) => {
+    const label = `tests.suites[${index}]`;
+    validateStep(entry, label, ["name", "runner", "journeys"]);
+    if (typeof entry.name !== "string" || !NAME.test(entry.name)) fail(`${label}.name must be set (letters, digits, . _ -)`);
+    if (entry.runner !== undefined && !runners[entry.runner]) fail(`${label}.runner names an undeclared runner: ${entry.runner}`);
+    const base = mergeRunner(entry.runner === undefined ? undefined : runners[entry.runner], entry);
+    if (base.cmd === undefined && base.node === undefined) fail(`${label} needs cmd, node or a runner that has one`);
+    const variants = entry.journeys === undefined
+      ? [{ name: entry.name, extra: [] }]
+      : expandJourneys(entry.journeys, label, appRoot).map((extra, chunk) => ({ name: `${entry.name}-${chunk + 1}`, extra }));
+    for (const variant of variants) {
+      if (seen.has(variant.name)) fail(`${label}: duplicate suite name ${variant.name}`);
+      seen.add(variant.name);
+      planned.push({ name: variant.name, group: entry.name, step: { ...base, args: [...base.args, ...variant.extra] }, extraArgs: [] });
+    }
+  });
+  let selected = planned;
+  if (suites.length) {
+    selected = planned.filter((item) => suites.includes(item.name) || suites.includes(item.group));
+    const missing = suites.filter((name) => !planned.some((item) => item.name === name || item.group === name));
+    if (missing.length) fail(`unknown suite: ${missing.join(", ")} (declared: ${[...new Set(planned.map((item) => item.group))].join(", ")})`);
+  }
+  if (passthrough.length) {
+    if (selected.length !== 1) fail("arguments after -- need exactly one selected suite (or use --runner)");
+    selected = [{ ...selected[0], extraArgs: [...passthrough] }];
+  }
+  return selected;
+}
+
+export function eventPrefix(config) {
+  const prefix = config?.tests?.eventPrefix ?? "test";
+  if (typeof prefix !== "string" || !PREFIX.test(prefix)) fail("tests.eventPrefix must be lower-case letters, digits and underscores");
+  return prefix;
+}
+
+/**
+ * Run the planned suites in order; stop at the first non-zero exit. `spawnFn` and `log` are injectable.
+ * Resolves `{ exitCode, results: [{ suite, exitCode, durationMs }] }`; a spawn error or a signal rejects.
+ */
+export async function runSuites(plan, { appRoot, prefix = "test", env = process.env, spawnFn = spawn, log = console.log } = {}) {
+  const results = [];
+  for (const item of plan) {
+    const invocation = resolveInvocation(item.step, { appRoot, baseEnv: env, extraArgs: item.extraArgs });
+    log(JSON.stringify({ event: `${prefix}_suite_started`, suite: item.name }));
+    const started = Date.now();
+    const exitCode = await new Promise((resolve, reject) => {
+      const child = spawnFn(invocation.cmd, invocation.args, { cwd: invocation.cwd, env: invocation.env, stdio: "inherit" });
+      child.once("error", reject);
+      child.once("exit", (code, signal) => {
+        if (signal) reject(new Error(`${item.name} stopped by ${signal}`));
+        else resolve(code ?? 1);
+      });
+    });
+    const durationMs = Date.now() - started;
+    log(JSON.stringify({ event: `${prefix}_suite_completed`, suite: item.name, exitCode, durationMs }));
+    results.push({ suite: item.name, exitCode, durationMs });
+    if (exitCode !== 0) return { exitCode, results };
+  }
+  return { exitCode: 0, results };
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const opts = parseTestArgs(argv);
+  const { config, appRoot } = await loadAppConfig(opts.config);
+  const plan = planTests(config, { suites: opts.suites, runner: opts.runner, passthrough: opts.passthrough, appRoot });
+  if (opts.list) {
+    const view = plan.map((item) => ({ suite: item.name, ...resolveInvocation(item.step, { appRoot, baseEnv: {}, extraArgs: item.extraArgs }), env: undefined }));
+    if (opts.json) console.log(JSON.stringify(view, null, 2));
+    else for (const item of view) console.log(`${item.suite}: ${[item.cmd, ...item.args].join(" ")}`);
+    return 0;
+  }
+  const { exitCode } = await runSuites(plan, { appRoot, prefix: eventPrefix(config) });
+  return exitCode;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().then((code) => { process.exitCode = code; }, (error) => {
+    console.error(`right-release test: ${error.code ? `[${error.code}] ` : ""}${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/toolchain-swift.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+// `right-release toolchain swift --version <x.y[.z]> --sha256 <pin> [--url <https url>] [--github-env] [--json]`
+// (Orthic-Labs/rightkit#436): the one owner of the pinned Swift toolchain install on Windows, replacing the swift.org installer
+// block copied into SwiftRight's workflows and release script.
+//
+//   1. download the swift.org Windows release installer (default URL derived from the version), or reuse a file already on disk;
+//   2. refuse unless its sha256 equals the pin (checked before anything runs, and a bad download is deleted);
+//   3. skip the install when the pinned version is already the swift.exe on PATH, else run it silently (`/quiet /norestart`;
+//      exit 0 and 3010 pass, anything else prints the log tail and fails);
+//   4. find swift.exe (the refreshed Machine/User PATH, then the installer's Toolchains folders), require `swift --version` to
+//      report the pinned version, and find the Swift runtime bin (`Runtimes\\<ver>\\usr\\bin`, marked by swiftCore.dll);
+//   5. with `--github-env` (GITHUB_ENV / GITHUB_PATH set), export what the installer changed: variables it added or changed in
+//      the Machine/User environment (SDKROOT and friends; values are never printed, only names) and the new PATH entries,
+//      the swift directory and the runtime bin.
+//
+// Windows only. It never signs, never builds and reads no secret; the sha256 pin is the trust anchor, not the URL.
+import { createHash } from "node:crypto";
+import nodeFs from "node:fs";
+import os from "node:os";
+import nodePath from "node:path";
+import { pathToFileURL } from "node:url";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { spawnSync as nodeSpawnSync } from "./background-process.mjs";
+
+const win = nodePath.win32;
+
+export class ToolchainError extends Error {
+  constructor(code, message, details = {}) { super(message); this.name = "ToolchainError"; this.code = code; this.details = details; }
+}
+const fail = (code, message, details) => { throw new ToolchainError(code, message, details); };
+
+const VERSION = /^\d+\.\d+(?:\.\d+)?$/;
+const SHA256 = /^[0-9A-Fa-f]{64}$/;
+/** Variables the installer may legitimately set; these names are never exported to later steps even when they changed. */
+const NEVER_EXPORT = /^(?:GITHUB_|RUNNER_|ACTIONS_|NODE_OPTIONS$|BASH_ENV$|ENV$|COMSPEC$|PATHEXT$|TEMP$|TMP$|PATH$)/i;
+
+/** swift.org release installer URL for a version (x86_64 Windows 10+). */
+export function swiftInstallerUrl(version) {
+  return `https://download.swift.org/swift-${version}-release/windows10/swift-${version}-RELEASE/swift-${version}-RELEASE-windows10.exe`;
+}
+
+/** Validate the options; returns the normalized { version, sha256 (lower case), url, githubEnv, json }. */
+export function resolveSwiftOptions(raw) {
+  const errors = [];
+  if (typeof raw.version !== "string" || !VERSION.test(raw.version)) errors.push("--version must be a Swift release such as 6.4.0");
+  if (typeof raw.sha256 !== "string" || !SHA256.test(raw.sha256)) errors.push("--sha256 is required: the 64-hex sha256 of the swift.org installer for this version");
+  if (raw.url !== undefined && !/^https:\/\/[^\s/]+\/\S*$/.test(raw.url)) errors.push("--url must be an https:// URL");
+  if (errors.length) fail("TOOLCHAIN_OPTIONS_INVALID", errors.join("; "));
+  return { version: raw.version, sha256: raw.sha256.toLowerCase(), url: raw.url ?? swiftInstallerUrl(raw.version), githubEnv: raw.githubEnv === true, json: raw.json === true };
+}
+
+export function parseToolchainArgs(argv) {
+  if (argv[0] !== "swift") throw new Error("expected: toolchain swift --version <x.y.z> --sha256 <pin> [--url <https url>] [--github-env] [--json]");
+  const opts = {};
+  for (let i = 1; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--version" || arg === "--sha256" || arg === "--url") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("--")) throw new Error(`${arg} needs a value`);
+      opts[arg.slice(2)] = value;
+      i += 1;
+    } else if (arg === "--github-env") opts.githubEnv = true;
+    else if (arg === "--json") opts.json = true;
+    else throw new Error(`unknown toolchain argument: ${arg}`);
+  }
+  return opts;
+}
+
+/**
+ * What an installer run changed: variables whose Machine or User value is new or different (never PATH, never a denied name,
+ * never a name or value GITHUB_ENV cannot carry on one line), and the PATH entries it added. Pure.
+ */
+export function diffInstallerEnvironment(before, after) {
+  const changed = {};
+  for (const level of ["Machine", "User"]) {
+    for (const [name, value] of Object.entries(after?.[level] ?? {})) {
+      if (/^path$/i.test(name) || NEVER_EXPORT.test(name) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) continue;
+      if (typeof value !== "string" || /[\r\n]/.test(value)) continue;
+      if (before?.[level]?.[name] !== value) changed[name] = value;
+    }
+  }
+  const entries = (environment) => ["Machine", "User"].flatMap((level) => String(Object.entries(environment?.[level] ?? {}).find(([name]) => /^path$/i.test(name))?.[1] ?? "").split(";")).map((entry) => entry.trim()).filter(Boolean);
+  const known = new Set(entries(before).map((entry) => entry.toLowerCase()));
+  const addedPath = [...new Set(entries(after))].filter((entry) => !known.has(entry.toLowerCase()));
+  return { changed, addedPath };
+}
+
+const READ_ENVIRONMENT = "$ErrorActionPreference='Stop'; $r=@{}; foreach($l in 'Machine','User'){ $h=@{}; foreach($e in [Environment]::GetEnvironmentVariables($l).GetEnumerator()){ $h[[string]$e.Key]=[string]$e.Value }; $r[$l]=$h }; $r | ConvertTo-Json -Compress -Depth 4";
+
+/** The Machine and User environment as the registry holds it now ({ Machine: {...}, User: {...} }). */
+export function readInstallerEnvironment(run = nodeSpawnSync) {
+  const result = run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", READ_ENVIRONMENT], { encoding: "utf8", windowsHide: true, shell: false });
+  if (result?.error || result?.status !== 0) fail("TOOLCHAIN_ENVIRONMENT_UNREADABLE", `cannot read the Machine/User environment (${result?.error?.message ?? `exit ${result?.status}`})`);
+  try { return JSON.parse(String(result.stdout)); } catch { return fail("TOOLCHAIN_ENVIRONMENT_UNREADABLE", "the environment listing was not JSON"); }
+}
+
+/** Depth-limited search for `name` below `root` (the installer's Toolchains folder). */
+function findBelow(fs, root, name, depth = 6) {
+  if (depth < 0 || !fs.existsSync(root)) return undefined;
+  let entries;
+  try { entries = [...fs.readdirSync(root)].sort(); } catch { return undefined; }
+  if (entries.includes(name)) return win.join(root, name);
+  for (const entry of entries) {
+    const child = win.join(root, entry);
+    let isDirectory = false;
+    try { isDirectory = fs.statSync(child).isDirectory(); } catch { isDirectory = false; }
+    if (isDirectory) { const hit = findBelow(fs, child, name, depth - 1); if (hit) return hit; }
+  }
+  return undefined;
+}
+
+async function defaultDownload(url, file, { fs = nodeFs } = {}) {
+  const response = await fetch(url, { redirect: "follow" });
+  if (!response.ok || !response.body) fail("TOOLCHAIN_DOWNLOAD_FAILED", `GET ${url} failed with ${response.status}`, { url });
+  if (typeof response.url === "string" && response.url && !response.url.startsWith("https://")) fail("TOOLCHAIN_DOWNLOAD_FAILED", `${url} redirected to a non-https URL`, { url });
+  const hash = createHash("sha256");
+  const temporary = `${file}.download`;
+  const sink = fs.createWriteStream(temporary);
+  await pipeline(Readable.fromWeb(response.body), async function* tap(source) { for await (const chunk of source) { hash.update(chunk); yield chunk; } }, sink);
+  fs.renameSync(temporary, file);
+  return hash.digest("hex");
+}
+
+const sha256OfFile = (fs, file) => createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+
+/**
+ * Install (or confirm) the pinned Swift toolchain. Every effect is injectable: platform, env, fs, run, download(url, file) ->
+ * sha256 hex, tmpdir, log. Returns { version, swift, runtimeBin, installed, exported: { variables: [names], path: [entries] } }.
+ */
+export async function installSwiftToolchain(rawOptions, deps = {}) {
+  const options = resolveSwiftOptions(rawOptions);
+  const platform = deps.platform ?? process.platform;
+  if (platform !== "win32") fail("TOOLCHAIN_HOST_UNSUPPORTED", `right-release toolchain swift installs the Windows toolchain only (host: ${platform}); install Swift ${options.version} with the platform's own tooling`);
+  const env = deps.env ?? process.env;
+  const fs = deps.fs ?? nodeFs;
+  const run = deps.run ?? nodeSpawnSync;
+  const log = deps.log ?? (() => {});
+  const swiftVersionOk = (swift, pathEnv) => {
+    const result = run(swift, ["--version"], { encoding: "utf8", windowsHide: true, shell: false, env: { ...env, Path: pathEnv, PATH: pathEnv } });
+    const text = `${result?.stdout ?? ""}${result?.stderr ?? ""}`;
+    if (result?.error || result?.status !== 0) return { ok: false, text };
+    return { ok: new RegExp(`Swift version ${options.version.replaceAll(".", "\\.")}(?!\\d)`).test(text), text };
+  };
+  const currentPath = env.Path ?? env.PATH ?? "";
+  const onPath = (pathEnv) => pathEnv.split(";").map((dir) => dir.trim()).filter(Boolean).map((dir) => win.join(dir, "swift.exe")).find((candidate) => fs.existsSync(candidate));
+
+  // Already the pinned version: nothing to install. The pin is still the contract for a fresh install below.
+  let installed = false;
+  let swift = onPath(currentPath);
+  let pathEnv = currentPath;
+  let before;
+  let after;
+  if (swift && swiftVersionOk(swift, currentPath).ok) log(`swift ${options.version} already installed at ${swift}`);
+  else {
+    swift = undefined;
+    const temp = deps.tmpdir ?? env.RUNNER_TEMP ?? os.tmpdir();
+    const installer = win.join(temp, `swift-${options.version}-RELEASE-windows10.exe`);
+    if (!(fs.existsSync(installer) && sha256OfFile(fs, installer) === options.sha256)) {
+      log(`downloading ${options.url}`);
+      const download = deps.download ?? ((url, file) => defaultDownload(url, file, { fs }));
+      const actual = String(await download(options.url, installer)).toLowerCase();
+      if (actual !== options.sha256) {
+        try { fs.rmSync(installer, { force: true }); } catch { /* best effort */ }
+        fail("TOOLCHAIN_HASH_MISMATCH", `Swift installer sha256 ${actual} does not match the pin ${options.sha256}; the download was removed and nothing was installed`, { expected: options.sha256, actual });
+      }
+    }
+    // Hash the bytes that will run, not the bytes that were streamed: a file reused from disk was checked above.
+    const onDisk = sha256OfFile(fs, installer);
+    if (onDisk !== options.sha256) fail("TOOLCHAIN_HASH_MISMATCH", `Swift installer on disk sha256 ${onDisk} does not match the pin ${options.sha256}`, { expected: options.sha256, actual: onDisk });
+    before = readInstallerEnvironment(run);
+    const installLog = win.join(temp, "swift-install.log");
+    const result = run(installer, ["/quiet", "/norestart", "/log", installLog], { encoding: "utf8", windowsHide: true, shell: false });
+    if (result?.error) fail("TOOLCHAIN_INSTALL_FAILED", `could not start the Swift installer: ${result.error.message}`);
+    if (result.status !== 0 && result.status !== 3010) {
+      let tail = "";
+      try { tail = String(fs.readFileSync(installLog)).split(/\r?\n/).slice(-60).join("\n"); } catch { /* no log */ }
+      fail("TOOLCHAIN_INSTALL_FAILED", `Swift installer failed with exit code ${result.status}${tail ? `\n${tail}` : ""}`, { exitCode: result.status });
+    }
+    installed = true;
+    after = readInstallerEnvironment(run);
+    const refreshed = diffInstallerEnvironment(before, after).addedPath;
+    pathEnv = [...new Set([...currentPath.split(";").filter(Boolean), ...["Machine", "User"].flatMap((level) => String(Object.entries(after[level] ?? {}).find(([name]) => /^path$/i.test(name))?.[1] ?? "").split(";").filter(Boolean)), ...refreshed])].join(";");
+    swift = onPath(pathEnv);
+    if (!swift) {
+      for (const root of [win.join(env.LOCALAPPDATA ?? "", "Programs", "Swift"), win.join(env.ProgramFiles ?? "C:\\Program Files", "Swift")]) {
+        swift = findBelow(fs, win.join(root, "Toolchains"), "swift.exe");
+        if (swift) { pathEnv = `${win.dirname(swift)};${pathEnv}`; break; }
+      }
+    }
+    if (!swift) fail("TOOLCHAIN_SWIFT_NOT_FOUND", "swift.exe was not found after the Swift installer ran");
+    const probe = swiftVersionOk(swift, pathEnv);
+    if (!probe.ok) fail("TOOLCHAIN_VERSION_MISMATCH", `the installed swift.exe does not report Swift version ${options.version}: ${probe.text.trim().split(/\r?\n/)[0] ?? "no output"}`, { swift });
+  }
+
+  // Runtimes\<version>\usr\bin is a sibling of Toolchains under the install root (swiftCore.dll marks it).
+  let installRoot;
+  for (let cursor = win.dirname(swift); cursor && win.dirname(cursor) !== cursor; cursor = win.dirname(cursor)) {
+    if (win.basename(cursor).toLowerCase() === "toolchains") { installRoot = win.dirname(cursor); break; }
+  }
+  let runtimeBin;
+  if (installRoot) {
+    const runtimes = win.join(installRoot, "Runtimes");
+    let versions = [];
+    try { versions = [...fs.readdirSync(runtimes)].sort(); } catch { versions = []; }
+    runtimeBin = versions.map((entry) => win.join(runtimes, entry, "usr", "bin")).find((dir) => fs.existsSync(win.join(dir, "swiftCore.dll")));
+  }
+  if (!runtimeBin) fail("TOOLCHAIN_RUNTIME_NOT_FOUND", `no Swift runtime directory (swiftCore.dll) beside ${swift}${installRoot ? ` under ${win.join(installRoot, "Runtimes")}` : " (swift.exe is not under a Toolchains folder)"}`);
+
+  const exported = { variables: [], path: [] };
+  if (options.githubEnv) {
+    if (!env.GITHUB_ENV || !env.GITHUB_PATH) fail("TOOLCHAIN_GITHUB_ENV_MISSING", "--github-env needs GITHUB_ENV and GITHUB_PATH (run it inside a GitHub Actions step)");
+    const { changed, addedPath } = installed ? diffInstallerEnvironment(before, after) : { changed: {}, addedPath: [] };
+    const lines = Object.entries(changed).map(([name, value]) => `${name}=${value}`);
+    if (lines.length) fs.appendFileSync(env.GITHUB_ENV, `${lines.join("\n")}\n`);
+    exported.variables = Object.keys(changed);
+    exported.path = [...new Set([...addedPath, win.dirname(swift), runtimeBin])];
+    fs.appendFileSync(env.GITHUB_PATH, `${exported.path.join("\n")}\n`);
+  }
+  return { version: options.version, swift, runtimeBin, installed, exported };
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const opts = parseToolchainArgs(argv);
+  const result = await installSwiftToolchain(opts, { log: (line) => console.error(`right-release toolchain: ${line}`) });
+  if (opts.json) console.log(JSON.stringify(result, null, 2));
+  else {
+    console.log(`right-release toolchain: Swift ${result.version} ${result.installed ? "installed" : "already present"}; swift.exe ${result.swift}; runtime ${result.runtimeBin}`);
+    if (result.exported.variables.length || result.exported.path.length) console.log(`right-release toolchain: exported variables ${JSON.stringify(result.exported.variables)} and ${result.exported.path.length} PATH entr${result.exported.path.length === 1 ? "y" : "ies"}`);
+  }
+  return 0;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().then((code) => { process.exitCode = code; }, (error) => {
+    console.error(`right-release toolchain: ${error.code ? `[${error.code}] ` : ""}${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/upload-release.mjs

@@ -36,7 +36,12 @@ if (platform === "android") {
   const { main } = await import("./android-play-upload.mjs");
   process.exit(await main({ releaseId, configName, apply, dryRun }));
 }
-if (apply) fail("--apply is Android only; win and mac preview with --dry-run");
+// iOS: TestFlight through the App Store Connect build-upload API (in process, no key file), with its own gate and a dry run by default (ios-upload.mjs).
+if (platform === "ios") {
+  const { main } = await import("./ios-upload.mjs");
+  process.exit(await main({ releaseId, configName, apply, dryRun }));
+}
+if (apply) fail("--apply is Android and iOS only; win and mac preview with --dry-run");
 
 // Tier, primary checkout, clean tree, sealed commit, ownership evidence, provider and repository are checked by
 // the gate that `right-release github --release` also uses; nothing below runs until it passes.
@@ -82,7 +87,7 @@ function writeJson(file, value) {
 }
 
 function usage(code) {
-  console.log("usage: right-release upload --release <sealed-id> --platform win|mac --tier patch|update [--config right-release.config.mjs] [--repo owner/repo] [--dry-run]\n       right-release upload --platform android --release <sealed-id> [--config right-release.config.mjs] [--apply]   (Play internal track; dry run unless --apply)");
+  console.log("usage: right-release upload --release <sealed-id> --platform win|mac --tier patch|update [--config right-release.config.mjs] [--repo owner/repo] [--dry-run]\n       right-release upload --platform android --release <sealed-id> [--config right-release.config.mjs] [--apply]   (Play internal track; dry run unless --apply)\n       right-release upload --platform ios --release <sealed-id> [--config right-release.config.mjs] [--apply]   (TestFlight; dry run unless --apply)");
   process.exit(code);
 }
 

package/web-build.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// `right-release web-build [--config <file>] [--dry-run]` (also `right-release build --web`): the web frontend build
+// alone, with no Tauri, signing or packaging. It runs the config's `web.build` steps in order, without a shell, from
+// the app root, and stops at the first failure.
+//
+//   web: {
+//     build: [
+//       { node: "node_modules/typescript/bin/tsc", nodeFlags: ["--disable-warning=DEP0205"] },
+//       { node: "node_modules/vite/bin/vite.js", args: ["build"], nodeFlags: ["--disable-warning=DEP0205"] },
+//     ],
+//   }
+//
+// A step is `{ cmd | node, args?, cwd?, env?, nodeFlags?, nodeOptions? }` (see command-spec.mjs). `--dry-run` prints the
+// resolved commands and runs nothing. Exit code: 0, or the failing step's exit code.
+import { pathToFileURL } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { CommandSpecError, loadAppConfig, resolveInvocation, validateStep } from "./command-spec.mjs";
+
+export function parseWebBuildArgs(argv) {
+  const opts = { config: "right-release.config.mjs", dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--config") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("--")) throw new Error("--config needs a value");
+      opts.config = value;
+      i += 1;
+    } else if (arg === "--dry-run") opts.dryRun = true;
+    else throw new Error(`unknown web-build argument: ${arg}`);
+  }
+  return opts;
+}
+
+/** The validated `web.build` steps of a config. */
+export function planWebBuild(config) {
+  const steps = config?.web?.build;
+  if (!Array.isArray(steps) || steps.length === 0) throw new CommandSpecError("the config declares no web.build steps");
+  const unknown = Object.keys(config.web).filter((key) => key !== "build");
+  if (unknown.length) throw new CommandSpecError(`web has unknown key(s): ${unknown.join(", ")} (allowed: build)`);
+  return steps.map((step, index) => validateStep(step, `web.build[${index}]`));
+}
+
+/** Run the steps in order; `spawnSyncFn` and `log` are injectable. Returns the exit code. */
+export function runWebBuild(steps, { appRoot, env = process.env, dryRun = false, spawnSyncFn = spawnSync, log = console.log } = {}) {
+  for (const step of steps) {
+    const invocation = resolveInvocation(step, { appRoot, baseEnv: env });
+    log(`${dryRun ? "[dry-run] " : ""}${[invocation.cmd, ...invocation.args].join(" ")}`);
+    if (dryRun) continue;
+    const result = spawnSyncFn(invocation.cmd, invocation.args, { cwd: invocation.cwd, env: invocation.env, stdio: "inherit" });
+    if (result.error) throw result.error;
+    if (result.status !== 0) return result.status ?? 1;
+  }
+  return 0;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const opts = parseWebBuildArgs(argv);
+  const { config, appRoot } = await loadAppConfig(opts.config);
+  return runWebBuild(planWebBuild(config), { appRoot, dryRun: opts.dryRun });
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().then((code) => { process.exitCode = code; }, (error) => {
+    console.error(`right-release web-build: ${error.code ? `[${error.code}] ` : ""}${error.message}`);
+    process.exitCode = 1;
+  });
+}