@cyanheads/mcp-ts-core 0.13.8 → 0.13.9

package/framework-skills/report-issue-local/SKILL.md

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against this MCP server's own repo. Use for server-specific issues — tool logic, service integrations, config problems, or domain bugs that aren't caused by the framework.
 metadata:
   author: cyanheads
-  version: "1.11"
+  version: "1.12"
   audience: external
   type: workflow
 ---
@@ -38,7 +38,8 @@ gh repo view --json nameWithOwner -q '.nameWithOwner'
 gh issue list --search "your error message or keyword" --state all
 
 # Assess a close match before commenting — is it already linked to a fix or referenced elsewhere?
-gh issue view <number> --comments
+gh issue view <number>              # body
+gh issue view <number> --comments   # thread only — without a TTY it prints no body
 gh api 'repos/{owner}/{repo}/issues/<number>/timeline' --paginate \
   --jq '.[] | select(.event=="cross-referenced") | .source.issue | "\(.repository.full_name)#\(.number) — \(.title)"'
 ```
@@ -87,11 +88,11 @@ gh issue create \
   --body "$(cat <<'ISSUE'
 ### Server version
 
-0.1.0
+<package.json version>
 
 ### mcp-ts-core version
 
-0.1.29
+<installed version from node_modules/@cyanheads/mcp-ts-core/package.json — not the ^ range>
 
 ### Runtime
 
@@ -99,7 +100,7 @@ Bun
 
 ### Runtime version
 
-Bun 1.3.x
+<bun --version>
 
 ### Transport
 
@@ -258,7 +259,8 @@ When genuinely ambiguous, file against this server's repo and note that it might
 ## Following Up
 
 ```bash
-# View issue details (with comment thread)
+# View the issue body, then its comment thread (--comments without a TTY prints no body)
+gh issue view <number>
 gh issue view <number> --comments
 
 # Add context

package/framework-skills/security-pass/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Review an MCP server for common security gaps: LLM-facing surfaces as injection vector (tools, resources, prompts, descriptions), scope blast radius, destructive ops without consent, upstream auth shape, input sinks (URL / path / roots / shell / schema strictness / ReDoS), tenant isolation, leakage through errors and telemetry, unbounded resources, and HTTP-mode deployment surface. Use before a release, after a batch of handler changes, or when the user asks for a security review, audit, or hardening pass. Produces grouped findings and a numbered options list.
 metadata:
   author: cyanheads
-  version: "1.10"
+  version: "1.11"
   audience: external
   type: audit
 ---
@@ -116,7 +116,7 @@ grep -rn "auth: \[" src/mcp-server/tools/definitions/
 
 ```bash
 grep -rn "destructiveHint" src/mcp-server/tools/definitions/
-grep -rn "ctx.requestInput\|ctx.inputs" src/mcp-server/tools/definitions/
+grep -rnE "ctx\.requestInput|ctx\.inputs" src/mcp-server/tools/definitions/
 ```
 
 **Check:**
@@ -127,7 +127,7 @@ grep -rn "ctx.requestInput\|ctx.inputs" src/mcp-server/tools/definitions/
 - Consent is scoped to the specific target (e.g., record ID rendered in the message), not a generic "proceed?"
 - Any `requestState` carried across rounds is integrity-protected if it influences authorization, resource access, or which target gets mutated. It round-trips through the client and comes back attacker-controlled; the SDK does not sign or verify it.
 - **A consent gate's state is server-issued and single-use.** A client can send `inputResponses` plus a `requestState` of its own on the very FIRST call — honored on 2025-era connections, even from a client that declared no `elicitation` — so a handler that only *compares* client-carried state against a fresh resolution deletes on a forged "accepted" answer without ever prompting. A signed state closes forgery but not replay within its TTL. Keep the confirmed target (plus a content hash, so a same-path swap is caught) in a server-side record keyed by a random id, send only the id, redeem it before anything else in the handler, and refuse an unknown, used, or expired id.
