@codewithagents/openapi-server 1.8.0 → 1.10.0

package/dist/plugins/router.js

@@ -1,4 +1,4 @@
-import { SUPPORTED_METHODS, isRef, extractPathParamsFromPath, resolveParam, deriveServiceName, deriveMethodName, getQueryParams, getBodyInfo, } from './shared.js';
+import { SUPPORTED_METHODS, isRef, refToName, extractPathParamsFromPath, resolveParam, deriveServiceName, deriveMethodName, getQueryParams, getBodyInfo, } from './shared.js';
 /** Convert OpenAPI path to Hono path: {id} -> :id */
 function toHonoPath(openapiPath) {
     return openapiPath.replace(/\{([^}]+)\}/g, ':$1');
@@ -24,13 +24,38 @@ function formatToZodModifier(format) {
 }
 /**
  * Build a Zod expression for a path parameter based on its schema.
- * Returns undefined when the parameter does not need format validation
- * (simple string with no format constraint or non-string types used as strings in URLs).
+ * Returns undefined when the parameter does not need validation.
+ *
+ * String params: validates format (uuid, email, url, date-time) via z.string().format().
+ * Integer/number params: validates range (minimum/maximum) via z.coerce.number().min().max().
+ * z.coerce.number() is used for path params because c.req.param() always returns a string;
+ * coercion converts the URL string to a number before the min/max check.
  */
 function pathParamZodExpr(schema) {
     if (schema === undefined || isRef(schema))
         return undefined;
     const s = schema;
+    // Integer / number path params with range constraints
+    if (s.type === 'integer' || s.type === 'number') {
+        const hasMin = typeof s.minimum === 'number';
+        const hasMax = typeof s.maximum === 'number';
+        const hasExcMin = typeof s.exclusiveMinimum === 'number';
+        const hasExcMax = typeof s.exclusiveMaximum === 'number';
+        if (hasMin || hasMax || hasExcMin || hasExcMax) {
+            let expr = 'z.coerce.number()';
+            if (hasMin)
+                expr += `.min(${s.minimum})`;
+            if (hasMax)
+                expr += `.max(${s.maximum})`;
+            if (hasExcMin)
+                expr += `.gt(${s.exclusiveMinimum})`;
+            if (hasExcMax)
+                expr += `.lt(${s.exclusiveMaximum})`;
+            return expr;
+        }
+        return undefined;
+    }
+    // String path params: only validated when a known format modifier exists
     if (s.type !== 'string')
         return undefined;
     const format = s.format;
@@ -41,33 +66,104 @@ function pathParamZodExpr(schema) {
         return undefined;
     return `z.string()${modifier}`;
 }
+// ── queryParamZodExpr helpers (one per param kind) ───────────────────────────
+/** Delimited array param: value has been split into string[] by the extraction layer. */
+function queryParamDelimitedZodBase(_param) {
+    return 'z.array(z.string())';
+}
 /**
- * Build a Zod expression for a query or header parameter based on its schema.
+ * DeepObject param: assembled into Record<string, string>.
+ * Emits z.object({...}) with per-property coercion; all properties are .optional()
+ * because their presence is governed by the outer object's required flag.
+ */
+function queryParamDeepObjectZodBase(param) {
+    const propFields = (param.deepObjectProperties ?? []).map((p) => {
+        const coerced = p.tsType === 'number' ? 'z.coerce.number()' : 'z.string()';
+        return `${p.key}: ${coerced}.optional()`;
+    });
+    return `z.object({ ${propFields.join(', ')} })`;
+}
+/** Number/integer param: z.coerce.number() with optional range modifiers.
+ * Uses coerce so that Fastify's raw string values (fast-querystring never converts types)
+ * are accepted alongside the already-coerced numbers from Express/Hono extraction. */
+function queryParamNumberZodBase(param) {
+    let base = 'z.coerce.number()';
+    if (param.minimum !== undefined)
+        base += `.min(${param.minimum})`;
+    if (param.maximum !== undefined)
+        base += `.max(${param.maximum})`;
+    if (param.exclusiveMinimum !== undefined)
+        base += `.gt(${param.exclusiveMinimum})`;
+    if (param.exclusiveMaximum !== undefined)
+        base += `.lt(${param.exclusiveMaximum})`;
+    return base;
+}
+/** String param: z.string() or z.enum([...]) with optional length/pattern modifiers. */
+function queryParamStringZodBase(param) {
+    let base;
+    if (param.enum !== undefined && param.enum.length > 0) {
+        const members = param.enum.map((v) => JSON.stringify(v)).join(', ');
+        base = `z.enum([${members}])`;
+    }
+    else {
+        base = 'z.string()';
+    }
+    if (param.minLength !== undefined)
+        base += `.min(${param.minLength})`;
+    if (param.maxLength !== undefined)
+        base += `.max(${param.maxLength})`;
+    if (param.pattern !== undefined)
+        base += `.regex(/${param.pattern}/)`;
+    return base;
+}
+/**
+ * Build a Zod expression for a query parameter based on its captured constraints.
  * Number/integer types use z.number() (after coercion by extraction code).
- * String types use z.string(). Boolean types use z.boolean().
+ * String types use z.string() with optional format/enum/pattern/length modifiers.
+ * Delimited array params use z.array(z.string()).
+ * DeepObject params use z.object({...}) with per-property coercion.
  * Appends .optional() for non-required params.
  */
-function paramZodExpr(tsType, required, schema) {
+function queryParamZodExpr(param) {
     let base;
-    if (tsType === 'number') {
-        base = 'z.number()';
+    if (param.delimiterStyle !== undefined) {
+        base = queryParamDelimitedZodBase(param);
+    }
+    else if (param.isDeepObject === true && param.deepObjectProperties !== undefined) {
+        base = queryParamDeepObjectZodBase(param);
+    }
+    else if (param.tsType === 'number') {
+        base = queryParamNumberZodBase(param);
     }
-    else if (tsType === 'boolean') {
+    else if (param.tsType === 'boolean') {
         base = 'z.boolean()';
     }
     else {
-        // string
-        if (schema !== undefined && !isRef(schema)) {
-            const s = schema;
-            const format = s.format;
-            const modifier = format !== undefined ? formatToZodModifier(format) : '';
-            base = `z.string()${modifier}`;
-        }
-        else {
-            base = 'z.string()';
-        }
+        base = queryParamStringZodBase(param);
+    }
+    return param.required ? base : `${base}.optional()`;
+}
+/**
+ * Build a Zod expression for a header parameter based on its captured constraints.
+ * Header values are always strings; emits z.string() or z.enum([...]) with optional
+ * pattern/length modifiers. Appends .optional() for non-required params.
+ */
+function headerParamZodExpr(param) {
+    let base;
+    if (param.enum !== undefined && param.enum.length > 0) {
+        const members = param.enum.map((v) => JSON.stringify(v)).join(', ');
+        base = `z.enum([${members}])`;
     }
-    return required ? base : `${base}.optional()`;
+    else {
+        base = 'z.string()';
+    }
+    if (param.minLength !== undefined)
+        base += `.min(${param.minLength})`;
+    if (param.maxLength !== undefined)
+        base += `.max(${param.maxLength})`;
+    if (param.pattern !== undefined)
+        base += `.regex(/${param.pattern}/)`;
+    return param.required ? base : `${base}.optional()`;
 }
 /**
  * Collect path parameters that have Zod format constraints.
@@ -98,7 +194,29 @@ function getPathParamValidations(operation, spec, rawPathParamNames) {
     return result;
 }
 /**
- * Collect header parameters from an operation.
+ * Build a Zod expression for a cookie parameter based on its captured constraints.
+ * Cookie values are always strings; emits z.string() or z.enum([...]) with optional
+ * pattern/length modifiers. Appends .optional() for non-required params.
+ */
+function cookieParamZodExpr(param) {
+    let base;
+    if (param.enum !== undefined && param.enum.length > 0) {
+        const members = param.enum.map((v) => JSON.stringify(v)).join(', ');
+        base = `z.enum([${members}])`;
+    }
+    else {
+        base = 'z.string()';
+    }
+    if (param.minLength !== undefined)
+        base += `.min(${param.minLength})`;
+    if (param.maxLength !== undefined)
+        base += `.max(${param.maxLength})`;
+    if (param.pattern !== undefined)
+        base += `.regex(/${param.pattern}/)`;
+    return param.required ? base : `${base}.optional()`;
+}
+/**
+ * Collect header parameters from an operation, including schema constraints.
  */
 function getHeaderParams(operation, spec) {
     const parameters = operation.parameters;
@@ -109,19 +227,93 @@ function getHeaderParams(operation, spec) {
         const resolved = resolveParam(p, spec);
         if (resolved === undefined || resolved.in !== 'header')
             continue;
-        result.push({
+        const param = {
+            rawName: resolved.name,
+            required: resolved.required === true,
+        };
+        const schema = resolved.schema;
+        if (schema !== undefined && !isRef(schema)) {
+            const s = schema;
+            if (Array.isArray(s.enum))
+                param.enum = s.enum;
+            if (typeof s.minLength === 'number')
+                param.minLength = s.minLength;
+            if (typeof s.maxLength === 'number')
+                param.maxLength = s.maxLength;
+            if (typeof s.pattern === 'string')
+                param.pattern = s.pattern;
+        }
+        result.push(param);
+    }
+    return result;
+}
+/**
+ * Collect cookie parameters (in: cookie) from an operation, including schema constraints.
+ * Cookie names are case-sensitive and are used as-is for both the Zod field key and value lookup.
+ */
+function getCookieParams(operation, spec) {
+    const parameters = operation.parameters;
+    if (parameters === undefined)
+        return [];
+    const result = [];
+    for (const p of parameters) {
+        const resolved = resolveParam(p, spec);
+        if (resolved === undefined || resolved.in !== 'cookie')
+            continue;
+        const param = {
             rawName: resolved.name,
             required: resolved.required === true,
-        });
+        };
+        const schema = resolved.schema;
+        if (schema !== undefined && !isRef(schema)) {
+            const s = schema;
+            if (Array.isArray(s.enum))
+                param.enum = s.enum;
+            if (typeof s.minLength === 'number')
+                param.minLength = s.minLength;
+            if (typeof s.maxLength === 'number')
+                param.maxLength = s.maxLength;
+            if (typeof s.pattern === 'string')
+                param.pattern = s.pattern;
+        }
+        result.push(param);
     }
     return result;
 }
+/**
+ * Returns true when a query param carries schema constraints beyond basic type/required.
+ * These constraints require a Zod validation block even if the param is optional or string.
+ */
+function queryParamHasConstraints(q) {
+    // Fields that, when defined, indicate schema constraints are present.
+    const constraintFields = [
+        q.enum,
+        q.minimum,
+        q.maximum,
+        q.exclusiveMinimum,
+        q.exclusiveMaximum,
+        q.minLength,
+        q.maxLength,
+        q.pattern,
+        q.delimiterStyle,
+    ];
+    return constraintFields.some((f) => f !== undefined) || q.isDeepObject === true;
+}
 /**
  * Determine whether query params need a Zod validation block.
- * Triggered when any param is required or has a non-string type (to catch NaN/invalid input).
+ * Triggered when any param is required, has a non-string type (to catch NaN/invalid input),
+ * or carries schema constraints (enum, min/max, pattern, etc.).
  */
 function queryParamsNeedValidation(queryParams) {
-    return queryParams.some((q) => q.required || q.tsType !== 'string');
+    return queryParams.some((q) => q.required || q.tsType !== 'string' || queryParamHasConstraints(q));
+}
+/** Returns the delimiter character for a delimited-style array query param. */
+function delimiterChar(style) {
+    if (style === 'ssv')
+        return ' ';
+    if (style === 'psv')
+        return '|';
+    return ',';
 }
 /**
  * Emit Zod validation lines for query parameters into the handler line buffer.
@@ -134,7 +326,7 @@ function emitQueryValidation(lines, queryParams, indent) {
     const fieldIndent = `${indent}    `;
     const fields = queryParams
         .map((q) => {
-        const expr = paramZodExpr(q.tsType, q.required);
+        const expr = queryParamZodExpr(q);
         return `${fieldIndent}${q.name}: ${expr}`;
     })
         .join(',\n');
@@ -166,7 +358,9 @@ function emitPathValidation(lines, validations, indent, framework) {
             access = `c.req.param(${JSON.stringify(v.rawName)})`;
         }
         else if (framework === 'express') {
-            access = `req.params[${JSON.stringify(v.rawName)}]`;
+            // Cast to string: Express 5 types req.params values as string | string[],
+            // but path params are always single strings in practice.
+            access = `req.params[${JSON.stringify(v.rawName)}] as string`;
         }
         else {
             access = /[^a-zA-Z0-9_$]/.test(v.rawName)
@@ -195,22 +389,23 @@ function emitHeaderValidation(lines, headerParams, indent, framework) {
     const schemaFields = headerParams
         .map((h) => {
         const key = JSON.stringify(h.rawName);
-        const expr = h.required ? 'z.string()' : 'z.string().optional()';
+        const expr = headerParamZodExpr(h);
         return `${fieldIndent}${key}: ${expr}`;
     })
         .join(',\n');
     const rawFields = headerParams
         .map((h) => {
         const key = JSON.stringify(h.rawName);
+        const lookupKey = JSON.stringify(h.rawName.toLowerCase());
         let access;
         if (framework === 'hono') {
             access = `c.req.header(${key})`;
         }
         else if (framework === 'express') {
-            access = `req.headers[${key}] as string | undefined`;
+            access = `req.headers[${lookupKey}] as string | undefined`;
         }
         else {
-            access = `req.headers[${key}]`;
+            access = `req.headers[${lookupKey}]`;
         }
         return `${fieldIndent}${key}: ${access}`;
     })
@@ -222,6 +417,56 @@ function emitHeaderValidation(lines, headerParams, indent, framework) {
     lines.push(rawFields);
     lines.push(`${inner}})`);
 }
+/**
+ * Emit Zod validation lines for cookie parameters into the handler line buffer.
+ * Cookie names are case-sensitive: the exact name is used for both the Zod field key and
+ * the value lookup (unlike headers, which are lowercased for lookup on Express/Fastify).
+ *
+ * Required plugins per framework:
+ *   Fastify: register @fastify/cookie before creating the router.
+ *   Express: apply cookie-parser middleware before mounting this router.
+ *   Hono:    getCookie is imported from 'hono/cookie' (added to generated output automatically).
+ *
+ * Uses short variable name _ckv to keep the 422 return line under Prettier's print width.
+ * @param indent - outer handler indent (e.g. '  ')
+ * @param framework - used to generate the correct cookie accessor syntax
+ */
+function emitCookieValidation(lines, cookieParams, indent, framework) {
+    const inner = `${indent}  `;
+    const fieldIndent = `${indent}    `;
+    const schemaFields = cookieParams
+        .map((ck) => {
+        const key = JSON.stringify(ck.rawName);
+        const expr = cookieParamZodExpr(ck);
+        return `${fieldIndent}${key}: ${expr}`;
+    })
+        .join(',\n');
+    const rawFields = cookieParams
+        .map((ck) => {
+        const key = JSON.stringify(ck.rawName);
+        let access;
+        if (framework === 'hono') {
+            // getCookie is imported from 'hono/cookie' when cookie params are present.
+            access = `getCookie(c, ${key})`;
+        }
+        else if (framework === 'express') {
+            // Requires cookie-parser middleware: req.cookies['name']
+            access = `req.cookies[${key}] as string | undefined`;
+        }
+        else {
+            // Requires @fastify/cookie plugin: req.cookies['name']
+            access = `req.cookies[${key}]`;
+        }
+        return `${fieldIndent}${key}: ${access}`;
+    })
+        .join(',\n');
+    lines.push(`${inner}// Validate request cookies: returns 422 with Zod issues on failure`);
+    lines.push(`${inner}const _ckv = z.object({`);
+    lines.push(schemaFields);
+    lines.push(`${inner}}).safeParse({`);
+    lines.push(rawFields);
+    lines.push(`${inner}})`);
+}
 function response200IsVoid(resp) {
     if (isRef(resp))
         return false;
@@ -229,22 +474,122 @@ function response200IsVoid(resp) {
     const content = r.content;
     return content === undefined || Object.keys(content).length === 0;
 }
+/**
+ * Detect the success response content type from a ResponseObject.
+ * Returns 'text/plain' or 'application/octet-stream' for non-JSON responses,
+ * or 'application/json' as the default.
+ */
+function detectResponseContentType(resp) {
+    if (isRef(resp))
+        return 'application/json';
+    const r = resp;
+    const content = r.content;
+    if (content === undefined)
+        return 'application/json';
+    if ('text/plain' in content)
+        return 'text/plain';
+    if ('application/octet-stream' in content)
+        return 'application/octet-stream';
+    return 'application/json';
+}
 function getResponseStatus(operation, httpMethod) {
     const responses = operation.responses;
     if (responses === undefined) {
-        return httpMethod === 'delete' ? { status: 204, isVoid: true } : { status: 200, isVoid: false };
+        return httpMethod === 'delete'
+            ? { status: 204, isVoid: true, responseContentType: 'application/json' }
+            : { status: 200, isVoid: false, responseContentType: 'application/json' };
+    }
+    // Multi-status: more than one 2xx response with a body (excluding 204/void).
+    // Must be checked before individual 200/201/204 branches so that e.g. 200+202
+    // is not absorbed by the responses['200'] early return.
+    // The handler selects the status at runtime via a { status, body } envelope.
+    const contentfulTwoxxKeys = Object.keys(responses)
+        .filter((k) => /^2\d\d$/.test(k) && k !== '204')
+        .sort();
+    if (contentfulTwoxxKeys.length > 1) {
+        return {
+            status: 200,
+            isVoid: false,
+            responseContentType: 'application/json',
+            isMultiStatus: true,
+        };
+    }
+    if (responses['201'] !== undefined) {
+        return {
+            status: 201,
+            isVoid: false,
+            responseContentType: detectResponseContentType(responses['201']),
+        };
+    }
+    if (responses['204'] !== undefined) {
+        return { status: 204, isVoid: true, responseContentType: 'application/json' };
     }
-    if (responses['201'] !== undefined)
-        return { status: 201, isVoid: false };
-    if (responses['204'] !== undefined)
-        return { status: 204, isVoid: true };
     if (responses['200'] !== undefined) {
-        if (response200IsVoid(responses['200']))
-            return { status: 204, isVoid: true };
-        return { status: 200, isVoid: false };
+        if (response200IsVoid(responses['200'])) {
+            return { status: 204, isVoid: true, responseContentType: 'application/json' };
+        }
+        return {
+            status: 200,
+            isVoid: false,
+            responseContentType: detectResponseContentType(responses['200']),
+        };
+    }
+    // Single non-200/201/204 2xx declared: honor that exact status code.
+    const twoxxKeys = Object.keys(responses).filter((k) => /^2\d\d$/.test(k) && k !== '200' && k !== '201' && k !== '204');
+    if (twoxxKeys.length === 1) {
+        const code = parseInt(twoxxKeys[0], 10);
+        const resp = responses[twoxxKeys[0]];
+        const isVoid = isRef(resp)
+            ? false
+            : (() => {
+                const r = resp;
+                const content = r.content;
+                return content === undefined || Object.keys(content).length === 0;
+            })();
+        return { status: code, isVoid, responseContentType: detectResponseContentType(resp) };
     }
     // Default: delete -> 204, otherwise 200
-    return httpMethod === 'delete' ? { status: 204, isVoid: true } : { status: 200, isVoid: false };
+    return httpMethod === 'delete'
+        ? { status: 204, isVoid: true, responseContentType: 'application/json' }
+        : { status: 200, isVoid: false, responseContentType: 'application/json' };
+}
+/**
+ * Resolve the response type name and shape for Fastify schema.response wiring.
+ * Returns the PascalCase type name of the first JSON 2xx response if it is a
+ * direct $ref or an array-of-$ref. Returns undefined for inline schemas, void,
+ * text/plain, or octet-stream responses.
+ *
+ * Priority order mirrors service.ts getReturnInfo: 200, 201, then other 2xx codes.
+ */
+function getResponseTypeName(operation) {
+    const responses = operation.responses;
+    if (responses === undefined)
+        return undefined;
+    const priority = ['200', '201', ...Object.keys(responses).filter((k) => /^2\d\d$/.test(k) && k !== '200' && k !== '201' && k !== '204')];
+    for (const code of priority) {
+        const response = responses[code];
+        if (response === undefined || isRef(response))
+            continue;
+        const resp = response;
+        const content = resp.content;
+        if (content === undefined)
+            continue;
+        const jsonContent = content['application/json'];
+        if (jsonContent === undefined || jsonContent.schema === undefined)
+            continue;
+        const schema = jsonContent.schema;
+        if (isRef(schema)) {
+            return { typeName: refToName(schema.$ref), isArray: false };
+        }
+        const s = schema;
+        if (s.type === 'array' && s.items !== undefined && isRef(s.items)) {
+            return {
+                typeName: refToName(s.items.$ref),
+                isArray: true,
+            };
+        }
+    }
+    return undefined;
 }
 function collectOperations(spec) {
     const paths = spec.paths;
@@ -261,8 +606,10 @@ function collectOperations(spec) {
             const pathParamValidations = getPathParamValidations(operation, spec, pathParams);
             const queryParams = getQueryParams(operation, spec);
             const headerParams = getHeaderParams(operation, spec);
+            const cookieParams = getCookieParams(operation, spec);
             const bodyInfo = getBodyInfo(operation);
             const responseStatus = getResponseStatus(operation, method);
+            const responseTypeInfo = getResponseTypeName(operation);
             operations.push({
                 methodName,
                 httpMethod: method,
@@ -272,19 +619,26 @@ function collectOperations(spec) {
                 pathParamValidations,
                 queryParams,
                 headerParams,
+                cookieParams,
                 bodyInfo,
                 responseStatus,
+                responseTypeName: responseTypeInfo?.typeName,
+                responseIsArray: responseTypeInfo?.isArray,
             });
         }
     }
     return operations;
 }
-/** Collect sorted body type names from all operations. */
+/** Collect sorted body type names from all operations.
+ * Synthesized names (inline schema, no $ref) are excluded because they have no
+ * corresponding entry in models.ts and must not appear in the model import.
+ */
 function collectSortedBodyTypes(operations) {
     const bodyTypes = new Set();
     for (const op of operations) {
-        if (op.bodyInfo?.typeName !== undefined)
+        if (op.bodyInfo?.typeName !== undefined && !op.bodyInfo.isSynthesized) {
             bodyTypes.add(op.bodyInfo.typeName);
+        }
     }
     return Array.from(bodyTypes).sort();
 }
@@ -301,6 +655,26 @@ function collectUsedSchemaNames(operations, schemaNames) {
     }
     return used;
 }
+/**
+ * Collect the subset of schemaNames used as Fastify response schemas.
+ * Only operations with a resolvable $ref response type (direct or array-of-$ref)
+ * and a matching schema in schemaNames are included.
+ * Multi-status operations are excluded because they cannot be mapped to a single
+ * status code in schema.response at generation time.
+ */
+function collectUsedResponseSchemaNames(operations, schemaNames) {
+    const used = new Set();
+    for (const op of operations) {
+        if (op.responseTypeName === undefined)
+            continue;
+        if (op.responseStatus.isMultiStatus === true)
+            continue;
+        const schemaName = `${op.responseTypeName}Schema`;
+        if (schemaNames.has(schemaName))
+            used.add(schemaName);
+    }
+    return used;
+}
 /**
  * Collect body type names, used schema names, and whether Zod is needed.
  * Shared by all three generator functions to avoid duplication.
@@ -310,13 +684,23 @@ function collectGeneratorSetup(operations, options) {
     const usedSchemaNames = options?.schemaNames !== undefined
         ? collectUsedSchemaNames(operations, options.schemaNames)
         : new Set();
+    const usedResponseSchemaNames = options?.schemaNames !== undefined
+        ? collectUsedResponseSchemaNames(operations, options.schemaNames)
+        : new Set();
+    // Zod is needed for param validation, body schema validation, or array response schemas.
+    // Array response schemas emit z.array(XSchema) which requires the z import.
+    const hasArrayResponseSchema = usedResponseSchemaNames.size > 0 &&
+        operations.some((op) => op.responseIsArray === true &&
+            op.responseTypeName !== undefined &&
+            usedResponseSchemaNames.has(`${op.responseTypeName}Schema`));
     const needsZod = (usedSchemaNames.size > 0 && options?.schemaImportPath !== undefined) ||
-        operationsNeedZodForParams(operations);
-    return { sortedBodyTypes, usedSchemaNames, needsZod };
+        operationsNeedZodForParams(operations) ||
+        (usedResponseSchemaNames.size > 0 && options?.schemaImportPath !== undefined && hasArrayResponseSchema);
+    return { sortedBodyTypes, usedSchemaNames, usedResponseSchemaNames, needsZod };
 }
 // ── Hono route handler ────────────────────────────────────────────────────────
 // fallow-ignore-next-line complexity
-function buildRouteHandler(op, indent, schemaNames) {
+function buildRouteHandler(op, indent, schemaNames, contextType) {
     const lines = [];
     lines.push(`${indent}app.${op.httpMethod}(${JSON.stringify(op.honoPath)}, async (c) => {`);
     // Path param format validation (e.g. uuid)
@@ -328,8 +712,30 @@ function buildRouteHandler(op, indent, schemaNames) {
     }
     // Query params extraction
     if (op.queryParams.length > 0) {
+        // Emit deepObject assembly blocks before the params object.
+        // c.req.queries() returns Record<string, string[]> with raw bracket-notation keys.
+        const deepObjectParams = op.queryParams.filter((q) => q.isDeepObject === true);
+        if (deepObjectParams.length > 0) {
+            lines.push(`${indent}  const _dq = c.req.queries()`);
+            for (const q of deepObjectParams) {
+                const prefixLen = q.rawName.length + 1; // e.g. 'filter['.length
+                const bracketPrefix = q.rawName + '[';
+                lines.push(`${indent}  const ${q.name} = Object.fromEntries(`);
+                lines.push(`${indent}    Object.entries(_dq).filter(([k]) => k.startsWith('${bracketPrefix}') && k.endsWith(']')).map(([k, vs]) => [k.slice(${prefixLen}, -1), vs[0]])`);
+                lines.push(`${indent}  )`);
+            }
+        }
         const fields = op.queryParams
             .map((q) => {
+            if (q.isDeepObject === true) {
+                // Already assembled above as a local variable
+                return `    ${q.name}`;
+            }
+            if (q.delimiterStyle !== undefined) {
+                // Use rawName to match the actual URL query key (e.g. 'csv', 'ssv', 'psv').
+                const delim = JSON.stringify(delimiterChar(q.delimiterStyle));
+                return `    ${q.name}: c.req.query('${q.rawName}') !== undefined ? c.req.query('${q.rawName}')!.split(${delim}) : undefined`;
+            }
             if (q.tsType === 'number') {
                 return `    ${q.name}: c.req.query('${q.name}') !== undefined ? Number(c.req.query('${q.name}')) : undefined`;
             }
@@ -354,11 +760,54 @@ function buildRouteHandler(op, indent, schemaNames) {
         lines.push(`${indent}    return c.json({ error: 'Invalid request headers', issues: _hv.error.issues }, 422)`);
         lines.push(`${indent}  }`);
     }
+    // Cookie param validation
+    // Requires @fastify/cookie on Fastify, cookie-parser on Express, getCookie from hono/cookie on Hono.
+    if (op.cookieParams.length > 0) {
+        emitCookieValidation(lines, op.cookieParams, indent, 'hono');
+        lines.push(`${indent}  if (!_ckv.success) {`);
+        lines.push(`${indent}    return c.json({ error: 'Invalid request cookies', issues: _ckv.error.issues }, 422)`);
+        lines.push(`${indent}  }`);
+    }
     // Body extraction
     let bodyVarName = 'body';
     if (op.bodyInfo !== undefined) {
-        const typeAnnotation = op.bodyInfo.typeName !== undefined ? `<${op.bodyInfo.typeName}>` : '';
-        lines.push(`${indent}  const body = await c.req.json${typeAnnotation}()`);
+        // Synthesized names (inline schemas) are schema-only; the TS type is unknown.
+        const typeDecl = op.bodyInfo.typeName !== undefined && !op.bodyInfo.isSynthesized
+            ? op.bodyInfo.typeName
+            : 'unknown';
+        if (op.bodyInfo.contentType === 'application/x-www-form-urlencoded') {
+            // Form-urlencoded: check Content-Type then decode with parseBody().
+            // Values arrive as strings; Zod coercion handles type conversion (e.g. z.coerce.number()).
+            lines.push(`${indent}  const _ct = c.req.header('content-type') ?? ''`);
+            lines.push(`${indent}  if (!_ct.toLowerCase().startsWith('application/x-www-form-urlencoded')) {`);
+            lines.push(`${indent}    return c.json({ error: 'Unsupported Media Type' }, 415)`);
+            lines.push(`${indent}  }`);
+            lines.push(`${indent}  const body: unknown = await c.req.parseBody()`);
+        }
+        else if (op.bodyInfo.contentType === 'multipart/form-data') {
+            // Multipart: decode with parseBody({ all: true }) so repeated file fields arrive as arrays.
+            // File fields are web-standard File objects; text fields are strings.
+            // No manual Content-Type check needed: parseBody handles multipart natively in Hono.
+            lines.push(`${indent}  // multipart/form-data: parseBody({ all: true }) collects repeated keys into arrays.`);
+            lines.push(`${indent}  const body: unknown = await c.req.parseBody({ all: true })`);
+        }
+        else {
+            // JSON body: check Content-Type then parse with JSON.parse (not c.req.json()).
+            // c.req.text() + JSON.parse() is used instead of c.req.json() because Hono's
+            // c.req.json() silently returns null for an empty body instead of throwing,
+            // which would pass the try/catch and reach Zod as null, causing a 422 rather
+            // than the correct 400. JSON.parse('') always throws SyntaxError.
+            lines.push(`${indent}  const _ct = c.req.header('content-type') ?? ''`);
+            lines.push(`${indent}  if (!_ct.toLowerCase().startsWith('application/json')) {`);
+            lines.push(`${indent}    return c.json({ error: 'Unsupported Media Type' }, 415)`);
+            lines.push(`${indent}  }`);
+            lines.push(`${indent}  let body: ${typeDecl}`);
+            lines.push(`${indent}  try {`);
+            lines.push(`${indent}    body = JSON.parse(await c.req.text()) as ${typeDecl}`);
+            lines.push(`${indent}  } catch {`);
+            lines.push(`${indent}    return c.json({ error: 'Invalid JSON body' }, 400)`);
+            lines.push(`${indent}  }`);
+        }
         // Zod validation when schema is available
         const schemaName = op.bodyInfo.typeName !== undefined ? `${op.bodyInfo.typeName}Schema` : undefined;
         if (schemaName !== undefined && schemaNames !== undefined && schemaNames.has(schemaName)) {
@@ -367,7 +816,12 @@ function buildRouteHandler(op, indent, schemaNames) {
             lines.push(`${indent}  if (!parseResult.success) {`);
             lines.push(`${indent}    return c.json({ error: 'Invalid request body', issues: parseResult.error.issues }, 422)`);
             lines.push(`${indent}  }`);
-            lines.push(`${indent}  const validatedBody = parseResult.data`);
+            // Forward the validated/coerced data (parseResult.data), NOT the raw parsed body,
+            // so Zod coercion is preserved (e.g. form-urlencoded numeric fields via
+            // z.coerce.number()). Cast to the declared model type so the service-call type
+            // stays correct even when the schema infers a narrower shape (e.g. z.unknown()
+            // for inline-union properties); safeParse above guarantees runtime safety.
+            lines.push(`${indent}  const validatedBody = parseResult.data as ${typeDecl}`);
             bodyVarName = 'validatedBody';
         }
     }
@@ -380,26 +834,64 @@ function buildRouteHandler(op, indent, schemaNames) {
         serviceArgs.push(bodyVarName);
     }
     if (op.queryParams.length > 0) {
-        serviceArgs.push('params');
+        // After successful Zod validation _qv.data carries the correct required/typed
+        // values (e.g. string[] for delimited arrays, object shape for deepObject params,
+        // and non-optional values for required scalar params). Use _qv.data when validation
+        // was applied; fall back to params when no validation is needed.
+        serviceArgs.push(queryParamsNeedValidation(op.queryParams) ? '_qv.data' : 'params');
+    }
+    // Context arg: pass the Hono Context object (c) as the final argument when contextType is set.
+    if (contextType !== undefined) {
+        serviceArgs.push('c');
     }
     const serviceCall = `service.${op.methodName}(${serviceArgs.join(', ')})`;
-    // Response
+    // Response — wrap in try/catch to map HttpError to its status
+    lines.push(`${indent}  try {`);
     if (op.responseStatus.isVoid) {
-        lines.push(`${indent}  await ${serviceCall}`);
-        lines.push(`${indent}  return new Response(null, { status: ${op.responseStatus.status} })`);
+        lines.push(`${indent}    await ${serviceCall}`);
+        lines.push(`${indent}    return new Response(null, { status: ${op.responseStatus.status} })`);
+    }
+    else if (op.responseStatus.isMultiStatus === true) {
+        // Multi-status: service returns { status: number; body: T }; router forwards both.
+        lines.push(`${indent}    const _envelope = await ${serviceCall}`);
+        lines.push(`${indent}    return c.json(_envelope.body, _envelope.status as any)`);
+    }
+    else if (op.responseStatus.responseContentType === 'text/plain') {
+        if (op.responseStatus.status === 200) {
+            lines.push(`${indent}    return c.text(await ${serviceCall})`);
+        }
+        else {
+            lines.push(`${indent}    return c.text(await ${serviceCall}, ${op.responseStatus.status})`);
+        }
     }
-    else if (op.responseStatus.status === 201) {
-        lines.push(`${indent}  return c.json(await ${serviceCall}, 201)`);
+    else if (op.responseStatus.responseContentType === 'application/octet-stream') {
+        if (op.responseStatus.status === 200) {
+            lines.push(`${indent}    const _result = await ${serviceCall}`);
+            lines.push(`${indent}    return new Response(_result, { headers: { 'content-type': 'application/octet-stream' } })`);
+        }
+        else {
+            lines.push(`${indent}    const _result = await ${serviceCall}`);
+            lines.push(`${indent}    return new Response(_result, { status: ${op.responseStatus.status}, headers: { 'content-type': 'application/octet-stream' } })`);
+        }
+    }
+    else if (op.responseStatus.status === 200) {
+        lines.push(`${indent}    return c.json(await ${serviceCall})`);
     }
     else {
-        lines.push(`${indent}  return c.json(await ${serviceCall})`);
+        lines.push(`${indent}    return c.json(await ${serviceCall}, ${op.responseStatus.status})`);
     }
+    lines.push(`${indent}  } catch (err) {`);
+    lines.push(`${indent}    if (err instanceof HttpError) {`);
+    lines.push(`${indent}      return new Response(JSON.stringify({ error: err.message }), { status: err.status, headers: { 'content-type': 'application/json' } })`);
+    lines.push(`${indent}    }`);
+    lines.push(`${indent}    throw err`);
+    lines.push(`${indent}  }`);
     lines.push(`${indent}})`);
     return lines.join('\n');
 }
 // ── Express route handler ─────────────────────────────────────────────────────
 // fallow-ignore-next-line complexity
-function buildExpressRouteHandler(op, indent, schemaNames) {
+function buildExpressRouteHandler(op, indent, schemaNames, contextType) {
     const lines = [];
     lines.push(`${indent}router.${op.httpMethod}(${JSON.stringify(op.honoPath)}, async (req: Request, res: Response) => {`);
     // Path param format validation (e.g. uuid)
@@ -411,8 +903,19 @@ function buildExpressRouteHandler(op, indent, schemaNames) {
     }
     // Query params extraction
     if (op.queryParams.length > 0) {
+        // Express (qs, extended:true) parses bracket-notation automatically:
+        // filter[gte]=10 → req.query.filter = { gte: '10' }.
+        // DeepObject params are already assembled; just cast the nested object.
         const fields = op.queryParams
             .map((q) => {
+            if (q.isDeepObject === true) {
+                // Express with qs: req.query['filter'] is already { gte: '10', lte: '20' }
+                return `    ${q.name}: (req.query['${q.rawName}'] ?? {}) as Record<string, string | undefined>`;
+            }
+            if (q.delimiterStyle !== undefined) {
+                const delim = JSON.stringify(delimiterChar(q.delimiterStyle));
+                return `    ${q.name}: typeof req.query['${q.rawName}'] === 'string' ? (req.query['${q.rawName}'] as string).split(${delim}) : undefined`;
+            }
             if (q.tsType === 'number') {
                 return `    ${q.name}: Number(req.query['${q.name}'] as string)`;
             }
@@ -440,70 +943,187 @@ function buildExpressRouteHandler(op, indent, schemaNames) {
         lines.push(`${indent}    return void res.status(422).json({ error: 'Invalid request headers', issues: _hv.error.issues })`);
         lines.push(`${indent}  }`);
     }
-    // Body extraction, with optional Zod validation
+    // Cookie param validation
+    // Requires cookie-parser middleware: app.use(cookieParser()) before mounting this router.
+    if (op.cookieParams.length > 0) {
+        emitCookieValidation(lines, op.cookieParams, indent, 'express');
+        lines.push(`${indent}  if (!_ckv.success) {`);
+        lines.push(`${indent}    return void res.status(422).json({ error: 'Invalid request cookies', issues: _ckv.error.issues })`);
+        lines.push(`${indent}  }`);
+    }
+    // Body extraction, with optional Zod validation.
+    // For both JSON and form-urlencoded bodies Express pre-populates req.body via middleware
+    // (express.json() for JSON, express.urlencoded() for form). The router just reads req.body.
+    // For multipart/form-data: assumes multer (or equivalent) middleware is applied before this
+    // router, populating req.files and req.body with the parsed multipart fields.
     let bodyVarName = 'body';
     if (op.bodyInfo !== undefined) {
-        const schemaName = op.bodyInfo.typeName !== undefined ? `${op.bodyInfo.typeName}Schema` : undefined;
-        const useZod = schemaName !== undefined && schemaNames !== undefined && schemaNames.has(schemaName);
-        if (useZod) {
-            lines.push(`${indent}  // Validate request body: returns 422 with Zod issues on failure`);
-            lines.push(`${indent}  const parseResult = ${schemaName}.safeParse(req.body)`);
-            lines.push(`${indent}  if (!parseResult.success) {`);
-            lines.push(`${indent}    return void res.status(422).json({ error: 'Invalid request body', issues: parseResult.error.issues })`);
-            lines.push(`${indent}  }`);
-            lines.push(`${indent}  const validatedBody = parseResult.data`);
-            bodyVarName = 'validatedBody';
+        if (op.bodyInfo.contentType === 'multipart/form-data') {
+            // Multipart assumption: multer middleware populates req.files (file fields) and
+            // req.body (text fields) before this handler runs. Merge them for service consumption.
+            lines.push(`${indent}  // multipart/form-data: assumes multer middleware has populated req.files + req.body.`);
+            lines.push(`${indent}  const body = { ...req.body, ...(req as any).files } as unknown`);
         }
         else {
-            const typeAnnotation = op.bodyInfo.typeName !== undefined ? ` as ${op.bodyInfo.typeName}` : '';
-            lines.push(`${indent}  const body = req.body${typeAnnotation}`);
+            const schemaName = op.bodyInfo.typeName !== undefined ? `${op.bodyInfo.typeName}Schema` : undefined;
+            const useZod = schemaName !== undefined && schemaNames !== undefined && schemaNames.has(schemaName);
+            if (useZod) {
+                lines.push(`${indent}  // Validate request body: returns 422 with Zod issues on failure`);
+                lines.push(`${indent}  const parseResult = ${schemaName}.safeParse(req.body)`);
+                lines.push(`${indent}  if (!parseResult.success) {`);
+                lines.push(`${indent}    return void res.status(422).json({ error: 'Invalid request body', issues: parseResult.error.issues })`);
+                lines.push(`${indent}  }`);
+                // Cast parseResult.data to the declared model type so the service call receives
+                // the correct TypeScript type even when the Zod schema infers a narrower or
+                // different shape (e.g. z.unknown() for inline-union properties). The cast is
+                // safe because safeParse already confirmed the value is structurally valid.
+                const typeDecl = op.bodyInfo.typeName !== undefined && !op.bodyInfo.isSynthesized
+                    ? op.bodyInfo.typeName
+                    : 'unknown';
+                lines.push(`${indent}  const validatedBody = parseResult.data as ${typeDecl}`);
+                bodyVarName = 'validatedBody';
+            }
+            else {
+                // Synthesized names (inline schemas) have no model type — use plain cast to unknown.
+                const typeAnnotation = op.bodyInfo.typeName !== undefined && !op.bodyInfo.isSynthesized
+                    ? ` as ${op.bodyInfo.typeName}`
+                    : '';
+                lines.push(`${indent}  const body = req.body${typeAnnotation}`);
+            }
         }
     }
     // Build service call args
     const serviceArgs = [];
     for (const p of op.pathParams) {
-        serviceArgs.push(`req.params['${p}']!`);
+        // Cast to string: Express 5 types req.params values as string | string[],
+        // but path params are always single strings in practice.
+        serviceArgs.push(`(req.params['${p}'] as string)`);
     }
     if (op.bodyInfo !== undefined) {
         serviceArgs.push(bodyVarName);
     }
     if (op.queryParams.length > 0) {
-        serviceArgs.push('params');
+        // After successful Zod validation _qv.data carries the correct required/typed
+        // values (e.g. string[] for delimited arrays, object shape for deepObject params,
+        // and non-optional values for required scalar params). Use _qv.data when validation
+        // was applied; fall back to params when no validation is needed.
+        serviceArgs.push(queryParamsNeedValidation(op.queryParams) ? '_qv.data' : 'params');
+    }
+    // Context arg: pass the Express Request object (req) as the final argument when contextType is set.
+    if (contextType !== undefined) {
+        serviceArgs.push('req');
     }
     const serviceCall = `service.${op.methodName}(${serviceArgs.join(', ')})`;
-    // Response
+    // Response — wrap in try/catch to map HttpError to its status
+    lines.push(`${indent}  try {`);
     if (op.responseStatus.isVoid) {
-        lines.push(`${indent}  await ${serviceCall}`);
-        lines.push(`${indent}  res.status(${op.responseStatus.status}).end()`);
+        lines.push(`${indent}    await ${serviceCall}`);
+        lines.push(`${indent}    res.status(${op.responseStatus.status}).end()`);
+    }
+    else if (op.responseStatus.isMultiStatus === true) {
+        // Multi-status: service returns { status: number; body: T }; router forwards both.
+        lines.push(`${indent}    const _envelope = await ${serviceCall}`);
+        lines.push(`${indent}    res.status(_envelope.status).json(_envelope.body)`);
+    }
+    else if (op.responseStatus.responseContentType === 'text/plain') {
+        if (op.responseStatus.status === 200) {
+            lines.push(`${indent}    res.type('text/plain').send(await ${serviceCall})`);
+        }
+        else {
+            lines.push(`${indent}    res.status(${op.responseStatus.status}).type('text/plain').send(await ${serviceCall})`);
+        }
     }
-    else if (op.responseStatus.status === 201) {
-        lines.push(`${indent}  res.status(201).json(await ${serviceCall})`);
+    else if (op.responseStatus.responseContentType === 'application/octet-stream') {
+        if (op.responseStatus.status === 200) {
+            lines.push(`${indent}    res.setHeader('Content-Type', 'application/octet-stream').send(Buffer.from(await ${serviceCall}))`);
+        }
+        else {
+            lines.push(`${indent}    res.status(${op.responseStatus.status}).setHeader('Content-Type', 'application/octet-stream').send(Buffer.from(await ${serviceCall}))`);
+        }
+    }
+    else if (op.responseStatus.status === 200) {
+        lines.push(`${indent}    res.json(await ${serviceCall})`);
     }
     else {
-        lines.push(`${indent}  res.json(await ${serviceCall})`);
+        lines.push(`${indent}    res.status(${op.responseStatus.status}).json(await ${serviceCall})`);
     }
+    lines.push(`${indent}  } catch (err) {`);
+    lines.push(`${indent}    if (err instanceof HttpError) {`);
+    lines.push(`${indent}      return void res.status(err.status).json({ error: err.message })`);
+    lines.push(`${indent}    }`);
+    lines.push(`${indent}    throw err`);
+    lines.push(`${indent}  }`);
     lines.push(`${indent}})`);
     return lines.join('\n');
 }
 // ── Fastify route handler ─────────────────────────────────────────────────────
+/**
+ * Build the route options object literal string for a Fastify route registration.
+ * Always includes config.operationId so onRequest hooks can identify the operation
+ * via request.routeOptions.config.operationId (issue #309).
+ * When a response schema is available in schemaNames, also includes schema.response
+ * so Fastify validates the response against the Zod schema (issue #308).
+ * Both properties are merged into a single options object literal when both apply.
+ */
+function buildFastifyRouteOptions(op, schemaNames) {
+    const parts = [];
+    const responseSchemaExpr = buildFastifyResponseSchemaExpr(op, schemaNames);
+    if (responseSchemaExpr !== undefined) {
+        parts.push(`schema: { response: { ${op.responseStatus.status}: ${responseSchemaExpr} } }`);
+    }
+    parts.push(`config: { operationId: '${op.methodName}' }`);
+    return `{ ${parts.join(', ')} }`;
+}
+/**
+ * Build the Zod schema expression for a Fastify schema.response entry.
+ * Returns undefined when no schema is available or the operation is multi-status.
+ * Direct $ref response: 'PetSchema'
+ * Array-of-$ref response: 'z.array(PetSchema)'
+ */
+function buildFastifyResponseSchemaExpr(op, schemaNames) {
+    if (schemaNames === undefined)
+        return undefined;
+    if (op.responseTypeName === undefined)
+        return undefined;
+    if (op.responseStatus.isMultiStatus === true)
+        return undefined;
+    if (op.responseStatus.isVoid)
+        return undefined;
+    const schemaName = `${op.responseTypeName}Schema`;
+    if (!schemaNames.has(schemaName))
+        return undefined;
+    return op.responseIsArray === true ? `z.array(${schemaName})` : schemaName;
+}
 // fallow-ignore-next-line complexity
-function buildFastifyRouteHandler(op, indent, schemaNames) {
+function buildFastifyRouteHandler(op, indent, schemaNames, contextType) {
     const lines = [];
     // Build generic type argument
     const genericParts = [];
     if (op.queryParams.length > 0) {
-        const queryFields = op.queryParams
-            .map((q) => {
-            if (q.tsType === 'number')
-                return `${q.name}?: number`;
-            if (q.tsType === 'boolean')
-                return `${q.name}?: boolean`;
-            return `${q.name}?: string`;
-        })
-            .join('; ');
-        genericParts.push(`Querystring: { ${queryFields} }`);
+        // DeepObject and delimited params use bracket-notation keys or raw strings;
+        // include them as Record<string, string> or string[] in the Querystring generic.
+        const hasDeepOrDelimited = op.queryParams.some((q) => q.isDeepObject === true || q.delimiterStyle !== undefined);
+        let querystringType;
+        if (hasDeepOrDelimited) {
+            // Use a loose Querystring type that allows bracket-notation keys (fast-querystring stores
+            // them as literal strings, e.g. 'filter[gte]') and array values for delimited params.
+            querystringType = 'Record<string, string | string[] | undefined>';
+        }
+        else {
+            const queryFields = op.queryParams
+                .map((q) => {
+                if (q.tsType === 'number')
+                    return `${q.name}?: number`;
+                if (q.tsType === 'boolean')
+                    return `${q.name}?: boolean`;
+                return `${q.name}?: string`;
+            })
+                .join('; ');
+            querystringType = `{ ${queryFields} }`;
+        }
+        genericParts.push(`Querystring: ${querystringType}`);
     }
-    if (op.bodyInfo !== undefined && op.bodyInfo.typeName !== undefined) {
+    if (op.bodyInfo !== undefined && op.bodyInfo.typeName !== undefined && !op.bodyInfo.isSynthesized) {
         genericParts.push(`Body: ${op.bodyInfo.typeName}`);
     }
     else if (op.bodyInfo !== undefined) {
@@ -514,12 +1134,13 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
         genericParts.push(`Params: { ${paramFields} }`);
     }
     const generic = genericParts.length > 0 ? `<{ ${genericParts.join('; ')} }>` : '';
-    lines.push(`${indent}app.${op.httpMethod}${generic}(${JSON.stringify(op.honoPath)}, async (req, reply) => {`);
+    const routeOpts = buildFastifyRouteOptions(op, schemaNames);
+    lines.push(`${indent}app.${op.httpMethod}${generic}(${JSON.stringify(op.honoPath)}, ${routeOpts}, async (req, reply) => {`);
     // Path param format validation (e.g. uuid)
     if (op.pathParamValidations.length > 0) {
         emitPathValidation(lines, op.pathParamValidations, indent, 'fastify');
         lines.push(`${indent}  if (!_pv.success) {`);
-        lines.push(`${indent}    return reply.status(422).send({`);
+        lines.push(`${indent}    return (reply as FastifyReply).status(422).send({`);
         lines.push(`${indent}      error: 'Invalid path parameters',`);
         lines.push(`${indent}      issues: _pv.error.issues,`);
         lines.push(`${indent}    })`);
@@ -527,7 +1148,46 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
     }
     // Query params extraction
     if (op.queryParams.length > 0) {
-        const fields = op.queryParams.map((q) => `    ${q.name}: req.query.${q.name}`).join(',\n');
+        // fast-querystring (Fastify default) stores bracket-notation keys as literals:
+        // filter[gte]=10 → req.query['filter[gte]'] = '10'.
+        // DeepObject and delimited params need raw string access; emit _dq cast once.
+        const deepObjectParams = op.queryParams.filter((q) => q.isDeepObject === true);
+        const hasDeepOrDelimited = op.queryParams.some((q) => q.isDeepObject === true || q.delimiterStyle !== undefined);
+        if (hasDeepOrDelimited) {
+            lines.push(`${indent}  const _dq = req.query as unknown as Record<string, string | undefined>`);
+        }
+        if (deepObjectParams.length > 0) {
+            for (const q of deepObjectParams) {
+                const prefixLen = q.rawName.length + 1; // e.g. 'filter['.length
+                const bracketPrefix = q.rawName + '[';
+                lines.push(`${indent}  const ${q.name} = Object.fromEntries(`);
+                lines.push(`${indent}    Object.entries(_dq).filter(([k]) => k.startsWith('${bracketPrefix}') && k.endsWith(']')).map(([k, v]) => [k.slice(${prefixLen}, -1), v])`);
+                lines.push(`${indent}  )`);
+            }
+        }
+        const fields = op.queryParams
+            .map((q) => {
+            if (q.isDeepObject === true) {
+                // Already assembled above as a local variable
+                return `    ${q.name}`;
+            }
+            if (q.delimiterStyle !== undefined) {
+                const delim = JSON.stringify(delimiterChar(q.delimiterStyle));
+                return `    ${q.name}: typeof _dq['${q.rawName}'] === 'string' ? _dq['${q.rawName}']!.split(${delim}) : undefined`;
+            }
+            // When _dq is defined, use it for consistent access; otherwise use typed req.query.
+            // Boolean params must be coerced from string at extraction time: z.coerce.boolean()
+            // is unusable because Boolean('false') === true, so mirror the Express === 'true' pattern.
+            if (q.tsType === 'boolean') {
+                return hasDeepOrDelimited
+                    ? `    ${q.name}: _dq['${q.rawName}'] === 'true'`
+                    : `    ${q.name}: (req.query.${q.name} as unknown as string) === 'true'`;
+            }
+            return hasDeepOrDelimited
+                ? `    ${q.name}: _dq['${q.rawName}']`
+                : `    ${q.name}: req.query.${q.name}`;
+        })
+            .join(',\n');
         lines.push(`${indent}  const params = {`);
         lines.push(fields);
         lines.push(`${indent}  }`);
@@ -535,7 +1195,7 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
         if (queryParamsNeedValidation(op.queryParams)) {
             emitQueryValidation(lines, op.queryParams, indent);
             lines.push(`${indent}  if (!_qv.success) {`);
-            lines.push(`${indent}    return reply.status(422).send({`);
+            lines.push(`${indent}    return (reply as FastifyReply).status(422).send({`);
             lines.push(`${indent}      error: 'Invalid query parameters',`);
             lines.push(`${indent}      issues: _qv.error.issues,`);
             lines.push(`${indent}    })`);
@@ -546,24 +1206,65 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
     if (op.headerParams.length > 0) {
         emitHeaderValidation(lines, op.headerParams, indent, 'fastify');
         lines.push(`${indent}  if (!_hv.success) {`);
-        lines.push(`${indent}    return reply.status(422).send({`);
+        lines.push(`${indent}    return (reply as FastifyReply).status(422).send({`);
         lines.push(`${indent}      error: 'Invalid request headers',`);
         lines.push(`${indent}      issues: _hv.error.issues,`);
         lines.push(`${indent}    })`);
         lines.push(`${indent}  }`);
     }
-    // Body handling, with optional Zod validation
+    // Cookie param validation
+    // Requires @fastify/cookie plugin registered before creating the router: fastify.register(fastifyCookie).
+    if (op.cookieParams.length > 0) {
+        emitCookieValidation(lines, op.cookieParams, indent, 'fastify');
+        lines.push(`${indent}  if (!_ckv.success) {`);
+        lines.push(`${indent}    return (reply as FastifyReply).status(422).send({`);
+        lines.push(`${indent}      error: 'Invalid request cookies',`);
+        lines.push(`${indent}      issues: _ckv.error.issues,`);
+        lines.push(`${indent}    })`);
+        lines.push(`${indent}  }`);
+    }
+    // Body handling, with optional Zod validation.
+    // Fastify natively parses only application/json and text/plain.
+    // For application/x-www-form-urlencoded: register @fastify/formbody before this router
+    // so that req.body is populated.
+    // For multipart/form-data: register @fastify/multipart with attachFieldsToBody: true before
+    // this router so that req.body is populated with parsed fields. Without attachFieldsToBody,
+    // @fastify/multipart v10 exposes files via async iterators (request.parts()), not req.body.
     let bodyVarName = 'req.body';
     if (op.bodyInfo !== undefined) {
-        const schemaName = op.bodyInfo.typeName !== undefined ? `${op.bodyInfo.typeName}Schema` : undefined;
-        const useZod = schemaName !== undefined && schemaNames !== undefined && schemaNames.has(schemaName);
-        if (useZod) {
-            lines.push(`${indent}  // Validate request body: returns 422 with Zod issues on failure`);
-            lines.push(`${indent}  const parseResult = ${schemaName}.safeParse(req.body)`);
-            lines.push(`${indent}  if (!parseResult.success) {`);
-            lines.push(`${indent}    return reply.status(422).send({ error: 'Invalid request body', issues: parseResult.error.issues })`);
-            lines.push(`${indent}  }`);
-            bodyVarName = 'parseResult.data';
+        if (op.bodyInfo.contentType === 'multipart/form-data') {
+            // multipart/form-data: @fastify/multipart must be registered with attachFieldsToBody: true.
+            // Without that option, files are only accessible via async iterators (request.parts()),
+            // NOT via req.body. The consumer must register the plugin before creating this router.
+            lines.push(`${indent}  // multipart/form-data: requires @fastify/multipart registered with { attachFieldsToBody: true }.`);
+            // bodyVarName stays 'req.body'
+        }
+        else if (op.bodyInfo.contentType === 'application/octet-stream') {
+            // application/octet-stream: req.body is a Buffer (parsed by the addContentTypeParser
+            // registration emitted in the createRouter body above). Forward it to the service as-is.
+            lines.push(`${indent}  // application/octet-stream: req.body is a Buffer from the registered content-type parser.`);
+            // bodyVarName stays 'req.body'
+        }
+        else {
+            const schemaName = op.bodyInfo.typeName !== undefined ? `${op.bodyInfo.typeName}Schema` : undefined;
+            const useZod = schemaName !== undefined && schemaNames !== undefined && schemaNames.has(schemaName);
+            if (useZod) {
+                lines.push(`${indent}  // Validate request body: returns 422 with Zod issues on failure`);
+                lines.push(`${indent}  const parseResult = ${schemaName}.safeParse(req.body)`);
+                lines.push(`${indent}  if (!parseResult.success) {`);
+                lines.push(`${indent}    return (reply as FastifyReply).status(422).send({ error: 'Invalid request body', issues: parseResult.error.issues })`);
+                lines.push(`${indent}  }`);
+                // Forward the validated/coerced data (parseResult.data), NOT the raw req.body,
+                // so Zod coercion is preserved (e.g. form-urlencoded numeric fields via
+                // z.coerce.number()). Cast to the declared model type so the service-call type
+                // stays correct even when the schema infers a narrower shape (e.g. z.unknown()
+                // for inline-union properties); safeParse above guarantees runtime safety.
+                const bodyCastType = op.bodyInfo.typeName !== undefined && !op.bodyInfo.isSynthesized
+                    ? op.bodyInfo.typeName
+                    : 'unknown';
+                lines.push(`${indent}  const validatedBody = parseResult.data as ${bodyCastType}`);
+                bodyVarName = 'validatedBody';
+            }
         }
     }
     // Build service call args
@@ -575,28 +1276,81 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
         serviceArgs.push(bodyVarName);
     }
     if (op.queryParams.length > 0) {
-        serviceArgs.push('params');
+        // After successful Zod validation _qv.data carries the correct required/typed
+        // values (e.g. string[] for delimited arrays, object shape for deepObject params,
+        // and non-optional values for required scalar params). Use _qv.data when validation
+        // was applied; fall back to params when no validation is needed.
+        serviceArgs.push(queryParamsNeedValidation(op.queryParams) ? '_qv.data' : 'params');
+    }
+    // Context arg: pass the Fastify Request object (req) as the final argument when contextType is set.
+    if (contextType !== undefined) {
+        serviceArgs.push('req');
     }
     const serviceCall = `service.${op.methodName}(${serviceArgs.join(', ')})`;
-    // Response
+    // Response — wrap in try/catch to map HttpError to its status
+    lines.push(`${indent}  try {`);
     if (op.responseStatus.isVoid) {
-        lines.push(`${indent}  await ${serviceCall}`);
-        lines.push(`${indent}  reply.status(${op.responseStatus.status}).send()`);
+        lines.push(`${indent}    await ${serviceCall}`);
+        lines.push(`${indent}    reply.status(${op.responseStatus.status}).send()`);
+    }
+    else if (op.responseStatus.isMultiStatus === true) {
+        // Multi-status: service returns { status: number; body: T }; router forwards both.
+        lines.push(`${indent}    const _envelope = await ${serviceCall}`);
+        lines.push(`${indent}    return reply.status(_envelope.status).send(_envelope.body)`);
+    }
+    else if (op.responseStatus.responseContentType === 'text/plain') {
+        if (op.responseStatus.status === 200) {
+            lines.push(`${indent}    return reply.type('text/plain').send(await ${serviceCall})`);
+        }
+        else {
+            lines.push(`${indent}    return reply.status(${op.responseStatus.status}).type('text/plain').send(await ${serviceCall})`);
+        }
     }
-    else if (op.responseStatus.status === 201) {
-        lines.push(`${indent}  reply.status(201)`);
-        lines.push(`${indent}  return ${serviceCall}`);
+    else if (op.responseStatus.responseContentType === 'application/octet-stream') {
+        if (op.responseStatus.status === 200) {
+            lines.push(`${indent}    return reply.type('application/octet-stream').send(Buffer.from(await ${serviceCall}))`);
+        }
+        else {
+            lines.push(`${indent}    return reply.status(${op.responseStatus.status}).type('application/octet-stream').send(Buffer.from(await ${serviceCall}))`);
+        }
+    }
+    else if (op.responseStatus.status === 200) {
+        lines.push(`${indent}    return await ${serviceCall}`);
     }
     else {
-        lines.push(`${indent}  return ${serviceCall}`);
+        lines.push(`${indent}    reply.status(${op.responseStatus.status})`);
+        lines.push(`${indent}    return await ${serviceCall}`);
     }
+    lines.push(`${indent}  } catch (err) {`);
+    lines.push(`${indent}    if (err instanceof HttpError) {`);
+    lines.push(`${indent}      return (reply as FastifyReply).status(err.status).send({ error: err.message })`);
+    lines.push(`${indent}    }`);
+    lines.push(`${indent}    throw err`);
+    lines.push(`${indent}  }`);
     lines.push(`${indent}})`);
     return lines.join('\n');
 }
+// ── HttpError class ───────────────────────────────────────────────────────────
+/**
+ * Lines that emit the exported HttpError class into a generated router file.
+ * Services throw `new HttpError(404, 'Not found')` and the generated router
+ * catches it, returning the matching HTTP status instead of a generic 500.
+ */
+function httpErrorClassLines() {
+    return [
+        'export class HttpError extends Error {',
+        '  constructor(public readonly status: number, message: string) {',
+        '    super(message)',
+        "    this.name = 'HttpError'",
+        '  }',
+        '}',
+    ];
+}
 // ── Zod import helpers ────────────────────────────────────────────────────────
 /**
  * Returns true when any operation in the list generates param validation code
- * that requires Zod (path format validation, required/typed query params, or header params).
+ * that requires Zod (path format validation, required/typed query params, header params,
+ * or cookie params).
  */
 function operationsNeedZodForParams(operations) {
     for (const op of operations) {
@@ -606,6 +1360,8 @@ function operationsNeedZodForParams(operations) {
             return true;
         if (op.headerParams.length > 0)
             return true;
+        if (op.cookieParams.length > 0)
+            return true;
     }
     return false;
 }
@@ -615,6 +1371,7 @@ export function generateExpressRouter(spec, options) {
     const serviceName = deriveServiceName(spec);
     const operations = collectOperations(spec);
     const { sortedBodyTypes, usedSchemaNames, needsZod } = collectGeneratorSetup(operations, options);
+    // usedResponseSchemaNames is Fastify-only; not used in Express generator.
     const lines = [];
     lines.push('// This file is auto-generated. Do not edit manually.');
     lines.push('// Express: apply express.json() middleware before mounting this router so req.body is populated.');
@@ -624,6 +1381,8 @@ export function generateExpressRouter(spec, options) {
     if (sortedBodyTypes.length > 0) {
         lines.push(`import type { ${sortedBodyTypes.join(', ')} } from './models.js'`);
     }
+    const ctx = options?.contextType;
+    const serviceRef = ctx !== undefined ? `${serviceName}<${ctx}>` : serviceName;
     lines.push(`import type { ${serviceName} } from './service.js'`);
     if (needsZod) {
         lines.push(`import { z } from 'zod'`);
@@ -633,11 +1392,14 @@ export function generateExpressRouter(spec, options) {
         lines.push(`import { ${sortedUsedSchemas.join(', ')} } from '${options.schemaImportPath}'`);
     }
     lines.push('');
-    lines.push(`export function createRouter(service: ${serviceName}): Router {`);
+    for (const l of httpErrorClassLines())
+        lines.push(l);
+    lines.push('');
+    lines.push(`export function createRouter(service: ${serviceRef}): Router {`);
     lines.push('  const router = Router()');
     lines.push('');
     for (const op of operations) {
-        lines.push(buildExpressRouteHandler(op, '  ', options?.schemaNames));
+        lines.push(buildExpressRouteHandler(op, '  ', options?.schemaNames, ctx));
         lines.push('');
     }
     lines.push('  return router');
@@ -653,11 +1415,20 @@ export function generateExpressRouter(spec, options) {
 export function generateFastifyRouter(spec, options) {
     const serviceName = deriveServiceName(spec);
     const operations = collectOperations(spec);
-    const { sortedBodyTypes, usedSchemaNames, needsZod } = collectGeneratorSetup(operations, options);
+    const { sortedBodyTypes, usedSchemaNames, usedResponseSchemaNames, needsZod } = collectGeneratorSetup(operations, options);
+    // Merge body and response schema imports into a single sorted import list.
+    const allUsedSchemaNames = new Set([...usedSchemaNames, ...usedResponseSchemaNames]);
+    // Detect operations that need the octet-stream request body parser.
+    const hasOctetStreamRequestBody = operations.some((op) => op.bodyInfo?.contentType === 'application/octet-stream');
     const lines = [];
     lines.push('// This file is auto-generated. Do not edit manually.');
+    lines.push('// Fastify natively parses only application/json and text/plain request bodies.');
+    lines.push('// For application/x-www-form-urlencoded bodies, register @fastify/formbody before this router.');
+    lines.push('// For multipart/form-data bodies, register @fastify/multipart with { attachFieldsToBody: true } before this router.');
     lines.push('');
-    lines.push("import type { FastifyInstance } from 'fastify'");
+    const ctx = options?.contextType;
+    const serviceRef = ctx !== undefined ? `${serviceName}<${ctx}>` : serviceName;
+    lines.push("import type { FastifyInstance, FastifyReply } from 'fastify'");
     if (sortedBodyTypes.length > 0) {
         lines.push(`import type { ${sortedBodyTypes.join(', ')} } from './models.js'`);
     }
@@ -665,15 +1436,46 @@ export function generateFastifyRouter(spec, options) {
     if (needsZod) {
         lines.push(`import { z } from 'zod'`);
     }
-    if (usedSchemaNames.size > 0 && options?.schemaImportPath !== undefined) {
-        const sortedUsedSchemas = Array.from(usedSchemaNames).sort();
+    if (allUsedSchemaNames.size > 0 && options?.schemaImportPath !== undefined) {
+        const sortedUsedSchemas = Array.from(allUsedSchemaNames).sort();
         lines.push(`import { ${sortedUsedSchemas.join(', ')} } from '${options.schemaImportPath}'`);
     }
     lines.push('');
-    lines.push(`export function createRouter(app: FastifyInstance, service: ${serviceName}): void {`);
+    // Augment FastifyContextConfig so that config: { operationId } on each route is type-safe.
+    // Without this, TypeScript rejects the operationId property because FastifyContextConfig
+    // is empty by default. The augmentation is scoped to the generated router module.
+    lines.push("declare module 'fastify' {");
+    lines.push('  interface FastifyContextConfig {');
+    lines.push('    operationId?: string');
+    lines.push('  }');
+    lines.push('}');
+    lines.push('');
+    for (const l of httpErrorClassLines())
+        lines.push(l);
+    lines.push('');
+    lines.push(`export function createRouter(app: FastifyInstance, service: ${serviceRef}): void {`);
+    // Register a built-in content-type parser for application/octet-stream so that
+    // req.body is a Buffer. Fastify 5 does not parse octet-stream natively; without
+    // this registration the framework returns a 415 before the handler runs.
+    // addContentTypeParser is a core Fastify API and requires no extra dependency.
+    if (hasOctetStreamRequestBody) {
+        lines.push("  app.addContentTypeParser('application/octet-stream', { parseAs: 'buffer' }, (req, body, done) => done(null, body))");
+    }
+    // Wire a Zod-aware serializer compiler when response schemas are present.
+    // Fastify's default serializer does not understand Zod schemas; this compiler
+    // detects any Zod schema by its .parse method and validates before serializing.
+    if (usedResponseSchemaNames.size > 0 && options?.schemaImportPath !== undefined) {
+        lines.push('  app.setSerializerCompiler(({ schema }) => {');
+        lines.push("    if (schema !== null && typeof schema === 'object' && 'parse' in schema) {");
+        lines.push('      const zodSchema = schema as { parse: (data: unknown) => unknown }');
+        lines.push('      return (data: unknown) => JSON.stringify(zodSchema.parse(data))');
+        lines.push('    }');
+        lines.push('    return (data: unknown) => JSON.stringify(data)');
+        lines.push('  })');
+    }
     for (const op of operations) {
         lines.push('');
-        lines.push(buildFastifyRouteHandler(op, '  ', options?.schemaNames));
+        lines.push(buildFastifyRouteHandler(op, '  ', options?.schemaNames, ctx));
     }
     lines.push('}');
     lines.push('');
@@ -691,7 +1493,14 @@ export function generateRouter(spec, options) {
     const lines = [];
     lines.push('// This file is auto-generated. Do not edit manually.');
     lines.push('');
+    const ctx = options?.contextType;
+    const serviceRef = ctx !== undefined ? `${serviceName}<${ctx}>` : serviceName;
+    // getCookie from hono/cookie is needed when any operation declares cookie params.
+    const needsGetCookie = operations.some((op) => op.cookieParams.length > 0);
     lines.push("import { Hono } from 'hono'");
+    if (needsGetCookie) {
+        lines.push("import { getCookie } from 'hono/cookie'");
+    }
     if (sortedBodyTypes.length > 0) {
         lines.push(`import type { ${sortedBodyTypes.join(', ')} } from './models.js'`);
     }
@@ -704,11 +1513,14 @@ export function generateRouter(spec, options) {
         lines.push(`import { ${sortedUsedSchemas.join(', ')} } from '${options.schemaImportPath}'`);
     }
     lines.push('');
-    lines.push(`export function createRouter(service: ${serviceName}): Hono {`);
+    for (const l of httpErrorClassLines())
+        lines.push(l);
+    lines.push('');
+    lines.push(`export function createRouter(service: ${serviceRef}): Hono {`);
     lines.push('  const app = new Hono()');
     lines.push('');
     for (const op of operations) {
-        lines.push(buildRouteHandler(op, '  ', options?.schemaNames));
+        lines.push(buildRouteHandler(op, '  ', options?.schemaNames, ctx));
         lines.push('');
     }
     lines.push('  return app');