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

package/scripts/privacy-check.mjs

@@ -3,9 +3,11 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { readBoundedRegularFileSync } from "../src/local/secure-file.mjs";
+import { createTrustedGitResolver } from "../src/local/trusted-git-executable.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const selfPath = "scripts/privacy-check.mjs";
+const gitExecutable = createTrustedGitResolver({ workspace: root });
 const requestedOptions = new Set(process.argv.slice(2));
 for (const option of requestedOptions) {
   if (option !== "--history") throw new Error(`unknown privacy-check option: ${option}`);
@@ -68,11 +70,17 @@ process.stderr.write(`privacy check ok (${candidates.length} tracked/unignored f
 
 function collectCandidateFiles(directory) {
   try {
-    return execFileSync("git", ["-C", directory, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+    const listed = execFileSync(gitExecutable(), ["-C", directory, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
       encoding: "buffer",
       maxBuffer: 32 * 1024 * 1024,
       stdio: ["ignore", "pipe", "ignore"],
-    }).toString("utf8").split("\0").filter(Boolean).sort();
+    }).toString("utf8").split("\0").filter(Boolean);
+    const deleted = new Set(execFileSync(gitExecutable(), ["-C", directory, "ls-files", "-z", "--deleted"], {
+      encoding: "buffer",
+      maxBuffer: 32 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).toString("utf8").split("\0").filter(Boolean));
+    return listed.filter((relativePath) => !deleted.has(relativePath)).sort();
   } catch {
     const excluded = new Set([".git", ".wrangler", "node_modules"]);
     const files = [];
@@ -98,7 +106,7 @@ function collectCandidateFiles(directory) {
 function scanReachableHistory(directory, entries, out) {
   let listing;
   try {
-    listing = execFileSync("git", ["-C", directory, "rev-list", "--objects", "--all", "-z"], {
+    listing = execFileSync(gitExecutable(), ["-C", directory, "rev-list", "--objects", "--all", "-z"], {
       encoding: "buffer",
       maxBuffer: 64 * 1024 * 1024,
       stdio: ["ignore", "pipe", "pipe"],
@@ -130,7 +138,7 @@ function scanReachableHistory(directory, entries, out) {
   const hashes = [...objectPaths.keys()];
   let metadata;
   try {
-    metadata = execFileSync("git", ["-C", directory, "cat-file", "--batch-check=%(objectname) %(objecttype) %(objectsize)"], {
+    metadata = execFileSync(gitExecutable(), ["-C", directory, "cat-file", "--batch-check=%(objectname) %(objecttype) %(objectsize)"], {
       input: `${hashes.join("\n")}\n`,
       encoding: "utf8",
       maxBuffer: 64 * 1024 * 1024,
@@ -162,7 +170,7 @@ function scanReachableHistory(directory, entries, out) {
     }
     let buffer;
     try {
-      buffer = execFileSync("git", ["-C", directory, "cat-file", "blob", hash], {
+      buffer = execFileSync(gitExecutable(), ["-C", directory, "cat-file", "blob", hash], {
         encoding: "buffer",
         maxBuffer: 6 * 1024 * 1024,
         stdio: ["ignore", "pipe", "pipe"],
@@ -194,7 +202,7 @@ function scanReachableHistory(directory, entries, out) {
 function scanReachableCommitMessages(directory, entries, out) {
   let output;
   try {
-    output = execFileSync("git", ["-C", directory, "log", "--all", "--format=%H%x00%B%x00"], {
+    output = execFileSync(gitExecutable(), ["-C", directory, "log", "--all", "--format=%H%x00%B%x00"], {
       encoding: "buffer",
       maxBuffer: 64 * 1024 * 1024,
       stdio: ["ignore", "pipe", "pipe"],

package/scripts/promotion-digest.mjs

@@ -0,0 +1,128 @@
+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";
+import { nestedNpmEnvironment } from "../src/local/npm-environment.mjs";
+import { releaseCommandFailure } from "./release-diagnostic.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",
+    "--workspaces=false",
+    "--global=false",
+    "--prefix", root,
+    "--ignore-scripts",
+    "--silent",
+    "--dry-run",
+    "--json",
+  ], {
+    cwd: root,
+    encoding: "utf8",
+    env: nestedNpmEnvironment(process.env),
+    timeout: 5 * 60 * 1000,
+    killSignal: "SIGKILL",
+    maxBuffer: 8 * 1024 * 1024,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) throw new Error(releaseCommandFailure("npm", ["pack"], result));
+  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,260 @@
+#!/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";
+import { nestedNpmEnvironment } from "../src/local/npm-environment.mjs";
+import { createHardenedNpmSession } from "./hardened-npm-session.mjs";
+import { normalizePackRecord, verifyCurrentReleaseAcceptance } from "./release-acceptance.mjs";
+import { stageAcceptedCandidateTarball } from "./accepted-candidate-tarball.mjs";
+import { readPublishedNpmPrereleaseIfPresent } from "./published-release.mjs";
+import { isTransientNetworkFailure } from "./network-retry.mjs";
+import { releaseCommandFailure, releaseDiagnosticEvent } from "./release-diagnostic.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", "--dry-run=false", "--workspaces=false", "--global=false", "--ignore-scripts=true", "--if-present=false", "--access=public", "--tag", parsed.npmTag];
+}
+
+export async function publishCurrentNpmPackage(repositoryRoot, mode, options = {}) {
+  const repository = resolve(repositoryRoot);
+  const pkg = JSON.parse(readFileSync(resolve(repository, "package.json"), "utf8"));
+  const parsed = parseReleaseVersion(pkg.version);
+  const publishArgs = npmPublishArguments(parsed.raw, mode);
+  const explicitNpmCli = String(options.npmCli || "").trim();
+  const lifecycleNpmCli = String(options.lifecycleNpmCli || process.env.npm_execpath || explicitNpmCli).trim();
+  if (!lifecycleNpmCli) throw new Error("npm publication must run through npm so npm_execpath is available");
+  if (!parsed.prerelease && requiresSoakForStable(parsed.raw)) {
+    verifyCurrentStableSoak(repository, { npmCli: lifecycleNpmCli });
+  }
+  const acceptance = options.acceptance || verifyCurrentReleaseAcceptance(repository, {
+    npmCli: lifecycleNpmCli,
+    env: options.env || process.env,
+  });
+  if (acceptance.required !== true) throw new Error("npm publication requires current local candidate acceptance");
+  const prepareCandidate = options.prepareCandidate || stageAcceptedCandidateTarball;
+  const candidate = prepareCandidate(repository, acceptance, options);
+  if (!candidate?.path) throw new Error("npm publication candidate tarball path is missing");
+
+  const createSession = options.createSession || createHardenedNpmSession;
+  const run = options.run || spawnSync;
+  const processOptions = {
+    cwd: repository,
+    encoding: "utf8",
+    env: nestedNpmEnvironment(options.env || process.env),
+    stdio: options.capture ? "pipe" : "inherit",
+    timeout: 10 * 60 * 1000,
+    killSignal: "SIGKILL",
+    maxBuffer: 8 * 1024 * 1024,
+    windowsHide: true,
+  };
+  let session = null;
+  let publication = null;
+  let primaryError = null;
+  try {
+    session = explicitNpmCli ? null : await createSession(options);
+    const npmCli = explicitNpmCli || session.cli;
+    runNpmStage(run, npmCli, [
+      "run", "--dry-run=false", "--workspaces=false", "--global=false", "--ignore-scripts=false",
+      "--if-present=false", "--tag", parsed.npmTag, "--prefix", repository, "prepublishOnly",
+    ], processOptions, "npm prepublication verification");
+    const preflightArgs = [
+      publishArgs[0], candidate.path,
+      ...publishArgs.slice(1).map((value) => value === "--dry-run=false" ? "--dry-run=true" : value),
+      "--json", "--prefix", repository,
+    ];
+    const preflight = runNpmStage(run, npmCli, preflightArgs, { ...processOptions, stdio: "pipe" }, "npm publish dry-run");
+    validateNpmPublishDryRun(preflight.stdout, acceptance.metadata);
+    const readPublished = options.readPublished || ((name, version, tag) => readPublishedNpmPrereleaseIfPresent(
+      name, version, tag, { npmCli, env: options.env || process.env },
+    ));
+    const preexisting = await readPublished(acceptance.metadata.package_name, parsed.raw, parsed.npmTag);
+    if (preexisting) {
+      assertPublishedCandidate(preexisting, acceptance.metadata, parsed.npmTag);
+      publication = publicationResult(parsed, acceptance.metadata, { alreadyPublished: true });
+    } else {
+      let uploadError = null;
+      try {
+        runNpmStage(run, npmCli, [
+          publishArgs[0], candidate.path, ...publishArgs.slice(1), "--prefix", repository,
+        ], processOptions, "npm publish");
+      } catch (error) {
+        uploadError = error;
+      }
+      let reconciled = null;
+      let reconciliationError = null;
+      try {
+        reconciled = await waitForPublishedCandidate({
+          readPublished,
+          packageName: acceptance.metadata.package_name,
+          version: parsed.raw,
+          tag: parsed.npmTag,
+          metadata: acceptance.metadata,
+          attempts: options.reconciliationAttempts,
+          wait: options.wait,
+        });
+      } catch (error) {
+        reconciliationError = error;
+      }
+      if (reconciled) {
+        publication = publicationResult(parsed, acceptance.metadata, {
+          recovered: Boolean(uploadError),
+          recoveryWarning: uploadError
+            ? "npm upload returned an error, but the registry now exposes the exact accepted bytes"
+            : "",
+        });
+      } else if (uploadError && reconciliationError) {
+        throw new AggregateError(
+          [uploadError, reconciliationError],
+          "npm publication outcome is ambiguous because upload and registry reconciliation both failed",
+        );
+      } else if (uploadError) {
+        throw new Error(
+          "npm publication outcome is ambiguous: the upload command returned an error and the exact version is not yet visible; do not retry until registry state is checked",
+          { cause: uploadError },
+        );
+      } else if (reconciliationError) {
+        throw new Error(
+          "npm upload returned success, but registry identity verification failed; publication state is ambiguous and must be checked before retrying",
+          { cause: reconciliationError },
+        );
+      } else {
+        throw new Error("npm upload returned success, but the exact accepted version is not yet visible in the registry; do not retry until registry state is checked");
+      }
+    }
+  } catch (error) {
+    primaryError = error;
+  }
+  const cleanupErrors = disposePublicationResources([session, candidate]);
+  if (primaryError) {
+    if (cleanupErrors.length) {
+      throw new AggregateError(
+        [primaryError, ...cleanupErrors],
+        "npm publication failed and temporary cleanup was incomplete",
+      );
+    }
+    throw primaryError;
+  }
+  if (cleanupErrors.length) publication.cleanupWarning = cleanupErrors.map(boundedCleanupWarning).join("; ").slice(0, 600);
+  return publication;
+}
+
+function disposePublicationResources(resources) {
+  const errors = [];
+  for (const resource of resources) {
+    try { resource?.dispose?.(); } catch (error) { errors.push(error); }
+  }
+  return errors;
+}
+
+export function validateNpmPublishDryRun(stdout, metadata) {
+  let value;
+  try { value = JSON.parse(String(stdout || "")); }
+  catch { throw new Error("npm publish dry-run did not return valid JSON"); }
+  const record = normalizePackRecord(value, metadata.package_name);
+  if (!record) throw new Error("npm publish dry-run did not return package metadata");
+  const expected = {
+    name: metadata.package_name,
+    version: metadata.package_version,
+    filename: metadata.filename,
+    shasum: metadata.shasum,
+    integrity: metadata.integrity,
+  };
+  for (const [key, expectedValue] of Object.entries(expected)) {
+    if (String(record[key] || "") !== expectedValue) {
+      throw new Error(`npm publish dry-run ${key} does not match the accepted candidate`);
+    }
+  }
+  return Object.freeze(expected);
+}
+
+function runNpmStage(run, npmCli, args, options, label) {
+  const result = run(process.execPath, [npmCli, ...args], options);
+  if (result.error || result.status !== 0) {
+    const error = new Error(`${label} failed: ${releaseCommandFailure("npm", args, result, { maxChars: 1200 })}`, result.error ? { cause: result.error } : undefined);
+    error.transient = isTransientNetworkFailure(result);
+    error.commandStatus = result.status;
+    throw error;
+  }
+  return result;
+}
+
+function publicationResult(parsed, metadata, options = {}) {
+  return {
+    version: parsed.raw,
+    tag: parsed.npmTag,
+    shasum: metadata.shasum,
+    integrity: metadata.integrity,
+    alreadyPublished: options.alreadyPublished === true,
+    recovered: options.recovered === true,
+    recoveryWarning: String(options.recoveryWarning || ""),
+    cleanupWarning: "",
+  };
+}
+
+async function waitForPublishedCandidate({
+  readPublished, packageName, version, tag, metadata, attempts = 5, wait = defaultPublicationWait,
+}) {
+  const maximumAttempts = Number.isSafeInteger(Number(attempts))
+    ? Math.min(Math.max(Number(attempts), 1), 10)
+    : 5;
+  const pause = typeof wait === "function" ? wait : defaultPublicationWait;
+  let lastTransientError = null;
+  for (let attempt = 1; attempt <= maximumAttempts; attempt += 1) {
+    try {
+      const published = await readPublished(packageName, version, tag);
+      if (published) return assertPublishedCandidate(published, metadata, tag);
+    } catch (error) {
+      const eventuallyConsistent = new Set(["npm_dist_tag_mismatch", "npm_publication_metadata_incomplete"]);
+      if (error?.transient !== true && !eventuallyConsistent.has(String(error?.code || ""))) throw error;
+      lastTransientError = error;
+    }
+    if (attempt < maximumAttempts) await pause(attempt);
+  }
+  if (lastTransientError) throw lastTransientError;
+  return null;
+}
+
+function assertPublishedCandidate(published, metadata, tag) {
+  if (published.version !== metadata.package_version
+      || published.shasum !== metadata.shasum
+      || published.integrity !== metadata.integrity
+      || published.distTag !== tag) {
+    throw new Error("npm registry version or dist-tag does not match the exact accepted candidate");
+  }
+  return published;
+}
+
+function defaultPublicationWait(attempt) {
+  return new Promise((resolvePromise) => { setTimeout(resolvePromise, Math.min(4_000, attempt * 1_000)); });
+}
+
+function boundedCleanupWarning(error) {
+  return String(error?.message || error || "temporary cleanup failed")
+    .replace(/[\r\n\t]+/g, " ")
+    .slice(0, 600);
+}
+
+async function main() {
+  const mode = process.argv[2] || "";
+  const result = await publishCurrentNpmPackage(root, mode);
+  if (result.recoveryWarning) console.warn(result.recoveryWarning);
+  if (result.cleanupWarning) console.warn(`npm publication succeeded but temporary hardened npm cleanup was incomplete: ${result.cleanupWarning}`);
+  const disposition = result.alreadyPublished ? "already matched" : result.recovered ? "reconciled" : "completed";
+  console.log(`npm publication ${disposition}: ${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(JSON.stringify(releaseDiagnosticEvent("npm.publish.failed", error?.message || error, 1600)));
+    process.exitCode = 1;
+  });
+}

