adorn-api 1.0.10 → 1.0.12

package/dist/express.cjs

@@ -43,10 +43,9 @@ module.exports = __toCommonJS(express_exports);
 // src/runtime/polyfill.ts
 Symbol.metadata ??= /* @__PURE__ */ Symbol("Symbol.metadata");
 
-// src/adapter/express/index.ts
-var import_express2 = require("express");
-var import_node_fs2 = require("fs");
-var import_node_path3 = require("path");
+// src/adapter/express/router.ts
+var import_express = require("express");
+var import_node_path2 = require("path");
 
 // src/runtime/metadata/key.ts
 var ADORN_META = /* @__PURE__ */ Symbol.for("adorn-api/meta");
@@ -266,101 +265,62 @@ async function loadArtifacts(options) {
   };
 }
 
-// src/adapter/express/index.ts
-var import_swagger_ui_express = __toESM(require("swagger-ui-express"), 1);
-
-// src/adapter/express/bootstrap.ts
-var import_express = __toESM(require("express"), 1);
-var import_node_path2 = __toESM(require("path"), 1);
-function bootstrap(options) {
-  return new Promise(async (resolve2, reject) => {
-    try {
-      const {
-        controllers,
-        port: userPort,
-        host: userHost,
-        artifactsDir: userArtifactsDir = ".adorn",
-        enableSwagger = true,
-        swaggerPath = "/docs",
-        swaggerJsonPath = "/docs/openapi.json",
-        middleware,
-        auth,
-        coerce
-      } = options;
-      if (controllers.length === 0) {
-        reject(new Error("At least one controller must be provided to bootstrap()."));
-        return;
-      }
-      const envPort = process.env.PORT;
-      const port = userPort ?? (envPort !== void 0 ? Number(envPort) : 3e3);
-      const host = userHost ?? process.env.HOST ?? "0.0.0.0";
-      if (isNaN(port) || port < 0 || port > 65535) {
-        reject(new Error(`Invalid port: ${port}. Port must be between 0 and 65535.`));
-        return;
-      }
-      const absoluteArtifactsDir = import_node_path2.default.isAbsolute(userArtifactsDir) ? userArtifactsDir : import_node_path2.default.resolve(process.cwd(), userArtifactsDir);
-      const app = (0, import_express.default)();
-      app.use(import_express.default.json());
-      const router = await createExpressRouter({
-        controllers,
-        artifactsDir: absoluteArtifactsDir,
-        middleware,
-        auth,
-        coerce
-      });
-      app.use(router);
-      if (enableSwagger) {
-        const displayHost = host === "0.0.0.0" ? "localhost" : host;
-        const serverUrl = `http://${displayHost}:${port}`;
-        app.use(
-          setupSwagger({
-            artifactsDir: absoluteArtifactsDir,
-            jsonPath: swaggerJsonPath,
-            uiPath: swaggerPath,
-            swaggerOptions: {
-              servers: [{ url: serverUrl }]
-            }
-          })
-        );
-      }
-      const server = app.listen(port, host, () => {
-        const displayHost = host === "0.0.0.0" ? "localhost" : host;
-        const serverUrl = `http://${displayHost}:${port}`;
-        console.log(`\u{1F680} Server running on ${serverUrl}`);
-        if (enableSwagger) {
-          console.log(`\u{1F4DA} Swagger UI: ${serverUrl}${swaggerPath}`);
-        }
-        const result = {
-          server,
-          app,
-          url: serverUrl,
-          port,
-          host,
-          close: () => new Promise((closeResolve) => {
-            server.close(() => {
-              console.log("Server closed gracefully");
-              closeResolve();
-            });
-          })
-        };
-        resolve2(result);
-      });
-      server.on("error", (error) => {
-        if (error.code === "EADDRINUSE") {
-          reject(new Error(`Port ${port} already in use. Please choose a different port.`));
-        } else if (error.code === "EACCES") {
-          reject(new Error(`Permission denied for port ${port}. Ports below 1024 require root privileges.`));
-        } else {
-          reject(new Error(`Failed to start server: ${error.message}`));
-        }
-      });
-    } catch (error) {
-      reject(error);
+// src/adapter/express/openapi.ts
+function toOpenApiPath(path3) {
+  return path3.replace(/:([^/]+)/g, "{$1}");
+}
+function getOpenApiOperation(openapi, route) {
+  const pathKey = toOpenApiPath(route.fullPath);
+  const pathItem = openapi.paths?.[pathKey];
+  if (!pathItem) return null;
+  return pathItem[route.httpMethod.toLowerCase()] ?? null;
+}
+function getParamSchemaIndex(operation) {
+  const index = /* @__PURE__ */ new Map();
+  const params = operation?.parameters ?? [];
+  for (const param of params) {
+    if (!param?.name || !param?.in) continue;
+    if (param.schema) {
+      index.set(`${param.in}:${param.name}`, param.schema);
     }
-  });
+  }
+  return index;
+}
+function getParamSchemaFromIndex(index, location, name) {
+  return index.get(`${location}:${name}`) ?? null;
+}
+function getRequestBodySchema(operation, contentType) {
+  const content = operation?.requestBody?.content;
+  if (!content) return null;
+  if (contentType && content[contentType]?.schema) {
+    return content[contentType].schema;
+  }
+  const first = Object.values(content)[0];
+  return first?.schema ?? null;
+}
+function schemaFromType(schemaType) {
+  if (!schemaType) return null;
+  return { type: schemaType };
+}
+function resolveSchema(schema, components, seen = /* @__PURE__ */ new Set()) {
+  const ref = schema.$ref;
+  if (typeof ref !== "string" || !ref.startsWith("#/components/schemas/")) {
+    return schema;
+  }
+  const name = ref.replace("#/components/schemas/", "");
+  if (seen.has(name)) return schema;
+  const next = components[name];
+  if (!next) return schema;
+  seen.add(name);
+  return resolveSchema(next, components, seen);
+}
+function getSchemaByRef(openapi, ref) {
+  if (!ref.startsWith("#/components/schemas/")) return null;
+  const schemaName = ref.replace("#/components/schemas/", "");
+  return openapi.components.schemas[schemaName] || null;
 }
 
-// src/adapter/express/index.ts
+// src/adapter/express/coercion.ts
 function normalizeCoerceOptions(coerce) {
   return {
     body: coerce?.body ?? false,
@@ -372,273 +332,270 @@ function normalizeCoerceOptions(coerce) {
     date: coerce?.date ?? false
   };
 }
-async function createExpressRouter(options) {
-  const { controllers, artifactsDir = ".adorn", middleware = {} } = options;
-  let manifest;
-  let openapi;
-  let precompiledValidators = null;
-  if (options.manifest && options.openapi) {
-    manifest = options.manifest;
-    openapi = options.openapi;
-    if (manifest.validation.mode === "precompiled" && manifest.validation.precompiledModule) {
-      try {
-        const validatorPath = (0, import_node_path3.join)(artifactsDir, manifest.validation.precompiledModule);
-        precompiledValidators = require(validatorPath).validators;
-      } catch (err) {
-        console.warn(`Failed to load precompiled validators: ${err}`);
-      }
+function getDateCoercionOptions(coerce, location) {
+  const enabled = coerce[location];
+  return {
+    dateTime: enabled && coerce.dateTime,
+    date: enabled && coerce.date
+  };
+}
+function coerceDatesWithSchema(value, schema, dateCoercion, components) {
+  if (!schema || !dateCoercion.date && !dateCoercion.dateTime) return value;
+  return coerceWithSchema(value, schema, dateCoercion, components, { coercePrimitives: false });
+}
+function coerceParamValue(value, schema, dateCoercion, components) {
+  if (!schema) return value;
+  return coerceWithSchema(value, schema, dateCoercion, components, { coercePrimitives: true });
+}
+function coerceWithSchema(value, schema, dateCoercion, components, options) {
+  if (value === void 0 || value === null) return value;
+  if (value instanceof Date) return value;
+  const resolved = resolveSchema(schema, components);
+  const override = resolved["x-adorn-coerce"];
+  const allowDateTime = override === true ? true : override === false ? false : dateCoercion.dateTime;
+  const allowDate = override === true ? true : override === false ? false : dateCoercion.date;
+  const byFormat = coerceDateString(value, resolved, allowDateTime, allowDate);
+  if (byFormat !== value) return byFormat;
+  const allOf = resolved.allOf;
+  if (Array.isArray(allOf)) {
+    let out = value;
+    for (const entry of allOf) {
+      out = coerceWithSchema(out, entry, { dateTime: allowDateTime, date: allowDate }, components, options);
     }
-  } else {
-    const artifacts = await loadArtifacts({ outDir: artifactsDir });
-    manifest = artifacts.manifest;
-    openapi = artifacts.openapi;
-    precompiledValidators = artifacts.validators?.validators ?? null;
+    return out;
   }
-  const routes = bindRoutes({ controllers, manifest });
-  const validator = precompiledValidators ? null : createValidator();
-  const router = (0, import_express2.Router)();
-  const instanceCache = /* @__PURE__ */ new Map();
-  const coerce = normalizeCoerceOptions(options.coerce);
-  function getInstance(Ctor) {
-    if (!instanceCache.has(Ctor)) {
-      instanceCache.set(Ctor, new Ctor());
+  const variants = resolved.oneOf ?? resolved.anyOf;
+  if (Array.isArray(variants)) {
+    for (const entry of variants) {
+      const out = coerceWithSchema(value, entry, { dateTime: allowDateTime, date: allowDate }, components, options);
+      if (out !== value) return out;
     }
-    return instanceCache.get(Ctor);
   }
-  function resolveMiddleware(items, named = {}) {
-    return items.map((item) => {
-      if (typeof item === "string") {
-        const fn = named[item];
-        if (!fn) {
-          throw new Error(`Named middleware "${item}" not found in middleware registry`);
-        }
-        return fn;
-      }
-      return item;
-    });
+  const schemaType = resolved.type;
+  const types = Array.isArray(schemaType) ? schemaType : schemaType ? [schemaType] : [];
+  if ((types.includes("array") || resolved.items) && Array.isArray(value)) {
+    const itemSchema = resolved.items ?? {};
+    return value.map((item) => coerceWithSchema(item, itemSchema, { dateTime: allowDateTime, date: allowDate }, components, options));
   }
-  function createAuthMiddleware(authConfig, routeAuth, globalSecurity) {
-    return async (req, res, next) => {
-      const isPublic = routeAuth === "public";
-      const hasAuthDecorator = routeAuth && routeAuth !== "public";
-      const hasGlobalSecurity = globalSecurity && globalSecurity.length > 0;
-      if (!hasAuthDecorator && !hasGlobalSecurity) {
-        return next();
-      }
-      if (isPublic) {
-        return next();
-      }
-      const authMeta = routeAuth;
-      const scheme = authMeta.scheme;
-      const requiredScopes = authMeta.scopes || [];
-      const isOptional = authMeta.optional ?? false;
-      const authRuntime = authConfig.schemes[scheme];
-      if (!authRuntime) {
-        throw new Error(`Auth scheme "${scheme}" not found in auth configuration`);
-      }
-      const result = await authRuntime.authenticate(req);
-      if (!result) {
-        if (isOptional) {
-          req.auth = null;
-          return next();
+  if ((types.includes("object") || resolved.properties || resolved.additionalProperties) && isPlainObject(value)) {
+    const props = resolved.properties;
+    const out = { ...value };
+    if (props) {
+      for (const [key, propSchema] of Object.entries(props)) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+          out[key] = coerceWithSchema(value[key], propSchema, { dateTime: allowDateTime, date: allowDate }, components, options);
         }
-        return authRuntime.challenge(res);
       }
-      req.auth = result.principal;
-      if (authRuntime.authorize && requiredScopes.length > 0) {
-        if (!authRuntime.authorize(result, requiredScopes)) {
-          res.status(403).json({ error: "Forbidden", message: "Insufficient scopes" });
-          return;
-        }
+    }
+    const additional = resolved.additionalProperties;
+    if (additional && typeof additional === "object") {
+      for (const [key, entry] of Object.entries(value)) {
+        if (props && Object.prototype.hasOwnProperty.call(props, key)) continue;
+        out[key] = coerceWithSchema(entry, additional, { dateTime: allowDateTime, date: allowDate }, components, options);
       }
-      next();
-    };
+    }
+    return out;
   }
-  function getSchemaByRef(ref) {
-    if (!ref.startsWith("#/components/schemas/")) return null;
-    const schemaName = ref.replace("#/components/schemas/", "");
-    return openapi.components.schemas[schemaName] || null;
+  if (options.coercePrimitives) {
+    return coercePrimitiveValue(value, types);
   }
-  for (const route of routes) {
-    const method = route.httpMethod.toLowerCase();
-    const openapiOperation = getOpenApiOperation(openapi, route);
-    const paramSchemaIndex = buildParamSchemaIndex(openapiOperation);
-    const bodySchema = getRequestBodySchema(openapiOperation, route.args.body?.contentType) ?? (route.args.body ? getSchemaByRef(route.args.body.schemaRef) : null);
-    const coerceBodyDates = getDateCoercionOptions(coerce, "body");
-    const coerceQueryDates = getDateCoercionOptions(coerce, "query");
-    const coercePathDates = getDateCoercionOptions(coerce, "path");
-    const coerceHeaderDates = getDateCoercionOptions(coerce, "header");
-    const coerceCookieDates = getDateCoercionOptions(coerce, "cookie");
-    const middlewareChain = [];
-    if (middleware.global) {
-      middlewareChain.push(...resolveMiddleware(middleware.global, middleware.named || {}));
-    }
-    if (route.controllerUse) {
-      middlewareChain.push(...resolveMiddleware(route.controllerUse, middleware.named || {}));
-    }
-    if (route.use) {
-      middlewareChain.push(...resolveMiddleware(route.use, middleware.named || {}));
-    }
-    if (options.auth) {
-      const authMw = createAuthMiddleware(options.auth, route.auth, openapi.security || []);
-      middlewareChain.push(authMw);
+  return value;
+}
+function coerceDateString(value, schema, allowDateTime, allowDate) {
+  if (typeof value !== "string") return value;
+  const format = schema.format;
+  const schemaType = schema.type;
+  const types = Array.isArray(schemaType) ? schemaType : schemaType ? [schemaType] : [];
+  const allowsString = types.length === 0 || types.includes("string");
+  if (format === "date-time" && allowDateTime && allowsString) {
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+      throw new Error(`Invalid date-time: ${value}`);
     }
-    router[method](route.fullPath, ...middlewareChain, async (req, res, next) => {
-      try {
-        const validationErrors = precompiledValidators ? validateRequestWithPrecompiled(route, req, precompiledValidators) : validateRequest(route, req, openapi, validator);
-        if (validationErrors) {
-          return res.status(400).json(formatValidationErrors(validationErrors));
-        }
-        const instance = getInstance(route.controllerCtor);
-        const handler = instance[route.methodName];
-        if (typeof handler !== "function") {
-          throw new Error(`Method ${route.methodName} not found on controller`);
-        }
-        const args = [];
-        if (route.args.body) {
-          const coercedBody = (coerceBodyDates.date || coerceBodyDates.dateTime) && bodySchema ? coerceDatesWithSchema(req.body, bodySchema, coerceBodyDates, openapi.components.schemas) : req.body;
-          args[route.args.body.index] = coercedBody;
-        }
-        for (const pathArg of route.args.path) {
-          const rawValue = req.params[pathArg.name];
-          const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "path", pathArg.name) ?? (pathArg.schemaRef ? getSchemaByRef(pathArg.schemaRef) : null) ?? schemaFromType(pathArg.schemaType);
-          const coerced = coerceParamValue(rawValue, paramSchema, coercePathDates, openapi.components.schemas);
-          args[pathArg.index] = coerced;
-        }
-        if (route.args.query.length > 0) {
-          const deepObjectArgs = route.args.query.filter((q) => q.serialization?.style === "deepObject");
-          const standardArgs = route.args.query.filter((q) => q.serialization?.style !== "deepObject");
-          if (deepObjectArgs.length > 0) {
-            const rawQuery = getRawQueryString(req);
-            const names = new Set(deepObjectArgs.map((q) => q.name));
-            const parsedDeep = parseDeepObjectParams(rawQuery, names);
-            for (const q of deepObjectArgs) {
-              const rawValue = parsedDeep[q.name];
-              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "query", q.name) ?? (q.schemaRef ? getSchemaByRef(q.schemaRef) : null) ?? schemaFromType(q.schemaType);
-              const baseValue = rawValue === void 0 ? {} : rawValue;
-              const coerced = coerceParamValue(baseValue, paramSchema, coerceQueryDates, openapi.components.schemas);
-              args[q.index] = coerced;
-            }
-          }
-          if (standardArgs.length > 0) {
-            const firstQueryIndex = standardArgs[0].index;
-            const allSameIndex = standardArgs.every((q) => q.index === firstQueryIndex);
-            if (allSameIndex) {
-              args[firstQueryIndex] = {};
-              for (const q of standardArgs) {
-                const parsed = parseQueryValue(req.query[q.name], q);
-                const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "query", q.name) ?? (q.schemaRef ? getSchemaByRef(q.schemaRef) : null) ?? schemaFromType(q.schemaType);
-                const coerced = coerceParamValue(parsed, paramSchema, coerceQueryDates, openapi.components.schemas);
-                args[firstQueryIndex][q.name] = coerced;
-              }
-            } else {
-              for (const q of standardArgs) {
-                const parsed = parseQueryValue(req.query[q.name], q);
-                const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "query", q.name) ?? (q.schemaRef ? getSchemaByRef(q.schemaRef) : null) ?? schemaFromType(q.schemaType);
-                const coerced = coerceParamValue(parsed, paramSchema, coerceQueryDates, openapi.components.schemas);
-                args[q.index] = coerced;
-              }
-            }
-          }
-        }
-        if (route.args.headers.length > 0) {
-          const firstHeaderIndex = route.args.headers[0].index;
-          const allSameIndex = route.args.headers.every((h) => h.index === firstHeaderIndex);
-          if (allSameIndex) {
-            args[firstHeaderIndex] = {};
-            for (const h of route.args.headers) {
-              const headerValue = req.headers[h.name.toLowerCase()];
-              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "header", h.name) ?? (h.schemaRef ? getSchemaByRef(h.schemaRef) : null) ?? schemaFromType(h.schemaType);
-              const coerced = coerceParamValue(headerValue, paramSchema, coerceHeaderDates, openapi.components.schemas);
-              args[firstHeaderIndex][h.name] = coerced ?? void 0;
-            }
-          } else {
-            for (const h of route.args.headers) {
-              const headerValue = req.headers[h.name.toLowerCase()];
-              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "header", h.name) ?? (h.schemaRef ? getSchemaByRef(h.schemaRef) : null) ?? schemaFromType(h.schemaType);
-              const coerced = coerceParamValue(headerValue, paramSchema, coerceHeaderDates, openapi.components.schemas);
-              args[h.index] = coerced ?? void 0;
-            }
-          }
-        }
-        if (route.args.cookies.length > 0) {
-          const firstCookieIndex = route.args.cookies[0].index;
-          const allSameIndex = route.args.cookies.every((c) => c.index === firstCookieIndex);
-          const cookies = parseCookies(req.headers.cookie);
-          if (allSameIndex) {
-            args[firstCookieIndex] = {};
-            for (const c of route.args.cookies) {
-              const cookieValue = cookies[c.name];
-              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "cookie", c.name) ?? (c.schemaRef ? getSchemaByRef(c.schemaRef) : null) ?? schemaFromType(c.schemaType);
-              const coerced = coerceParamValue(cookieValue, paramSchema, coerceCookieDates, openapi.components.schemas);
-              args[firstCookieIndex][c.name] = coerced;
-            }
-          } else {
-            for (const c of route.args.cookies) {
-              const cookieValue = cookies[c.name];
-              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "cookie", c.name) ?? (c.schemaRef ? getSchemaByRef(c.schemaRef) : null) ?? schemaFromType(c.schemaType);
-              const coerced = coerceParamValue(cookieValue, paramSchema, coerceCookieDates, openapi.components.schemas);
-              args[c.index] = coerced;
-            }
-          }
-        }
-        if (args.length === 0) {
-          args.push(req);
-        }
-        const result = await handler.apply(instance, args);
-        const primaryResponse = route.responses[0];
-        const status = primaryResponse?.status ?? 200;
-        res.status(status).json(result);
-      } catch (error) {
-        next(error);
-      }
-    });
+    return parsed;
   }
-  return router;
+  if (format === "date" && allowDate && allowsString) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+      throw new Error(`Invalid date: ${value}`);
+    }
+    const parsed = /* @__PURE__ */ new Date(`${value}T00:00:00.000Z`);
+    if (Number.isNaN(parsed.getTime())) {
+      throw new Error(`Invalid date: ${value}`);
+    }
+    return parsed;
+  }
+  return value;
 }
-function getDateCoercionOptions(coerce, location) {
-  const enabled = coerce[location];
-  return {
-    dateTime: enabled && coerce.dateTime,
-    date: enabled && coerce.date
-  };
+function coercePrimitiveValue(value, types) {
+  if (value === void 0 || value === null) return value;
+  if (types.includes("number") || types.includes("integer")) {
+    const num = Number(value);
+    if (Number.isNaN(num)) {
+      throw new Error(`Invalid number: ${value}`);
+    }
+    return num;
+  }
+  if (types.includes("boolean")) {
+    if (value === "true") return true;
+    if (value === "false") return false;
+    if (typeof value === "boolean") return value;
+    throw new Error(`Invalid boolean: ${value}`);
+  }
+  return value;
 }
-function toOpenApiPath(path3) {
-  return path3.replace(/:([^/]+)/g, "{$1}");
+function isPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
 }
-function getOpenApiOperation(openapi, route) {
-  const pathKey = toOpenApiPath(route.fullPath);
-  const pathItem = openapi.paths?.[pathKey];
-  if (!pathItem) return null;
-  return pathItem[route.httpMethod.toLowerCase()] ?? null;
+function parseQueryValue(value, param) {
+  if (value === void 0 || value === null) return value;
+  const isArray = Array.isArray(param.schemaType) ? param.schemaType.includes("array") : param.schemaType === "array";
+  if (!isArray) return value;
+  const style = param.serialization?.style ?? "form";
+  const explode = param.serialization?.explode ?? true;
+  if (Array.isArray(value)) {
+    return value;
+  }
+  if (style === "form") {
+    if (explode) {
+      return value;
+    }
+    return value.split(",");
+  }
+  if (style === "spaceDelimited") {
+    return value.split(" ");
+  }
+  if (style === "pipeDelimited") {
+    return value.split("|");
+  }
+  return value;
 }
-function buildParamSchemaIndex(operation) {
-  const index = /* @__PURE__ */ new Map();
-  const params = operation?.parameters ?? [];
-  for (const param of params) {
-    if (!param?.name || !param?.in) continue;
-    if (param.schema) {
-      index.set(`${param.in}:${param.name}`, param.schema);
+function getRawQueryString(req) {
+  const url = req.originalUrl ?? req.url ?? "";
+  const index = url.indexOf("?");
+  if (index === -1) return "";
+  return url.slice(index + 1);
+}
+function parseDeepObjectParams(rawQuery, names) {
+  const out = {};
+  if (!rawQuery || names.size === 0) return out;
+  const params = new URLSearchParams(rawQuery);
+  for (const [key, value] of params.entries()) {
+    const path3 = parseBracketPath(key);
+    if (path3.length === 0) continue;
+    const root = path3[0];
+    if (!names.has(root)) continue;
+    assignDeepValue(out, path3, value);
+  }
+  return out;
+}
+function parseBracketPath(key) {
+  const parts = [];
+  let current = "";
+  for (let i = 0; i < key.length; i++) {
+    const ch = key[i];
+    if (ch === "[") {
+      if (current) parts.push(current);
+      current = "";
+      continue;
+    }
+    if (ch === "]") {
+      if (current) parts.push(current);
+      current = "";
+      continue;
     }
+    current += ch;
   }
-  return index;
+  if (current) parts.push(current);
+  return parts;
 }
-function getParamSchemaFromIndex(index, location, name) {
-  return index.get(`${location}:${name}`) ?? null;
+function assignDeepValue(target, path3, value) {
+  let cursor = target;
+  for (let i = 0; i < path3.length; i++) {
+    const key = path3[i];
+    if (!key) continue;
+    const isLast = i === path3.length - 1;
+    if (isLast) {
+      const existing = cursor[key];
+      if (existing === void 0) {
+        cursor[key] = value;
+      } else if (Array.isArray(existing)) {
+        existing.push(value);
+      } else {
+        cursor[key] = [existing, value];
+      }
+      return;
+    }
+    const next = cursor[key];
+    if (!isPlainObject(next)) {
+      cursor[key] = {};
+    }
+    cursor = cursor[key];
+  }
 }
-function getRequestBodySchema(operation, contentType) {
-  const content = operation?.requestBody?.content;
-  if (!content) return null;
-  if (contentType && content[contentType]?.schema) {
-    return content[contentType].schema;
+function parseCookies(cookieHeader) {
+  if (!cookieHeader) return {};
+  const cookies = {};
+  const pairs = cookieHeader.split(";");
+  for (const pair of pairs) {
+    const [name, ...valueParts] = pair.trim().split("=");
+    if (name) {
+      cookies[name] = valueParts.join("=");
+    }
   }
-  const first = Object.values(content)[0];
-  return first?.schema ?? null;
+  return cookies;
 }
-function schemaFromType(schemaType) {
-  if (!schemaType) return null;
-  return { type: schemaType };
+function normalizeSort(sort) {
+  if (Array.isArray(sort)) {
+    return sort.map((s) => String(s));
+  }
+  if (typeof sort === "string") {
+    return sort.split(",").map((s) => s.trim()).filter(Boolean);
+  }
+  return [];
 }
+
+// src/adapter/express/auth.ts
+function createAuthMiddleware(authConfig, routeAuth, globalSecurity) {
+  return async (req, res, next) => {
+    const isPublic = routeAuth === "public";
+    const hasAuthDecorator = routeAuth && routeAuth !== "public";
+    const hasGlobalSecurity = globalSecurity && globalSecurity.length > 0;
+    if (!hasAuthDecorator && !hasGlobalSecurity) {
+      return next();
+    }
+    if (isPublic) {
+      return next();
+    }
+    const authMeta = routeAuth;
+    const scheme = authMeta.scheme;
+    const requiredScopes = authMeta.scopes || [];
+    const isOptional = authMeta.optional ?? false;
+    const authRuntime = authConfig.schemes[scheme];
+    if (!authRuntime) {
+      throw new Error(`Auth scheme "${scheme}" not found in auth configuration`);
+    }
+    const result = await authRuntime.authenticate(req);
+    if (!result) {
+      if (isOptional) {
+        req.auth = null;
+        return next();
+      }
+      return authRuntime.challenge(res);
+    }
+    req.auth = result.principal;
+    if (authRuntime.authorize && requiredScopes.length > 0) {
+      if (!authRuntime.authorize(result, requiredScopes)) {
+        res.status(403).json({ error: "Forbidden", message: "Insufficient scopes" });
+        return;
+      }
+    }
+    next();
+  };
+}
+
+// src/adapter/express/validation.ts
 function validateRequestWithPrecompiled(route, req, validators) {
   const errors = [];
   const deepNames = new Set(route.args.query.filter((q) => q.serialization?.style === "deepObject").map((q) => q.name));
@@ -661,48 +618,31 @@ function validateRequestWithPrecompiled(route, req, validators) {
     }
   }
   for (const q of route.args.query) {
-    const value = q.serialization?.style === "deepObject" ? deepValues[q.name] : req.query[q.name];
-    if (value === void 0) continue;
-    const schema = schemaFromType(q.schemaType) ?? {};
-    const coerced = coerceParamValue(value, schema, { dateTime: false, date: false }, {});
-    if (Object.keys(schema).length > 0 && coerced !== void 0) {
-      errors.push({
-        path: `#/query/${q.name}`,
-        message: `Schema validation not supported for query params in precompiled mode`,
-        keyword: "notSupported",
-        params: {}
-      });
-    }
-  }
-  for (const p of route.args.path) {
-    const value = req.params[p.name];
-    if (value === void 0) continue;
-    const schema = schemaFromType(p.schemaType) ?? {};
-    const coerced = coerceParamValue(value, schema, { dateTime: false, date: false }, {});
-    if (Object.keys(schema).length > 0 && coerced !== void 0) {
-      errors.push({
-        path: `#/path/${p.name}`,
-        message: `Schema validation not supported for path params in precompiled mode`,
-        keyword: "notSupported",
-        params: {}
-      });
+    let value = q.serialization?.style === "deepObject" ? deepValues[q.name] : req.query[q.name];
+    if (q.content === "application/json" && typeof value === "string") {
+      try {
+        value = JSON.parse(value);
+      } catch (e) {
+        errors.push({
+          path: `#/query/${q.name}`,
+          message: `Invalid JSON string`,
+          keyword: "json",
+          params: {}
+        });
+        continue;
+      }
     }
   }
   return errors.length > 0 ? errors : null;
 }
 function validateRequest(route, req, openapi, validator) {
-  function getSchemaByRef(ref) {
-    if (!ref.startsWith("#/components/schemas/")) return null;
-    const schemaName = ref.replace("#/components/schemas/", "");
-    return openapi.components.schemas[schemaName] || null;
-  }
   const openapiOperation = getOpenApiOperation(openapi, route);
-  const paramSchemaIndex = buildParamSchemaIndex(openapiOperation);
+  const paramSchemaIndex = getParamSchemaIndex(openapiOperation);
   const deepNames = new Set(route.args.query.filter((q) => q.serialization?.style === "deepObject").map((q) => q.name));
   const deepValues = deepNames.size > 0 ? parseDeepObjectParams(getRawQueryString(req), deepNames) : {};
   const errors = [];
   if (route.args.body) {
-    const bodySchema = getSchemaByRef(route.args.body.schemaRef);
+    const bodySchema = getSchemaByRef(openapi, route.args.body.schemaRef);
     if (bodySchema) {
       const validate = validator.compile(bodySchema);
       const valid = validate(req.body);
@@ -719,7 +659,20 @@ function validateRequest(route, req, openapi, validator) {
     }
   }
   for (const q of route.args.query) {
-    const value = q.serialization?.style === "deepObject" ? deepValues[q.name] : req.query[q.name];
+    let value = q.serialization?.style === "deepObject" ? deepValues[q.name] : req.query[q.name];
+    if (q.content === "application/json" && typeof value === "string") {
+      try {
+        value = JSON.parse(value);
+      } catch (e) {
+        errors.push({
+          path: `#/query/${q.name}`,
+          message: `Invalid JSON string`,
+          keyword: "json",
+          params: {}
+        });
+        continue;
+      }
+    }
     const openapiSchema = getParamSchemaFromIndex(paramSchemaIndex, "query", q.name);
     let schema = {};
     if (openapiSchema) {
@@ -730,7 +683,7 @@ function validateRequest(route, req, openapi, validator) {
         schema.type = type;
       }
       if (q.schemaRef && q.schemaRef.includes("Inline")) {
-        const inlineSchema = getSchemaByRef(q.schemaRef);
+        const inlineSchema = getSchemaByRef(openapi, q.schemaRef);
         if (inlineSchema) {
           Object.assign(schema, inlineSchema);
         }
@@ -764,7 +717,7 @@ function validateRequest(route, req, openapi, validator) {
         schema.type = type;
       }
       if (p.schemaRef && p.schemaRef.includes("Inline")) {
-        const inlineSchema = getSchemaByRef(p.schemaRef);
+        const inlineSchema = getSchemaByRef(openapi, p.schemaRef);
         if (inlineSchema) {
           Object.assign(schema, inlineSchema);
         }
@@ -788,225 +741,213 @@ function validateRequest(route, req, openapi, validator) {
   }
   return errors.length > 0 ? errors : null;
 }
-function resolveSchema(schema, components, seen = /* @__PURE__ */ new Set()) {
-  const ref = schema.$ref;
-  if (typeof ref !== "string" || !ref.startsWith("#/components/schemas/")) {
-    return schema;
-  }
-  const name = ref.replace("#/components/schemas/", "");
-  if (seen.has(name)) return schema;
-  const next = components[name];
-  if (!next) return schema;
-  seen.add(name);
-  return resolveSchema(next, components, seen);
-}
-function coerceDatesWithSchema(value, schema, dateCoercion, components) {
-  if (!schema || !dateCoercion.date && !dateCoercion.dateTime) return value;
-  return coerceWithSchema(value, schema, dateCoercion, components, { coercePrimitives: false });
-}
-function coerceParamValue(value, schema, dateCoercion, components) {
-  if (!schema) return value;
-  return coerceWithSchema(value, schema, dateCoercion, components, { coercePrimitives: true });
-}
-function coerceWithSchema(value, schema, dateCoercion, components, options) {
-  if (value === void 0 || value === null) return value;
-  if (value instanceof Date) return value;
-  const resolved = resolveSchema(schema, components);
-  const override = resolved["x-adorn-coerce"];
-  const allowDateTime = override === true ? true : override === false ? false : dateCoercion.dateTime;
-  const allowDate = override === true ? true : override === false ? false : dateCoercion.date;
-  const byFormat = coerceDateString(value, resolved, allowDateTime, allowDate);
-  if (byFormat !== value) return byFormat;
-  const allOf = resolved.allOf;
-  if (Array.isArray(allOf)) {
-    let out = value;
-    for (const entry of allOf) {
-      out = coerceWithSchema(out, entry, { dateTime: allowDateTime, date: allowDate }, components, options);
-    }
-    return out;
-  }
-  const variants = resolved.oneOf ?? resolved.anyOf;
-  if (Array.isArray(variants)) {
-    for (const entry of variants) {
-      const out = coerceWithSchema(value, entry, { dateTime: allowDateTime, date: allowDate }, components, options);
-      if (out !== value) return out;
-    }
-  }
-  const schemaType = resolved.type;
-  const types = Array.isArray(schemaType) ? schemaType : schemaType ? [schemaType] : [];
-  if ((types.includes("array") || resolved.items) && Array.isArray(value)) {
-    const itemSchema = resolved.items ?? {};
-    return value.map((item) => coerceWithSchema(item, itemSchema, { dateTime: allowDateTime, date: allowDate }, components, options));
-  }
-  if ((types.includes("object") || resolved.properties || resolved.additionalProperties) && isPlainObject(value)) {
-    const props = resolved.properties;
-    const out = { ...value };
-    if (props) {
-      for (const [key, propSchema] of Object.entries(props)) {
-        if (Object.prototype.hasOwnProperty.call(value, key)) {
-          out[key] = coerceWithSchema(value[key], propSchema, { dateTime: allowDateTime, date: allowDate }, components, options);
-        }
-      }
-    }
-    const additional = resolved.additionalProperties;
-    if (additional && typeof additional === "object") {
-      for (const [key, entry] of Object.entries(value)) {
-        if (props && Object.prototype.hasOwnProperty.call(props, key)) continue;
-        out[key] = coerceWithSchema(entry, additional, { dateTime: allowDateTime, date: allowDate }, components, options);
-      }
-    }
-    return out;
-  }
-  if (options.coercePrimitives) {
-    return coercePrimitiveValue(value, types);
-  }
-  return value;
-}
-function coerceDateString(value, schema, allowDateTime, allowDate) {
-  if (typeof value !== "string") return value;
-  const format = schema.format;
-  const schemaType = schema.type;
-  const types = Array.isArray(schemaType) ? schemaType : schemaType ? [schemaType] : [];
-  const allowsString = types.length === 0 || types.includes("string");
-  if (format === "date-time" && allowDateTime && allowsString) {
-    const parsed = new Date(value);
-    if (Number.isNaN(parsed.getTime())) {
-      throw new Error(`Invalid date-time: ${value}`);
-    }
-    return parsed;
-  }
-  if (format === "date" && allowDate && allowsString) {
-    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
-      throw new Error(`Invalid date: ${value}`);
-    }
-    const parsed = /* @__PURE__ */ new Date(`${value}T00:00:00.000Z`);
-    if (Number.isNaN(parsed.getTime())) {
-      throw new Error(`Invalid date: ${value}`);
-    }
-    return parsed;
-  }
-  return value;
-}
-function coercePrimitiveValue(value, types) {
-  if (value === void 0 || value === null) return value;
-  if (types.includes("number") || types.includes("integer")) {
-    const num = Number(value);
-    if (Number.isNaN(num)) {
-      throw new Error(`Invalid number: ${value}`);
-    }
-    return num;
-  }
-  if (types.includes("boolean")) {
-    if (value === "true") return true;
-    if (value === "false") return false;
-    if (typeof value === "boolean") return value;
-    throw new Error(`Invalid boolean: ${value}`);
-  }
-  return value;
-}
-function isPlainObject(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null;
-}
-function parseQueryValue(value, param) {
-  if (value === void 0 || value === null) return value;
-  const isArray = Array.isArray(param.schemaType) ? param.schemaType.includes("array") : param.schemaType === "array";
-  if (!isArray) return value;
-  const style = param.serialization?.style ?? "form";
-  const explode = param.serialization?.explode ?? true;
-  if (Array.isArray(value)) {
-    return value;
-  }
-  if (style === "form") {
-    if (explode) {
-      return value;
-    }
-    return value.split(",");
-  }
-  if (style === "spaceDelimited") {
-    return value.split(" ");
-  }
-  if (style === "pipeDelimited") {
-    return value.split("|");
-  }
-  return value;
-}
-function getRawQueryString(req) {
-  const url = req.originalUrl ?? req.url ?? "";
-  const index = url.indexOf("?");
-  if (index === -1) return "";
-  return url.slice(index + 1);
-}
-function parseDeepObjectParams(rawQuery, names) {
-  const out = {};
-  if (!rawQuery || names.size === 0) return out;
-  const params = new URLSearchParams(rawQuery);
-  for (const [key, value] of params.entries()) {
-    const path3 = parseBracketPath(key);
-    if (path3.length === 0) continue;
-    const root = path3[0];
-    if (!names.has(root)) continue;
-    assignDeepValue(out, path3, value);
-  }
-  return out;
-}
-function parseBracketPath(key) {
-  const parts = [];
-  let current = "";
-  for (let i = 0; i < key.length; i++) {
-    const ch = key[i];
-    if (ch === "[") {
-      if (current) parts.push(current);
-      current = "";
-      continue;
-    }
-    if (ch === "]") {
-      if (current) parts.push(current);
-      current = "";
-      continue;
+
+// src/adapter/express/router.ts
+async function createExpressRouter(options) {
+  const { controllers, artifactsDir = ".adorn", middleware = {}, defaultPageSize = 10 } = options;
+  let manifest;
+  let openapi;
+  let precompiledValidators = null;
+  if (options.manifest && options.openapi) {
+    manifest = options.manifest;
+    openapi = options.openapi;
+    if (manifest.validation.mode === "precompiled" && manifest.validation.precompiledModule) {
+      try {
+        const validatorPath = (0, import_node_path2.join)(artifactsDir, manifest.validation.precompiledModule);
+        precompiledValidators = require(validatorPath).validators;
+      } catch (err) {
+        console.warn(`Failed to load precompiled validators: ${err}`);
+      }
     }
-    current += ch;
+  } else {
+    const artifacts = await loadArtifacts({ outDir: artifactsDir });
+    manifest = artifacts.manifest;
+    openapi = artifacts.openapi;
+    precompiledValidators = artifacts.validators?.validators ?? null;
   }
-  if (current) parts.push(current);
-  return parts;
-}
-function assignDeepValue(target, path3, value) {
-  let cursor = target;
-  for (let i = 0; i < path3.length; i++) {
-    const key = path3[i];
-    if (!key) continue;
-    const isLast = i === path3.length - 1;
-    if (isLast) {
-      const existing = cursor[key];
-      if (existing === void 0) {
-        cursor[key] = value;
-      } else if (Array.isArray(existing)) {
-        existing.push(value);
-      } else {
-        cursor[key] = [existing, value];
+  const routes = bindRoutes({ controllers, manifest });
+  const validator = precompiledValidators ? null : createValidator();
+  const router = (0, import_express.Router)();
+  const instanceCache = /* @__PURE__ */ new Map();
+  const coerce = normalizeCoerceOptions(options.coerce);
+  function getInstance(Ctor) {
+    if (!instanceCache.has(Ctor)) {
+      instanceCache.set(Ctor, new Ctor());
+    }
+    return instanceCache.get(Ctor);
+  }
+  function resolveMiddleware(items, named = {}) {
+    return items.map((item) => {
+      if (typeof item === "string") {
+        const fn = named[item];
+        if (!fn) {
+          throw new Error(`Named middleware "${item}" not found in middleware registry`);
+        }
+        return fn;
       }
-      return;
+      return item;
+    });
+  }
+  for (const route of routes) {
+    const method = route.httpMethod.toLowerCase();
+    const openapiOperation = getOpenApiOperation(openapi, route);
+    const paramSchemaIndex = getParamSchemaIndex(openapiOperation);
+    const bodySchema = getRequestBodySchema(openapiOperation, route.args.body?.contentType) ?? (route.args.body ? getSchemaByRef(openapi, route.args.body.schemaRef) : null);
+    const coerceBodyDates = getDateCoercionOptions(coerce, "body");
+    const coerceQueryDates = getDateCoercionOptions(coerce, "query");
+    const coercePathDates = getDateCoercionOptions(coerce, "path");
+    const coerceHeaderDates = getDateCoercionOptions(coerce, "header");
+    const coerceCookieDates = getDateCoercionOptions(coerce, "cookie");
+    const middlewareChain = [];
+    if (middleware.global) {
+      middlewareChain.push(...resolveMiddleware(middleware.global, middleware.named || {}));
     }
-    const next = cursor[key];
-    if (!isPlainObject(next)) {
-      cursor[key] = {};
+    if (route.controllerUse) {
+      middlewareChain.push(...resolveMiddleware(route.controllerUse, middleware.named || {}));
     }
-    cursor = cursor[key];
-  }
-}
-function parseCookies(cookieHeader) {
-  if (!cookieHeader) return {};
-  const cookies = {};
-  const pairs = cookieHeader.split(";");
-  for (const pair of pairs) {
-    const [name, ...valueParts] = pair.trim().split("=");
-    if (name) {
-      cookies[name] = valueParts.join("=");
+    if (route.use) {
+      middlewareChain.push(...resolveMiddleware(route.use, middleware.named || {}));
+    }
+    if (options.auth) {
+      const authMw = createAuthMiddleware(options.auth, route.auth, openapi.security || []);
+      middlewareChain.push(authMw);
     }
+    router[method](route.fullPath, ...middlewareChain, async (req, res, next) => {
+      try {
+        const validationErrors = precompiledValidators ? validateRequestWithPrecompiled(route, req, precompiledValidators) : validateRequest(route, req, openapi, validator);
+        if (validationErrors) {
+          return res.status(400).json(formatValidationErrors(validationErrors));
+        }
+        const instance = getInstance(route.controllerCtor);
+        const handler = instance[route.methodName];
+        if (typeof handler !== "function") {
+          throw new Error(`Method ${route.methodName} not found on controller`);
+        }
+        const args = [];
+        if (route.args.body) {
+          const coercedBody = (coerceBodyDates.date || coerceBodyDates.dateTime) && bodySchema ? coerceDatesWithSchema(req.body, bodySchema, coerceBodyDates, openapi.components.schemas) : req.body;
+          args[route.args.body.index] = coercedBody;
+        }
+        for (const pathArg of route.args.path) {
+          const rawValue = req.params[pathArg.name];
+          const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "path", pathArg.name) ?? (pathArg.schemaRef ? getSchemaByRef(openapi, pathArg.schemaRef) : null) ?? schemaFromType(pathArg.schemaType);
+          const coerced = coerceParamValue(rawValue, paramSchema, coercePathDates, openapi.components.schemas);
+          args[pathArg.index] = coerced;
+        }
+        if (route.args.query.length > 0) {
+          const jsonArgs = route.args.query.filter((q) => q.content === "application/json");
+          const standardArgs = route.args.query.filter((q) => q.content !== "application/json");
+          const queryArgIndex = standardArgs[0]?.index;
+          if (queryArgIndex !== void 0) {
+            args[queryArgIndex] = {};
+          }
+          if (jsonArgs.length > 0) {
+            for (const q of jsonArgs) {
+              const rawValue = req.query[q.name];
+              if (rawValue === void 0 || rawValue === null) continue;
+              let parsed = rawValue;
+              if (typeof rawValue === "string" && rawValue.length > 0) {
+                try {
+                  parsed = JSON.parse(rawValue);
+                } catch (e) {
+                  parsed = rawValue;
+                }
+              }
+              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "query", q.name) ?? (q.schemaRef ? getSchemaByRef(openapi, q.schemaRef) : null) ?? schemaFromType(q.schemaType);
+              const coerced = coerceParamValue(parsed, paramSchema, coerceQueryDates, openapi.components.schemas);
+              if (!args[q.index] || typeof args[q.index] !== "object") {
+                args[q.index] = {};
+              }
+              Object.assign(args[q.index], coerced);
+            }
+          }
+          if (standardArgs.length > 0) {
+            for (const q of standardArgs) {
+              const rawValue = req.query[q.name];
+              if (rawValue === void 0) continue;
+              const parsed = parseQueryValue(rawValue, q);
+              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "query", q.name) ?? (q.schemaRef ? getSchemaByRef(openapi, q.schemaRef) : null) ?? schemaFromType(q.schemaType);
+              const coerced = coerceParamValue(parsed, paramSchema, coerceQueryDates, openapi.components.schemas);
+              if (!args[q.index] || typeof args[q.index] !== "object") {
+                args[q.index] = {};
+              }
+              args[q.index][q.name] = coerced;
+            }
+          }
+          if (queryArgIndex !== void 0 && args[queryArgIndex]) {
+            const queryObj = args[queryArgIndex];
+            if (queryObj.page === void 0) {
+              queryObj.page = 1;
+            }
+            if (queryObj.pageSize === void 0) {
+              queryObj.pageSize = defaultPageSize;
+            }
+            if (queryObj.sort) {
+              queryObj.sort = normalizeSort(queryObj.sort);
+            }
+          }
+        }
+        if (route.args.headers.length > 0) {
+          const firstHeaderIndex = route.args.headers[0].index;
+          const allSameIndex = route.args.headers.every((h) => h.index === firstHeaderIndex);
+          if (allSameIndex) {
+            args[firstHeaderIndex] = {};
+            for (const h of route.args.headers) {
+              const headerValue = req.headers[h.name.toLowerCase()];
+              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "header", h.name) ?? (h.schemaRef ? getSchemaByRef(openapi, h.schemaRef) : null) ?? schemaFromType(h.schemaType);
+              const coerced = coerceParamValue(headerValue, paramSchema, coerceHeaderDates, openapi.components.schemas);
+              args[firstHeaderIndex][h.name] = coerced ?? void 0;
+            }
+          } else {
+            for (const h of route.args.headers) {
+              const headerValue = req.headers[h.name.toLowerCase()];
+              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "header", h.name) ?? (h.schemaRef ? getSchemaByRef(openapi, h.schemaRef) : null) ?? schemaFromType(h.schemaType);
+              const coerced = coerceParamValue(headerValue, paramSchema, coerceHeaderDates, openapi.components.schemas);
+              args[h.index] = coerced ?? void 0;
+            }
+          }
+        }
+        if (route.args.cookies.length > 0) {
+          const firstCookieIndex = route.args.cookies[0].index;
+          const allSameIndex = route.args.cookies.every((c) => c.index === firstCookieIndex);
+          const cookies = parseCookies(req.headers.cookie);
+          if (allSameIndex) {
+            args[firstCookieIndex] = {};
+            for (const c of route.args.cookies) {
+              const cookieValue = cookies[c.name];
+              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "cookie", c.name) ?? (c.schemaRef ? getSchemaByRef(openapi, c.name) : null) ?? schemaFromType(c.schemaType);
+              const coerced = coerceParamValue(cookieValue, paramSchema, coerceCookieDates, openapi.components.schemas);
+              args[firstCookieIndex][c.name] = coerced;
+            }
+          } else {
+            for (const c of route.args.cookies) {
+              const cookieValue = cookies[c.name];
+              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "cookie", c.name) ?? (c.schemaRef ? getSchemaByRef(openapi, c.name) : null) ?? schemaFromType(c.schemaType);
+              const coerced = coerceParamValue(cookieValue, paramSchema, coerceCookieDates, openapi.components.schemas);
+              args[c.index] = coerced;
+            }
+          }
+        }
+        if (args.length === 0) {
+          args.push(req);
+        }
+        const result = await handler.apply(instance, args);
+        const primaryResponse = route.responses[0];
+        const status = primaryResponse?.status ?? 200;
+        res.status(status).json(result);
+      } catch (error) {
+        next(error);
+      }
+    });
   }
-  return cookies;
+  return router;
 }
+
+// src/adapter/express/swagger.ts
+var import_express2 = require("express");
+var import_node_fs2 = require("fs");
+var import_node_path3 = require("path");
+var import_swagger_ui_express = __toESM(require("swagger-ui-express"), 1);
 function setupSwagger(options = {}) {
   const {
     artifactsDir = ".adorn",
@@ -1029,6 +970,97 @@ function setupSwagger(options = {}) {
   }));
   return router;
 }
+
+// src/adapter/express/bootstrap.ts
+var import_express3 = __toESM(require("express"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
+function bootstrap(options) {
+  return new Promise(async (resolve2, reject) => {
+    try {
+      const {
+        controllers,
+        port: userPort,
+        host: userHost,
+        artifactsDir: userArtifactsDir = ".adorn",
+        enableSwagger = true,
+        swaggerPath = "/docs",
+        swaggerJsonPath = "/docs/openapi.json",
+        middleware,
+        auth,
+        coerce
+      } = options;
+      if (controllers.length === 0) {
+        reject(new Error("At least one controller must be provided to bootstrap()."));
+        return;
+      }
+      const envPort = process.env.PORT;
+      const port = userPort ?? (envPort !== void 0 ? Number(envPort) : 3e3);
+      const host = userHost ?? process.env.HOST ?? "0.0.0.0";
+      if (isNaN(port) || port < 0 || port > 65535) {
+        reject(new Error(`Invalid port: ${port}. Port must be between 0 and 65535.`));
+        return;
+      }
+      const absoluteArtifactsDir = import_node_path4.default.isAbsolute(userArtifactsDir) ? userArtifactsDir : import_node_path4.default.resolve(process.cwd(), userArtifactsDir);
+      const app = (0, import_express3.default)();
+      app.use(import_express3.default.json());
+      const router = await createExpressRouter({
+        controllers,
+        artifactsDir: absoluteArtifactsDir,
+        middleware,
+        auth,
+        coerce
+      });
+      app.use(router);
+      if (enableSwagger) {
+        const displayHost = host === "0.0.0.0" ? "localhost" : host;
+        const serverUrl = `http://${displayHost}:${port}`;
+        app.use(
+          setupSwagger({
+            artifactsDir: absoluteArtifactsDir,
+            jsonPath: swaggerJsonPath,
+            uiPath: swaggerPath,
+            swaggerOptions: {
+              servers: [{ url: serverUrl }]
+            }
+          })
+        );
+      }
+      const server = app.listen(port, host, () => {
+        const displayHost = host === "0.0.0.0" ? "localhost" : host;
+        const serverUrl = `http://${displayHost}:${port}`;
+        console.log(`\u{1F680} Server running on ${serverUrl}`);
+        if (enableSwagger) {
+          console.log(`\u{1F4DA} Swagger UI: ${serverUrl}${swaggerPath}`);
+        }
+        const result = {
+          server,
+          app,
+          url: serverUrl,
+          port,
+          host,
+          close: () => new Promise((closeResolve) => {
+            server.close(() => {
+              console.log("Server closed gracefully");
+              closeResolve();
+            });
+          })
+        };
+        resolve2(result);
+      });
+      server.on("error", (error) => {
+        if (error.code === "EADDRINUSE") {
+          reject(new Error(`Port ${port} already in use. Please choose a different port.`));
+        } else if (error.code === "EACCES") {
+          reject(new Error(`Permission denied for port ${port}. Ports below 1024 require root privileges.`));
+        } else {
+          reject(new Error(`Failed to start server: ${error.message}`));
+        }
+      });
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ValidationErrorResponse,