@cyanheads/mcp-ts-core 0.11.3 → 0.11.5

package/templates/.github/SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes land on the latest release of `{{PACKAGE_NAME}}`. Older
+versions are not patched — upgrade to the current release.
+
+## Reporting a Vulnerability
+
+Please do not open a public issue for security reports. Instead:
+
+<!-- GitHub's private reporting is off by default. Turn it on under
+     Settings → Code security → Private vulnerability reporting. -->
+
+- Report privately via GitHub: **Security** tab → **Report a vulnerability**, or
+- Email **[your-contact-email]**
+
+Include a minimal reproduction where possible, with any API keys, tokens, or
+credentials redacted — a placeholder is enough to show the shape. You'll
+receive an acknowledgment, and credit in the release notes if the report leads
+to a fix (unless you prefer otherwise).
+
+<!-- If you want to commit to a response window, say so above — e.g.
+     "You'll receive an acknowledgment within a few days." -->

package/templates/Dockerfile

@@ -51,8 +51,13 @@ COPY package.json bun.lock ./
 
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
 # that are not needed in the final production image.
+# `--omit=peer` drops the framework's optional peer tiers (test runner, service
+# SDKs, parsers) that Bun would otherwise auto-install. Anything this server
+# actually imports belongs in its own `dependencies`, so nothing needed at
+# runtime is lost. The OTEL step below carries the same flag — without it, that
+# install re-resolves the graph and pulls every optional peer back in.
 RUN --mount=type=cache,target=/root/.bun/install/cache \
-    bun install --production --frozen-lockfile --ignore-scripts
+    bun install --production --omit=peer --frozen-lockfile --ignore-scripts
 
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
 # These are not bundled by default to keep the base image lean. Enable at build time
@@ -60,7 +65,7 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
 ARG OTEL_ENABLED=true
 RUN --mount=type=cache,target=/root/.bun/install/cache \
     if [ "$OTEL_ENABLED" = "true" ]; then \
-      bun add --omit=dev --ignore-scripts @hono/otel \
+      bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
         @opentelemetry/instrumentation-http \
         @opentelemetry/exporter-metrics-otlp-http \
         @opentelemetry/exporter-trace-otlp-http \

package/templates/_tsconfig.build.json

@@ -1,4 +1,9 @@
 {
   "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "noEmit": false
+  },
+  "include": ["src/**/*"],
   "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
 }

package/templates/_tsconfig.json

@@ -1,12 +1,14 @@
 {
   "extends": "@cyanheads/mcp-ts-core/tsconfig.base.json",
   "compilerOptions": {
-    "rootDir": "src",
+    "rootDir": ".",
     "outDir": "dist",
+    "noEmit": true,
+    "tsBuildInfoFile": ".tsbuildinfo",
     "paths": {
       "@/*": ["./src/*"]
     }
   },
-  "include": ["src/**/*"],
+  "include": ["src/**/*", "tests/**/*"],
   "exclude": ["node_modules", "dist"]
 }

package/templates/changelog/template.md

@@ -4,10 +4,11 @@
 # to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
 # with a concrete date.
 
-# Required. One-line GitHub Release-style headline. 350 character cap.
-# Default short and scannable. Don't pad, don't stitch unrelated changes with
-# semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
-# inside the value as a key separator and fails GitHub's strict parser.
+# Required. One-line GitHub Release-style headline. 350 character cap — a
+# ceiling, not a target. Default short and scannable. Don't pad, don't stitch
+# unrelated changes with commas/semicolons into an inventory — pick the
+# headline, like a tag's theme line. Quotes required: unquoted YAML treats
+# `: ` inside the value as a key separator and fails GitHub's strict parser.
 summary: ""
 
 # Set `true` when consumers must change code to upgrade: API removals,
@@ -24,9 +25,10 @@ security: false
 
 # Optional free-form notes for maintenance agents processing this release.
 # Not rendered in CHANGELOG — consumed by agents running `maintenance` on
-# downstream servers. Use for adoption instructions that don't fit the
-# human-facing sections: new files to create, fields to populate, one-time
-# migration steps. Omit the field entirely when there's nothing to say.
+# downstream servers. ADOPTION STEPS ONLY — new files to create, fields to
+# populate, one-time migration steps. Never a second rendering of the body:
+# if a body bullet already says it, name the bullet's symbol instead of
+# re-explaining. Omit the field entirely when there's nothing to say.
 # agent-notes: |
 #   <instructions for downstream maintenance agents>
 ---
@@ -41,17 +43,54 @@ security: false
   each bullet with the symbol or concept name in **bold** so they can skip
   what's irrelevant and zoom in on what's not.
 