package/scripts/published-release.mjs

@@ -0,0 +1,132 @@
+import { resolveTrustedGithubCli } from "../src/local/trusted-github-cli.mjs";
+import { nestedNpmEnvironment } from "../src/local/npm-environment.mjs";
+import { githubReleaseByTagEndpoint, normalizeGithubReleaseAsset } from "./github-release-asset.mjs";
+import { isTransientNetworkFailure, runNetworkCommand } from "./network-retry.mjs";
+import { releaseCommandFailure } from "./release-diagnostic.mjs";
+
+export function readPublishedNpmPrereleaseIfPresent(name, version, distTag, options = {}) {
+  try {
+    return readPublishedNpmPrerelease(name, version, distTag, options);
+  } catch (error) {
+    if (error?.code === "npm_version_not_found") return null;
+    throw error;
+  }
+}
+
+export function readPublishedNpmPrerelease(name, version, distTag, options = {}) {
+  const run = options.run || ((args) => runNpmView(args, options));
+  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 publicationMetadataError("npm registry returned another prerelease version", "npm_version_mismatch");
+  if (tags?.[distTag] !== requestedVersion) {
+    throw publicationMetadataError(`npm dist-tag ${distTag} does not point to ${requestedVersion}`, "npm_dist_tag_mismatch");
+  }
+  if (!/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(integrity)) throw publicationMetadataError("npm prerelease integrity is invalid", "npm_integrity_invalid");
+  if (!/^[0-9a-f]{40}$/.test(shasum)) throw publicationMetadataError("npm prerelease SHA-1 is invalid", "npm_shasum_invalid");
+  if (!Number.isFinite(Date.parse(publishedAt))) {
+    throw publicationMetadataError("npm prerelease publication timestamp is invalid", "npm_publication_metadata_incomplete");
+  }
+  return Object.freeze({ version, integrity, shasum, distTag, publishedAt: new Date(Date.parse(publishedAt)).toISOString() });
+}
+
+function publicationMetadataError(message, code) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function unwrapNpmJsonValue(value) {
+  return Array.isArray(value) && value.length === 1 ? value[0] : value;
+}
+
+export function readGithubPrerelease(version, options = {}) {
+  const run = options.run || runGh;
+  const tag = `v${version}`;
+  const value = run(["release", "view", tag, "--json", "tagName,isPrerelease,publishedAt,assets"]);
+  const normalized = normalizeGithubPrerelease(value, version);
+  const expectedSha256 = String(options.expectedArtifactSha256 || "");
+  if (!expectedSha256) return normalized;
+  const assetRun = options.assetRun || runGh;
+  const release = assetRun(["api", githubReleaseByTagEndpoint(tag)]);
+  const verifiedAsset = normalizeGithubReleaseAsset(release, {
+    tag,
+    assetName: normalized.asset.name,
+    expectedSha256,
+  });
+  if (verifiedAsset.size !== normalized.asset.size) {
+    throw new Error("GitHub prerelease asset size differs between release metadata and REST digest evidence");
+  }
+  return Object.freeze({ ...normalized, asset: verifiedAsset });
+}
+
+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, options = {}) {
+  const npmCli = options.npmCli || process.env.npm_execpath;
+  if (!npmCli) throw new Error("npm registry verification must run through npm");
+  const result = runNetworkCommand(process.execPath, [npmCli, "view", "--workspaces=false", "--global=false", ...args], {
+    env: nestedNpmEnvironment(options.env || process.env),
+    timeoutMs: options.timeoutMs,
+  });
+  if (result.error || result.status !== 0) {
+    const detail = String(result.stderr || result.stdout || result.error?.message || "");
+    const error = new Error(releaseCommandFailure("npm", ["view"], result));
+    if (/\bE404\b|is not in this registry/i.test(detail)) error.code = "npm_version_not_found";
+    else {
+      error.code = "npm_registry_query_failed";
+      error.transient = isTransientNetworkFailure(result);
+    }
+    throw error;
+  }
+  try { return JSON.parse(result.stdout); } catch { throw new Error(`npm view ${args[0]} returned invalid JSON`); }
+}
+
+function runGh(args) {
+  const result = runNetworkCommand(resolveTrustedGithubCli({ workspace: process.cwd() }), args, {
+    env: process.env,
+    timeoutMs: 120_000,
+  });
+  if (result.error || result.status !== 0) throw new Error(releaseCommandFailure("gh", args, result));
+  try { return JSON.parse(result.stdout); } catch { throw new Error("GitHub prerelease query returned invalid JSON"); }
+}