-- **The weak point is answerability, not availability.** `ctx.requestInput` is present on every transport and both protocol eras — the 2025-era shim issues the real `elicitation/create` round trip, the 2026-07-28 client fulfils the embedded request directly. A client that never retries simply leaves the destructive step un-run, which fails safe. Keep `destructiveHint: true` so client-side approval flows still surface the risk, and do not accept "proceed anyway when the round is unavailable" as a fallback — there is no such state to detect.
+- **The weak point is answerability, not availability.** `ctx.requestInput` is present on every transport and both protocol eras — the 2025-era shim issues the real `elicitation/create` round trip, the 2026-07-28 client fulfils the embedded request directly. A client that never retries simply leaves the destructive step un-run, which fails safe. Keep `destructiveHint: true` so client-side approval flows still surface the risk, and do not accept "proceed anyway when the round is unavailable" as a fallback. On a 2025-era connection whose client lacks the capability, `ctx.requestInput` throws `client_capability_missing` inside the handler; catching that to run the side effect is exactly this bypass — let it propagate.
 
 **Smell:** `destructiveHint: true` file with no `ctx.requestInput` in it. Or `ctx.inputs.accepted('confirm')` with no schema argument — the content could be anything. Or a handler that re-issues the same request after a `decline`.
 
@@ -157,22 +157,22 @@ LLM-supplied inputs feel internal but aren't. Classic sinks apply, amplified. Sa
 grep -rn "z.string().url()" src/
 
 # Path sinks — traversal
-grep -rn "readFile\|writeFile\|readdirSync\|createReadStream\|statSync" src/
+grep -rnE "readFile|writeFile|readdirSync|createReadStream|statSync" src/
 
 # Shell sinks — command injection
 grep -rnE "\b(exec|spawn|execSync|spawnSync)\b" src/
 
 # Merges — prototype pollution
-grep -rn "Object.assign\b\|structuredClone" src/
+grep -rnE "Object\.assign\b|structuredClone" src/
 
 # Lookups — prototype chain read through an object literal
 grep -rnE "\[[a-zA-Z_$][a-zA-Z0-9_$.]*\] *\?\? |\[[a-zA-Z_$][a-zA-Z0-9_$.]*\] *\|\| " src/
 
 # Roots — client-shared filesystem
-grep -rn "roots/list\|ctx.roots" src/
+grep -rnE "roots/list|ctx\.roots" src/
 
 # Schema laxity — fields sneaking past validation
-grep -rn "\.passthrough()\|\.loose()\|looseObject(\|\.catchall(" src/mcp-server/
+grep -rnE "\.passthrough\(\)|\.loose\(\)|looseObject\(|\.catchall\(" src/mcp-server/
 ```
 
 **Check:**
@@ -245,7 +245,7 @@ Unbounded = DoS of self, upstream, or the LLM's context window (billing-DoS is r
 
 ```bash
 grep -rnE "while\s*\(|for\s*\(.*of" src/mcp-server/tools/definitions/
-grep -rn "cursor\|nextPage\|paginate" src/
+grep -rnE "cursor|nextPage|paginate" src/
 grep -rn "JSON.parse\b" src/
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.13.8",
+  "version": "0.13.9",
   "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": [
@@ -201,7 +201,7 @@
     "@cloudflare/workers-types": "5.20260922.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,7 +290,7 @@
   },
   "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",
     "jose": "^6.2.12",

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/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,16 @@
  *      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: every stage that runs `bun run build` must
+ *      start `FROM --platform=$BUILDPLATFORM`. Without it the non-native leg of
+ *      a multi-arch `docker buildx` build runs under QEMU, where bun >= 1.4
+ *      aborts inside the build and no image publishes for either architecture —
+ *      and the image publishes last, after npm and the MCP Registry. Skipped
+ *      when there is no `Dockerfile` or no stage builds.
  *
  * 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 +113,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-]+)\}$/;