-  Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
-  name the symbol, state what changed, stop. Use a second sentence only when
-  it carries weight. If a bullet feels long, it is.
-
-  Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
-  relevant skill), ceremonial framings ("This release introduces…",
-  backwards-compat paragraphs), file-by-file test enumerations, internal
-  implementation notes. Prefer code/symbol names over English re-explanations.
+  Tone: terse, fact-dense, not verbose. Bullet shape: **symbol** + what
+  changed + at most one consumer-facing caveat. One sentence by default, two
+  when the second carries weight — a bullet past ~40 words or three sentences
+  is wrong. The depth lives one hop away: the linked issue carries the why,
+  the commit diff carries the how. The changelog names what changed and what
+  a consumer does about it; a reader who wants mechanism opens the link.
+
+  Model length on THIS guide, never on the previous entry — entries modeled
+  on entries compound.
+
+  Cut (each has shipped as a wall of text; these are the cruft):
+  - History/justification narration — how the bug worked, why the old
+    behavior was wrong. One short clause at most; the issue carries the story.
+  - Design-rationale defense — "chosen over Y because…", "guarding the
+    getter is not enough…". That is the author arguing with a reviewer;
+    reviewers read the PR, not the changelog.
+  - Defensive unchanged-clauses — "X is unchanged", "byte-identical to
+    <prev>". Keep one only where its absence would cause a real misread,
+    as a short parenthetical.
+  - Edge-case inventories — marker lists, not-flagged lists, escape tables.
+    Tests and the issue carry those.
+  - Mechanism walkthroughs (JSDoc, CLAUDE.md/AGENTS.md, or the relevant
+    skill own those), ceremonial framings ("This release introduces…"),
+    backwards-compat paragraphs, file-by-file test enumerations. Prefer
+    code/symbol names over English re-explanations.
+
+  Verified ≠ included: the every-claim-verified-from-the-diff rule bounds
+  the TRUTH of what you write, never the AMOUNT.
+
+  Example — same fact, right size:
+
+    TOO LONG: **`fetchWithTimeout`'s `timeoutMs` bounds the whole exchange**
+    (#341). `fetch` resolves once headers arrive and the deadline was
+    cleared as the helper returned, so a peer that answered promptly and
+    then stalled the stream held the request open indefinitely. A 2xx
+    carrying a body now comes back as a passthrough wrapper that disarms
+    the deadline when the body closes, errors, or is cancelled; …
+    [+90 more words of mechanism and edge cases]
+
+    RIGHT: **`fetchWithTimeout`'s `timeoutMs` now bounds the whole
+    exchange, not just the headers** (#341). A stalled body aborts with
+    the same `Timeout` error; the returned `Response` is a wrapper, so
+    identity assertions (`toBe(response)`) no longer hold.
 
   Narrative intro: skip by default. Add one short sentence only when the
-  release theme genuinely needs framing the bullets can't carry.
+  release theme genuinely needs framing the bullets can't carry. When many
+  bullets share one upgrade consequence, state it ONCE — intro line or
+  agent-notes — never per bullet.
 
   Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
   Fixed, Security. Include only sections with entries; delete the rest

package/templates/package.json

@@ -70,6 +70,7 @@
     "@types/node": "26.1.1",
     "@vitest/coverage-istanbul": "4.1.10",
     "depcheck": "^1.4.7",
+    "fast-check": "^4.9.0",
     "ignore": "^7.0.6",
     "tsc-alias": "^1.9.1",
     "typescript": "^7.0.2",

package/templates/tests/prompts/echo.prompt.test.ts

@@ -7,9 +7,10 @@ import { describe, expect, it } from 'vitest';
 import { echoPrompt } from '@/mcp-server/prompts/definitions/echo.prompt.js';
 
 describe('echoPrompt', () => {
-  it('generates a user message with the echoed text', () => {
-    const args = echoPrompt.args.parse({ message: 'hello world' });
-    const messages = echoPrompt.generate(args);
+  it('generates a user message with the echoed text', async () => {
+    const args = echoPrompt.args!.parse({ message: 'hello world' });
+    // `generate` may be async — await covers both shapes.
+    const messages = await echoPrompt.generate(args);
     expect(messages).toHaveLength(1);
     expect(messages[0]).toMatchObject({
       role: 'user',

package/templates/tests/resources/echo.resource.test.ts

@@ -10,13 +10,21 @@ import { echoResource } from '@/mcp-server/resources/definitions/echo.resource.j
 describe('echoResource', () => {
   it('echoes the message from params', async () => {
     const ctx = createMockContext();
-    const params = echoResource.params.parse({ message: 'hello world' });
+    const params = echoResource.params!.parse({ message: 'hello world' });
     const result = await echoResource.handler(params, ctx);
     expect(result).toEqual({ message: 'hello world' });
   });
 
-  it('lists available resources', () => {
-    const listing = echoResource.list!();
+  it('lists available resources', async () => {
+    // `list` receives the SDK's request-handler extra, not a Context, and may be
+    // async — a minimal literal is enough for a listing that ignores it.
+    const extra = {
+      signal: new AbortController().signal,
+      requestId: 'test',
+      sendNotification: () => Promise.resolve(),
+      sendRequest: () => Promise.resolve({} as never),
+    };
+    const listing = await echoResource.list!(extra);
     expect(listing.resources).toHaveLength(1);
     expect(listing.resources[0]).toMatchObject({
       uri: 'echo://hello',

package/templates/tests/smoke/definitions.smoke.test.ts

@@ -13,23 +13,27 @@ import { echoTool } from '@/mcp-server/tools/definitions/echo.tool.js';
 
 describe('scaffold definition smoke test', () => {
   it('executes the shipped tool, resource, and prompt definitions', async () => {
-    const ctx = createMockContext();
+    // `echoTool` declares an error contract, so its handler wants a context
+    // typed against it — passing `errors` narrows what `createMockContext` returns.
+    const ctx = createMockContext({ errors: echoTool.errors });
     const toolResult = await echoTool.handler(
       echoTool.input.parse({ message: 'smoke' }),
       ctx,
     );
     const resourceResult = await echoResource.handler(
-      echoResource.params.parse({ message: 'smoke' }),
+      echoResource.params!.parse({ message: 'smoke' }),
       ctx,
     );
-    const promptMessages = echoPrompt.generate(echoPrompt.args.parse({ message: 'smoke' }));
+    const promptMessages = await echoPrompt.generate(
+      echoPrompt.args!.parse({ message: 'smoke' }),
+    );
     const appResult = await echoAppTool.handler(
       echoAppTool.input.parse({ message: 'smoke app' }),
       ctx,
     );
     const appContent = echoAppTool.format?.(appResult);
     const appHtml = await echoAppUiResource.handler(
-      echoAppUiResource.params.parse({}),
+      echoAppUiResource.params!.parse({}),
       createMockContext({ uri: new URL('ui://template-echo-app/app.html') }),
     );
 

package/templates/tests/tools/echo.tool.test.ts

@@ -3,22 +3,41 @@
  * @module tests/tools/echo.tool.test
  */
 
+import type { HandlerContext, ReasonOf } from '@cyanheads/mcp-ts-core';
 import { describe, expect, it } from 'vitest';
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
 import { mcpTest } from '@cyanheads/mcp-ts-core/testing/vitest';
 import { echoTool } from '@/mcp-server/tools/definitions/echo.tool.js';
 
+/**
+ * A tool that declares `errors[]` types its handler's `ctx` against that
+ * contract, so tests hand it a context built the same way — `createMockContext`
+ * narrows its return type from the `errors` it is given. Drop this if your tool
+ * declares no error contract; a bare `createMockContext()` is enough then.
+ */
+type EchoContext = HandlerContext<ReasonOf<typeof echoTool.errors>>;
+
+const echoContext = () => createMockContext({ errors: echoTool.errors });
+
 // ---------------------------------------------------------------------------
 // Fixture-based tests (mcpTest) — fresh ctx per test, no manual construction
 // ---------------------------------------------------------------------------
 
-mcpTest('echoTool: echoes the message back (fixture)', async ({ ctx }) => {
+/** Function form, not a bare value — every test gets its own context. */
+const echoTest = mcpTest.extend<{ ctx: EchoContext }>({
+  // biome-ignore lint/correctness/noEmptyPattern: vitest's fixture API requires a destructuring pattern as the first parameter
+  ctx: async ({}, use) => {
+    await use(echoContext());
+  },
+});
+
+echoTest('echoTool: echoes the message back (fixture)', async ({ ctx }) => {
   const input = echoTool.input.parse({ message: 'hello world' });
   const result = await echoTool.handler(input, ctx);
   expect(result).toEqual({ message: 'hello world' });
 });
 
-mcpTest('echoTool: output conforms to declared schema (fixture)', async ({ ctx }) => {
+echoTest('echoTool: output conforms to declared schema (fixture)', async ({ ctx }) => {
   const input = echoTool.input.parse({ message: 'hello world' });
   const result = await echoTool.handler(input, ctx);
   expect(result).toEqual(expect.schemaMatching(echoTool.output));
@@ -30,14 +49,14 @@ mcpTest('echoTool: output conforms to declared schema (fixture)', async ({ ctx }
 
 describe('echoTool', () => {
   it('echoes the message back', async () => {
-    const ctx = createMockContext();
+    const ctx = echoContext();
     const input = echoTool.input.parse({ message: 'hello world' });
     const result = await echoTool.handler(input, ctx);
     expect(result).toEqual({ message: 'hello world' });
   });
 
   it('output conforms to the declared output schema', async () => {
-    const ctx = createMockContext();
+    const ctx = echoContext();
     const input = echoTool.input.parse({ message: 'hello world' });
     const result = await echoTool.handler(input, ctx);
     expect(result).toEqual(expect.schemaMatching(echoTool.output));