@cyanheads/mcp-ts-core 0.13.8 → 0.13.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.13.8",
+  "version": "0.13.10",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for MCP servers. Includes runtime infrastructure and agent skills for building, testing, and shipping servers.",
   "files": [
@@ -16,6 +16,7 @@
     "scripts/clean-mcpb.ts",
     "scripts/clean.ts",
     "scripts/devcheck.ts",
+    "scripts/install-otel.ts",
     "scripts/lint-mcp.ts",
     "scripts/lint-packaging.ts",
     "scripts/list-skills.ts",
@@ -198,10 +199,10 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.14",
     "@cloudflare/vitest-pool-workers": "^0.22.0",
-    "@cloudflare/workers-types": "5.20260922.1",
+    "@cloudflare/workers-types": "5.20260924.1",
     "@duckdb/node-api": "^1.5.5-r.5",
     "@hono/otel": "^1.1.2",
-    "@modelcontextprotocol/client": "^2.0.0",
+    "@modelcontextprotocol/client": "^2.1.0",
     "@opentelemetry/api-logs": "^0.222.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.222.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.222.0",
@@ -290,9 +291,9 @@
   },
   "dependencies": {
     "@hono/node-server": "^2.1.1",
-    "@modelcontextprotocol/server": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.1.0",
     "@opentelemetry/api": "^1.9.1",
-    "hono": "^4.13.8",
+    "hono": "^4.13.9",
     "jose": "^6.2.12",
     "pino": "^10.3.1",
     "zod": "^4.6.5"

package/scripts/devcheck.ts

@@ -711,12 +711,12 @@ const ALL_CHECKS: Check[] = [
     canFix: false,
     // Validates env var alignment between manifest.json (MCPB bundle) and
     // server.json (MCP Registry), plus plugin marketplace manifests (#240), the
-    // bundle-content guards on .mcpbignore (#343), and the README version badge
-    // (#418). Runs when any of those inputs is present; skipped cleanly when
-    // none exist — consumers on an HTTP-only deploy are unaffected. README.md is
-    // a trigger in its own right: the badge check must gate a project that
-    // carries no bundle or plugin metadata at all, which the other three inputs
-    // only covered incidentally.
+    // bundle-content guards on .mcpbignore (#343), the README version badge
+    // (#418), and the Dockerfile build platform. Runs when any of those inputs
+    // is present; skipped cleanly when none exist — consumers on an HTTP-only
+    // deploy are unaffected. README.md and Dockerfile are triggers in their own
+    // right: each check must gate a project that carries no bundle or plugin
+    // metadata at all, which the other inputs only covered incidentally.
     getCommand: () => {
       const inputs = [
         'manifest.json',
@@ -725,6 +725,7 @@ const ALL_CHECKS: Check[] = [
         '.codex-plugin/mcp.json',
         '.mcpbignore',
         'README.md',
+        'Dockerfile',
       ];
       if (!inputs.some((input) => existsSync(path.join(ROOT_DIR, input)))) return null;
       return ['bun', 'run', 'scripts/lint-packaging.ts'];

package/scripts/install-otel.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env bun
+/**
+ * @fileoverview Installs the OpenTelemetry packages the framework loads at
+ * runtime into a production dependency tree — the Dockerfile's OTel step.
+ *
+ * The list is every `peerDependencies` entry named `@opentelemetry/*`, plus
+ * `@hono/otel`, in `@cyanheads/mcp-ts-core/package.json` resolved from the
+ * project root: the installed framework in a server, the package itself (by
+ * self-reference) in the framework. Each package moves into the project's
+ * `dependencies` at its declared peer range, out of `peerDependencies`,
+ * `peerDependenciesMeta`, and `devDependencies`, so `--omit=peer` keeps it
+ * while every other optional peer stays out. Then `bun install --omit=dev
+ * --omit=peer --ignore-scripts` runs with every argument given to this script
+ * appended, under the project's `bunfig.toml`, and its exit code is this
+ * script's. Not `--production`: it implies `--frozen-lockfile`, which fails
+ * once the manifest gains packages the lockfile lacks.
+ *
+ * @example
+ * // In a Dockerfile stage on $BUILDPLATFORM, cross-installing for the target:
+ * // bun scripts/install-otel.ts --os=linux --cpu=x64
+ * @module scripts/install-otel
+ */
+import { spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+interface Manifest {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, unknown>;
+}
+
+/** The OTel optional peers a framework manifest declares, keyed by name, at their declared ranges. */
+export function otelPeers(framework: Manifest): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(framework.peerDependencies ?? {}).filter(
+      ([name]) => name.startsWith('@opentelemetry/') || name === '@hono/otel',
+    ),
+  );
+}
+
+function main(args: string[]): number {
+  const manifestPath = join(process.cwd(), 'package.json');
+  const frameworkPath = createRequire(manifestPath).resolve('@cyanheads/mcp-ts-core/package.json');
+  const peers = otelPeers(JSON.parse(readFileSync(frameworkPath, 'utf8')) as Manifest);
+  const names = Object.keys(peers);
+  if (names.length === 0) {
+    console.error(
+      `install-otel: ${frameworkPath} declares no @opentelemetry/* or @hono/otel peerDependencies — nothing to install.`,
+    );
+    return 1;
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as Manifest;
+  manifest.dependencies = { ...manifest.dependencies, ...peers };
+  for (const name of names) {
+    delete manifest.peerDependencies?.[name];
+    delete manifest.peerDependenciesMeta?.[name];
+    delete manifest.devDependencies?.[name];
+  }
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  console.log(
+    `install-otel: ${names.length} OpenTelemetry packages from ${frameworkPath}: ` +
+      names.map((name) => `${name}@${peers[name]}`).join(' '),
+  );
+
+  const install = spawnSync(
+    'bun',
+    ['install', '--omit=dev', '--omit=peer', '--ignore-scripts', ...args],
+    { stdio: 'inherit' },
+  );
+  if (install.error) {
+    console.error(`install-otel: could not run bun install: ${install.error.message}`);
+    return 1;
+  }
+  return install.status ?? 1;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}

package/scripts/lint-mcp.ts

@@ -12,6 +12,11 @@
  *   3. Extracts exported definitions by duck-typing (has name/handler/input etc.)
  *   4. Feeds them into `validateDefinitions()`
  *
+ * A definition file whose `import()` rejects, and a `server.json` that exists
+ * but does not parse, are errors (`definition-import-failed`,
+ * `server-json-parse`): what they declare cannot be checked, so the run fails
+ * instead of passing without them. The remaining files are still linted.
+ *
  * Runtime-agnostic: works with bun, tsx, and Node.js (via ts-node/esm).
  *
  * Rule knobs come from the project's `devcheck.config.json` `lint` block, so one
@@ -20,7 +25,7 @@
  * @module scripts/lint-mcp
  */
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 // ---------------------------------------------------------------------------
@@ -100,19 +105,64 @@ function discoverFiles(): string[] {
   return [...new Set(files)];
 }
 
+// ---------------------------------------------------------------------------
+// Load failures
+// ---------------------------------------------------------------------------
+
+/** Where the rule reference lives — the breadcrumb `validateDefinitions()` appends too. */
+const SKILL_REFERENCE_PATH = 'framework-skills/api-linter/SKILL.md';
+
+/** A file the CLI could not load, shaped like the diagnostics it is printed beside. */
+interface LoadFailure {
+  message: string;
+  rule: 'definition-import-failed' | 'server-json-parse';
+}
+
+/**
+ * The text of a thrown value. An `AggregateError` keeps its causes in `errors`
+ * — Bun rejects a definition that fails to transpile with one whose own message
+ * only counts them ("2 errors building …") — so each cause is appended.
+ */
+function describeError(err: unknown): string {
+  if (!(err instanceof Error)) return String(err);
+  const message = err.message || err.name;
+  if (!(err instanceof AggregateError) || err.errors.length === 0) return message;
+  return `${message} (${err.errors.map(describeError).join('; ')})`;
+}
+
+function loadFailure(rule: LoadFailure['rule'], file: string, err: unknown): LoadFailure {
+  const anchor = rule === 'server-json-parse' ? 'server-json-rules' : rule;
+  return {
+    rule,
+    message: `${file}: ${describeError(err)}\nSee: ${SKILL_REFERENCE_PATH}#${anchor}`,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
 
-/** Try to read and parse a JSON file. Returns undefined on failure. */
-function tryReadJson(path: string): unknown {
+/** A parsed JSON file, or the error an existing one failed to read or parse with. */
+type JsonRead = { ok: true; value: unknown } | { ok: false; error: unknown };
+
+/** Reads and parses a JSON file. `undefined` when the file does not exist. */
+function readJson(path: string): JsonRead | undefined {
+  if (!existsSync(path)) return;
   try {
-    if (!existsSync(path)) return;
-    return JSON.parse(readFileSync(path, 'utf-8'));
-  } catch (err) {
-    console.warn(`Warning: Failed to parse ${path}: ${err instanceof Error ? err.message : err}`);
+    return { ok: true, value: JSON.parse(readFileSync(path, 'utf-8')) };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+/** Try to read and parse a JSON file. Returns undefined when absent, and warns when unparseable. */
+function tryReadJson(path: string): unknown {
+  const read = readJson(path);
+  if (read?.ok === false) {
+    console.warn(`Warning: Failed to parse ${path}: ${describeError(read.error)}`);
     return;
   }
+  return read?.value;
 }
 
 /** The `lint` block of `devcheck.config.json`, as far as this script reads it. */
@@ -149,12 +199,17 @@ export function readLintOptions(configPath = resolve('devcheck.config.json')): L
 
 async function main(): Promise<void> {
   const files = discoverFiles();
+  const failures: LoadFailure[] = [];
 
   // Discover server.json and package.json at project root
-  const serverJson = tryReadJson(resolve('server.json'));
+  const serverJsonRead = readJson(resolve('server.json'));
+  if (serverJsonRead?.ok === false) {
+    failures.push(loadFailure('server-json-parse', 'server.json', serverJsonRead.error));
+  }
+  const serverJson = serverJsonRead?.ok ? serverJsonRead.value : undefined;
   const packageJson = tryReadJson(resolve('package.json')) as { version?: string } | undefined;
 
-  if (files.length === 0 && serverJson == null) {
+  if (files.length === 0 && serverJson == null && failures.length === 0) {
     console.log('No MCP definition files or server.json found. Skipping lint.');
     process.exit(0);
   }
@@ -162,36 +217,42 @@ async function main(): Promise<void> {
   const tools: unknown[] = [];
   const resources: unknown[] = [];
   const prompts: unknown[] = [];
+  let failedImports = 0;
 
   for (const file of files) {
+    let mod: Record<string, unknown>;
     try {
-      const mod = await import(file);
-      for (const exported of Object.values(mod)) {
-        if (isToolLike(exported)) tools.push(exported);
-        else if (isResourceLike(exported)) resources.push(exported);
-        else if (isPromptLike(exported)) prompts.push(exported);
-      }
+      mod = await import(file);
     } catch (err) {
-      console.warn(
-        `Warning: Failed to import ${file}: ${err instanceof Error ? err.message : err}`,
-      );
+      failures.push(loadFailure('definition-import-failed', relative(process.cwd(), file), err));
+      failedImports++;
+      continue;
+    }
+    for (const exported of Object.values(mod)) {
+      if (isToolLike(exported)) tools.push(exported);
+      else if (isResourceLike(exported)) resources.push(exported);
+      else if (isPromptLike(exported)) prompts.push(exported);
     }
   }
 
   const defTotal = tools.length + resources.length + prompts.length;
-  if (defTotal === 0 && serverJson == null) {
+  if (defTotal === 0 && serverJson == null && failures.length === 0) {
     console.log(`Scanned ${files.length} files but found no definitions. Skipping lint.`);
     process.exit(0);
   }
 
   const parts: string[] = [];
-  if (defTotal > 0) {
+  if (defTotal > 0 || failedImports > 0) {
+    const fileCount =
+      failedImports === 0
+        ? `${files.length}`
+        : `${files.length - failedImports} of ${files.length}`;
     parts.push(
-      `${tools.length} tool(s), ${resources.length} resource(s), ${prompts.length} prompt(s) from ${files.length} file(s)`,
+      `${tools.length} tool(s), ${resources.length} resource(s), ${prompts.length} prompt(s) from ${fileCount} file(s)`,
     );
   }
   if (serverJson != null) parts.push('server.json');
-  console.log(`Linting ${parts.join(' + ')}...`);
+  if (parts.length > 0) console.log(`Linting ${parts.join(' + ')}...`);
 
   const report = validateDefinitions({
     tools,
@@ -202,14 +263,15 @@ async function main(): Promise<void> {
     ...readLintOptions(),
   });
 
+  const errors = [...failures, ...report.errors];
   for (const w of report.warnings) {
     console.warn(`  ⚠ [${w.rule}] ${w.message}`);
   }
-  for (const e of report.errors) {
+  for (const e of errors) {
     console.error(`  ✗ [${e.rule}] ${e.message}`);
   }
 
-  if (report.passed) {
+  if (errors.length === 0) {
     if (report.warnings.length > 0) {
       console.log(`\nPassed with ${report.warnings.length} warning(s).`);
     } else {
@@ -217,9 +279,7 @@ async function main(): Promise<void> {
     }
     process.exit(0);
   } else {
-    console.error(
-      `\nFailed: ${report.errors.length} error(s), ${report.warnings.length} warning(s).`,
-    );
+    console.error(`\nFailed: ${errors.length} error(s), ${report.warnings.length} warning(s).`);
     process.exit(1);
   }
 }

package/scripts/lint-packaging.ts

@@ -65,6 +65,21 @@
  *      so without the entry a release that bundles before publishing ships the
  *      server and its production dependencies inside the npm tarball
  *      (issue #469). Skipped when `manifest.json` or `files` is absent.
+ *  14. manifest.json version parity: `version` must equal `package.json`'s, the
+ *      same rule check 10 applies to the plugin manifests — the bundle's install
+ *      dialog shows it. Skipped when `manifest.json` or the package version is
+ *      absent.
+ *  15. Dockerfile build platform: a stage that does not start
+ *      `FROM --platform=$BUILDPLATFORM` must not run JavaScript while it
+ *      builds — no `RUN` invoking `bun` for anything but `install`/`add`
+ *      (`bun run build`, `bun -e`, a script, `bunx`), and no `bun install`/
+ *      `bun add` once `bunfig.toml` is in the stage, since its security scanner
+ *      runs as a Bun program. The non-native leg of a multi-arch `docker buildx`
+ *      build runs such a stage under QEMU, where bun >= 1.4 aborts and no image
+ *      publishes for either architecture — and the image publishes last, after
+ *      npm and the MCP Registry. `HEALTHCHECK`/`CMD`/`ENTRYPOINT` run at
+ *      container start and never count. One error per stage, naming each
+ *      offending line (issue #575). Skipped when there is no `Dockerfile`.
  *
  * Every check skips cleanly when its input is absent — consumers who deleted
  * `manifest.json` for an HTTP-only deploy, or who haven't built a bundle,
@@ -103,6 +118,7 @@ interface Manifest {
   name?: string;
   server?: { mcp_config?: { args?: unknown[]; env?: Record<string, string> } };
   user_config?: Record<string, ManifestUserConfigEntry>;
+  version?: unknown;
 }
 
 const USER_CONFIG_REF = /^\$\{user_config\.([\w-]+)\}$/;
@@ -172,10 +188,10 @@ function tryReadJson<T>(path: string): T | undefined {
  * to evaluate which paths survive the ignore rules. Returns an array of error
  * strings; empty means all checks passed.
  *
- * **Context note:** this guard runs inside the scaffolded server project, not
- * inside mcp-ts-core itself. `ignore` is listed in `templates/package.json`
- * devDependencies (`^7.0.5`) and is therefore available in the server's
- * `node_modules` when `bun run lint:packaging` is invoked there.
+ * **Context note:** `ignore` is a devDependency of the framework and of every
+ * scaffold (`templates/package.json`), so it resolves wherever
+ * `bun run lint:packaging` runs against an `.mcpbignore` — a server project, or
+ * mcp-ts-core itself. Where it cannot load, the guard is skipped.
  */
 interface IgnoreMatcher {
   add(patterns: string[]): IgnoreMatcher;
@@ -775,6 +791,205 @@ export function checkBundleExcludedFromFiles(files: unknown): string[] {
   ];
 }
 
+/**
+ * Check 14: manifest.json `version` must equal `package.json`'s. Skipped when
+ * the package version is absent — the same fail-safe as checks 10 and 12.
+ */
+export function checkManifestVersion(manifest: Manifest, packageVersion?: string): string[] {
+  if (!packageVersion || manifest.version === packageVersion) return [];
+  return [
+    manifest.version === undefined
+      ? `manifest.json has no "version" — must declare the package.json version "${packageVersion}"`
+      : `manifest.json "version" is "${String(manifest.version)}" — must equal the package.json version "${packageVersion}"`,
+  ];
+}
+
+/** One Dockerfile instruction: continuations joined, a `RUN` heredoc body folded in. */
+interface DockerInstruction {
+  args: string;
+  keyword: string;
+  /** 1-based line the instruction starts on. */
+  line: number;
+  text: string;
+}
+
+const DOCKERFILE_SKIPPED_LINE = /^\s*(?:#|$)/;
+const DOCKERFILE_CONTINUATION = /\\\s*$/;
+const DOCKERFILE_HEREDOC = /<<-?(["']?)([A-Za-z_]\w*)\1/g;
+
+/**
+ * Splits a Dockerfile into instructions the way BuildKit reads it: a trailing
+ * `\` continues onto the next line, comment and blank lines inside a
+ * continuation are dropped, and a `RUN` heredoc's body belongs to its `RUN`.
+ */
+function dockerInstructions(dockerfile: string): DockerInstruction[] {
+  const lines = dockerfile.split(/\r?\n/);
+  const instructions: DockerInstruction[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (DOCKERFILE_SKIPPED_LINE.test(lines[i] ?? '')) continue;
+    const line = i + 1;
+    let text = (lines[i] ?? '').trim();
+    while (DOCKERFILE_CONTINUATION.test(text) && i + 1 < lines.length) {
+      text = text.replace(DOCKERFILE_CONTINUATION, ' ');
+      do i++;
+      while (i < lines.length && DOCKERFILE_SKIPPED_LINE.test(lines[i] ?? ''));
+      text += (lines[i] ?? '').trim();
+    }
+    const keyword = (text.split(/\s/, 1)[0] ?? '').toUpperCase();
+    if (keyword === 'RUN') {
+      for (const [, , delimiter] of text.matchAll(DOCKERFILE_HEREDOC)) {
+        while (i + 1 < lines.length && (lines[++i] ?? '').trim() !== delimiter) {
+          text += `\n${lines[i]}`;
+        }
+      }
+    }
+    instructions.push({ keyword, args: text.slice(keyword.length).trim(), line, text });
+  }
+  return instructions;
+}
+
+/** Words that may precede the command itself in a simple shell command. */
+const SHELL_COMMAND_PREFIX = new Set([
+  '!',
+  'command',
+  'do',
+  'elif',
+  'else',
+  'env',
+  'exec',
+  'if',
+  'then',
+  'time',
+  'until',
+  'while',
+]);
+
+/** A `bun`/`bunx` invocation in a `RUN`: the command word and the words after it. */
+interface BunInvocation {
+  args: string[];
+  command: 'bun' | 'bunx';
+}
+
+function bunCommand(word: string | undefined): BunInvocation['command'] | undefined {
+  const name = word?.split('/').pop();
+  return name === 'bun' || name === 'bunx' ? name : undefined;
+}
+
+/**
+ * The `bun`/`bunx` invocations a `RUN` instruction's command makes, read from
+ * command position only — `chown bun:bun`, `/root/.bun/`, and a quoted
+ * mention are not invocations. Quoted strings are opaque, so a `bun -e '…'`
+ * program never splits into commands of its own.
+ */
+function bunInvocations(runArgs: string): BunInvocation[] {
+  const command = runArgs.replace(/^(?:--[\w-]+=\S+\s+)*/, '');
+  if (command.startsWith('[')) {
+    try {
+      const argv: unknown = JSON.parse(command);
+      if (Array.isArray(argv)) {
+        const name = bunCommand(String(argv[0]));
+        return name ? [{ command: name, args: argv.slice(1).map(String) }] : [];
+      }
+    } catch {
+      // Not a JSON exec form: fall through and read it as shell.
+    }
+  }
+  return command
+    .replace(/'[^']*'|"(?:\\.|[^"\\])*"/g, "'…'")
+    .split(/&&|\|\||[;|&(){}`\n]/)
+    .flatMap((segment) => {
+      const words = segment.trim().split(/\s+/);
+      const start = words.findIndex(
+        (word) => !SHELL_COMMAND_PREFIX.has(word) && !/^[A-Za-z_]\w*=/.test(word),
+      );
+      const name = bunCommand(words[start]);
+      return name ? [{ command: name, args: words.slice(start + 1) }] : [];
+    });
+}
+
+const DOCKERFILE_BUILD_PLATFORM = /--platform=\$\{?BUILDPLATFORM\}?(?:\s|$)/;
+const BUN_INSTALL_SUBCOMMANDS = new Set(['install', 'i', 'add', 'a']);
+const BUNFIG_SOURCE = /(?:^|[\s/"'[,])bunfig\.toml(?=[\s"',\]]|$)/;
+
+/** Whether a `COPY`/`ADD` brings `bunfig.toml` into the stage, by name or with the whole context. */
+function copiesBunfig(args: string): boolean {
+  if (BUNFIG_SOURCE.test(args)) return true;
+  const words = args.split(/\s+/);
+  if (words.some((word) => word.startsWith('--from='))) return false;
+  const sources = words.filter((word) => !word.startsWith('--')).slice(0, -1);
+  return sources.some((source) => source === '.' || source === './');
+}
+
+/**
+ * Check 15: a Dockerfile stage built for the target platform must not run
+ * JavaScript while it builds. A multi-arch `docker buildx` build runs every
+ * such stage under QEMU on the non-native leg, where bun >= 1.4 aborts, and the
+ * image publishes last — after npm and the MCP Registry. A stage counts as
+ * running JavaScript when a `RUN` invokes `bun` for anything but
+ * `install`/`add` (`bun run build`, `bun -e`, a script, `bunx`), or runs
+ * `bun install`/`bun add` once `bunfig.toml` is in the stage, since its
+ * `[install.security]` scanner runs as a Bun program. A stage whose `FROM`
+ * carries `--platform=$BUILDPLATFORM` is exempt, and so are `HEALTHCHECK`,
+ * `CMD`, and `ENTRYPOINT`, which run at container start on the real target.
+ * One error per stage, naming each offending line.
+ */
+export function checkDockerfileBuildPlatform(dockerfile: string): string[] {
+  const stages: {
+    alias: string | undefined;
+    bunfig: boolean;
+    findings: string[];
+    from: DockerInstruction;
+    pinned: boolean;
+  }[] = [];
+
+  for (const instruction of dockerInstructions(dockerfile)) {
+    if (instruction.keyword === 'FROM') {
+      const [image = '', , alias] = instruction.args
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((word) => !word.startsWith('--'));
+      stages.push({
+        alias,
+        // A stage built FROM an earlier one starts with that stage's files.
+        bunfig: stages.find((earlier) => earlier.alias === image)?.bunfig ?? false,
+        findings: [],
+        from: instruction,
+        pinned: DOCKERFILE_BUILD_PLATFORM.test(instruction.args),
+      });
+      continue;
+    }
+    const stage = stages.at(-1);
+    if (!stage) continue;
+    if (instruction.keyword === 'COPY' || instruction.keyword === 'ADD') {
+      stage.bunfig ||= copiesBunfig(instruction.args);
+    } else if (instruction.keyword === 'RUN' && !stage.pinned) {
+      const finding = bunInvocations(instruction.args)
+        .map(({ command, args }) => {
+          const subcommand = args.find((arg) => !arg.startsWith('-'));
+          if (command === 'bun' && BUN_INSTALL_SUBCOMMANDS.has(subcommand ?? '')) {
+            return stage.bunfig
+              ? `\`bun ${subcommand}\` after bunfig.toml is in the stage, which starts its security scanner as a Bun program`
+              : undefined;
+          }
+          return `\`${[command, args[0]].filter(Boolean).join(' ')}\``;
+        })
+        .find(Boolean);
+      if (finding) stage.findings.push(`Dockerfile:${instruction.line} runs ${finding}`);
+    }
+  }
+
+  return stages
+    .filter((stage) => stage.findings.length > 0)
+    .map(
+      ({ from, findings }) =>
+        `Dockerfile:${from.line} "${from.text}" builds for the target platform but runs JavaScript while ` +
+        `building — ${findings.join('; ')}. A multi-arch buildx build runs that under QEMU on the non-native ` +
+        `leg, where bun aborts and no image publishes. Move these steps into a stage that starts ` +
+        `"FROM --platform=$BUILDPLATFORM" (cross-install with \`bun install --os=<os> --cpu=<x64|arm64>\`) and ` +
+        `copy their output (dist/, node_modules/) into this stage`,
+    );
+}
+
 /** Read `packaging.pluginManifests` from devcheck.config.json; default on. */
 function pluginManifestsEnabled(): boolean {
   const cfg = tryReadJson<{ packaging?: { pluginManifests?: boolean } }>(
@@ -862,6 +1077,7 @@ async function main(): Promise<void> {
       errors.push(...checkManifestIdentity(manifest, unscopedName));
     }
 
+    errors.push(...checkManifestVersion(manifest, pkg?.version));
     errors.push(...checkBundleExcludedFromFiles(pkg?.files));
   } else {
     notes.push('No manifest.json — skipping manifest/server.json alignment checks.');
@@ -911,6 +1127,12 @@ async function main(): Promise<void> {
     }
   }
 
+  // ── Dockerfile build platform (check 15) ──
+  const dockerfilePath = resolve('Dockerfile');
+  if (existsSync(dockerfilePath)) {
+    errors.push(...checkDockerfileBuildPlatform(readFileSync(dockerfilePath, 'utf-8')));
+  }
+
   // ── README version badge (check 12) ──
   const readmePath = resolve('README.md');
   if (existsSync(readmePath)) {