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

package/scripts/install-published-prerelease.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defaultStateRoot, expandHome } from "../src/local/state.mjs";
+import { writePrereleaseActivation } from "./prerelease-activation.mjs";
+import { computePromotionContentDigest } from "./promotion-digest.mjs";
+import { readPublishedNpmPrerelease } from "./published-release.mjs";
+import { verifyCurrentReleaseAcceptance } from "./release-acceptance.mjs";
+import { assertSoakEligiblePrerelease } from "./release-channel.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const npmCli = process.env.npm_execpath;
+let previousInstallation = null;
+let installedPrerelease = "";
+if (!npmCli) fail("published prerelease installation must run through npm");
+
+try {
+  if (!process.argv.includes("--allow-worker-deploy")) {
+    throw new Error("published prerelease activation updates the global package, same-name Worker, and login daemon; rerun with --allow-worker-deploy");
+  }
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  const requested = argumentValue("--version") || pkg.version;
+  const prerelease = assertSoakEligiblePrerelease(requested);
+  if (pkg.version !== prerelease.raw) {
+    throw new Error(`source checkout version ${pkg.version} does not match requested prerelease ${prerelease.raw}`);
+  }
+  const acceptance = verifyCurrentReleaseAcceptance(root);
+  if (!acceptance.required || acceptance.metadata.package_version !== prerelease.raw) {
+    throw new Error("published prerelease installation requires the locally accepted exact prerelease source");
+  }
+  const promotionDigest = computePromotionContentDigest(root);
+  if (acceptance.record.promotion_content_sha256 !== promotionDigest) {
+    throw new Error("current source promotion digest does not match local candidate acceptance");
+  }
+  const published = readPublishedNpmPrerelease(pkg.name, prerelease.raw, prerelease.npmTag);
+  if (published.integrity !== acceptance.metadata.integrity || published.shasum !== acceptance.metadata.shasum) {
+    throw new Error("npm prerelease bytes do not match the locally accepted candidate");
+  }
+
+  previousInstallation = currentGlobalInstallation(pkg.name);
+  runNpm([
+    "install", "--global", "--omit=optional",
+    "--allow-scripts=esbuild,workerd,sharp,fsevents",
+    `${pkg.name}@${prerelease.raw}`,
+  ]);
+  const installed = currentGlobalInstallation(pkg.name);
+  if (!installed || installed.version !== prerelease.raw) {
+    throw new Error(`global prerelease installation did not converge on ${prerelease.raw}`);
+  }
+  installedPrerelease = prerelease.raw;
+
+  const stateRoot = resolve(expandHome(argumentValue("--state-dir") || defaultStateRoot()));
+  const forwarded = forwardedActivationArgs();
+  const activation = runActivation(installed.entry, ["activate", ...forwarded, "--state-dir", stateRoot, "--json"]);
+  if (activation.version !== prerelease.raw || activation.daemon?.version !== prerelease.raw || activation.worker?.health?.version !== prerelease.raw) {
+    throw new Error("published prerelease activation did not converge on the exact registry version");
+  }
+  const recordPath = writePrereleaseActivation({
+    schema_version: 1,
+    package_name: pkg.name,
+    package_version: prerelease.raw,
+    source: "npm-prerelease",
+    shasum: published.shasum,
+    integrity: published.integrity,
+    promotion_content_sha256: promotionDigest,
+    activated_at: new Date().toISOString(),
+    published_at: published.publishedAt,
+    npm_dist_tag: prerelease.npmTag,
+    workspace_hash: workspaceHash(activation.workspace),
+    runtime_entry: installed.entry,
+    ...(previousInstallation ? { previous: previousInstallation } : {}),
+  }, stateRoot);
+
+  console.log(`Published prerelease activated: ${prerelease.raw}`);
+  console.log(`Worker and login daemon version: ${activation.version}`);
+  console.log(`Soak activation record: ${recordPath}`);
+  console.log("Use this prerelease normally. Any blocking issue requires a new beta/rc version and restarts the soak clock.");
+} catch (error) {
+  const message = boundedDiagnostic(error?.message || error);
+  if (installedPrerelease) {
+    const previousVersion = previousInstallation?.version || "unknown";
+    fail(`${message}. The global package is now ${installedPrerelease}, but Worker/service activation may not have converged. Previous global version: ${previousVersion}. Preserve state and logs; fix forward with the exact prerelease or restore package, Worker, service definition, browser extension, and state as one verified unit.`);
+  }
+  fail(message);
+}
+
+function currentGlobalInstallation(packageName) {
+  try {
+    const globalRoot = runNpm(["root", "--global"]).stdout.trim();
+    const packageRoot = join(globalRoot, packageName);
+    const packagePath = join(packageRoot, "package.json");
+    const entry = join(packageRoot, "bin", "machine-mcp.mjs");
+    if (!existsSync(packagePath) || !existsSync(entry)) return null;
+    const value = JSON.parse(readFileSync(packagePath, "utf8"));
+    return { version: String(value.version || ""), entry };
+  } catch {
+    return null;
+  }
+}
+
+function runActivation(entry, args) {
+  const result = spawnSync(process.execPath, [entry, ...args], {
+    cwd: root,
+    env: process.env,
+    encoding: "utf8",
+    timeout: 300_000,
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`prerelease runtime activation failed: ${boundedDiagnostic(result.stderr || result.stdout)}`);
+  try { return JSON.parse(result.stdout); } catch { throw new Error("prerelease runtime activation did not return valid JSON"); }
+}
+
+function runNpm(args) {
+  const result = spawnSync(process.execPath, [npmCli, ...args], {
+    cwd: root,
+    env: process.env,
+    encoding: "utf8",
+    timeout: 300_000,
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`npm ${args[0]} failed: ${boundedDiagnostic(result.stderr || result.stdout)}`);
+  return result;
+}
+
+function forwardedActivationArgs() {
+  const out = [];
+  const skipWithValue = new Set(["--version", "--state-dir"]);
+  for (let index = 2; index < process.argv.length; index += 1) {
+    const value = process.argv[index];
+    if (value === "--allow-worker-deploy") continue;
+    if (skipWithValue.has(value)) { index += 1; continue; }
+    if (["--version=", "--state-dir="].some((prefix) => value.startsWith(prefix))) continue;
+    if (value === "--json" || value.startsWith("--json=")) continue;
+    out.push(value);
+  }
+  return out;
+}
+
+function argumentValue(name) {
+  const exact = process.argv.find((value) => value.startsWith(`${name}=`));
+  if (exact) return exact.slice(name.length + 1);
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : "";
+}
+
+function workspaceHash(workspace) {
+  const value = process.platform === "win32" ? String(workspace).toLowerCase() : String(workspace);
+  return createHash("sha256").update(value).digest("hex").slice(0, 24);
+}
+
+function boundedDiagnostic(value) {
+  const home = String(process.env.HOME || process.env.USERPROFILE || "");
+  let text = String(value || "unknown error").replace(/[\r\n\t]+/g, " ").trim();
+  if (home) text = text.split(home).join("<home>");
+  return text.slice(0, 1600);
+}
+
+function fail(message) {
+  console.error(`published prerelease installation failed: ${message}`);
+  process.exit(1);
+}

package/scripts/local-release-acceptance.mjs

@@ -5,14 +5,13 @@ import {
   mkdtempSync,
   readFileSync,
   rmSync,
-  writeFileSync,
 } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
-  ACCEPTANCE_CONFIRMATION,
+  acceptanceConfirmationForVersion,
   ACCEPTANCE_SCHEMA_VERSION,
   acceptancePath,
   packProject,
@@ -21,6 +20,10 @@ import {
   verifyCurrentReleaseAcceptance,
   verifyTarball,
 } from "./release-acceptance.mjs";
+import { computePromotionContentDigest } from "./promotion-digest.mjs";
+import { parseReleaseVersion } from "./release-channel.mjs";
+import { validateCandidateManifest } from "./release-candidate-manifest.mjs";
+import { replaceFileAtomicallySync } from "../src/local/exclusive-file.mjs";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const candidateDirectory = join(root, ".release-candidate");
@@ -48,14 +51,16 @@ function prepareCandidate() {
     schema_version: ACCEPTANCE_SCHEMA_VERSION,
     result: "pending",
     ...metadata,
+    promotion_content_sha256: computePromotionContentDigest(root),
     prepared_at: new Date().toISOString(),
   };
-  writeFileSync(candidateManifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  replaceFileAtomicallySync(candidateManifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
   const phrase = confirmationPhrase(pkg.name, pkg.version);
   console.log(`Release candidate created: ${join(candidateDirectory, metadata.filename)}`);
-  console.log("After the repository owner explicitly authorizes this exact candidate in the active conversation, the coding agent starts it through Machine Bridge with:");
-  console.log("npm run release:candidate:start -- --allow-worker-deploy");
-  console.log("The owner does not need to run a terminal authorization command. The coding agent keeps the candidate running while verifying connection readiness and representative functionality through Machine Bridge.");
+  console.log("The repository owner activates this exact candidate with one persistent owner-side command:");
+  parseReleaseVersion(pkg.version);
+  console.log("npm run release:candidate:activate -- --allow-worker-deploy");
+  console.log("The owner runs this one command. It installs the exact candidate in the private state root, updates the same-name Worker, verifies candidate relay readiness, replaces the login daemon, verifies the background handoff, and exits while the service remains active.");
   console.log("After that observed live verification succeeds, the coding agent records acceptance with:");
   console.log(`npm run release:accept -- --confirm \"${phrase}\"`);
   console.log("Automated tests alone do not authorize acceptance or the first GitHub push.");
@@ -68,10 +73,10 @@ function recordAcceptance() {
   if (supplied !== expected) {
     throw new Error(`interactive candidate verification confirmation must exactly match: ${expected}`);
   }
-  const pending = readJson(candidateManifestPath, "release candidate manifest");
-  if (pending.result !== "pending" || pending.package_name !== pkg.name || pending.package_version !== pkg.version) {
-    throw new Error("release candidate manifest does not match the current package");
-  }
+  const pending = validateCandidateManifest(readJson(candidateManifestPath, "release candidate manifest"), {
+    packageName: pkg.name,
+    packageVersion: pkg.version,
+  });
   verifyTarball(join(candidateDirectory, pending.filename), pending);
 
   const verificationDirectory = join(candidateDirectory, "verification");
@@ -84,10 +89,15 @@ function recordAcceptance() {
     }
   }
 
+  const promotionDigest = computePromotionContentDigest(root);
+  if (pending.promotion_content_sha256 !== promotionDigest) {
+    throw new Error("source changed after candidate preparation: promotion content digest no longer matches");
+  }
+
   const record = {
     schema_version: ACCEPTANCE_SCHEMA_VERSION,
     result: "passed",
-    confirmation: ACCEPTANCE_CONFIRMATION,
+    confirmation: acceptanceConfirmationForVersion(pkg.version),
     package_name: current.package_name,
     package_version: current.package_version,
     filename: current.filename,
@@ -95,11 +105,12 @@ function recordAcceptance() {
     integrity: current.integrity,
     accepted_at: new Date().toISOString(),
     package_content_sha256: computePortablePackageDigest(),
+    promotion_content_sha256: promotionDigest,
   };
   verifyAcceptanceRecord(record, current);
   const path = acceptancePath(root, pkg.version);
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  replaceFileAtomicallySync(path, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o644 });
   console.log(`Interactive local candidate acceptance recorded: ${path}`);
   console.log("Commit this record with the candidate. Any packaged-file change invalidates it.");
 }

package/scripts/npm-publication-policy.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { assertPublishTag, parseReleaseVersion } from "./release-channel.mjs";
+
+try {
+  const pkg = JSON.parse(readFileSync(resolve("package.json"), "utf8"));
+  const parsed = parseReleaseVersion(pkg.version);
+  const configured = String(process.env.npm_config_tag || "latest").trim().toLowerCase() || "latest";
+  assertPublishTag(parsed.raw, configured);
+  console.log(`npm publication channel verified: ${parsed.raw} -> ${parsed.npmTag}`);
+} catch (error) {
+  console.error(`npm publication policy failed: ${error?.message || error}`);
+  process.exit(1);
+}

package/scripts/prerelease-activation.mjs

@@ -0,0 +1,79 @@
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { defaultStateRoot, expandHome } from "../src/local/state.mjs";
+import { replaceFileAtomicallySync } from "../src/local/exclusive-file.mjs";
+import { ensureOwnerOnlyDirectorySync, readBoundedRegularFileSync } from "../src/local/secure-file.mjs";
+import { assertSoakEligiblePrerelease } from "./release-channel.mjs";
+
+export const ACTIVATION_SCHEMA_VERSION = 1;
+const MAX_ACTIVATION_BYTES = 64 * 1024;
+const SOURCES = new Set(["local-candidate", "npm-prerelease"]);
+
+export function prereleaseActivationPath(version, stateRoot = defaultStateRoot()) {
+  const parsed = assertSoakEligiblePrerelease(version);
+  return join(resolve(expandHome(stateRoot)), "release-channels", "activations", `v${parsed.raw}.json`);
+}
+
+export function writePrereleaseActivation(record, stateRoot = defaultStateRoot()) {
+  const normalized = validatePrereleaseActivation(record);
+  const file = prereleaseActivationPath(normalized.package_version, stateRoot);
+  ensureOwnerOnlyDirectorySync(dirname(file));
+  replaceFileAtomicallySync(file, `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600 });
+  return file;
+}
+
+export function readPrereleaseActivation(version, stateRoot = defaultStateRoot()) {
+  const file = prereleaseActivationPath(version, stateRoot);
+  if (!existsSync(file)) throw new Error(`prerelease activation record is missing: ${file}`);
+  let value;
+  try { value = JSON.parse(readBoundedRegularFileSync(file, MAX_ACTIVATION_BYTES, "prerelease activation record", { verifyPathIdentity: true }).toString("utf8")); }
+  catch (error) { throw new Error(`prerelease activation record is unavailable or invalid: ${error.message}`); }
+  return validatePrereleaseActivation(value);
+}
+
+export function validatePrereleaseActivation(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("prerelease activation record must be an object");
+  if (value.schema_version !== ACTIVATION_SCHEMA_VERSION) throw new Error("unsupported prerelease activation schema");
+  const parsed = assertSoakEligiblePrerelease(value.package_version);
+  if (value.package_name !== "machine-bridge-mcp") throw new Error("prerelease activation package name is invalid");
+  if (!SOURCES.has(value.source)) throw new Error("prerelease activation source is invalid");
+  if (!/^[0-9a-f]{40}$/.test(String(value.shasum || ""))) throw new Error("prerelease activation SHA-1 is invalid");
+  if (!/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(String(value.integrity || ""))) throw new Error("prerelease activation integrity is invalid");
+  if (!/^[0-9a-f]{64}$/.test(String(value.promotion_content_sha256 || ""))) throw new Error("prerelease activation promotion digest is invalid");
+  const activatedAt = Date.parse(String(value.activated_at || ""));
+  if (!Number.isFinite(activatedAt)) throw new Error("prerelease activation timestamp is invalid");
+  if (value.source === "npm-prerelease") {
+    if (value.npm_dist_tag !== parsed.npmTag) throw new Error("prerelease activation npm dist-tag is invalid");
+    const publishedAt = Date.parse(String(value.published_at || ""));
+    if (!Number.isFinite(publishedAt) || publishedAt > activatedAt + 5 * 60 * 1000) throw new Error("prerelease activation publication timestamp is invalid");
+  }
+  const workspaceHash = String(value.workspace_hash || "");
+  if (workspaceHash && !/^[0-9a-f]{24}$/.test(workspaceHash)) throw new Error("prerelease activation workspace hash is invalid");
+  const runtimeEntry = String(value.runtime_entry || "");
+  if (runtimeEntry && !isAbsolute(runtimeEntry)) throw new Error("prerelease activation runtime entry must be absolute");
+  let previous;
+  if (value.previous !== undefined) {
+    if (!value.previous || typeof value.previous !== "object" || Array.isArray(value.previous)) throw new Error("prerelease activation previous runtime is invalid");
+    const previousVersion = String(value.previous.version || "");
+    const previousEntry = String(value.previous.entry || "");
+    if (!previousVersion || !previousEntry || !isAbsolute(previousEntry)) throw new Error("prerelease activation previous runtime is invalid");
+    previous = { version: previousVersion, entry: previousEntry };
+  }
+  return Object.freeze({
+    schema_version: ACTIVATION_SCHEMA_VERSION,
+    package_name: value.package_name,
+    package_version: parsed.raw,
+    source: value.source,
+    shasum: value.shasum,
+    integrity: value.integrity,
+    promotion_content_sha256: value.promotion_content_sha256,
+    activated_at: new Date(activatedAt).toISOString(),
+    ...(value.source === "npm-prerelease" ? {
+      npm_dist_tag: value.npm_dist_tag,
+      published_at: new Date(Date.parse(value.published_at)).toISOString(),
+    } : {}),
+    ...(workspaceHash ? { workspace_hash: workspaceHash } : {}),
+    ...(runtimeEntry ? { runtime_entry: runtimeEntry } : {}),
+    ...(previous ? { previous } : {}),
+  });
+}

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,7 +70,7 @@ 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"], {
+    return execFileSync(gitExecutable(), ["-C", directory, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
       encoding: "buffer",
       maxBuffer: 32 * 1024 * 1024,
       stdio: ["ignore", "pipe", "ignore"],
@@ -98,7 +100,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 +132,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 +164,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 +196,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,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;
+  });
+}