@cyanheads/mcp-ts-core 0.5.3 → 0.6.0

package/scripts/build-changelog.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Generate CHANGELOG.md as a navigation index from per-version files.
+ *
+ * Source of truth: `changelog/<major.minor>.x/<version>.md` — each file opens with
+ * YAML frontmatter declaring:
+ *   • summary (required)  — ≤250-char headline, no markdown, one line
+ *   • breaking (optional) — `true` flags releases with breaking changes
+ *
+ * The rollup is a thin **index**, not a copy of bodies — each entry is just a
+ * clickable header + one-line summary. Full content stays in the per-version files.
+ *
+ * Rendered rollup entry:
+ *   ## [X.Y.Z](changelog/N.N.x/X.Y.Z.md) — YYYY-MM-DD · ⚠️ Breaking
+ *
+ *   <summary>
+ *
+ * (The `· ⚠️ Breaking` badge only appears when `breaking: true`.)
+ *
+ * Modes:
+ *   • default   → regenerate CHANGELOG.md
+ *   • --check   → exit 1 if CHANGELOG.md differs from what would be generated
+ *
+ * Missing `summary`: warning (not failure) — the entry renders header-only.
+ * Summary > 250 chars, or malformed `breaking`: hard error.
+ *
+ * @module scripts/build-changelog
+ */
+
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import process from 'node:process';
+
+const CHANGELOG_DIR = resolve('changelog');
+const CHANGELOG_PATH = resolve('CHANGELOG.md');
+const EXCLUDED_FILES = new Set(['unreleased.md', 'README.md']);
+const SERIES_PATTERN = /^\d+\.\d+\.x$/;
+const SUMMARY_MAX_LENGTH = 250;
+
+const HEADER = `# Changelog
+
+All notable changes to this project. Each entry links to its full per-version file in [changelog/](changelog/).
+`;
+
+interface VersionEntry {
+  path: string;
+  series: string;
+  version: string;
+}
+
+interface Frontmatter {
+  breaking: boolean;
+  summary: string | null;
+}
+
+/**
+ * Semver descending compare. Final releases rank above their prereleases
+ * (`0.6.0 > 0.6.0-rc.1 > 0.6.0-beta.1`). Prereleases compared lexicographically.
+ */
+function compareSemverDesc(a: string, b: string): number {
+  const parse = (v: string): [number[], string | null] => {
+    const [base, pre = null] = v.split('-', 2) as [string, string | undefined];
+    return [base.split('.').map(Number), pre ?? null];
+  };
+  const [aParts, aPre] = parse(a);
+  const [bParts, bPre] = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const diff = (bParts[i] ?? 0) - (aParts[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  if (aPre === bPre) return 0;
+  if (aPre === null) return -1;
+  if (bPre === null) return 1;
+  return bPre.localeCompare(aPre);
+}
+
+/**
+ * Parse minimal YAML frontmatter. Only recognizes `summary` and `breaking` —
+ * other keys are ignored, so the format stays extensible without touching the
+ * parser. Throws on malformed values we actually care about.
+ */
+function parseFrontmatter(content: string, fileLabel: string): Frontmatter {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!match) return { summary: null, breaking: false };
+
+  const block = match[1] as string;
+
+  // summary: quoted or bare, single line
+  let summary: string | null = null;
+  const summaryMatch = block.match(/^summary:\s*(.*)$/m);
+  if (summaryMatch) {
+    let raw = (summaryMatch[1] ?? '').trim();
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+      raw = raw.slice(1, -1);
+    }
+    summary = raw.length > 0 ? raw : null;
+  }
+  if (summary !== null && summary.length > SUMMARY_MAX_LENGTH) {
+    throw new Error(
+      `${fileLabel}: summary is ${summary.length} chars, exceeds cap of ${SUMMARY_MAX_LENGTH}. Keep it tight — headline, not paragraph.`,
+    );
+  }
+
+  // breaking: must be literal true/false if present
+  let breaking = false;
+  const breakingMatch = block.match(/^breaking:\s*(\S+)\s*$/m);
+  if (breakingMatch) {
+    const val = breakingMatch[1];
+    if (val !== 'true' && val !== 'false') {
+      throw new Error(`${fileLabel}: breaking must be 'true' or 'false', got '${val}'.`);
+    }
+    breaking = val === 'true';
+  }
+
+  return { summary, breaking };
+}
+
+/** Extract the release date from the H1 heading. */
+function extractDate(body: string, fileLabel: string): string {
+  const match = body.match(/^#\s+\S+\s+[—–-]\s+(\d{4}-\d{2}-\d{2})/m);
+  if (!match) {
+    throw new Error(
+      `${fileLabel}: H1 heading missing or malformed. Expected '# <version> — YYYY-MM-DD'.`,
+    );
+  }
+  return match[1] as string;
+}
+
+function renderEntry(entry: VersionEntry, fm: Frontmatter, date: string): string {
+  const link = `changelog/${entry.series}/${entry.version}.md`;
+  const breakingBadge = fm.breaking ? ' · ⚠️ Breaking' : '';
+  const header = `## [${entry.version}](${link}) — ${date}${breakingBadge}`;
+  if (fm.summary) {
+    return `${header}\n\n${fm.summary}\n`;
+  }
+  return `${header}\n`;
+}
+
+function collectVersionFiles(): VersionEntry[] {
+  const entries: VersionEntry[] = [];
+  for (const entry of readdirSync(CHANGELOG_DIR, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !SERIES_PATTERN.test(entry.name)) continue;
+    const seriesDir = resolve(CHANGELOG_DIR, entry.name);
+    for (const file of readdirSync(seriesDir)) {
+      if (!file.endsWith('.md') || EXCLUDED_FILES.has(file)) continue;
+      entries.push({
+        version: file.replace(/\.md$/, ''),
+        series: entry.name,
+        path: resolve(seriesDir, file),
+      });
+    }
+  }
+  return entries.sort((a, b) => compareSemverDesc(a.version, b.version));
+}
+
+function buildRollup(): { content: string; missingSummary: string[] } {
+  const entries = collectVersionFiles();
+
+  if (entries.length === 0) {
+    throw new Error(`No per-version changelog files found under ${CHANGELOG_DIR}/<major.minor>.x/`);
+  }
+
+  const missingSummary: string[] = [];
+  const sections: string[] = [];
+
+  for (const entry of entries) {
+    const fileLabel = `changelog/${entry.series}/${entry.version}.md`;
+    const content = readFileSync(entry.path, 'utf-8');
+    const fm = parseFrontmatter(content, fileLabel);
+    const date = extractDate(content, fileLabel);
+
+    if (!fm.summary) {
+      missingSummary.push(fileLabel);
+    }
+
+    sections.push(renderEntry(entry, fm, date));
+  }
+
+  return {
+    content: `${HEADER}\n${sections.join('\n')}`,
+    missingSummary,
+  };
+}
+
+function reportMissingSummaries(missing: string[]): void {
+  if (missing.length === 0) return;
+  const shown = missing.slice(0, 10);
+  const extra = missing.length - shown.length;
+  console.warn(`\nWarning: ${missing.length} file(s) missing 'summary' frontmatter:`);
+  for (const file of shown) console.warn(`  - ${file}`);
+  if (extra > 0) console.warn(`  ... and ${extra} more`);
+  console.warn(`\nBackfill these — see CLAUDE.md § Changelog for the frontmatter format.`);
+}
+
+function main(): void {
+  const checkOnly = process.argv.includes('--check');
+  const { content: generated, missingSummary } = buildRollup();
+
+  if (checkOnly) {
+    let existing = '';
+    try {
+      existing = readFileSync(CHANGELOG_PATH, 'utf-8');
+    } catch {
+      // missing file counts as drift
+    }
+    if (existing === generated) {
+      console.log('CHANGELOG.md is in sync with changelog/ directory.');
+      reportMissingSummaries(missingSummary);
+      process.exit(0);
+    }
+    console.error('CHANGELOG.md is out of sync with changelog/ directory.');
+    console.error('Fix: run `bun run changelog:build` to regenerate.');
+    reportMissingSummaries(missingSummary);
+    process.exit(1);
+  }
+
+  writeFileSync(CHANGELOG_PATH, generated);
+  console.log(`Wrote ${CHANGELOG_PATH} (${generated.split('\n').length - 1} lines).`);
+  reportMissingSummaries(missingSummary);
+}
+
+main();

package/scripts/devcheck.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 import { type ChildProcess, spawn, spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
@@ -67,7 +67,7 @@ const createColor = (open: string, close: string, closeRe: RegExp) => (str: stri
   return open + `${str}`.replace(closeRe, close + open) + close;
 };
 
-const esc = (code: string) => new RegExp(code.replace('[', '\\['), 'g');
+const esc = (code: string) => new RegExp(code.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g');
 const c = {
   bold: createColor('\x1b[1m', '\x1b[22m', esc('\x1b[22m')),
   dim: createColor('\x1b[2m', '\x1b[22m', esc('\x1b[22m')),
@@ -411,7 +411,7 @@ const ALL_CHECKS: Check[] = [
     canFix: false,
     getCommand: () => ['bun', 'run', 'scripts/lint-mcp.ts'],
     tip: (c) =>
-      `Fix definition errors reported above. See ${c.bold('validateDefinitions()')} docs for rule details.`,
+      `Fix definition errors above — each diagnostic links to its rule in ${c.bold('skills/api-linter/SKILL.md')}.`,
   },
   {
     name: 'Docs Sync',
@@ -421,6 +421,21 @@ const ALL_CHECKS: Check[] = [
     tip: (c) =>
       `Edit both files together, or run ${c.bold('cp CLAUDE.md AGENTS.md')} (or reverse) to resync.`,
   },
+  {
+    name: 'Changelog Sync',
+    flag: '--no-changelog-sync',
+    canFix: false,
+    // --check exits non-zero if CHANGELOG.md drifts from changelog/*.md.
+    // Skipped cleanly when neither CHANGELOG.md nor changelog/ exists (non-mcp-ts-core projects).
+    getCommand: () => {
+      const hasChangelog = existsSync(path.join(ROOT_DIR, 'changelog'));
+      const hasRollup = existsSync(path.join(ROOT_DIR, 'CHANGELOG.md'));
+      if (!hasChangelog && !hasRollup) return null;
+      return ['bun', 'run', 'scripts/build-changelog.ts', '--check'];
+    },
+    tip: (c) =>
+      `Edit the per-version file in ${c.bold('changelog/')} and run ${c.bold('bun run changelog:build')} to regenerate ${c.bold('CHANGELOG.md')}.`,
+  },
   {
     name: 'Biome',
     flag: '--no-lint',
@@ -562,7 +577,7 @@ const ALL_CHECKS: Check[] = [
       return unexpected.length === 0;
     },
     tip: (c) =>
-      `Run ${c.bold(`${PM_CMD} update`)} to upgrade dependencies. Configure allowlist in ${c.bold('devcheck.config.json')}.`,
+      `Run ${c.bold(`${PM_CMD} update`)} to upgrade; the ${c.bold('maintenance')} skill then investigates changelogs and adopts upstream changes. Configure allowlist in ${c.bold('devcheck.config.json')}.`,
   },
 ];
 

package/scripts/tree.ts

@@ -39,6 +39,9 @@ const DEFAULT_IGNORE_PATTERNS: string[] = [
   'coverage',
   'logs',
   '.husky/_',
+  // Directory-based changelog — keep series dirs visible (0.1.x/, 0.5.x/) for structural
+  // orientation, but collapse out the per-version files. Top-level unreleased.md stays.
+  'changelog/*/*.md',
 ];
 
 interface ParsedArgs {

package/skills/add-app-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold an MCP App tool + UI resource pair. Use when the user asks to add a tool with interactive UI, create an MCP App, or build a visual/interactive tool.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: reference
 ---
@@ -18,9 +18,7 @@ MCP Apps extend the standard tool pattern with an interactive HTML UI rendered i
 
 Both builders are exported from `@cyanheads/mcp-ts-core`. They handle `_meta.ui.resourceUri`, the compat key (`ui/resourceUri`), and the correct MIME type (`text/html;profile=mcp-app`) automatically.
 
-For the full API, Context interface, and error codes, read:
-
-    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+For the full API, Context interface, and error codes, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
 
 ## Steps
 

package/skills/add-prompt/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP prompt template. Use when the user asks to add a prompt, create a reusable message template, or define a prompt for LLM interactions.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: external
   type: reference
 ---
@@ -15,9 +15,7 @@ Prompts use the `prompt()` builder from `@cyanheads/mcp-ts-core`. Each prompt li
 
 Prompts are pure message templates — no `Context`, no auth, no side effects.
 
-For the full `prompt()` API, read:
-
-    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+For the full `prompt()` API, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
 
 ## Steps
 

package/skills/add-resource/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP resource definition. Use when the user asks to add a resource, expose data via URI, or create a readable endpoint.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: reference
 ---
@@ -15,9 +15,7 @@ Resources use the `resource()` builder from `@cyanheads/mcp-ts-core`. Each resou
 
 **Tool coverage.** Not all MCP clients expose resources — many are tool-only (Claude Code, Cursor, most chat UIs). Before adding a resource, verify the same data is reachable via the tool surface — either through a dedicated tool, included in another tool's output, or bundled into a broader tool. A resource whose data has no tool path is invisible to a large share of agents.
 
-For the full `resource()` API, pagination utilities, and `Context` interface, read:
-
-    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+For the full `resource()` API, pagination utilities, and `Context` interface, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
 
 ## Steps
 

package/skills/add-service/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new service integration. Use when the user asks to add a service, integrate an external API, or create a reusable domain module with its own initialization and state.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: reference
 ---
@@ -15,9 +15,7 @@ Services use the init/accessor pattern: initialized once in `createApp`'s `setup
 
 Service methods receive `Context` for correlated logging (`ctx.log`) and tenant-scoped storage (`ctx.state`). Convention: `ctx.elicit` and `ctx.sample` should only be called from tool handlers, not from services.
 
-For the full service pattern, `CoreServices`, and `Context` interface, read:
-
-    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+For the full service pattern, `CoreServices`, and `Context` interface, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
 
 ## Steps
 

package/skills/add-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
 metadata:
   author: cyanheads
-  version: "1.6"
+  version: "1.7"
   audience: external
   type: reference
 ---
@@ -13,9 +13,7 @@ metadata:
 
 Tools use the `tool()` builder from `@cyanheads/mcp-ts-core`. Each tool lives in `src/mcp-server/tools/definitions/` with a `.tool.ts` suffix and is registered into `createApp()` in `src/index.ts`. Some larger repos later add `definitions/index.ts` barrels; match the pattern already used by the project you're editing.
 
-For the full `tool()` API, `Context` interface, and error codes, read:
-
-    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+For the full `tool()` API, `Context` interface, and error codes, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
 
 ## Steps
 
@@ -164,6 +162,8 @@ async handler(input, ctx) {
 },
 ```
 
+**Note on the `try/catch`:** this is the deliberate exception to the "logic throws, framework catches" rule. Per-item isolation is the whole point of partial-success batch tools — one failed item must not abort the batch, and the framework's partial-success telemetry (below) depends on seeing a populated `failed` array. Don't remove it to conform to the handler-level rule.
+
 Single-item tools don't need this — they either succeed or throw. The partial success question only arises with array inputs.
 
 **Telemetry:** The framework automatically detects this pattern — when a handler result contains a non-empty `failed` array, the span gets `mcp.tool.partial_success`, `mcp.tool.batch.succeeded_count`, and `mcp.tool.batch.failed_count` attributes. No manual instrumentation needed.
@@ -242,7 +242,8 @@ import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
 throw serviceUnavailable(`arXiv API returned HTTP ${status}. Retry in a few seconds.`);
 
 // Structured hint for programmatic recovery
-throw new McpError(JsonRpcErrorCode.InvalidParams,
+import { invalidParams } from '@cyanheads/mcp-ts-core/errors';
+throw invalidParams(
   `Date range exceeds 90-day API limit. Narrow the range or split into multiple queries.`,
   { maxDays: 90, requestedDays: daysBetween },
 );

package/skills/api-context/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.sample`, `ctx.progress`), and when to use each.
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.1"
   audience: external
   type: reference
 ---
@@ -181,7 +181,7 @@ if (ctx.elicit) {
     await produceOutput(result.content?.format as string, result.content?.includeHeaders as boolean);
   } else {
     // 'decline' or 'cancel' — user opted out
-    throw new McpError(JsonRpcErrorCode.InvalidRequest, 'User declined input');
+    throw invalidRequest('User declined input');
   }
 }
 ```