machine-bridge-mcp 2.0.0 → 3.0.0-beta.11

package/scripts/promotion-digest.mjs

@@ -0,0 +1,121 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { readBoundedRegularFileSync } from "../src/local/secure-file.mjs";
+import { normalizePackRecord } from "./release-acceptance.mjs";
+import { parseReleaseVersion } from "./release-channel.mjs";
+
+const MAX_FILE_BYTES = 16 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 96 * 1024 * 1024;
+const VERSION_PLACEHOLDER = "<machine-bridge-release-version>";
+
+export function computePromotionContentDigest(root, options = {}) {
+  const pkg = options.packageJson || JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  const version = parseReleaseVersion(pkg.version).raw;
+  const record = options.packRecord || packageDryRun(root, pkg.name, options.npmCli);
+  if (!Array.isArray(record.files) || record.files.length < 1) throw new Error("npm pack dry-run omitted the package file inventory");
+  const entries = record.files.map((item) => ({
+    path: String(item?.path || ""),
+    mode: normalizePackMode(item?.mode),
+  })).sort((left, right) => left.path.localeCompare(right.path));
+  if (!entries.length || entries.some((entry) => entry.path.startsWith("/") || entry.path.includes("\\") || entry.path.split("/").includes(".."))) {
+    throw new Error("npm pack dry-run returned an invalid package path");
+  }
+  for (let index = 1; index < entries.length; index += 1) {
+    if (entries[index - 1].path === entries[index].path) throw new Error(`npm pack dry-run returned duplicate path: ${entries[index].path}`);
+  }
+  const hash = createHash("sha256");
+  let total = 0;
+  for (const entry of entries) {
+    const relative = entry.path;
+    const bytes = readBoundedRegularFileSync(join(root, relative), MAX_FILE_BYTES, `promotion package file ${relative}`, { verifyPathIdentity: true });
+    total += bytes.length;
+    if (total > MAX_TOTAL_BYTES) throw new Error(`promotion package content exceeds ${MAX_TOTAL_BYTES} bytes`);
+    const normalized = normalizeReleaseMetadata(relative, bytes, version);
+    hash.update(`${relative}\0${entry.mode}\0${normalized.length}\0`, "utf8");
+    hash.update(normalized);
+    hash.update("\0", "utf8");
+  }
+  return hash.digest("hex");
+}
+
+
+function normalizePackMode(value) {
+  const numeric = Number(value);
+  const mode = Number.isSafeInteger(numeric) ? numeric & 0o777 : NaN;
+  if (![0o644, 0o755].includes(mode)) throw new Error(`npm pack dry-run returned an invalid file mode: ${String(value)}`);
+  return mode.toString(8).padStart(4, "0");
+}
+
+function packageDryRun(root, packageName, npmCli = process.env.npm_execpath) {
+  if (!npmCli) throw new Error("promotion digest must run through npm so npm_execpath is available");
+  const result = spawnSync(process.execPath, [
+    npmCli,
+    "pack",
+    "--ignore-scripts",
+    "--silent",
+    "--dry-run",
+    "--json",
+  ], {
+    cwd: root,
+    encoding: "utf8",
+    env: process.env,
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`npm pack dry-run failed: ${String(result.stderr || result.stdout).trim()}`);
+  let parsed;
+  try { parsed = JSON.parse(result.stdout); } catch { throw new Error("npm pack dry-run did not return valid JSON"); }
+  const record = normalizePackRecord(parsed, packageName);
+  if (!record) throw new Error("npm pack dry-run did not return package metadata");
+  return record;
+}
+
+function normalizeReleaseMetadata(relative, bytes, version) {
+  if (relative === "package.json") {
+    const value = parseJson(bytes, relative);
+    value.version = VERSION_PLACEHOLDER;
+    return canonicalJson(value);
+  }
+  if (relative === "package-lock.json") {
+    const value = parseJson(bytes, relative);
+    value.version = VERSION_PLACEHOLDER;
+    if (value.packages?.[""] && typeof value.packages[""] === "object") value.packages[""].version = VERSION_PLACEHOLDER;
+    return canonicalJson(value);
+  }
+  if (relative === "browser-extension/manifest.json") {
+    const value = parseJson(bytes, relative);
+    value.version = "0.0.0";
+    value.version_name = VERSION_PLACEHOLDER;
+    return canonicalJson(value);
+  }
+  if (relative === "src/worker/index.ts") {
+    const text = bytes.toString("utf8");
+    const normalized = text.replace(/const SERVER_VERSION = "[^"]+";/, `const SERVER_VERSION = "${VERSION_PLACEHOLDER}";`);
+    if (normalized === text && !text.includes(`const SERVER_VERSION = "${VERSION_PLACEHOLDER}";`)) {
+      throw new Error("Worker source omitted the synchronized SERVER_VERSION constant");
+    }
+    return Buffer.from(normalized, "utf8");
+  }
+  if (relative === "CHANGELOG.md") {
+    return Buffer.from(bytes.toString("utf8").split(version).join(VERSION_PLACEHOLDER), "utf8");
+  }
+  return bytes;
+}
+
+function parseJson(bytes, label) {
+  try { return JSON.parse(bytes.toString("utf8")); } catch (error) {
+    throw new Error(`${label} is not valid JSON: ${error.message}`);
+  }
+}
+
+function canonicalJson(value) {
+  return Buffer.from(`${JSON.stringify(sortValue(value))}\n`, "utf8");
+}
+
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortValue(value[key])]));
+}

