machine-bridge-mcp 1.2.7 → 1.2.9

package/scripts/release-acceptance.mjs

@@ -0,0 +1,181 @@
+import { createHash } from "node:crypto";
+import {
+  lstatSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+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 ACCEPTANCE_CONFIRMATION = "owner-started-agent-verified-local-candidate";
+export const LEGACY_ACCEPTANCE_CONFIRMATION = "repository-owner-local-test";
+const MAX_ACCEPTANCE_BYTES = 64 * 1024;
+
+export function requiresLocalAcceptance(version) {
+  return compareVersions(parseVersion(version), parseVersion(ACCEPTANCE_POLICY_VERSION)) >= 0;
+}
+
+export function acceptanceConfirmationForVersion(version) {
+  return compareVersions(parseVersion(version), parseVersion(AGENT_VERIFIED_ACCEPTANCE_VERSION)) >= 0
+    ? ACCEPTANCE_CONFIRMATION
+    : 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;
+  if (!npmCli) {
+    throw new Error("release acceptance commands must run through npm so npm_execpath is available");
+  }
+  const result = spawnSync(process.execPath, [
+    npmCli,
+    "pack",
+    "--ignore-scripts",
+    "--silent",
+    "--json",
+    "--pack-destination",
+    destination,
+  ], {
+    cwd: root,
+    encoding: "utf8",
+    env: process.env,
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`npm pack failed: ${String(result.stderr || result.stdout).trim()}`);
+  }
+  let value;
+  try {
+    value = JSON.parse(result.stdout);
+  } catch {
+    throw new Error("npm pack did not return valid JSON");
+  }
+  const pkg = readPackage(root);
+  const record = normalizePackRecord(value, pkg.name);
+  if (!record) throw new Error("npm pack did not return package metadata");
+  const metadata = {
+    package_name: pkg.name,
+    package_version: pkg.version,
+    filename: String(record.filename || ""),
+    shasum: String(record.shasum || ""),
+    integrity: String(record.integrity || ""),
+  };
+  validatePackMetadata(metadata);
+  verifyTarball(join(destination, metadata.filename), metadata);
+  return metadata;
+}
+
+export function readAcceptance(root, version) {
+  const path = acceptancePath(root, version);
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`release acceptance record must be a regular file: ${path}`);
+  }
+  if (stat.size > MAX_ACCEPTANCE_BYTES) {
+    throw new Error(`release acceptance record exceeds ${MAX_ACCEPTANCE_BYTES} bytes`);
+  }
+  let value;
+  try {
+    value = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(`release acceptance record is not valid JSON: ${error.message}`);
+  }
+  return value;
+}
+
+export function verifyAcceptanceRecord(record, metadata) {
+  if (!record || typeof record !== "object" || Array.isArray(record)) {
+    throw new Error("release acceptance record must be an object");
+  }
+  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) {
+    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 || ""));
+  if (!Number.isFinite(acceptedAt)) throw new Error("local release acceptance timestamp is invalid");
+  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");
+  }
+  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;
+}
+
+export function verifyCurrentReleaseAcceptance(root) {
+  const pkg = readPackage(root);
+  if (!requiresLocalAcceptance(pkg.version)) {
+    return { required: false, version: pkg.version };
+  }
+  const temp = mkdtempSync(join(tmpdir(), "mbm-release-acceptance-"));
+  try {
+    const metadata = packProject(root, temp);
+    const record = readAcceptance(root, pkg.version);
+    verifyAcceptanceRecord(record, metadata);
+    return { required: true, metadata, record };
+  } finally {
+    rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+export function verifyTarball(path, metadata) {
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("release candidate tarball is not a regular file");
+  const bytes = readFileSync(path);
+  const shasum = createHash("sha1").update(bytes).digest("hex");
+  const integrity = `sha512-${createHash("sha512").update(bytes).digest("base64")}`;
+  if (shasum !== metadata.shasum || integrity !== metadata.integrity) {
+    throw new Error("release candidate tarball hash does not match npm pack metadata");
+  }
+}
+
+export function normalizePackRecord(value, packageName) {
+  if (Array.isArray(value)) return value[0] ?? null;
+  if (!value || typeof value !== "object") return null;
+  if (value[packageName] && typeof value[packageName] === "object") return value[packageName];
+  return Object.values(value).find((item) => item && typeof item === "object") ?? null;
+}
+
+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");
+  return value;
+}
+
+function validatePackMetadata(metadata) {
+  if (!metadata.filename.endsWith(".tgz") || metadata.filename.includes("/") || metadata.filename.includes("\\")) {
+    throw new Error("npm pack returned an invalid filename");
+  }
+  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-impact-check.mjs

@@ -25,20 +25,36 @@ const changed = new Set([
   ...lines(git(["ls-files", "--others", "--exclude-standard"])),
 ]);
 const relevant = [...changed].sort();
+const packageRelevant = relevant.filter((path) => isPackageRelevant(path, pkg.files));
 
 if (!relevant.length) {
-  process.stderr.write(`release impact check ok: no release-relevant changes since ${latestTag}\n`);
+  process.stderr.write(`release impact check ok: no repository changes since ${latestTag}\n`);
+  process.exit(0);
+}
+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) {
-  fail(`release-relevant changes exist since ${latestTag}, but package.json is still ${pkg.version}; bump the npm version and add a CHANGELOG section before merging`);
+  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 heading = new RegExp(`^## ${escapeRegExp(pkg.version)}(?:\\s+-[^\\n]*)?$`, "m");
 if (!heading.test(changelog)) fail(`CHANGELOG.md has no section for ${pkg.version}`);
 
-process.stderr.write(`release impact check ok: ${relevant.length} release-relevant file(s) since ${latestTag}; next npm version ${pkg.version}\n`);
+process.stderr.write(`release impact check ok: ${packageRelevant.length} npm-package file(s) changed since ${latestTag}; next npm version ${pkg.version}\n`);
+
+export function isPackageRelevant(path, packageFiles = []) {
+  const normalized = String(path || "").replaceAll("\\", "/").replace(/^\.\//, "");
+  if (!normalized) return false;
+  if (["package.json", "package-lock.json", "npm-shrinkwrap.json"].includes(normalized)) return true;
+  for (const entry of packageFiles || []) {
+    const candidate = String(entry || "").replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
+    if (candidate && (normalized === candidate || normalized.startsWith(`${candidate}/`))) return true;
+  }
+  return false;
+}
 
 function git(args) {
   try {

package/scripts/release-state.mjs

@@ -1,7 +1,7 @@
 export function tagSyncError({ scope = "local", tag, head, commit }) {
   const label = scope === "remote" ? "remote tag" : "local tag";
   if (!commit) {
-    return `${label} ${tag} is missing; run npm run release:publish before npm publish`;
+    return `${label} ${tag} is missing; run npm run release before npm publish`;
   }
   if (commit !== head) {
     return `${label} ${tag} points to ${commit}, not HEAD ${head}`;

package/scripts/run-checks.mjs

@@ -0,0 +1,29 @@
+import { spawnSync } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { checkTasks } from "./check-plan.mjs";
+
+const mode = process.argv[2] || "full";
+const tasks = checkTasks(mode);
+const npmCli = process.env.npm_execpath;
+if (!npmCli) throw new Error("check runner must run through npm so npm_execpath is available");
+const planStartedAt = performance.now();
+
+console.log(`running ${mode} verification plan (${tasks.length} tasks)`);
+for (const [index, task] of tasks.entries()) {
+  const taskStartedAt = performance.now();
+  console.log(`\n[${index + 1}/${tasks.length}] npm run ${task}`);
+  const result = spawnSync(process.execPath, [npmCli, "run", task], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: "inherit",
+  });
+  const elapsedSeconds = ((performance.now() - taskStartedAt) / 1000).toFixed(1);
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    console.error(`verification task failed after ${elapsedSeconds}s: ${task}`);
+    process.exit(result.status || 1);
+  }
+  console.log(`completed ${task} in ${elapsedSeconds}s`);
+}
+const totalSeconds = ((performance.now() - planStartedAt) / 1000).toFixed(1);
+console.log(`\n${mode} verification plan passed in ${totalSeconds}s`);

package/scripts/start-release-candidate.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { verifyTarball } from "./release-acceptance.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const candidateDirectory = join(root, ".release-candidate");
+const manifestPath = join(candidateDirectory, "manifest.json");
+const installPrefix = join(candidateDirectory, "runtime");
+const npmCli = process.env.npm_execpath;
+
+if (!npmCli) fail("candidate startup must run through npm so npm_execpath is available");
+
+try {
+  const manifest = readJson(manifestPath, "release candidate manifest");
+  if (manifest.result !== "pending") throw new Error("release candidate manifest is not pending");
+  const tarball = join(candidateDirectory, String(manifest.filename || ""));
+  verifyTarball(tarball, manifest);
+
+  const npmVersion = runNpm(["--version"], root).stdout.trim();
+  if (Number(npmVersion.split(".")[0]) < 12) {
+    throw new Error(`candidate startup requires npm 12 or newer; current ${npmVersion}`);
+  }
+
+  rmSync(installPrefix, { recursive: true, force: true });
+  mkdirSync(installPrefix, { recursive: true });
+  runNpm([
+    "install",
+    "--global",
+    "--prefix", installPrefix,
+    "--omit=optional",
+    "--allow-scripts=esbuild,workerd,sharp,fsevents",
+    tarball,
+  ], root);
+
+  const globalRoot = runNpm(["root", "--global", "--prefix", installPrefix], root).stdout.trim();
+  const installedPackage = join(globalRoot, manifest.package_name);
+  const installed = readJson(join(installedPackage, "package.json"), "installed candidate package");
+  if (installed.version !== manifest.package_version) {
+    throw new Error(`installed candidate version ${installed.version} does not match ${manifest.package_version}`);
+  }
+
+  console.log(`Verified candidate tarball: ${manifest.filename} (${manifest.shasum})`);
+  console.log(`Installed isolated candidate: ${installedPackage}`);
+  const installOnly = process.argv.includes("--install-only");
+  const allowWorkerDeploy = process.argv.includes("--allow-worker-deploy");
+  if (installOnly) {
+    console.log("Candidate installation check passed; startup was skipped by --install-only.");
+    process.exit(0);
+  }
+
+  if (!allowWorkerDeploy) {
+    throw new Error("foreground candidate startup may update the configured same-name Worker; rerun with --allow-worker-deploy to authorize that live candidate deployment");
+  }
+
+  const forwardedArgs = process.argv.slice(2).filter((value) => value !== "--install-only" && value !== "--allow-worker-deploy");
+  const cli = join(installedPackage, "bin", "machine-mcp.mjs");
+  console.log("Authorized live candidate deployment: startup may update the configured same-name Worker when its version or deployment hash differs.");
+  console.log("Starting the exact candidate in the foreground. Leave this process running while the coding agent verifies the Worker, relay, and local runtime end to end.");
+  const child = spawn(process.execPath, [cli, ...forwardedArgs], {
+    cwd: root,
+    env: process.env,
+    stdio: "inherit",
+    windowsHide: true,
+  });
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.on(signal, () => {
+      try { child.kill(signal); } catch {
+        // The child may already have exited.
+      }
+    });
+  }
+  child.once("error", (error) => fail(error?.message || error));
+  child.once("exit", (code, signal) => {
+    if (signal) {
+      console.error(`release candidate exited from ${signal}`);
+      process.exitCode = 1;
+      return;
+    }
+    process.exitCode = code ?? 1;
+  });
+} catch (error) {
+  fail(error?.message || error);
+}
+
+function runNpm(args, cwd) {
+  const result = spawnSync(process.execPath, [npmCli, ...args], {
+    cwd,
+    encoding: "utf8",
+    env: process.env,
+    timeout: 300_000,
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`npm ${args[0]} failed: ${result.stderr || result.stdout}`);
+  return result;
+}
+
+function readJson(path, label) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(`${label} is unavailable or invalid: ${error.message}`);
+  }
+}
+
+function fail(message) {
+  console.error(`release candidate startup failed: ${message}`);
+  process.exit(1);
+}

package/src/local/agent-context-projection.mjs

@@ -0,0 +1,158 @@
+// @ts-check
+import { createHash } from "node:crypto";
+
+/** @typedef {(value: string) => string} DisplayPath */
+/**
+ * @typedef {object} InstructionItem
+ * @property {string} [source]
+ * @property {string} [path]
+ * @property {string} scope
+ * @property {number} bytes
+ * @property {string} sha256
+ * @property {number} precedence
+ * @property {string} content
+ */
+/**
+ * @typedef {object} SkillSummary
+ * @property {string} id
+ * @property {string} name
+ * @property {string} description
+ * @property {string} entrypoint
+ * @property {string} sourceRoot
+ * @property {number} bytes
+ * @property {string} sha256
+ */
+/**
+ * @typedef {object} CommandSummary
+ * @property {string} name
+ * @property {string} description
+ * @property {string[]} argv
+ * @property {string} cwd
+ * @property {number} timeoutSeconds
+ * @property {boolean} allowExtraArgs
+ * @property {string} source
+ * @property {string} [sourceType]
+ * @property {string} [script]
+ */
+/**
+ * @typedef {object} ProjectionState
+ * @property {string[]} configFiles
+ * @property {InstructionItem | null} builtinInstructions
+ * @property {InstructionItem | null} automaticProjectContext
+ * @property {InstructionItem | null} modelInstructions
+ * @property {InstructionItem[]} instructions
+ * @property {Map<string, CommandSummary>} commands
+ */
+
+/** @param {ProjectionState} state @param {SkillSummary[]} skills */
+export function capabilityFingerprint(state, skills) {
+  return sha256(JSON.stringify({
+    configs: state.configFiles,
+    instructions: [
+      state.builtinInstructions?.sha256 || "",
+      state.automaticProjectContext?.sha256 || "",
+      state.modelInstructions?.sha256 || "",
+      ...state.instructions.map((item) => item.sha256),
+    ],
+    skills: skills.map((skill) => [skill.id, skill.sha256]),
+    commands: [...state.commands.values()].map((command) => [command.name, command.argv]),
+  }));
+}
+
+/** @param {SkillSummary} skill @param {DisplayPath} displayPath */
+export function publicSkill(skill, displayPath) {
+  return {
+    id: skill.id,
+    name: skill.name,
+    description: skill.description,
+    entrypoint: displayPath(skill.entrypoint),
+    source_root: displayPath(skill.sourceRoot),
+    bytes: skill.bytes,
+    sha256: skill.sha256,
+  };
+}
+
+/** @param {SkillSummary[]} skills @param {DisplayPath} displayPath @param {number} maxSkills @param {number} budgetChars */
+export function contextSkillSummaries(skills, displayPath, maxSkills, budgetChars) {
+  /** @type {Array<ReturnType<typeof publicSkill> & {description_truncated?: boolean}>} */
+  const selected = [];
+  let used = 0;
+  for (const skill of skills) {
+    if (selected.length >= maxSkills) return { skills: selected, truncated: true };
+    const item = publicSkill(skill, displayPath);
+    const fullSize = JSON.stringify(item).length;
+    if (used + fullSize <= budgetChars) {
+      selected.push(item);
+      used += fullSize;
+      continue;
+    }
+    const withoutDescription = { ...item, description: "", description_truncated: true };
+    const baseSize = JSON.stringify(withoutDescription).length;
+    const available = budgetChars - used - baseSize;
+    if (available >= 32) selected.push({ ...withoutDescription, description: item.description.slice(0, available) });
+    return { skills: selected, truncated: true };
+  }
+  return { skills: selected, truncated: false };
+}
+
+/** @param {Array<{entrypoint: string, message: string}>} warnings @param {DisplayPath} displayPath */
+export function publicSkillWarnings(warnings, displayPath) {
+  return warnings.map((warning) => ({ entrypoint: displayPath(warning.entrypoint), message: warning.message }));
+}
+
+/** @param {Map<string, CommandSummary>} commands @param {DisplayPath} displayPath */
+export function publicCommands(commands, displayPath) {
+  return [...commands.values()]
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .map((command) => ({
+      name: command.name,
+      description: command.description,
+      argv: [...command.argv],
+      cwd: displayPath(command.cwd),
+      timeout_seconds: command.timeoutSeconds,
+      allow_extra_args: command.allowExtraArgs,
+      source: displayPath(command.source),
+      source_type: command.sourceType || "agent-config",
+      ...(command.script ? { package_script: command.script } : {}),
+    }));
+}
+
+/** @param {ProjectionState} state */
+export function effectiveInstructionItems(state) {
+  return [
+    ...(state.builtinInstructions ? [state.builtinInstructions] : []),
+    ...(state.automaticProjectContext ? [state.automaticProjectContext] : []),
+    ...(state.modelInstructions ? [state.modelInstructions] : []),
+    ...state.instructions,
+  ];
+}
+
+/** @param {InstructionItem | null} item @param {boolean} includeContent */
+export function publicVirtualInstruction(item, includeContent) {
+  if (!item) return null;
+  return {
+    source: item.source,
+    scope: item.scope,
+    bytes: item.bytes,
+    sha256: item.sha256,
+    precedence: item.precedence,
+    ...(includeContent ? { content: item.content } : {}),
+  };
+}
+
+/** @param {InstructionItem[]} instructions @param {DisplayPath} displayPath */
+export function renderEffectiveInstructions(instructions, displayPath) {
+  return instructions.map((item) => {
+    const source = item.source || displayPath(item.path || "");
+    return [
+      `--- BEGIN ${source} (precedence ${item.precedence}) ---`,
+      item.content,
+      `--- END ${source} ---`,
+    ].join("\n");
+  }).join("\n\n");
+}
+
+/** @param {unknown} value */
+export function sha256(value) {
+  return createHash("sha256").update(String(value)).digest("hex");
+}