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

package/scripts/release-acceptance.mjs

@@ -8,40 +8,31 @@ 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 { parseReleaseVersion } from "./release-channel.mjs";
+import { nestedNpmEnvironment } from "../src/local/npm-environment.mjs";
+import { releaseCommandFailure } from "./release-diagnostic.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 OWNER_STARTED_ACCEPTANCE_CONFIRMATION = "owner-started-agent-verified-local-candidate";
-export const LEGACY_ACCEPTANCE_CONFIRMATION = "repository-owner-local-test";
+export const ACCEPTANCE_CONFIRMATION = "owner-activated-agent-verified-persistent-candidate";
 const MAX_ACCEPTANCE_BYTES = 64 * 1024;
 const MAX_RELEASE_TARBALL_BYTES = 64 * 1024 * 1024;
 
-export function requiresLocalAcceptance(version) {
-  return compareVersions(parseVersion(version), parseVersion(ACCEPTANCE_POLICY_VERSION)) >= 0;
-}
-
-export function acceptanceConfirmationForVersion(version) {
-  const parsed = parseVersion(version);
-  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;
-}
-
 export function acceptancePath(root, version) {
   return join(root, "release-acceptance", `v${version}.json`);
 }
 
-export function packProject(root, destination) {
-  const npmCli = process.env.npm_execpath;
+export function packProject(root, destination, options = {}) {
+  const npmCli = options.npmCli || process.env.npm_execpath;
   if (!npmCli) {
     throw new Error("release acceptance commands must run through npm so npm_execpath is available");
   }
   const result = spawnSync(process.execPath, [
     npmCli,
     "pack",
+    "--dry-run=false",
+    "--workspaces=false",
+    "--global=false",
+    "--prefix", root,
     "--ignore-scripts",
     "--silent",
     "--json",
@@ -50,13 +41,13 @@ export function packProject(root, destination) {
   ], {
     cwd: root,
     encoding: "utf8",
-    env: process.env,
+    env: nestedNpmEnvironment(options.env || process.env),
+    timeout: 5 * 60 * 1000,
+    killSignal: "SIGKILL",
+    maxBuffer: 8 * 1024 * 1024,
     windowsHide: true,
   });
-  if (result.error) throw result.error;
-  if (result.status !== 0) {
-    throw new Error(`npm pack failed: ${String(result.stderr || result.stdout).trim()}`);
-  }
+  if (result.error || result.status !== 0) throw new Error(releaseCommandFailure("npm", ["pack"], result));
   let value;
   try {
     value = JSON.parse(result.stdout);
@@ -84,12 +75,12 @@ export function readAcceptance(root, version) {
   try {
     bytes = readBoundedRegularFileSync(
       path, MAX_ACCEPTANCE_BYTES, "release acceptance record",
-      { verifyPathIdentity: true },
+      { verifyPathIdentity: true, rejectMultipleLinks: true },
     );
   } catch (error) {
     const message = String(error?.message || error);
     if (message.includes("exceeds")) throw new Error(`release acceptance record exceeds ${MAX_ACCEPTANCE_BYTES} bytes`);
-    if (message.includes("regular file") || message.includes("symbolic link") || message.includes("identity changed")) {
+    if (message.includes("regular file") || message.includes("symbolic link") || message.includes("multiple links") || message.includes("identity changed")) {
       throw new Error(`release acceptance record must be a regular file: ${path}`);
     }
     throw error;
@@ -105,12 +96,17 @@ 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}`);
   }
   if (record.result !== "passed") throw new Error("local release acceptance result is not passed");
-  const expectedConfirmation = acceptanceConfirmationForVersion(metadata.package_version);
-  if (record.confirmation !== expectedConfirmation) {
+  if (record.confirmation !== ACCEPTANCE_CONFIRMATION) {
     throw new Error("local release acceptance confirmation is missing or does not match the active verification workflow");
   }
   const acceptedAt = Date.parse(String(record.accepted_at || ""));
@@ -118,28 +114,53 @@ 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 (!/^[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: ACCEPTANCE_CONFIRMATION,
+    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) {
+export function verifyCurrentReleaseAcceptance(root, options = {}) {
   const pkg = readPackage(root);
-  if (!requiresLocalAcceptance(pkg.version)) {
-    return { required: false, version: pkg.version };
-  }
   const temp = mkdtempSync(join(tmpdir(), "mbm-release-acceptance-"));
+  let result = null;
+  let primaryError = null;
   try {
-    const metadata = packProject(root, temp);
+    const metadata = packProject(root, temp, options);
     const record = readAcceptance(root, pkg.version);
     verifyAcceptanceRecord(record, metadata);
-    return { required: true, metadata, record };
-  } finally {
-    rmSync(temp, { recursive: true, force: true });
+    const bytes = verifyTarball(join(temp, metadata.filename), metadata);
+    const artifactSha256 = createHash("sha256").update(bytes).digest("hex");
+    result = { required: true, metadata, record, artifactSha256 };
+  } catch (error) {
+    primaryError = error;
+  }
+  let cleanupError = null;
+  try { rmSync(temp, { recursive: true, force: true }); }
+  catch (error) { cleanupError = error; }
+  if (primaryError && cleanupError) {
+    throw new AggregateError([primaryError, cleanupError], "release acceptance verification failed and temporary cleanup was incomplete");
   }
+  if (primaryError) throw primaryError;
+  if (cleanupError) throw cleanupError;
+  return result;
 }
 
 export function verifyTarball(path, metadata) {
@@ -147,11 +168,11 @@ export function verifyTarball(path, metadata) {
   try {
     bytes = readBoundedRegularFileSync(
       path, MAX_RELEASE_TARBALL_BYTES, "release candidate tarball",
-      { verifyPathIdentity: true },
+      { verifyPathIdentity: true, rejectMultipleLinks: true },
     );
   } catch (error) {
     const message = String(error?.message || error);
-    if (message.includes("regular file") || message.includes("symbolic link") || message.includes("identity changed")) {
+    if (message.includes("regular file") || message.includes("symbolic link") || message.includes("multiple hard links") || message.includes("identity changed")) {
       throw new Error("release candidate tarball is not a regular file");
     }
     throw error;
@@ -161,6 +182,7 @@ export function verifyTarball(path, metadata) {
   if (shasum !== metadata.shasum || integrity !== metadata.integrity) {
     throw new Error("release candidate tarball hash does not match npm pack metadata");
   }
+  return bytes;
 }
 
 export function normalizePackRecord(value, packageName) {
@@ -173,7 +195,7 @@ export function normalizePackRecord(value, packageName) {
 function readPackage(root) {
   const value = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
   if (typeof value.name !== "string" || !value.name) throw new Error("package.json name is invalid");
-  if (!parseVersion(value.version)) throw new Error("package.json version is invalid");
+  parseReleaseVersion(value.version);
   return value;
 }
 
@@ -184,17 +206,3 @@ function validatePackMetadata(metadata) {
   if (!/^[0-9a-f]{40}$/.test(metadata.shasum)) throw new Error("npm pack returned an invalid SHA-1 shasum");
   if (!/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(metadata.integrity)) throw new Error("npm pack returned an invalid SHA-512 integrity value");
 }
-
-function parseVersion(value) {
-  const match = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?$/.exec(String(value || ""));
-  if (!match) return null;
-  return [Number(match[1]), Number(match[2]), Number(match[3])];
-}
-
-function compareVersions(left, right) {
-  if (!left || !right) throw new Error("version comparison requires semantic versions");
-  for (let index = 0; index < 3; index += 1) {
-    if (left[index] !== right[index]) return left[index] - right[index];
-  }
-  return 0;
-}

package/scripts/release-browser-extension-store.mjs

@@ -0,0 +1,172 @@
+// @ts-check
+import {
+  closeSync, constants as fsConstants, fsyncSync, lstatSync, readSync,
+  readdirSync, rmdirSync, unlinkSync, writeSync,
+} from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { replaceFileSync } from "../src/local/atomic-fs.mjs";
+import { releaseBrowserExtensionPath } from "../src/local/browser-extension-path.mjs";
+import { ensureOwnerOnlyDirectorySync, inspectPathIfPresentSync, openRegularFileSync } from "../src/local/secure-file.mjs";
+
+const MANIFEST = "manifest.json";
+const MAX_EXTENSION_FILES = 256;
+const MAX_EXTENSION_FILE_BYTES = 8 * 1024 * 1024;
+const MAX_EXTENSION_TOTAL_BYTES = 32 * 1024 * 1024;
+
+export function publishReleaseBrowserExtension({ stateRoot, sourceDirectory, expectedVersion = "", beforeManifestCommit = null } = {}) {
+  const source = resolve(String(sourceDirectory || ""));
+  const destination = releaseBrowserExtensionPath(stateRoot);
+  const snapshot = snapshotExtensionTree(source);
+  if (!snapshot.files.some((entry) => entry.relative === MANIFEST)) throw new Error("release browser extension is missing manifest.json");
+  const manifest = parseManifest(snapshot.files.find((entry) => entry.relative === MANIFEST)?.bytes);
+  if (expectedVersion && manifest.version !== expectedVersion) {
+    throw new Error(`release browser extension version ${manifest.version} does not match ${expectedVersion}`);
+  }
+
+  ensureOwnerOnlyDirectorySync(dirname(destination));
+  ensureOwnerOnlyDirectorySync(destination);
+  validateDestinationTree(destination);
+  for (const directory of snapshot.directories) ensureOwnerOnlyDirectorySync(join(destination, directory));
+  for (const entry of snapshot.files.filter((item) => item.relative !== MANIFEST)) {
+    replaceStableFile(destination, entry.relative, entry.bytes);
+  }
+  removeStaleEntries(destination, snapshot);
+  if (typeof beforeManifestCommit === "function") beforeManifestCommit({ destination, version: manifest.version });
+  const manifestEntry = snapshot.files.find((entry) => entry.relative === MANIFEST);
+  replaceStableFile(destination, MANIFEST, manifestEntry.bytes);
+  verifyPublishedTree(destination, snapshot);
+  return { path: destination, version: manifest.version, file_count: snapshot.files.length };
+}
+
+function snapshotExtensionTree(source) {
+  const rootInfo = inspectPathIfPresentSync(source, "release browser extension source");
+  if (!rootInfo || rootInfo.isSymbolicLink() || !rootInfo.isDirectory()) {
+    throw new Error("release browser extension source must be a real directory");
+  }
+  const files = [];
+  const directories = [];
+  let totalBytes = 0;
+  const walk = (directory, relativeDirectory = "") => {
+    for (const entry of readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+      const relativePath = relativeDirectory ? join(relativeDirectory, entry.name) : entry.name;
+      const absolutePath = join(directory, entry.name);
+      const info = lstatSync(absolutePath);
+      if (info.isSymbolicLink()) throw new Error("release browser extension source must not contain symbolic links");
+      if (info.isDirectory()) {
+        directories.push(relativePath);
+        walk(absolutePath, relativePath);
+        continue;
+      }
+      if (!info.isFile()) throw new Error("release browser extension source contains an unsupported entry type");
+      if (files.length >= MAX_EXTENSION_FILES) throw new Error("release browser extension contains too many files");
+      const bytes = readRegularFile(absolutePath, MAX_EXTENSION_FILE_BYTES, "release browser extension source file");
+      totalBytes += bytes.length;
+      if (totalBytes > MAX_EXTENSION_TOTAL_BYTES) throw new Error("release browser extension exceeds the total byte budget");
+      files.push({ relative: relativePath, bytes });
+    }
+  };
+  walk(source);
+  return { files, directories };
+}
+
+function replaceStableFile(destination, relativePath, bytes) {
+  const target = join(destination, relativePath);
+  const targetInfo = inspectPathIfPresentSync(target, "stable browser extension target");
+  if (targetInfo && (targetInfo.isSymbolicLink() || !targetInfo.isFile())) {
+    throw new Error("stable browser extension target must be a regular file");
+  }
+  ensureOwnerOnlyDirectorySync(dirname(target));
+  const temporary = join(dirname(target), `.mbm-extension-${process.pid}-${randomBytes(8).toString("hex")}.tmp`);
+  let fd;
+  try {
+    const opened = openRegularFileSync(
+      temporary,
+      Number(fsConstants.O_WRONLY) | Number(fsConstants.O_CREAT) | Number(fsConstants.O_EXCL),
+      { label: "stable browser extension staging file", mode: 0o600, chmod: 0o600, rejectMultipleLinks: true },
+    );
+    fd = opened.fd;
+    let offset = 0;
+    while (offset < bytes.length) offset += writeSync(fd, bytes, offset, bytes.length - offset, offset);
+    fsyncSync(fd);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+  try { replaceFileSync(temporary, target); }
+  catch (error) { try { unlinkSync(temporary); } catch { /* Preserve the primary publication error; temp cleanup is best-effort. */ } throw error; }
+}
+
+function removeStaleEntries(destination, snapshot) {
+  const expectedFiles = new Set(snapshot.files.map((entry) => entry.relative));
+  const expectedDirectories = new Set(snapshot.directories);
+  const staleDirectories = [];
+  const walk = (directory, relativeDirectory = "") => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const relativePath = relativeDirectory ? join(relativeDirectory, entry.name) : entry.name;
+      const absolutePath = join(directory, entry.name);
+      const info = lstatSync(absolutePath);
+      if (info.isSymbolicLink()) throw new Error("stable browser extension must not contain symbolic links");
+      if (info.isDirectory()) {
+        walk(absolutePath, relativePath);
+        if (!expectedDirectories.has(relativePath)) staleDirectories.push(absolutePath);
+        continue;
+      }
+      if (!info.isFile()) throw new Error("stable browser extension contains an unsupported entry type");
+      if (!expectedFiles.has(relativePath)) unlinkSync(absolutePath);
+    }
+  };
+  walk(destination);
+  staleDirectories.sort((left, right) => right.length - left.length);
+  for (const directory of staleDirectories) rmdirSync(directory);
+}
+
+function validateDestinationTree(destination) {
+  const root = resolve(destination);
+  const walk = (directory) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const absolutePath = join(directory, entry.name);
+      const info = lstatSync(absolutePath);
+      if (info.isSymbolicLink()) throw new Error("stable browser extension must not contain symbolic links");
+      if (info.isDirectory()) { walk(absolutePath); continue; }
+      if (!info.isFile()) throw new Error("stable browser extension contains an unsupported entry type");
+      const rel = relative(root, absolutePath);
+      if (!rel || rel === ".." || rel.startsWith(`..${sep}`)) throw new Error("stable browser extension entry escaped its root");
+    }
+  };
+  walk(root);
+}
+
+function verifyPublishedTree(destination, snapshot) {
+  const actual = snapshotExtensionTree(destination);
+  const expectedFiles = new Map(snapshot.files.map((entry) => [entry.relative, entry.bytes]));
+  if (actual.files.length !== expectedFiles.size) throw new Error("stable browser extension file inventory does not match the candidate");
+  for (const entry of actual.files) {
+    const expected = expectedFiles.get(entry.relative);
+    if (!expected || !entry.bytes.equals(expected)) throw new Error("stable browser extension bytes do not match the candidate");
+  }
+}
+
+function readRegularFile(file, maximum, label) {
+  const opened = openRegularFileSync(file, fsConstants.O_RDONLY, { label, verifyPathIdentity: true });
+  try {
+    if (opened.info.size > maximum) throw new Error(`${label} exceeds ${maximum} bytes`);
+    const bytes = Buffer.alloc(opened.info.size);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const count = readSync(opened.fd, bytes, offset, bytes.length - offset, offset);
+      if (!count) break;
+      offset += count;
+    }
+    return bytes.subarray(0, offset);
+  } finally {
+    closeSync(opened.fd);
+  }
+}
+
+function parseManifest(bytes) {
+  let value;
+  try { value = JSON.parse(String(bytes || "")); } catch { throw new Error("release browser extension manifest is invalid JSON"); }
+  const version = typeof value?.version_name === "string" && value.version_name ? value.version_name : value?.version;
+  if (typeof version !== "string" || !version) throw new Error("release browser extension manifest has no version");
+  return { version };
+}

package/scripts/release-candidate-manifest.mjs

@@ -0,0 +1,52 @@
+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(),
+  });
+}
+
+export function assertCandidateMatchesCurrentSource(manifest, current) {
+  const packageName = String(current?.packageName || "");
+  const packageVersion = String(current?.packageVersion || "");
+  const promotionDigest = String(current?.promotionDigest || "");
+  if (manifest.package_name !== packageName || manifest.package_version !== packageVersion) {
+    throw new Error("release candidate is stale: package identity no longer matches the current source");
+  }
+  if (!/^[0-9a-f]{64}$/.test(promotionDigest) || manifest.promotion_content_sha256 !== promotionDigest) {
+    throw new Error("release candidate is stale: promotion content digest no longer matches the current source");
+  }
+}

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-diagnostic.mjs

@@ -0,0 +1,41 @@
+import os from "node:os";
+import process from "node:process";
+import { sanitizePortableLogText } from "../src/shared/log-redaction.mjs";
+
+const EVENT_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,79}$/;
+
+const HOME_PATHS = [...new Set([
+  process.env.HOME,
+  process.env.USERPROFILE,
+  safeHomeDirectory(),
+].filter((value) => typeof value === "string" && value.length > 1))];
+
+export function releaseDiagnostic(value, maxChars = 1000) {
+  return sanitizePortableLogText(value, { maxChars, homePaths: HOME_PATHS }).trim();
+}
+
+export function releaseDiagnosticEvent(event, value, maxChars = 1000) {
+  const name = String(event || "");
+  if (!EVENT_NAME_PATTERN.test(name)) throw new Error("release diagnostic event name is invalid");
+  return Object.freeze({ event: name, error: releaseDiagnostic(value, maxChars) });
+}
+
+export function releaseCommandLabel(command, args = []) {
+  const executable = String(command || "command").split(/[\\/]/).filter(Boolean).at(-1) || "command";
+  const first = Array.isArray(args) && args.length ? String(args[0] || "") : "";
+  return releaseDiagnostic(first ? `${executable} ${first}` : executable, 160);
+}
+
+export function releaseCommandFailure(command, args, result, options = {}) {
+  const label = releaseCommandLabel(command, args);
+  const detail = releaseDiagnostic([
+    result?.stderr,
+    result?.stdout,
+    result?.error?.message,
+  ].filter(Boolean).join("\n"), options.maxChars || 1000);
+  return `${label} failed${detail ? `: ${detail}` : ""}`;
+}
+
+function safeHomeDirectory() {
+  try { return os.homedir(); } catch { return ""; }
+}

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, "\\$&");
 }