@@ -775,6 +786,49 @@ 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}"`,
+  ];
+}
+
+const DOCKERFILE_FROM = /^\s*FROM\s/i;
+const DOCKERFILE_BUILD_PLATFORM = /--platform=\$\{?BUILDPLATFORM\}?(?:\s|$)/;
+const DOCKERFILE_BUILD_STEP = /\bbun run (?:re)?build\b/;
+
+/**
+ * Check 15: every Dockerfile stage that runs `bun run build` must be pinned to
+ * the build platform. Stages are split at `FROM` lines; comment lines are
+ * ignored so a note mentioning the build does not count as one.
+ */
+export function checkDockerfileBuildPlatform(dockerfile: string): string[] {
+  const stages: { from: string; line: number; builds: boolean }[] = [];
+  for (const [index, line] of dockerfile.split('\n').entries()) {
+    if (DOCKERFILE_FROM.test(line)) {
+      stages.push({ from: line.trim(), line: index + 1, builds: false });
+    } else if (!line.trimStart().startsWith('#') && DOCKERFILE_BUILD_STEP.test(line)) {
+      const stage = stages.at(-1);
+      if (stage) stage.builds = true;
+    }
+  }
+
+  return stages
+    .filter((stage) => stage.builds && !DOCKERFILE_BUILD_PLATFORM.test(stage.from))
+    .map(
+      (stage) =>
+        `Dockerfile:${stage.line} "${stage.from}" runs \`bun run build\` without --platform=$BUILDPLATFORM — ` +
+        `a multi-arch buildx build then runs it under QEMU, where bun aborts and no image publishes; ` +
+        `start the build stage with "FROM --platform=$BUILDPLATFORM" and copy dist/ into a separate runtime stage`,
+    );
+}
+
 /** Read `packaging.pluginManifests` from devcheck.config.json; default on. */
 function pluginManifestsEnabled(): boolean {
   const cfg = tryReadJson<{ packaging?: { pluginManifests?: boolean } }>(
@@ -862,6 +916,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 +966,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)) {

package/scripts/release-github.ts

@@ -18,6 +18,15 @@
  * The framework itself has no `manifest.json`/`.mcpb`, so the attach path is
  * skipped here but scaffolded servers that do have a manifest get the full flow.
  *
+ * Before any `gh` call it validates the tag — `--notes-from-tag` publishes the
+ * message verbatim as the release body, so a malformed tag becomes a malformed
+ * public release. `--check` runs only that validation, for use right after
+ * `git tag -a` and before the tag is pushed. The rules are the ones the
+ * `release-and-publish` skill states for the annotation: an annotated tag, a
+ * subject of at most 72 characters with no version and no `;`, flat bullets
+ * with no section headers, no signature block leaked into the body, and the
+ * `[CHANGELOG v<version>](…)` link as the final line.
+ *
  * @module scripts/release-github
  *
  * @example
@@ -25,6 +34,10 @@
  * // bun run release:github
  *
  * @example
+ * // Validate the tag annotation only (exit 1 on a violation, no gh calls):
+ * // bun run release:github -- --check
+ *
+ * @example
  * // Dry-run — print the command that would be executed without running it:
  * // bun run release:github -- --dry-run
  */
@@ -33,8 +46,86 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import process from 'node:process';
+import { fileURLToPath } from 'node:url';
 
 const DRY_RUN = process.argv.includes('--dry-run');
+const CHECK_ONLY = process.argv.includes('--check');
+
+/** A tag subject longer than this reads as a digest, not a release title. */
+const MAX_SUBJECT_LENGTH = 72;
+
+/**
+ * Section headers belong in the changelog entry, never in the tag body: a
+ * markdown heading, a Keep a Changelog section name, or any other line that is
+ * not a bullet and ends in a colon (`Dependency bumps:`, `Highlights:`).
+ */
+const SECTION_HEADER =
+  /^(?:#{1,6}\s.*|(?:Added|Changed|Deprecated|Removed|Fixed|Security|Dependencies)\s*:?|[^\s\-*+[].*:)$/;
+
+/** The parts of an annotated tag that become the GitHub Release title and body. */
+export interface TagMessage {
+  body: string;
+  /** `git for-each-ref %(objecttype)` — `tag` for an annotated tag, `commit` for a lightweight one. */
+  objectType: string;
+  subject: string;
+}
+
+/**
+ * Validates a tag annotation against the release-body rules. Returns one
+ * message per violation; an empty array means the tag is publishable.
+ */
+export function checkTagMessage(tag: TagMessage, version: string): string[] {
+  if (tag.objectType !== 'tag') {
+    return [
+      `v${version} is a lightweight tag — recreate it annotated: git tag -a v${version} -F <file>`,
+    ];
+  }
+
+  const errors: string[] = [];
+  const { subject } = tag;
+  if (subject.length > MAX_SUBJECT_LENGTH) {
+    errors.push(
+      `subject is ${subject.length} characters — keep it one short theme (≤${MAX_SUBJECT_LENGTH}); the bullets carry the digest`,
+    );
+  }
+  if (subject.includes(version)) {
+    errors.push(
+      `subject contains the version "${version}" — GitHub prepends "v${version}:" to the title`,
+    );
+  }
+  if (subject.includes(';')) {
+    errors.push('subject contains ";" — one theme, not a list of changes');
+  }
+
+  if (tag.body.includes('-----BEGIN')) {
+    errors.push(
+      'body contains a signature block — the signature did not parse (usually --cleanup=verbatim); recreate the tag with --cleanup=whitespace before it is pushed',
+    );
+  }
+
+  const lines = tag.body
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  const headers = lines.filter((line) => SECTION_HEADER.test(line));
+  if (headers.length > 0) {
+    errors.push(
+      `body has section headers (${headers.map((h) => `"${h}"`).join(', ')}) — flat bullets only; sections belong in the changelog entry`,
+    );
+  }
+
+  const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const changelogLink = new RegExp(
+    `^\\[CHANGELOG v${escaped}\\]\\(\\S+/changelog/\\d+\\.\\d+\\.x/${escaped}\\.md\\)`,
+  );
+  if (!changelogLink.test(lines.at(-1) ?? '')) {
+    errors.push(
+      `final line is not the changelog link — end the body with "[CHANGELOG v${version}](https://github.com/<OWNER>/<REPO>/blob/main/changelog/<major.minor>.x/${version}.md)"`,
+    );
+  }
+
+  return errors;
+}
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -107,15 +198,34 @@ function main(): void {
   if (!subject) {
     console.error(
       `Tag ${tag} not found locally or has no subject line. ` +
-        `Create the annotated tag first: git tag -a ${tag} -m "..."`,
+        `Create the annotated tag first: git tag -a ${tag} -F <file>`,
     );
     process.exit(1);
   }
 
+  // 3. Validate the annotation — it becomes the public release body verbatim
+  const errors = checkTagMessage(
+    {
+      subject,
+      body: run('git', ['for-each-ref', `refs/tags/${tag}`, '--format=%(contents:body)']),
+      objectType: run('git', ['for-each-ref', `refs/tags/${tag}`, '--format=%(objecttype)']),
+    },
+    version,
+  );
+  if (errors.length > 0) {
+    console.error(`Tag ${tag} is not publishable:`);
+    for (const error of errors) console.error(`  ✗ ${error}`);
+    process.exit(1);
+  }
+  if (CHECK_ONLY) {
+    console.log(`Tag ${tag} OK.`);
+    return;
+  }
+
   const title = `${tag}: ${subject}`;
   const hasMcpb = existsSync('manifest.json');
 
-  // 3. Build the gh release create command
+  // 4. Build the gh release create command
   const createArgs = [
     'release',
     'create',
@@ -152,7 +262,7 @@ function main(): void {
     console.log('  asset: dist/*.mcpb');
   }
 
-  // 4. Try to create the release
+  // 5. Try to create the release
   const createResult = gh(createArgs, { required: false });
 
   if (!createResult.startsWith('__ERROR__:')) {
@@ -170,7 +280,7 @@ function main(): void {
     process.exit(1);
   }
 
-  // 5. Release already exists — repair: upload asset (if applicable) and set title.
+  // 6. Release already exists — repair: upload asset (if applicable) and set title.
   console.log(`Release ${tag} already exists. Repairing…`);
 
   if (hasMcpb) {
@@ -184,4 +294,6 @@ function main(): void {
   console.log(`Release ${tag} repaired.`);
 }
 
-main();
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

package/templates/_.mcpbignore

@@ -3,6 +3,8 @@
 /.claude/
 /.agents/
 /framework-skills/
+/docs/idea.md
+/logs/
 /Dockerfile
 /bun.lock
 /bunfig.toml