stitchkit 0.25.0 → 0.27.0

package/llms-full.txt

@@ -237,11 +237,13 @@ export const users = defineContract({ prefix: 'users' }, {
 | `output` | no | Zod schema for the **response body** |
 | `scope` | no | access scope for this endpoint — see [Auth & errors](./auth-and-errors.md) |
 | `expose` | no | which transports carry this endpoint — see [below](#transports) |
-| `toolName` | no | explicit MCP / agent tool name (defaults to `prefix_key`) |
+| `toolName` | no | explicit MCP / agent tool name (default: a verb-aware derivation, see below — not a literal `prefix_key`) |
 | `multipart` | no | field name of a file upload — see [below](#file-uploads) |
 | `timeout` | no | per-endpoint client timeout in ms, for slow endpoints |
 | `idempotent` | no | safe to call twice with the same input (like `PUT`/`DELETE`); a retrying transport reads it — see [Realtime](./realtime.md#bring-your-own-transport) |
 | `meta` | no | opaque app metadata — read in hooks / on tool mounts, never in OpenAPI ([below](#endpoint-metadata-meta)) |
+| `rawResponse` | no | the handler returns the `Response` itself — a download, a file, an SSE stream. HTTP-only, never a tool, no `output`. See [Raw-response endpoints](./server.md#raw-response-endpoints) |
+| `contentType` | no | documented response media type of a `rawResponse` endpoint (OpenAPI only) |
 
 ## `params` vs `input` vs `output`
 
@@ -313,8 +315,10 @@ tools. Narrow it with `expose`:
 - `expose: ['MCP', 'AGENT']` — a tool only; no HTTP route.
 - omit `expose` — all transports.
 
-Tool transports (`MCP`, `AGENT`) skip `multipart` endpoints automatically — a
-file upload is not a tool call.
+Tool transports (`MCP`, `AGENT`) skip two kinds of endpoint automatically:
+`multipart` (a file upload is not a tool call) and
+[`rawResponse`](./server.md#raw-response-endpoints) (its answer is bytes, which
+a tool result cannot carry — it would serialize to `{}`).
 
 ## `toolName`
 
@@ -326,8 +330,53 @@ derivation from the method key + prefix (`users` + `create` ⇒ `create_user`,
 { method: 'POST', path: '/', desc: 'Create a user', toolName: 'create_user', /* … */ }
 ```
 
+**Every tool name — derived or explicit — must match `[a-zA-Z0-9_-]` and be at
+most 64 characters**, the character class every major provider accepts.
+
+Note the two classes differ. What is *accepted* includes the hyphen; what
+derivation *keeps* does not — a derived name normalises everything outside
+`[a-zA-Z0-9_]` to `_`, the hyphen included, so `bot-status` + `get` ⇒
+`get_bot_status` and `admin/analytics` + `get` ⇒ `get_admin_analytics`. A hyphen
+survives only in an explicit `toolName`, which is taken verbatim.
+
+A prefix with *no* usable character at all (`'///'`, `'_'`, a fully non-ASCII
+prefix) and any explicit `toolName` outside the accepted class **throw at
+mount**. An unusable prefix is rescued by setting an explicit `toolName` — the
+prefix then never enters the name. An over-long name is fixed by a shorter
+explicit `toolName` (or a shorter prefix / method key). Nothing downstream checks this: the provider rejects the whole
+request, so one bad name takes every tool of that mount down with it.
+→ [ADR 0035](../decisions/0035-tool-name-derivation-and-validation.md).
+
 ## Endpoint metadata (`meta`)
 
+A contract can declare a **default** `meta` that every endpoint inherits, and an
+endpoint's own keys are **shallow-merged over** it:
+
+```ts
+defineContract({ prefix: 'admin', meta: { public: true } }, {
+  list: { method: 'GET', path: '/', desc: 'List', /* meta → { public: true } */ },
+  purge: { method: 'POST', path: '/purge', desc: 'Purge', meta: { rateTier: 2 } },
+  //                                          meta → { public: true, rateTier: 2 }
+})
+```
+
+One level deep — no deep merge. To **opt an endpoint out** of an inherited key,
+declare it with an explicit `undefined`:
+
+```ts
+defineContract({ prefix: 'leads', meta: { page: 'LEADS' } }, {
+  // Public website form inside an otherwise admin-gated contract:
+  submit: { method: 'POST', path: '/', desc: 'Submit', meta: { page: undefined } },
+  //                                       meta → { page: undefined } — gate off
+  list: { method: 'GET', path: '/list', desc: 'List' },   // meta → { page: 'LEADS' }
+})
+```
+
+The key stays *present* with value `undefined`, so read `meta` by **value**
+(`method.meta?.page`), never by key membership. `expose` deliberately has **no**
+contract-level equivalent
+(→ [ADR 0036](../decisions/0036-contract-level-meta.md)).
+
 `meta` is an **opaque, app-defined** bag the core attaches no meaning to — the
 same escape-hatch spirit as `scope` being a free string ([ADR 0002](../decisions/0002-generic-core.md) /
 [ADR 0021](../decisions/0021-endpoint-meta-passthrough.md)). Declare app concerns
@@ -569,7 +618,7 @@ server. See [Testing & deployment](./testing-and-deployment.md).
 | `rawRoutes` | non-contract routes (see below) |
 | `maxUploadBytes` | default multipart upload cap (bytes); per-route `EndpointDef.maxUploadBytes` overrides |
 | `port` / `hostname` | listen address — port defaults to `3000` |
-| `cors` | CORS policy — `{ origin, … }` |
+| `cors` | CORS policy — `{ origin, credentials, methods, headers, exposeHeaders }` |
 | `hooks` | lifecycle hooks (see below) |
 | `logging` | `true` for built-in request logs, or a custom `StitchLogger` |
 | `traceId` | override per-request trace-id resolution |
@@ -689,6 +738,87 @@ createServer({
 Hooks see `RuntimeContext` (loose types); handlers see `HandlerContext` (typed).
 That split is deliberate — see [ADR 0003](../decisions/0003-two-context-types.md).
 
+## Raw-response endpoints
+
+An endpoint that answers with **bytes rather than data** — a PDF download, a
+file, an SSE stream — declares `rawResponse: true` and returns the `Response` itself:
+
+```ts
+// contract
+export const documents = defineContract(
+  { prefix: 'documents', scope: 'admin' },
+  {
+    download: {
+      method: 'GET', path: '/:id/pdf', desc: 'Download a document as a PDF',
+      params: z.object({ id: z.uuid() }),
+      rawResponse: true, contentType: 'application/pdf',
+    },
+  },
+)
+
+// handler — no guard on the first line; `beforeHandle` already ran
+download: (ctx) => serveFile(ctx.req, { path: pathFor(ctx.params.id),
+                                        filename: 'offer.pdf' }),
+```
+
+The request half is untouched: `params`, `input` and `multipart` parse and
+validate exactly as elsewhere, and the endpoint goes through `beforeHandle` — so
+the **auth gate applies without a guard in the handler**. Only the response is
+handed over, so there is no `output` schema, `afterHandle` is skipped (it
+transforms data; there is none) and the endpoint is HTTP-only: never an MCP
+tool, an agent tool or a CLI command. Declaring `output`, `toolName`, `ui`,
+`annotations` or a non-HTTP `expose` alongside `rawResponse` is a type error, and throws
+at definition time for a contract assembled at runtime.
+
+On the typed client the method resolves to the untouched `Response` — the
+filename lives in `Content-Disposition`, so a `Blob` alone would lose it:
+
+```ts
+const client = createClient(documents, http)
+const res = await client.download({ id })          // Response
+const name = res.headers.get('Content-Disposition')
+const blob = await res.blob()
+```
+
+Cross-origin, remember that those headers are readable only because CORS exposes
+them — see [`cors.exposeHeaders`](#serving-files--range-requests).
+
+**Raw response or [raw route](#raw-routes)?** Both hand the `Response` to your
+code. A raw-response *endpoint* stays in the contract: only its response is
+raw — it is still routed, gated, typed and documented like every other endpoint.
+A raw *route* is outside the contract entirely — no schemas, no auth gate, no
+client — which is what you want for an OAuth redirect or a webhook, and what you
+do not want for a download.
+
+⚠️ **Delete the old raw route when you move an endpoint into the contract.** Raw
+routes are matched **first**, so a leftover one keeps serving the bytes and the
+contract endpoint — with its auth gate — never runs. stitchkit warns at startup
+when a raw route shadows a contract route, naming both and the scope being
+bypassed; treat that warning as a bug.
+
+⚠️ **A path built from user input needs a containment check.** `staticRoute`
+enforces it; `serveFile` deliberately leaves it to the caller, so an endpoint
+serving `/:filename` must not pass it through:
+
+```ts
+import { isWithinDir, serveFile } from 'stitchkit/server'
+import { resolve } from 'node:path'
+
+const ROOT = resolve('./uploads')
+
+file: (ctx) => {
+  const target = resolve(ROOT, ctx.params.filename)
+  // `../../etc/passwd` resolves outside ROOT — reject before touching disk.
+  if (!isWithinDir(ROOT, target)) throw notFound('File not found')
+  return serveFile(ctx.req, { path: target })
+},
+```
+
+`implementRemote` proxies a raw-response endpoint like any other — the remote
+`Response` is forwarded verbatim. Request headers are not relayed, so a `Range`
+sent to the proxy does not reach the origin and the full body comes back.
+→ ADR 0038.
+
 ## Raw routes
 
 Some routes cannot be a clean JSON contract — an OAuth redirect, a webhook with
@@ -782,6 +912,13 @@ It always sets `Accept-Ranges: bytes`, a weak `ETag` and `Last-Modified` (so
 and `nosniff`. `Content-Type` is auto-detected from the path — override it, or
 pass `disposition` / `cacheControl` / `etag: false`, via the options.
 
+Cross-origin, the browser lets JavaScript read only the CORS-safelisted response
+headers. stitchkit therefore exposes the download-relevant ones by default
+(`Content-Disposition`, `Content-Range`, `ETag`, …) — without that a `fetch`-based
+download cannot recover the file's name. Override with `cors.exposeHeaders`
+(extend `DEFAULT_CORS_EXPOSE_HEADERS` rather than replacing it), or pass `[]` to
+emit none.
+
 `serveFile` takes an explicit `path` and trusts it — **the caller owns
 containment**. For a URL-derived path use `staticRoute` (which enforces it) or
 `isWithinDir` first. The byte-range parser is exported on its own as
@@ -803,11 +940,20 @@ focused helper — not a sub-framework.
 
 ### SSE streaming
 
+`streamSSE` returns a `Response`, so its endpoint declares
+[`rawResponse: true`](#raw-response-endpoints) — in a plain contract handler the response
+would be serialized into `{}` (that now fails loudly instead of shipping silently).
+
 ```ts
 import { streamSSE } from 'stitchkit/server'
 
+// contract
+stream: { method: 'GET', path: '/stream', desc: 'Stream tokens',
+          rawResponse: true, contentType: 'text/event-stream' },
+
+// handler
 async function* tokens() { yield 'a'; yield 'b' }
-return streamSSE(tokens())            // → a text/event-stream Response
+stream: () => streamSSE(tokens()),    // → a text/event-stream Response
 ```
 
 The client side is [`parseSSE`](./client.md#sse).
@@ -1169,10 +1315,23 @@ By default every endpoint is a tool on every transport. `expose` narrows it:
 { method: 'GET', path: '/lookup', desc: 'Look up a price', expose: ['MCP'] }     // MCP tool only
 ```
 
+Two kinds of endpoint are **never** tools, whatever `expose` says: a `multipart`
+upload (not a tool call), and a
+[`rawResponse`](./server.md#raw-response-endpoints) endpoint (its answer is
+bytes — a tool result cannot carry them, and it would reach the model as `{}`).
+Pin the full list with `listToolNames` in a snapshot test.
+
 `desc` is the tool description the model reads — write it for the model, not
-just for a human. A `multipart` endpoint is never a tool. The tool name defaults
+just for a human. The tool name defaults
 to a verb-aware name from the method + prefix (`list` → `list_widgets`, `get` →
-`get_widget`); set `toolName` for an explicit one. See
+`get_widget`); set `toolName` for an explicit one. Derivation normalises every
+character outside `[a-zA-Z0-9_]` to `_` — the hyphen included, so `bot-status`
+derives `get_bot_status` — while a name is *accepted* if it matches
+`[a-zA-Z0-9_-]`, so a hyphen survives in an explicit `toolName`. A name that
+still cannot be delivered (illegal explicit `toolName`, over 64 characters, or a
+prefix with no usable character) throws at mount rather than at the first model
+call —
+→ [ADR 0035](../decisions/0035-tool-name-derivation-and-validation.md). See
 [Contracts → transports](./contracts.md#transports).
 
 ### Pinning tool names — `listToolNames`
@@ -1196,6 +1355,14 @@ now fails this test instead of silently breaking the clients that call the
 tool. It is also the mechanical diff when migrating a service: run it before
 and after, compare.
 
+> **This is also the guard against a forgotten `expose`.** An endpoint that
+> declares none is a tool on MCP **and** AGENT — the default is fail-open, and
+> there is no contract-level `expose` to set once (→
+> [ADR 0036](../decisions/0036-contract-level-meta.md)). A snapshot of
+> `listToolNames` fails the build the moment an endpoint you meant to keep
+> HTTP-only shows up in the list, which is the one check that catches it however
+> many places the line was forgotten.
+
 ## MCP — `createMcpHandler`
 
 `createMcpHandler` builds a complete Streamable-HTTP MCP server as a single
@@ -1234,11 +1401,11 @@ createServer({
 | `hooks` | tool-call observability hooks — `afterToolCall` fires on every result |
 | `onIncompatibleSchema` | `'throw'` (default) · `'skip'` · `'warn'` — see below |
 | `logger` | a `StitchLogger` for the `'warn'` policy |
-| `nativeTools` | register non-contract tools directly on the `McpServer` |
+| `nativeTools` | `(server, auth) => …` — register non-contract tools directly on the `McpServer`; receives the resolved identity, but is **not** a scope gate (`lifecycle` does not run for native tools) |
 | `instructions` | a short host-facing usage hint, surfaced to MCP tool-search |
 
-`services` and `context` receive the resolved identity, so a tenant can be
-shown only its own tools and every handler can read `ctx.tenantId`.
+`services`, `context` and `nativeTools` all receive the resolved identity, so a
+tenant can be shown only its own tools and every handler can read `ctx.tenantId`.
 
 ### Guarding tools — `lifecycle`
 
@@ -2479,7 +2646,13 @@ const onError = createErrorHook({
     CONFLICT: 'conflict', RATE_LIMITED: 'rate_limited',
     INTERNAL_SERVER_ERROR: 'internal',
   } satisfies Record<StitchErrorCode, string>,
-  render: (info) => ({ ok: false, error: { code: info.code, message: info.message } }),
+  // `ctx` is the request's RuntimeContext — read `ctx.traceId` for a
+  // correlation id in the envelope. Declaring it is optional.
+  render: (info, ctx) => ({
+    ok: false,
+    error: { code: info.code, message: info.message },
+    traceId: ctx.traceId,
+  }),
 })
 
 createServer({ services, hooks: { onError } })
@@ -3123,6 +3296,42 @@ current one *up to* your target, and apply each snippet.
    (`STITCH_ERROR_STATUS`, `serveFile`, `scopePrefixes`, `afterToolCall`'s
    `MethodDef`, `maxUploadBytes`) are available to adopt, not required.
 
+## Your handlers may be returning more than the contract declares
+
+stitchkit validates every handler's return value against the endpoint's `output`
+schema and **passes on the parsed result** — so any field the schema does not
+declare is silently removed. That is deliberate (the contract is the published
+shape of the response), but when you are moving a *live* API onto stitchkit it is
+invisible: TypeScript does not reject excess properties, nothing logs it, and the
+client just receives fewer fields.
+
+While migrating, turn the diagnostic on:
+
+```ts
+createServer({ services, warnOnOutputStrip: true })   // off by default
+```
+
+Every removed key is logged as a dot-path with the endpoint that produced it
+(`notes.get: secret, nested.alsoSecret`). Tool transports strip identically —
+`mountMcp` / `mountAgent` take `onOutputStrip: (toolName, paths) => …`. Read the
+list, then either widen the contract or stop returning the field, and turn the
+flag back off: it is for the migration window, not for production.
+
+## Tool names may shift between versions
+
+Derived tool names are part of your public surface — an MCP client config or an
+agent prompt refers to them by string. Before and after any upgrade that touches
+name derivation, diff them mechanically:
+
+```ts
+import { listToolNames } from 'stitchkit/tools'
+console.log(JSON.stringify(listToolNames(services), null, 2))
+```
+
+`listToolNames` never throws on an illegal name — that is deliberate, so it can
+show you the offending row when a mount would refuse it. Pin it in a snapshot
+test and a shift fails your build instead of your clients.
+
 ## When you author a breaking change in stitchkit
 
 You are on the other side of this flow — see
@@ -3212,7 +3421,7 @@ from the root `stitchkit`.
 | `ScopedDefineContract` | _type_ | the `defineContract` `createContractFactory` returns |
 | `ALL_TRANSPORTS` | constant | `['HTTP', 'MCP', 'AGENT', 'CLI']` |
 | `ContractDef` | _type_ | a defined contract |
-| `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` |
+| `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` and `meta` (a default every endpoint shallow-merges over) |
 | `EndpointDef` | _type_ | a single endpoint definition |
 | `HttpMethod` | _type_ | `GET \| POST \| PUT \| PATCH \| DELETE` |
 | `Transport` | _type_ | `HTTP \| MCP \| AGENT \| CLI` |
@@ -3276,6 +3485,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `staticRoute` | function | a raw route that serves a directory |
 | `serveFile` | function | serve a file with `Range` / `304` / `HEAD` — [guide](../guide/server.md#serving-files--range-requests) |
 | `parseByteRange` | function | parse a single `Range` header → range / `unsatisfiable` / `null` |
+| `isWithinDir` | function | path containment — `(root, resolvedTarget) => boolean`; call it before `serveFile` on any URL-derived path |
 | `weakETag` | function | a weak `ETag` from size + mtime |
 | `ServeFileOptions` | _type_ | options for `serveFile` |
 | `ByteRange` | _type_ | an inclusive `{ start, end }` byte range |
@@ -3332,6 +3542,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `corsHeaders` | function | compute CORS response headers |
 | `corsPreflightResponse` | function | build a preflight `Response` |
 | `DEFAULT_CORS_ALLOW_HEADERS` | const | the default `Access-Control-Allow-Headers` (incl. `traceparent`) — extend it when overriding `cors.headers` |
+| `DEFAULT_CORS_EXPOSE_HEADERS` | const | the default `Access-Control-Expose-Headers` (incl. `Content-Disposition`, `ETag`, `Content-Range`) — extend it when overriding `cors.exposeHeaders` |
 | `CookieDef` | _type_ | the `defineCookie` handle |
 | `CookieOptions` | _type_ | cookie attributes |
 | `CorsConfig` | _type_ | CORS policy |

package/llms.txt

@@ -7,7 +7,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 ## Guide
 - [Getting started](https://github.com/max-listov/stitchkit/blob/master/docs/guide/getting-started.md): install, entrypoints, and a first contract → server → client app
 - [Contracts](https://github.com/max-listov/stitchkit/blob/master/docs/guide/contracts.md): every endpoint field — method, path, params/input/output, scope, expose, meta, multipart
-- [HTTP server](https://github.com/max-listov/stitchkit/blob/master/docs/guide/server.md): createServer/createHandler, implement, lifecycle hooks, raw routes + helpers, scopePrefixes, serveFile, primitives
+- [HTTP server](https://github.com/max-listov/stitchkit/blob/master/docs/guide/server.md): createServer/createHandler, implement, lifecycle hooks, raw routes + raw-response endpoints + helpers, scopePrefixes, serveFile, primitives
 - [Typed client](https://github.com/max-listov/stitchkit/blob/master/docs/guide/client.md): createClient/createHttpClient, the typed call surface, scoped clients, SSE
 - [MCP & agents](https://github.com/max-listov/stitchkit/blob/master/docs/guide/mcp-and-agents.md): contracts as MCP tools (createMcpHandler) and AI-agent tools (mountAgent); tool lifecycle, extend, identity
 - [CLI](https://github.com/max-listov/stitchkit/blob/master/docs/guide/cli.md): contracts as a command-line program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",