package/scripts/publish-npm.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { parseReleaseVersion, requiresSoakForStable } from "./release-channel.mjs";
+import { verifyCurrentStableSoak } from "./release-soak.mjs";
+
+const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
+
+export function npmPublishArguments(version, mode) {
+  const parsed = parseReleaseVersion(version);
+  if (mode === "prerelease" && !parsed.prerelease) throw new Error("prerelease publication requires a dev, beta, or rc version");
+  if (mode === "stable" && parsed.prerelease) throw new Error("stable publication requires a version without a prerelease suffix");
+  if (!new Set(["prerelease", "stable"]).has(mode)) throw new Error("publication mode must be prerelease or stable");
+  return ["publish", "--tag", parsed.npmTag];
+}
+
+export function publishCurrentNpmPackage(repositoryRoot, mode, options = {}) {
+  const pkg = JSON.parse(readFileSync(resolve(repositoryRoot, "package.json"), "utf8"));
+  const parsed = parseReleaseVersion(pkg.version);
+  const args = npmPublishArguments(parsed.raw, mode);
+  if (!parsed.prerelease && requiresSoakForStable(parsed.raw)) verifyCurrentStableSoak(repositoryRoot);
+  const npmCli = options.npmCli || process.env.npm_execpath;
+  if (!npmCli) throw new Error("npm publication must run through npm so npm_execpath is available");
+  const run = options.run || spawnSync;
+  const result = run(process.execPath, [npmCli, ...args], {
+    cwd: repositoryRoot,
+    encoding: "utf8",
+    env: process.env,
+    stdio: options.capture ? "pipe" : "inherit",
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`npm publish failed with status ${result.status}`);
+  return { version: parsed.raw, tag: parsed.npmTag };
+}
+
+async function main() {
+  const mode = process.argv[2] || "";
+  const result = publishCurrentNpmPackage(root, mode);
+  console.log(`npm publication completed: ${result.version} with dist-tag ${result.tag}`);
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  main().catch((error) => {
+    console.error(`npm publication failed: ${error?.message || error}`);
+    process.exitCode = 1;
+  });
+}

package/scripts/published-release.mjs

@@ -0,0 +1,87 @@
+import { spawnSync } from "node:child_process";
+import { resolveTrustedGithubCli } from "../src/local/trusted-github-cli.mjs";
+
+export function readPublishedNpmPrerelease(name, version, distTag, options = {}) {
+  const run = options.run || runNpmView;
+  const actualVersion = run([`${name}@${version}`, "version", "--json"]);
+  const integrity = run([`${name}@${version}`, "dist.integrity", "--json"]);
+  const shasum = run([`${name}@${version}`, "dist.shasum", "--json"]);
+  const tags = run([name, "dist-tags", "--json"]);
+  const times = run([name, "time", "--json"]);
+  return normalizePublishedNpmPrerelease({
+    requestedVersion: version,
+    requestedTag: distTag,
+    actualVersion,
+    integrity,
+    shasum,
+    tags,
+    times,
+  });
+}
+
+export function normalizePublishedNpmPrerelease(value) {
+  const actualVersion = unwrapNpmJsonValue(value.actualVersion);
+  const tags = unwrapNpmJsonValue(value.tags);
+  const times = unwrapNpmJsonValue(value.times);
+  const version = String(actualVersion || "");
+  const requestedVersion = String(value.requestedVersion || "");
+  const distTag = String(value.requestedTag || "");
+  const integrity = String(unwrapNpmJsonValue(value.integrity) || "");
+  const shasum = String(unwrapNpmJsonValue(value.shasum) || "");
+  const publishedAt = String(times?.[requestedVersion] || "");
+  if (version !== requestedVersion) throw new Error("npm registry returned another prerelease version");
+  if (tags?.[distTag] !== requestedVersion) throw new Error(`npm dist-tag ${distTag} does not point to ${requestedVersion}`);
+  if (!/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(integrity)) throw new Error("npm prerelease integrity is invalid");
+  if (!/^[0-9a-f]{40}$/.test(shasum)) throw new Error("npm prerelease SHA-1 is invalid");
+  if (!Number.isFinite(Date.parse(publishedAt))) throw new Error("npm prerelease publication timestamp is invalid");
+  return Object.freeze({ version, integrity, shasum, distTag, publishedAt: new Date(Date.parse(publishedAt)).toISOString() });
+}
+
+function unwrapNpmJsonValue(value) {
+  return Array.isArray(value) && value.length === 1 ? value[0] : value;
+}
+
+export function readGithubPrerelease(version, options = {}) {
+  const run = options.run || runGh;
+  const value = run(["release", "view", `v${version}`, "--json", "tagName,isPrerelease,publishedAt,assets"]);
+  return normalizeGithubPrerelease(value, version);
+}
+
+export function normalizeGithubPrerelease(value, version) {
+  const tag = String(value?.tagName || "");
+  const publishedAt = String(value?.publishedAt || "");
+  if (tag !== `v${version}` || value?.isPrerelease !== true) throw new Error("GitHub prerelease is missing or not marked as a prerelease");
+  if (!Number.isFinite(Date.parse(publishedAt))) throw new Error("GitHub prerelease publication timestamp is invalid");
+  if (!Array.isArray(value?.assets)) throw new Error("GitHub prerelease asset inventory is unavailable");
+  const expectedAsset = `machine-bridge-mcp-${version}.tgz`;
+  const asset = value.assets.find((entry) => entry && typeof entry === "object" && entry.name === expectedAsset);
+  if (!asset) throw new Error(`GitHub prerelease is missing ${expectedAsset}`);
+  const size = Number(asset.size);
+  if (!Number.isSafeInteger(size) || size < 1) throw new Error("GitHub prerelease package asset size is invalid");
+  return Object.freeze({
+    tag,
+    isPrerelease: true,
+    publishedAt: new Date(Date.parse(publishedAt)).toISOString(),
+    asset: Object.freeze({ name: expectedAsset, size }),
+  });
+}
+
+function runNpmView(args) {
+  const npmCli = process.env.npm_execpath;
+  if (!npmCli) throw new Error("npm registry verification must run through npm");
+  const result = spawnSync(process.execPath, [npmCli, "view", ...args], {
+    encoding: "utf8",
+    env: process.env,
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`npm view ${args[0]} failed: ${String(result.stderr || result.stdout).trim()}`);
+  try { return JSON.parse(result.stdout); } catch { throw new Error(`npm view ${args[0]} returned invalid JSON`); }
+}
+
+function runGh(args) {
+  const result = spawnSync(resolveTrustedGithubCli({ workspace: process.cwd() }), args, { encoding: "utf8", env: process.env, windowsHide: true });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`gh ${args[0]} failed: ${String(result.stderr || result.stdout).trim()}`);
+  try { return JSON.parse(result.stdout); } catch { throw new Error("GitHub prerelease query returned invalid JSON"); }
+}

package/scripts/release-acceptance.mjs

@@ -8,12 +8,16 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { readBoundedRegularFileSync } from "../src/local/secure-file.mjs";
+import { compareReleaseVersions, parseReleaseVersion } from "./release-channel.mjs";
 
 export const ACCEPTANCE_SCHEMA_VERSION = 1;
 export const ACCEPTANCE_POLICY_VERSION = "1.2.8";
 export const AGENT_VERIFIED_ACCEPTANCE_VERSION = "1.2.9";
 export const AGENT_OPERATED_ACCEPTANCE_VERSION = "2.0.0";
 export const ACCEPTANCE_CONFIRMATION = "owner-authorized-agent-operated-local-candidate";
+export const PROMOTION_DIGEST_POLICY_VERSION = "3.0.0-beta.1";
+export const PERSISTENT_OWNER_ACTIVATED_ACCEPTANCE_VERSION = "3.0.0-beta.1";
+export const PERSISTENT_OWNER_ACTIVATED_CONFIRMATION = "owner-activated-agent-verified-persistent-candidate";
 export const OWNER_STARTED_ACCEPTANCE_CONFIRMATION = "owner-started-agent-verified-local-candidate";
 export const LEGACY_ACCEPTANCE_CONFIRMATION = "repository-owner-local-test";
 const MAX_ACCEPTANCE_BYTES = 64 * 1024;
@@ -25,6 +29,9 @@ export function requiresLocalAcceptance(version) {
 
 export function acceptanceConfirmationForVersion(version) {
   const parsed = parseVersion(version);
+  if (compareReleaseVersions(parseReleaseVersion(version), parseReleaseVersion(PERSISTENT_OWNER_ACTIVATED_ACCEPTANCE_VERSION)) >= 0) {
+    return PERSISTENT_OWNER_ACTIVATED_CONFIRMATION;
+  }
   if (compareVersions(parsed, parseVersion(AGENT_OPERATED_ACCEPTANCE_VERSION)) >= 0) return ACCEPTANCE_CONFIRMATION;
   if (compareVersions(parsed, parseVersion(AGENT_VERIFIED_ACCEPTANCE_VERSION)) >= 0) return OWNER_STARTED_ACCEPTANCE_CONFIRMATION;
   return LEGACY_ACCEPTANCE_CONFIRMATION;
@@ -105,6 +112,12 @@ export function verifyAcceptanceRecord(record, metadata) {
   if (!record || typeof record !== "object" || Array.isArray(record)) {
     throw new Error("release acceptance record must be an object");
   }
+  const allowed = new Set([
+    "schema_version", "result", "confirmation", "package_name", "package_version", "filename",
+    "shasum", "integrity", "accepted_at", "package_content_sha256", "promotion_content_sha256",
+  ]);
+  const unknown = Object.keys(record).filter((key) => !allowed.has(key));
+  if (unknown.length) throw new Error(`release acceptance record contains unsupported fields: ${unknown.join(", ")}`);
   if (record.schema_version !== ACCEPTANCE_SCHEMA_VERSION) {
     throw new Error(`unsupported release acceptance schema: ${record.schema_version}`);
   }
@@ -118,12 +131,28 @@ export function verifyAcceptanceRecord(record, metadata) {
   if (!/^[0-9a-f]{64}$/.test(String(record.package_content_sha256 || ""))) {
     throw new Error("local release acceptance portable package-content digest is missing or invalid");
   }
+  if (compareReleaseVersions(parseReleaseVersion(metadata.package_version), parseReleaseVersion(PROMOTION_DIGEST_POLICY_VERSION)) >= 0
+    && !/^[0-9a-f]{64}$/.test(String(record.promotion_content_sha256 || ""))) {
+    throw new Error("local release acceptance promotion-content digest is missing or invalid");
+  }
   for (const key of ["package_name", "package_version", "filename", "shasum", "integrity"]) {
     if (record[key] !== metadata[key]) {
       throw new Error(`local release acceptance ${key} does not match the current npm package`);
     }
   }
-  return record;
+  return Object.freeze({
+    schema_version: ACCEPTANCE_SCHEMA_VERSION,
+    result: "passed",
+    confirmation: expectedConfirmation,
+    package_name: metadata.package_name,
+    package_version: metadata.package_version,
+    filename: metadata.filename,
+    shasum: metadata.shasum,
+    integrity: metadata.integrity,
+    accepted_at: new Date(acceptedAt).toISOString(),
+    package_content_sha256: String(record.package_content_sha256),
+    ...(record.promotion_content_sha256 ? { promotion_content_sha256: String(record.promotion_content_sha256) } : {}),
+  });
 }
 
 export function verifyCurrentReleaseAcceptance(root) {

package/scripts/release-candidate-manifest.mjs

@@ -0,0 +1,40 @@
+import { parseReleaseVersion } from "./release-channel.mjs";
+
+export const CANDIDATE_MANIFEST_SCHEMA_VERSION = 1;
+const FIELDS = new Set([
+  "schema_version", "result", "package_name", "package_version", "filename", "shasum", "integrity",
+  "promotion_content_sha256", "prepared_at",
+]);
+
+export function validateCandidateManifest(value, expected = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("release candidate manifest must be an object");
+  const unknown = Object.keys(value).filter((key) => !FIELDS.has(key));
+  if (unknown.length) throw new Error(`release candidate manifest contains unsupported fields: ${unknown.join(", ")}`);
+  if (value.schema_version !== CANDIDATE_MANIFEST_SCHEMA_VERSION || value.result !== "pending") {
+    throw new Error("release candidate manifest is not pending current-schema state");
+  }
+  const version = parseReleaseVersion(value.package_version).raw;
+  const packageName = String(value.package_name || "");
+  if (packageName !== "machine-bridge-mcp") throw new Error("release candidate manifest package is invalid");
+  if (expected.packageName && packageName !== expected.packageName) throw new Error("release candidate manifest package does not match the current package");
+  if (expected.packageVersion && version !== expected.packageVersion) throw new Error("release candidate manifest version does not match the current package");
+  const filename = String(value.filename || "");
+  const expectedFilename = `${packageName}-${version}.tgz`;
+  if (filename !== expectedFilename) throw new Error(`release candidate manifest filename is invalid; expected ${expectedFilename}`);
+  if (!/^[0-9a-f]{40}$/.test(String(value.shasum || ""))) throw new Error("release candidate manifest SHA-1 is invalid");
+  if (!/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(String(value.integrity || ""))) throw new Error("release candidate manifest integrity is invalid");
+  if (!/^[0-9a-f]{64}$/.test(String(value.promotion_content_sha256 || ""))) throw new Error("release candidate promotion digest is invalid");
+  const preparedAt = Date.parse(String(value.prepared_at || ""));
+  if (!Number.isFinite(preparedAt)) throw new Error("release candidate preparation timestamp is invalid");
+  return Object.freeze({
+    schema_version: CANDIDATE_MANIFEST_SCHEMA_VERSION,
+    result: "pending",
+    package_name: packageName,
+    package_version: version,
+    filename,
+    shasum: String(value.shasum),
+    integrity: String(value.integrity),
+    promotion_content_sha256: String(value.promotion_content_sha256),
+    prepared_at: new Date(preparedAt).toISOString(),
+  });
+}

package/scripts/release-channel.mjs

@@ -0,0 +1,106 @@
+const CHANNEL_TAGS = Object.freeze({ dev: "dev", beta: "beta", rc: "next" });
+const SOAK_SECONDS = Object.freeze({ major: 7 * 24 * 60 * 60, minor: 3 * 24 * 60 * 60, patch: 24 * 60 * 60 });
+
+export const SOAK_POLICY_VERSION = "3.0.0";
+export const SOAK_CONFIRMATION = "owner-reported-published-prerelease-soak-passed";
+
+export function parseReleaseVersion(value) {
+  const raw = String(value || "").trim();
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z]+)\.(\d+))?$/.exec(raw);
+  if (!match) throw new Error(`release version must use x.y.z or x.y.z-(dev|beta|rc).n: ${raw || "<empty>"}`);
+  const channel = match[4] || "";
+  if (channel && !Object.hasOwn(CHANNEL_TAGS, channel)) {
+    throw new Error(`unsupported prerelease channel ${channel}; use dev, beta, or rc`);
+  }
+  const sequence = channel ? Number(match[5]) : 0;
+  if (channel && (!Number.isSafeInteger(sequence) || sequence < 1)) {
+    throw new Error("prerelease sequence must be a positive integer");
+  }
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  const patch = Number(match[3]);
+  for (const part of [major, minor, patch]) {
+    if (!Number.isSafeInteger(part) || part < 0) throw new Error("release version contains an invalid numeric component");
+  }
+  return Object.freeze({
+    raw,
+    major,
+    minor,
+    patch,
+    channel,
+    sequence,
+    prerelease: Boolean(channel),
+    baseVersion: `${major}.${minor}.${patch}`,
+    npmTag: channel ? CHANNEL_TAGS[channel] : "latest",
+  });
+}
+
+export function compareReleaseVersions(leftValue, rightValue) {
+  const left = typeof leftValue === "string" ? parseReleaseVersion(leftValue) : leftValue;
+  const right = typeof rightValue === "string" ? parseReleaseVersion(rightValue) : rightValue;
+  for (const key of ["major", "minor", "patch"]) {
+    if (left[key] !== right[key]) return left[key] - right[key];
+  }
+  if (!left.prerelease && !right.prerelease) return 0;
+  if (!left.prerelease) return 1;
+  if (!right.prerelease) return -1;
+  const channelOrder = { dev: 0, beta: 1, rc: 2 };
+  if (left.channel !== right.channel) return channelOrder[left.channel] - channelOrder[right.channel];
+  return left.sequence - right.sequence;
+}
+
+export function requiresSoakForStable(version) {
+  const parsed = parseReleaseVersion(version);
+  return !parsed.prerelease && compareReleaseVersions(parsed, parseReleaseVersion(SOAK_POLICY_VERSION)) >= 0;
+}
+
+export function assertPublishTag(version, requestedTag) {
+  const parsed = parseReleaseVersion(version);
+  const actual = String(requestedTag || (parsed.prerelease ? "latest" : "latest")).trim().toLowerCase();
+  if (actual !== parsed.npmTag) {
+    throw new Error(`${parsed.raw} must be published with npm dist-tag ${parsed.npmTag}, not ${actual || "<empty>"}`);
+  }
+  return parsed.npmTag;
+}
+
+export function assertSoakEligiblePrerelease(version) {
+  const parsed = parseReleaseVersion(version);
+  if (!parsed.prerelease || !["beta", "rc"].includes(parsed.channel)) {
+    throw new Error("stable-release soak requires a published beta or rc version");
+  }
+  return parsed;
+}
+
+export function assertStablePromotion(stableVersion, prereleaseVersion) {
+  const stable = parseReleaseVersion(stableVersion);
+  const prerelease = assertSoakEligiblePrerelease(prereleaseVersion);
+  if (stable.prerelease) throw new Error("stable promotion target must not contain a prerelease suffix");
+  if (stable.baseVersion !== prerelease.baseVersion) {
+    throw new Error(`prerelease ${prerelease.raw} cannot promote to unrelated stable version ${stable.raw}`);
+  }
+  return { stable, prerelease };
+}
+
+export function minimumSoakSeconds(baseVersion, previousStableVersion = "") {
+  const target = parseReleaseVersion(baseVersion);
+  if (target.prerelease) throw new Error("minimum soak target must be a stable base version");
+  if (!previousStableVersion) {
+    if (target.minor === 0 && target.patch === 0) return SOAK_SECONDS.major;
+    if (target.patch === 0) return SOAK_SECONDS.minor;
+    return SOAK_SECONDS.patch;
+  }
+  const previous = parseReleaseVersion(previousStableVersion);
+  if (previous.prerelease) throw new Error("previous stable version must not be a prerelease");
+  if (compareReleaseVersions(target, previous) <= 0) throw new Error("target stable version must be newer than the previous stable version");
+  if (target.major !== previous.major) return SOAK_SECONDS.major;
+  if (target.minor !== previous.minor) return SOAK_SECONDS.minor;
+  return SOAK_SECONDS.patch;
+}
+
+export function formatSoakDuration(seconds) {
+  const value = Number(seconds);
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error("soak duration must be a non-negative integer");
+  if (value % (24 * 60 * 60) === 0) return `${value / (24 * 60 * 60)}d`;
+  if (value % (60 * 60) === 0) return `${value / (60 * 60)}h`;
+  return `${value}s`;
+}

package/scripts/release-impact-check.mjs

@@ -2,12 +2,17 @@
 
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { compareReleaseVersions, parseReleaseVersion } from "./release-channel.mjs";
+import { createTrustedGitResolver } from "../src/local/trusted-git-executable.mjs";
 
 const VERSION_TAG = /^v(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
 
-const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-const current = parseVersion(String(pkg.version || ""));
-if (!current) fail("package.json contains an invalid version");
+const root = new URL("../", import.meta.url);
+const pkg = JSON.parse(readFileSync(new URL("package.json", root), "utf8"));
+const gitExecutable = createTrustedGitResolver({ workspace: fileURLToPath(root) });
+let current;
+try { current = parseReleaseVersion(String(pkg.version || "")); } catch { fail("package.json contains an invalid version"); }
 
 const tags = git(["tag", "--merged", "HEAD", "--sort=-version:refname", "--list", "v[0-9]*"])
   .split("\n")
@@ -19,7 +24,7 @@ if (!tags.length) {
 }
 
 const latestTag = tags[0];
-const latest = parseVersion(latestTag.slice(1));
+const latest = parseReleaseVersion(latestTag.slice(1));
 const changed = new Set([
   ...lines(git(["diff", "--name-only", latestTag, "--"])),
   ...lines(git(["ls-files", "--others", "--exclude-standard"])),
@@ -35,11 +40,11 @@ if (!packageRelevant.length) {
   process.stderr.write(`release impact check ok: ${relevant.length} repository-only file(s) changed since ${latestTag}; npm package content is unchanged\n`);
   process.exit(0);
 }
-if (compareVersions(current, latest) <= 0) {
+if (compareReleaseVersions(current, latest) <= 0) {
   fail(`npm-package changes exist since ${latestTag}, but package.json is still ${pkg.version}; bump the npm version and add a CHANGELOG section before merging`);
 }
 
-const changelog = readFileSync(new URL("../CHANGELOG.md", import.meta.url), "utf8");
+const changelog = readFileSync(new URL("CHANGELOG.md", root), "utf8");
 const heading = new RegExp(`^## ${escapeRegExp(pkg.version)}(?:\\s+-[^\\n]*)?$`, "m");
 if (!heading.test(changelog)) fail(`CHANGELOG.md has no section for ${pkg.version}`);
 
@@ -58,7 +63,7 @@ export function isPackageRelevant(path, packageFiles = []) {
 
 function git(args) {
   try {
-    return execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    return execFileSync(gitExecutable(), args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
   } catch (error) {
     const detail = String(error?.stderr || error?.message || error).trim();
     fail(`git ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
@@ -69,21 +74,6 @@ function lines(value) {
   return value ? value.split("\n").map((item) => item.trim()).filter(Boolean) : [];
 }
 
-function parseVersion(value) {
-  const match = String(value).match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
-  return match ? { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]), prerelease: match[4] || "" } : null;
-}
-
-function compareVersions(left, right) {
-  for (const key of ["major", "minor", "patch"]) {
-    if (left[key] !== right[key]) return left[key] - right[key];
-  }
-  if (left.prerelease === right.prerelease) return 0;
-  if (!left.prerelease) return 1;
-  if (!right.prerelease) return -1;
-  return left.prerelease.localeCompare(right.prerelease);
-}
-
 function escapeRegExp(value) {
   return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }