stitchkit 0.25.0 → 0.27.0

package/dist/browser/client-multipart.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Multipart field encoding for the client — the platform-sensitive corner of
+ * `client.ts`, split out so the request-building logic there reads without it.
+ *
+ * Internal: none of this is public surface. The React Native descriptor path is
+ * the only genuinely subtle part, and keeping it together with its two guards
+ * makes that subtlety readable in one screen.
+ */
+import type { MultipartFile } from '../contract';
+/** A multipart file field — a `Blob` (web / Bun) or a platform descriptor (RN). */
+export declare function isMultipartFile(value: unknown): value is MultipartFile;
+/**
+ * Append the file part. `FormData.append` is typed `(name, value: string | Blob)`
+ * by the DOM lib, but on React Native attaching a `{ uri, name, type }`
+ * descriptor is the native way to send a file (RN streams it from disk). Route
+ * through a structural type whose `append` also accepts a `FileDescriptor` —
+ * method-parameter bivariance lets the real `FormData` satisfy it, so the
+ * descriptor path stays cast-free. Web / Bun still pass a `Blob`.
+ */
+export declare function appendMultipartFile(form: FormData, field: string, file: MultipartFile): void;
+export declare function appendFormFields(formData: FormData, values: Record<string, unknown>, skipKeys: Set<string>): void;
+//# sourceMappingURL=client-multipart.d.ts.map

package/dist/browser/client-multipart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-multipart.d.ts","sourceRoot":"","sources":["../../src/browser/client-multipart.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAkB,aAAa,EAAE,MAAM,aAAa,CAAC;AAqBjE,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAG5F;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,GACpB,IAAI,CAKN"}

package/dist/browser/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/browser/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EAGX,gBAAgB,EAChB,eAAe,EAChB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAEL,KAAK,UAAU,IAAI,WAAW,EAG/B,MAAM,QAAQ,CAAC;AA+EhB,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClE,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;CACnD;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC1D,OAAO,GACP;KAAG,CAAC,IAAI,CAAC,GAAG,MAAM;CAAE,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,MAAM,GAAG,KAAK;IAC5D,UAAU,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,CAAC;IAClE,eAAe,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACrC,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,KAAK,EAE9B,QAAQ,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,EAChC,cAAc,EAAE,YAAY,GAAG,WAAW,EAC1C,cAAc,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,GACvC,gBAAgB,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAepC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC,EAC1E,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;CAAE,CAKzF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/browser/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAI/F,OAAO,EAEL,KAAK,UAAU,IAAI,WAAW,EAG/B,MAAM,QAAQ,CAAC;AAsFhB,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClE,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;CACnD;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC1D,OAAO,GACP;KAAG,CAAC,IAAI,CAAC,GAAG,MAAM;CAAE,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,MAAM,GAAG,KAAK;IAC5D,UAAU,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,CAAC;IAClE,eAAe,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACrC,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,KAAK,EAE9B,QAAQ,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,EAChC,cAAc,EAAE,YAAY,GAAG,WAAW,EAC1C,cAAc,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,GACvC,gBAAgB,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAepC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC,EAC1E,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;CAAE,CAKzF"}

package/dist/browser/http.d.ts

@@ -65,7 +65,13 @@ type ParamArrayValue = Array<string | number>;
 export interface RequestOptions {
     params?: Record<string, ParamValue | ParamArrayValue>;
     timeout?: number;
-    responseType?: 'json' | 'blob';
+    /**
+     * How to read the body. `'response'` hands back the untouched `Response` —
+     * what a `raw` endpoint answers with, and strictly more than `'blob'`: the
+     * caller still gets `.blob()` / `.body`, plus the headers where
+     * `Content-Disposition` (the download filename) lives.
+     */
+    responseType?: 'json' | 'blob' | 'response';
 }
 /** The HTTP transport adapter `createClient` builds typed methods on. */
 export interface HttpClient {

package/dist/browser/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/browser/http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/browser/http.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -4,9 +4,9 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-h9d1fm0p.js";
+} from "./index-4whcb3c3.js";
 import"./index-0ed3bx43.js";
-import"./index-4gawbm74.js";
+import"./index-zza375qp.js";
 import"./index-c7nyw0yt.js";
 export {
   pollUntilDone,

package/dist/contract/define.d.ts

@@ -93,6 +93,7 @@ export interface EndpointToolAnnotations {
 interface HttpOnlyEndpointDef extends EndpointDefBase {
     expose: readonly ['HTTP'];
     toolName?: never;
+    rawResponse?: never;
 }
 interface ToolEndpointDef extends EndpointDefBase {
     toolName?: string;
@@ -101,11 +102,70 @@ interface ToolEndpointDef extends EndpointDefBase {
     ui?: EndpointUiMeta;
     /** MCP behavioural hints (read-only / destructive / title) for hosts. */
     annotations?: EndpointToolAnnotations;
+    rawResponse?: never;
 }
-export type EndpointDef = HttpOnlyEndpointDef | ToolEndpointDef;
+/**
+ * An endpoint whose handler returns the **`Response` itself** instead of data —
+ * a file download, a PDF, an SSE stream, a redirect. → ADR 0038.
+ *
+ * ```ts
+ * pdf: {
+ *   method: 'GET', path: '/:id/pdf', desc: 'Download the offer as a PDF',
+ *   params: z.object({ id: z.uuid() }),
+ *   rawResponse: true, contentType: 'application/pdf',
+ * }
+ * ```
+ *
+ * Only the **response** is raw — hence the name, and the difference from
+ * `rawRoutes`, which sit outside the contract entirely. Here the request half is
+ * unchanged: `params` / `input` / `multipart` parse and validate exactly as
+ * elsewhere, and `beforeHandle` runs, so the auth gate applies with no guard in
+ * the handler. What is handed over is the response, so there is no `output` to
+ * validate, nothing to serialize into a tool result, and the endpoint is
+ * **HTTP-only**: never an MCP tool, an agent tool or a CLI command.
+ * `afterHandle` is skipped (it transforms data; there is none).
+ */
+interface RawResponseEndpointDef extends EndpointDefBase {
+    /**
+     * Marks the response as raw. Must be the literal `true` — it is the
+     * discriminant of the union, so `rawResponse: false` is not a way to say
+     * "normal".
+     */
+    rawResponse: true;
+    /**
+     * The `Content-Type` this endpoint answers with, for documentation only —
+     * the handler still sets the real header (`serveFile` detects it from the
+     * path). Drives the OpenAPI response media type; without it the endpoint
+     * documents as `application/octet-stream`.
+     */
+    contentType?: string;
+    /** There is no output schema — the handler owns the whole response. */
+    output?: never;
+    /** Never a tool, so a tool name would be dead metadata. */
+    toolName?: never;
+    /** MCP-only decoration; a raw endpoint never reaches MCP. */
+    ui?: never;
+    /** MCP-only decoration; a raw endpoint never reaches MCP. */
+    annotations?: never;
+    /** Redundant but allowed, so `expose: ['HTTP']` survives a migration. */
+    expose?: readonly ['HTTP'];
+}
+export type EndpointDef = HttpOnlyEndpointDef | ToolEndpointDef | RawResponseEndpointDef;
 export interface ContractMeta<TScope extends string = string> {
     prefix: string;
     scope?: TScope;
+    /**
+     * Contract-wide default for every endpoint's opaque `meta` (→ ADR 0021).
+     * Endpoints **shallow-merge** over it, key by key — so a contract-wide
+     * `{ public: true }` survives an endpoint that adds `{ rateTier: 2 }`. One
+     * level only, no deep merge. An explicit `key: undefined` on the endpoint is
+     * the opt-out: it shadows the contract's value, so `meta?.key` readers see
+     * nothing — test values, not key membership. → ADR 0036.
+     *
+     * `expose` deliberately has no equivalent — see ADR 0036 for why, and pin
+     * `listToolNames` in a snapshot to catch an endpoint that forgot it.
+     */
+    meta?: Record<string, unknown>;
 }
 export interface ContractDef<T extends Record<string, EndpointDef> = Record<string, EndpointDef>, TScope extends string = string> {
     meta: ContractMeta<TScope>;
@@ -119,11 +179,21 @@ export interface ContractDef<T extends Record<string, EndpointDef> = Record<stri
  */
 export declare function defineContract<const T extends Record<string, EndpointDef>>(meta: {
     prefix: string;
+    meta?: Record<string, unknown>;
 }, endpoints: T): ContractDef<T, 'public'>;
 export declare function defineContract<TScope extends string, const T extends Record<string, EndpointDef>>(meta: {
     prefix: string;
     scope: TScope;
+    meta?: Record<string, unknown>;
 }, endpoints: T): ContractDef<T, TScope>;
+/**
+ * Shallow-merge a contract-wide `meta` default with an endpoint's own — endpoint
+ * keys win. Returns `undefined` when neither side declares anything, because
+ * readers test `method.meta?.x` and an empty object would read as "declared".
+ * One level deep by design: a deep merge invites "how do I unset an inherited
+ * key", which has no answer without a sentinel. → ADR 0036.
+ */
+export declare function mergeMeta(contractMeta: Record<string, unknown> | undefined, endpointMeta: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
 export interface RuntimeContext {
     params: unknown;
     input: unknown;
@@ -191,7 +261,14 @@ type MultipartArgs<E> = E extends {
     [P in K]: MultipartFile;
 } : unknown;
 type EndpointArgs<E> = InferInput<Prop<E, 'params'>> & InferInput<Prop<E, 'input'>> & MultipartArgs<E>;
-type EndpointOutput<E> = Prop<E, 'output'> extends ZodType<infer O> ? O : undefined;
+/**
+ * What the typed client resolves to. A `raw` endpoint hands back the untouched
+ * `Response` — its body is bytes, and the headers carry what the caller needs
+ * (`Content-Disposition`, `Content-Range`, `ETag`). → ADR 0038.
+ */
+type EndpointOutput<E> = E extends {
+    rawResponse: true;
+} ? Response : Prop<E, 'output'> extends ZodType<infer O> ? O : undefined;
 export type EndpointFn<E> = [keyof EndpointArgs<E>] extends [never] ? () => Promise<EndpointOutput<E>> : (args: EndpointArgs<E>) => Promise<EndpointOutput<E>>;
 export type TypedClient<C extends Record<string, EndpointDef>> = {
     [K in keyof C]: EndpointFn<C[K]>;

package/dist/contract/define.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/contract/define.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/contract/define.ts"],"names":[],"mappings":"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"}

package/dist/contract/factory.d.ts

@@ -25,6 +25,7 @@ import type { ContractDef, EndpointDef } from './define';
 export type ScopedDefineContract<TScope extends string> = <const T extends Record<string, EndpointDef>>(meta: {
     prefix: string;
     scope: TScope;
+    meta?: Record<string, unknown>;
 }, endpoints: T) => ContractDef<T, TScope>;
 /**
  * Build a `defineContract` that requires a `scope` from the application's own

package/dist/contract/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/contract/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGzD,0EAA0E;AAC1E,MAAM,MAAM,oBAAoB,CAAC,MAAM,SAAS,MAAM,IAAI,CACxD,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAE3C,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EACvC,SAAS,EAAE,CAAC,KACT,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAE5B;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,SAAS,MAAM,KAAK;IAC9D,cAAc,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;CAC9C,CAcA"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/contract/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGzD,0EAA0E;AAC1E,MAAM,MAAM,oBAAoB,CAAC,MAAM,SAAS,MAAM,IAAI,CACxD,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAE3C,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EACvE,SAAS,EAAE,CAAC,KACT,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAE5B;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,SAAS,MAAM,KAAK;IAC9D,cAAc,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;CAC9C,CAiBA"}

package/dist/contract/index.js

@@ -16,7 +16,7 @@ import {
   paginatedSchema,
   rateLimited,
   unauthorized
-} from "../index-x62gnfsk.js";
+} from "../index-pmftwk2a.js";
 import"../index-809wc1tt.js";
 export {
   unauthorized,

package/dist/{index-h9d1fm0p.js → index-4whcb3c3.js}

@@ -7,7 +7,7 @@ import {
   isWithinDir,
   normalizeError,
   validateHandlerOutput
-} from "./index-4gawbm74.js";
+} from "./index-zza375qp.js";
 import {
   isRecord,
   isUnsafeKey,
@@ -346,7 +346,7 @@ function toolResultFromError(err) {
     ...appErr.hint && { hint: appErr.hint }
   };
 }
-async function executeToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson = false) {
+async function executeToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson = false, onOutputStrip) {
   const startedAt = Date.now();
   const finish = async (result) => {
     await hooks?.afterToolCall?.(toolName, rawArgs, result, Date.now() - startedAt, context, method);
@@ -410,7 +410,7 @@ async function executeToolMethod(method, toolName, rawArgs, context, hooks, life
         data = transformed;
     }
     if (method.outputSchema) {
-      const checked = validateHandlerOutput(method.outputSchema, data);
+      const checked = validateHandlerOutput(method.outputSchema, data, onOutputStrip);
       if (!checked.ok) {
         return finish({
           ok: false,
@@ -437,6 +437,13 @@ var SINGULAR_EXCEPTIONS = new Set([
   "progress",
   "news"
 ]);
+var TOOL_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+function normalizeService(value) {
+  return value.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+function normalizeMethod(value) {
+  return value.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
 function singularize(name) {
   if (SINGULAR_EXCEPTIONS.has(name))
     return name;
@@ -446,22 +453,44 @@ function singularize(name) {
     return name.slice(0, -1);
   return name;
 }
+function singularizeTail(name) {
+  const cut = name.lastIndexOf("_");
+  if (cut === -1)
+    return singularize(name);
+  return `${name.slice(0, cut + 1)}${singularize(name.slice(cut + 1))}`;
+}
+function hasUsableChars(value) {
+  return /[a-zA-Z0-9]/.test(value);
+}
+function assertToolName(name, serviceName, key) {
+  const where = `service "${serviceName}", method "${key}"`;
+  if (!TOOL_NAME_RE.test(name)) {
+    const why = name.length > 64 ? `is ${name.length} characters (max 64) — set an explicit \`toolName\`` : "must match [a-zA-Z0-9_-]";
+    throw new Error(`Tool name "${name}" (${where}) ${why}`);
+  }
+}
 function toToolName(serviceName, methodName) {
-  const normalized = serviceName.replace(/-/g, "_");
-  const singular = singularize(normalized);
-  if (methodName === "list")
+  const normalized = normalizeService(serviceName);
+  const singular = singularizeTail(normalized);
+  const method = normalizeMethod(methodName);
+  if (method === "list")
     return `list_${normalized}`;
-  if (methodName === "get")
+  if (method === "get")
     return `get_${singular}`;
-  if (methodName === "create")
+  if (method === "create")
     return `create_${singular}`;
-  if (methodName === "update")
+  if (method === "update")
     return `update_${singular}`;
-  if (methodName === "delete")
+  if (method === "delete")
     return `delete_${singular}`;
-  const snake = methodName.replace(/([A-Z])/g, "_$1").toLowerCase();
+  const snake = method.replace(/([A-Z])/g, "_$1").toLowerCase();
   return `${snake}_${singular}`.replace(/^_/, "");
 }
+function assertUniqueToolName(name, taken, surface) {
+  if (taken) {
+    throw new Error(`Duplicate ${surface} "${name}" across mounted services`);
+  }
+}
 
 // src/tools/mount.ts
 function applyExtend(base, extra) {
@@ -475,7 +504,7 @@ function applyExtend(base, extra) {
   return z4.intersection(z4.object(extra), base);
 }
 function collectTools(service, transport, config = {}) {
-  const { extend, flattenUnionInput = false } = config;
+  const { extend, flattenUnionInput = false, assertNames = true } = config;
   const tools = [];
   for (const [methodName, method] of Object.entries(service.methods)) {
     if (transport === "CLI") {
@@ -486,7 +515,15 @@ function collectTools(service, transport, config = {}) {
     }
     if (method.multipart)
       continue;
+    if (method.rawResponse)
+      continue;
     const name = method.toolName ?? toToolName(service.name, methodName);
+    if (assertNames && transport !== "CLI") {
+      if (!method.toolName && !hasUsableChars(service.name)) {
+        throw new Error(`Service prefix "${service.name}" (method "${methodName}") has no characters usable in a tool name — set an explicit \`toolName\` or rename the prefix`);
+      }
+      assertToolName(name, service.name, methodName);
+    }
     const baseSchema = flattenUnionInput ? mergeSchemas(method.paramsSchema ? flattenUnionsDeep(method.paramsSchema) : undefined, method.inputSchema ? flattenUnionsDeep(method.inputSchema) : undefined) : mergeSchemas(method.paramsSchema, method.inputSchema);
     const shouldExtend = !!extend && (!extend.filter || extend.filter(service, method));
     const schema = shouldExtend && extend ? applyExtend(baseSchema, extend.schema) : baseSchema;
@@ -502,7 +539,7 @@ function createToolRunner(config) {
       extraContext = await config.extend.resolve(rawArgs);
     }
     const cleanArgs = tool.shouldExtend && extendKeys ? Object.fromEntries(Object.entries(rawArgs).filter(([key]) => !extendKeys.has(key))) : rawArgs;
-    return executeToolMethod(tool.method, tool.name, cleanArgs, { ...config.context, ...extraContext, source: config.source }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true);
+    return executeToolMethod(tool.method, tool.name, cleanArgs, { ...config.context, ...extraContext, source: config.source }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(tool.name, paths) : undefined);
   };
 }
 function formatToolError(result, toolName, errorHint) {
@@ -845,7 +882,6 @@ async function pollUntilDone(params) {
 }
 
 // src/tools/cli.ts
-import { mkdir, writeFile } from "node:fs/promises";
 import { basename, resolve } from "node:path";
 import process from "node:process";
 
@@ -962,6 +998,17 @@ async function readCapped(res, max) {
   return Buffer.concat(chunks);
 }
 
+// src/internal/write-download.ts
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+async function writeDownload(root, target, data) {
+  if (!isWithinDir(root, target)) {
+    throw new Error("download name escapes the output dir");
+  }
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, data);
+}
+
 // src/tools/cli.ts
 var GLOBAL_OPTIONS = [
   ["--json", "Emit raw JSON on stdout (for piping / scripts)"],
@@ -1085,7 +1132,6 @@ function renderCommandHelp(name, command, tool) {
 var DEFAULT_DOWNLOAD_MAX_BYTES = 100 * 1024 * 1024;
 async function downloadResults(files, dir, stderr, quiet, allowPrivate, maxBytes) {
   const root = resolve(dir);
-  await mkdir(root, { recursive: true });
   for (const file of files) {
     try {
       const res = await fetchGuarded(new URL(file.url), allowPrivate);
@@ -1095,9 +1141,7 @@ async function downloadResults(files, dir, stderr, quiet, allowPrivate, maxBytes
       if (!buffer)
         throw new Error(`file exceeds the ${maxBytes}-byte cap`);
       const target = resolve(root, basename(file.name));
-      if (!isWithinDir(root, target))
-        throw new Error("download name escapes the output dir");
-      await writeFile(target, buffer);
+      await writeDownload(root, target, buffer);
       if (!quiet)
         stderr(`saved ${target} (${(buffer.length / 1024).toFixed(0)}KB)
 `);
@@ -1119,9 +1163,7 @@ async function createCli(config) {
   const tools = new Map;
   for (const service of services) {
     for (const mountable of collectTools(service, "CLI")) {
-      if (tools.has(mountable.name)) {
-        throw new Error(`Duplicate CLI command "${mountable.name}" across mounted services`);
-      }
+      assertUniqueToolName(mountable.name, tools.has(mountable.name), "CLI command");
       tools.set(mountable.name, mountable);
     }
   }
@@ -1216,4 +1258,4 @@ function safeInputSchema(tool) {
   }
 }
 
-export { coerceJsonArgs, toolResultFromError, flattenDiscriminatedUnion, flattenUnionsDeep, collectTools, createToolRunner, formatToolError, fetchGuarded, readCapped, parseCliArgs, DEFAULT_EXIT_CODES, emitResult, pollUntil, pollUntilDone, createCli };
+export { coerceJsonArgs, toolResultFromError, flattenDiscriminatedUnion, flattenUnionsDeep, assertToolName, assertUniqueToolName, collectTools, createToolRunner, formatToolError, fetchGuarded, readCapped, writeDownload, parseCliArgs, DEFAULT_EXIT_CODES, emitResult, pollUntil, pollUntilDone, createCli };

package/dist/{index-a9n8m4ec.js → index-jvescqgr.js}

@@ -3,7 +3,7 @@ import {
   bytesToBase64Url,
   forbidden,
   unauthorized
-} from "./index-4gawbm74.js";
+} from "./index-zza375qp.js";
 import {
   isRecord,
   isUnsafeKey,

package/dist/{index-x62gnfsk.js → index-pmftwk2a.js}

@@ -10,6 +10,8 @@ function defineContract(meta, endpoints) {
     if (ep.desc.trim() === "") {
       throw new Error(`Contract "${meta.prefix}": endpoint "${key}" has an empty desc`);
     }
+    if (ep.rawResponse)
+      assertRawEndpoint(meta.prefix, key, ep);
     if (!("toolName" in ep) || !ep.toolName)
       continue;
     const transports = new Set(ep.expose ? ep.expose.filter((t) => t !== "HTTP") : ["MCP", "AGENT"]);
@@ -30,6 +32,22 @@ function defineContract(meta, endpoints) {
   }
   return { meta, endpoints };
 }
+function assertRawEndpoint(prefix, key, ep) {
+  const where = `Contract "${prefix}": raw endpoint "${key}"`;
+  if (ep.output)
+    throw new Error(`${where} cannot declare an output schema`);
+  if ("toolName" in ep && ep.toolName)
+    throw new Error(`${where} cannot set a toolName`);
+  if ("ui" in ep && ep.ui)
+    throw new Error(`${where} cannot set MCP ui metadata`);
+  if ("annotations" in ep && ep.annotations) {
+    throw new Error(`${where} cannot set MCP annotations`);
+  }
+  const nonHttp = (ep.expose ?? []).filter((t) => t !== "HTTP");
+  if (nonHttp.length > 0) {
+    throw new Error(`${where} is HTTP-only — remove ${nonHttp.join(", ")} from expose`);
+  }
+}
 // src/contract/errors.ts
 var APP_ERROR_BRAND = Symbol.for("stitchkit.AppError");
 
@@ -116,7 +134,7 @@ function createContractFactory() {
       const validated = defineContract({ prefix: meta.prefix }, endpoints);
       return {
         endpoints: validated.endpoints,
-        meta: { prefix: meta.prefix, scope: meta.scope }
+        meta: { ...meta, prefix: meta.prefix, scope: meta.scope }
       };
     }
   };

package/dist/{index-g8kyab85.js → index-y4132gqh.js}

@@ -2,15 +2,16 @@ import {
   assertCorsConfig,
   corsHeaders,
   corsPreflightResponse
-} from "./index-tje0q6gp.js";
+} from "./index-zfscdskj.js";
 import {
   AppError,
   badRequest,
   errorCode,
   isWithinDir,
+  mergeMeta,
   normalizeError,
   validateHandlerOutput
-} from "./index-4gawbm74.js";
+} from "./index-zza375qp.js";
 import {
   extractIp,
   getClientInfo,
@@ -212,6 +213,26 @@ function validateRoutes(routeMap) {
     }
   }
 }
+function findShadowedRoutes(routeMap, rawRoutes) {
+  if (!rawRoutes || rawRoutes.length === 0)
+    return [];
+  const shadowed = [];
+  for (const [httpMethod, entries] of routeMap) {
+    for (const entry of entries) {
+      const probe = `/${entry.segments.map((s) => s.startsWith(":") ? "__param__" : s).join("/")}`;
+      const match = matchRawRoute(rawRoutes, httpMethod, probe);
+      if (!match)
+        continue;
+      shadowed.push({
+        pattern: `${httpMethod} ${entry.pattern}`,
+        endpoint: `${entry.method.serviceName}.${entry.method.key}`,
+        rawRoute: `${match.route.method} ${match.route.path}`,
+        scope: entry.method.scope
+      });
+    }
+  }
+  return shadowed;
+}
 function matchRawRoute(rawRoutes, httpMethod, pathname) {
   for (const route of rawRoutes) {
     if (route.method !== "ALL" && route.method !== httpMethod)
@@ -476,6 +497,14 @@ function createHandler(config) {
   const resolveId = config.traceId ?? resolveTraceId;
   const routeMap = buildRouteMap(normalizeGroups(config));
   validateRoutes(routeMap);
+  for (const shadow of findShadowedRoutes(routeMap, config.rawRoutes)) {
+    const gate = shadow.scope && shadow.scope !== "public" ? ` (scope "${shadow.scope}")` : "";
+    const line = `[stitchkit] raw route ${shadow.rawRoute} shadows contract route ${shadow.pattern}` + ` → ${shadow.endpoint}${gate} will never run, and its hooks never apply`;
+    if (customLogger)
+      customLogger.warn(line);
+    else
+      console.warn(line);
+  }
   async function dispatch(req, url, traceId, server, clientIp) {
     const shouldLogRequest = logging && shouldLog(url.pathname, req.method);
     const ipAddress = extractIp(req, clientIp) || undefined;
@@ -570,6 +599,14 @@ function createHandler(config) {
         await groupHooks.beforeHandle(ctx, method);
       }
       let result = await method.handler(ctx);
+      if (method.rawResponse) {
+        if (!(result instanceof Response)) {
+          throw new AppError("INTERNAL_SERVER_ERROR", `Raw endpoint ${method.serviceName}.${method.key} must return a Response`, 500);
+        }
+        const rawRes = applyCors(result, cors, req);
+        logDone(rawRes.status);
+        return rawRes;
+      }
       if (groupHooks?.afterHandle) {
         const transformed = await groupHooks.afterHandle(ctx, result, method);
         if (transformed !== undefined)
@@ -580,8 +617,17 @@ function createHandler(config) {
         if (transformed !== undefined)
           result = transformed;
       }
+      if (result instanceof Response) {
+        throw new AppError("INTERNAL_SERVER_ERROR", `${method.serviceName}.${method.key} produced a Response on the data path — only a \`rawResponse: true\` endpoint may return one (an afterHandle hook must return data)`, 500);
+      }
       if (method.outputSchema) {
-        const checked = validateHandlerOutput(method.outputSchema, result);
+        const checked = validateHandlerOutput(method.outputSchema, result, config.warnOnOutputStrip ? (paths) => {
+          const line = `[stitchkit] output strip ${method.serviceName}.${method.key}: ${paths.join(", ")}`;
+          if (customLogger)
+            customLogger.warn(line);
+          else
+            console.warn(line);
+        } : undefined);
         if (!checked.ok) {
           throw new AppError("INTERNAL_SERVER_ERROR", checked.message, 500);
         }
@@ -656,20 +702,41 @@ function applyCors(res, cors, req) {
   const extra = corsHeaders2(cors, req);
   if (Object.keys(extra).length === 0)
     return res;
-  const headers = new Headers(res.headers);
-  for (const [key, value] of Object.entries(extra))
+  try {
+    for (const [key, value] of Object.entries(extra))
+      setCorsHeader(res.headers, key, value);
+    return res;
+  } catch {
+    const headers = new Headers(res.headers);
+    for (const [key, value] of Object.entries(extra))
+      setCorsHeader(headers, key, value);
+    return new Response(res.body, {
+      status: res.status,
+      statusText: res.statusText,
+      headers
+    });
+  }
+}
+function setCorsHeader(headers, key, value) {
+  if (key !== "Vary") {
     headers.set(key, value);
-  return new Response(res.body, {
-    status: res.status,
-    statusText: res.statusText,
-    headers
-  });
+    return;
+  }
+  const existing = headers.get("Vary");
+  if (existing === null || existing.trim() === "") {
+    headers.set("Vary", value);
+    return;
+  }
+  const present = existing.split(",").some((field) => field.trim().toLowerCase() === "origin");
+  if (!present)
+    headers.set("Vary", `${existing}, ${value}`);
 }
 function json(data, status, cors, req) {
   return Response.json(data, { status, headers: corsHeaders2(cors, req) });
 }
 
 // src/server/implement.ts
+var HTTP_ONLY = Object.freeze(["HTTP"]);
 function implement(contract, handlers) {
   const methods = {};
   const groupScope = contract.meta.scope ?? "public";
@@ -682,7 +749,7 @@ function implement(contract, handlers) {
       serviceName: contract.meta.prefix,
       key: String(key),
       toolName: "toolName" in endpoint ? endpoint.toolName : undefined,
-      expose: endpoint.expose,
+      expose: endpoint.rawResponse ? HTTP_ONLY : endpoint.expose,
       scope: endpoint.scope ?? groupScope,
       paramsSchema: endpoint.params,
       inputSchema: endpoint.input,
@@ -692,7 +759,9 @@ function implement(contract, handlers) {
       idempotent: endpoint.idempotent,
       ui: "ui" in endpoint ? endpoint.ui : undefined,
       annotations: "annotations" in endpoint ? endpoint.annotations : undefined,
-      meta: endpoint.meta,
+      meta: mergeMeta(contract.meta.meta, endpoint.meta),
+      rawResponse: endpoint.rawResponse,
+      contentType: "contentType" in endpoint ? endpoint.contentType : undefined,
       handler: (ctx) => typedHandler(ctx)
     };
   }