@warlock.js/core 5.26.0 → 5.27.0

package/esm/openapi/schema-registry.mjs

@@ -0,0 +1,143 @@
+import { castToJsonSchema } from "./cast-schema.mjs";
+import { isLazy } from "@mongez/reinforcements";
+
+//#region ../core/src/openapi/schema-registry.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sanitizeName(name) {
+	return name.replace(/[^A-Za-z0-9._-]/g, "");
+}
+/**
+* Owns `components.schemas`: names resource classes (by identity), builds their schemas once
+* and hands out `$ref`s, so nested, lazy and `"self"` references recurse without unrolling.
+*/
+var SchemaRegistry = class {
+	constructor(resolveName, warn) {
+		this.resolveName = resolveName;
+		this.warn = warn;
+		this.schemas = {};
+		this.resourceNames = /* @__PURE__ */ new Map();
+		this.sharedNames = /* @__PURE__ */ new Map();
+		this.fallbackCounter = 0;
+	}
+	/**
+	* Register a fixed schema (an error shape shared by many operations) under a stable key.
+	* Returns its `$ref`; the component name gets a numeric suffix only if a resource took it.
+	*/
+	shared(key, schema) {
+		let name = this.sharedNames.get(key);
+		if (!name) {
+			name = this.claim(key);
+			this.sharedNames.set(key, name);
+			this.schemas[name] = schema;
+		}
+		return { $ref: `#/components/schemas/${name}` };
+	}
+	/**
+	* `$ref` to a resource class, building its component on first use.
+	*/
+	resourceRef(resource) {
+		const existing = this.resourceNames.get(resource);
+		if (existing) return { $ref: `#/components/schemas/${existing}` };
+		const name = this.claim(this.nameFor(resource));
+		const ref = { $ref: `#/components/schemas/${name}` };
+		this.resourceNames.set(resource, name);
+		this.schemas[name] = {};
+		this.schemas[name] = this.buildResourceSchema(resource, name, ref);
+		return ref;
+	}
+	/**
+	* Schema of a cast string, or `{}` and a warning for an unknown cast.
+	*/
+	cast(cast, path, warn = this.warn) {
+		const schema = castToJsonSchema(cast);
+		if (!schema) {
+			warn(`${path}: unknown cast "${cast}" is documented as {}.`);
+			return {};
+		}
+		return schema;
+	}
+	/**
+	* True when the function looks like a resource class: it carries a static `schema` object.
+	*/
+	isResourceClass(value) {
+		return typeof value === "function" && isRecord(Reflect.get(value, "schema"));
+	}
+	nameFor(resource) {
+		const resolved = sanitizeName(this.resolveName?.(resource) ?? "");
+		if (resolved && resolved !== "default") return resolved;
+		const className = typeof resource === "function" ? sanitizeName(resource.name) : "";
+		if (className && className !== "default") return className;
+		return `Resource${++this.fallbackCounter}`;
+	}
+	claim(base) {
+		if (!(base in this.schemas)) return base;
+		let suffix = 2;
+		while (`${base}${suffix}` in this.schemas) suffix++;
+		return `${base}${suffix}`;
+	}
+	buildResourceSchema(resource, name, ref) {
+		const schema = Reflect.get(resource, "schema");
+		if (!isRecord(schema) || Object.keys(schema).length === 0) {
+			this.warn(`Resource "${name}" declares no static schema and is documented as {}.`);
+			return {};
+		}
+		const properties = {};
+		for (const [key, config] of Object.entries(schema)) properties[key] = this.fieldSchema(config, {
+			ownerRef: ref,
+			path: `${name}.${key}`
+		});
+		return {
+			type: "object",
+			properties,
+			required: Object.keys(properties)
+		};
+	}
+	fieldSchema(config, context) {
+		if (config === "self") return context.ownerRef;
+		if (config === "self[]") return {
+			type: "array",
+			items: context.ownerRef
+		};
+		if (typeof config === "string") return this.cast(config, context.path);
+		if (isLazy(config)) return this.lazyFieldSchema(config, context);
+		if (Array.isArray(config) && config.length === 2 && typeof config[1] === "string") return this.cast(config[1], context.path);
+		if (typeof config === "function") {
+			if (this.isResourceClass(config)) return this.resourceRef(config);
+			this.warn(`${context.path}: a resolver function has no static shape and is documented as {}.`);
+			return {};
+		}
+		if (isRecord(config) && config.__type === "arrayOf" && isRecord(config.schema)) {
+			const properties = {};
+			for (const [key, item] of Object.entries(config.schema)) properties[key] = this.fieldSchema(item, {
+				...context,
+				path: `${context.path}.${key}`
+			});
+			return {
+				type: "array",
+				items: {
+					type: "object",
+					properties,
+					required: Object.keys(properties)
+				}
+			};
+		}
+		this.warn(`${context.path}: a field builder has no static shape and is documented as {}. Declare it with a cast string to document it.`);
+		return {};
+	}
+	lazyFieldSchema(lazy, context) {
+		let resolved;
+		try {
+			resolved = lazy.resolve();
+		} catch (error) {
+			this.warn(`${context.path}: a lazy resource reference could not be resolved (${error instanceof Error ? error.message : String(error)}) and is documented as {}.`);
+			return {};
+		}
+		return this.fieldSchema(resolved, context);
+	}
+};
+
+//#endregion
+export { SchemaRegistry };
+//# sourceMappingURL=schema-registry.mjs.map

package/esm/openapi/schema-registry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-registry.mjs","names":[],"sources":["../../../../../../../core/src/openapi/schema-registry.ts"],"sourcesContent":["import { isLazy } from \"@mongez/reinforcements\";\nimport { castToJsonSchema } from \"./cast-schema\";\nimport type { OpenApiSchema, WarningSink } from \"./types\";\n\ntype ResourceFieldContext = {\n  /** `$ref` schema of the resource whose field is being mapped, the target of `\"self\"`. */\n  ownerRef: OpenApiSchema;\n  /** Display name used in warnings, for example `UserResource.avatar`. */\n  path: string;\n};\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction sanitizeName(name: string): string {\n  return name.replace(/[^A-Za-z0-9._-]/g, \"\");\n}\n\n/**\n * Owns `components.schemas`: names resource classes (by identity), builds their schemas once\n * and hands out `$ref`s, so nested, lazy and `\"self\"` references recurse without unrolling.\n */\nexport class SchemaRegistry {\n  public readonly schemas: Record<string, OpenApiSchema> = {};\n\n  private readonly resourceNames = new Map<unknown, string>();\n  private readonly sharedNames = new Map<string, string>();\n  private fallbackCounter = 0;\n\n  public constructor(\n    private readonly resolveName: ((resource: unknown) => string | undefined) | undefined,\n    private readonly warn: WarningSink,\n  ) {}\n\n  /**\n   * Register a fixed schema (an error shape shared by many operations) under a stable key.\n   * Returns its `$ref`; the component name gets a numeric suffix only if a resource took it.\n   */\n  public shared(key: string, schema: OpenApiSchema): OpenApiSchema {\n    let name = this.sharedNames.get(key);\n\n    if (!name) {\n      name = this.claim(key);\n      this.sharedNames.set(key, name);\n      this.schemas[name] = schema;\n    }\n\n    return { $ref: `#/components/schemas/${name}` };\n  }\n\n  /**\n   * `$ref` to a resource class, building its component on first use.\n   */\n  public resourceRef(resource: unknown): OpenApiSchema {\n    const existing = this.resourceNames.get(resource);\n\n    if (existing) {\n      return { $ref: `#/components/schemas/${existing}` };\n    }\n\n    const name = this.claim(this.nameFor(resource));\n    const ref = { $ref: `#/components/schemas/${name}` };\n\n    // Named before its fields are mapped, so a cycle resolves to this same ref.\n    this.resourceNames.set(resource, name);\n    this.schemas[name] = {};\n    this.schemas[name] = this.buildResourceSchema(resource, name, ref);\n\n    return ref;\n  }\n\n  /**\n   * Schema of a cast string, or `{}` and a warning for an unknown cast.\n   */\n  public cast(cast: string, path: string, warn: WarningSink = this.warn): OpenApiSchema {\n    const schema = castToJsonSchema(cast);\n\n    if (!schema) {\n      warn(`${path}: unknown cast \"${cast}\" is documented as {}.`);\n\n      return {};\n    }\n\n    return schema;\n  }\n\n  /**\n   * True when the function looks like a resource class: it carries a static `schema` object.\n   */\n  public isResourceClass(value: unknown): boolean {\n    return typeof value === \"function\" && isRecord(Reflect.get(value, \"schema\"));\n  }\n\n  private nameFor(resource: unknown): string {\n    const resolved = sanitizeName(this.resolveName?.(resource) ?? \"\");\n\n    if (resolved && resolved !== \"default\") {\n      return resolved;\n    }\n\n    const className = typeof resource === \"function\" ? sanitizeName(resource.name) : \"\";\n\n    if (className && className !== \"default\") {\n      return className;\n    }\n\n    return `Resource${++this.fallbackCounter}`;\n  }\n\n  private claim(base: string): string {\n    if (!(base in this.schemas)) {\n      return base;\n    }\n\n    let suffix = 2;\n\n    while (`${base}${suffix}` in this.schemas) {\n      suffix++;\n    }\n\n    return `${base}${suffix}`;\n  }\n\n  private buildResourceSchema(resource: unknown, name: string, ref: OpenApiSchema): OpenApiSchema {\n    const schema = Reflect.get(resource as object, \"schema\");\n\n    if (!isRecord(schema) || Object.keys(schema).length === 0) {\n      this.warn(`Resource \"${name}\" declares no static schema and is documented as {}.`);\n\n      return {};\n    }\n\n    const properties: Record<string, OpenApiSchema> = {};\n\n    for (const [key, config] of Object.entries(schema)) {\n      properties[key] = this.fieldSchema(config, { ownerRef: ref, path: `${name}.${key}` });\n    }\n\n    return { type: \"object\", properties, required: Object.keys(properties) };\n  }\n\n  private fieldSchema(config: unknown, context: ResourceFieldContext): OpenApiSchema {\n    if (config === \"self\") {\n      return context.ownerRef;\n    }\n\n    if (config === \"self[]\") {\n      return { type: \"array\", items: context.ownerRef };\n    }\n\n    if (typeof config === \"string\") {\n      return this.cast(config, context.path);\n    }\n\n    if (isLazy(config)) {\n      return this.lazyFieldSchema(config, context);\n    }\n\n    if (Array.isArray(config) && config.length === 2 && typeof config[1] === \"string\") {\n      return this.cast(config[1], context.path);\n    }\n\n    if (typeof config === \"function\") {\n      if (this.isResourceClass(config)) {\n        return this.resourceRef(config);\n      }\n\n      this.warn(`${context.path}: a resolver function has no static shape and is documented as {}.`);\n\n      return {};\n    }\n\n    if (isRecord(config) && config.__type === \"arrayOf\" && isRecord(config.schema)) {\n      const properties: Record<string, OpenApiSchema> = {};\n\n      for (const [key, item] of Object.entries(config.schema)) {\n        properties[key] = this.fieldSchema(item, { ...context, path: `${context.path}.${key}` });\n      }\n\n      return {\n        type: \"array\",\n        items: { type: \"object\", properties, required: Object.keys(properties) },\n      };\n    }\n\n    this.warn(\n      `${context.path}: a field builder has no static shape and is documented as {}. Declare it with a cast string to document it.`,\n    );\n\n    return {};\n  }\n\n  private lazyFieldSchema(lazy: { resolve(): unknown }, context: ResourceFieldContext): OpenApiSchema {\n    let resolved: unknown;\n\n    try {\n      resolved = lazy.resolve();\n    } catch (error) {\n      this.warn(\n        `${context.path}: a lazy resource reference could not be resolved (${\n          error instanceof Error ? error.message : String(error)\n        }) and is documented as {}.`,\n      );\n\n      return {};\n    }\n\n    return this.fieldSchema(resolved, context);\n  }\n}\n"],"mappings":"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"}

package/esm/openapi/security.mjs

@@ -0,0 +1,98 @@
+//#region ../core/src/openapi/security.ts
+/**
+* The marker `authMiddleware()` attaches to the middleware it returns.
+* Core reads it structurally; it never imports the auth package.
+*/
+const AUTH_DESCRIPTOR_SYMBOL = Symbol.for("warlock.auth");
+function isAuthSource(value) {
+	if (value === "header") return true;
+	return typeof value === "object" && value !== null && typeof value.cookie === "string" && value.cookie.length > 0;
+}
+/**
+* Validate an auth descriptor. Returns `undefined` for anything that is not
+* `{ sources: ("header" | { cookie: string })[], userTypes?: string[] }` with at least one source.
+*/
+function parseAuthDescriptor(value) {
+	if (typeof value !== "object" || value === null) return;
+	const { sources, userTypes } = value;
+	if (!Array.isArray(sources) || sources.length === 0 || !sources.every(isAuthSource)) return;
+	if (userTypes !== void 0 && !(Array.isArray(userTypes) && userTypes.every((type) => typeof type === "string"))) return;
+	return {
+		sources: [...sources],
+		userTypes: Array.isArray(userTypes) ? [...userTypes] : []
+	};
+}
+/**
+* Combine the descriptors of every guard on a route (group middleware is already merged into
+* the route): unique sources, union of user types.
+*
+* Middleware without a descriptor is ordinary middleware and is ignored silently. A function
+* that carries a descriptor of the wrong shape is reported through `warn`.
+*
+* @returns `undefined` when the route has no valid auth descriptor.
+*/
+function readRouteAuth(middleware, warn) {
+	if (!Array.isArray(middleware)) return;
+	const sources = [];
+	const userTypes = [];
+	let found = false;
+	for (const fn of middleware) {
+		if (typeof fn !== "function") continue;
+		const raw = Reflect.get(fn, AUTH_DESCRIPTOR_SYMBOL);
+		if (raw === void 0) continue;
+		const descriptor = parseAuthDescriptor(raw);
+		if (!descriptor) {
+			warn("a middleware carries a malformed warlock.auth descriptor; the route is documented without security.");
+			continue;
+		}
+		found = true;
+		for (const source of descriptor.sources) if (!sources.some((existing) => typeof existing === "string" || typeof source === "string" ? existing === source : existing.cookie === source.cookie)) sources.push(source);
+		for (const type of descriptor.userTypes) if (!userTypes.includes(type)) userTypes.push(type);
+	}
+	return found ? {
+		sources,
+		userTypes
+	} : void 0;
+}
+/**
+* Collects the security schemes the routes actually use and turns descriptors into
+* per-operation requirements. A dual header + cookie guard is an OR: one requirement each.
+*/
+var SecuritySchemes = class {
+	constructor() {
+		this.schemes = {};
+		this.cookieSchemeNames = /* @__PURE__ */ new Map();
+	}
+	requirementsFor(descriptor) {
+		return descriptor.sources.map((source) => {
+			if (source === "header") {
+				this.schemes.bearerAuth = {
+					type: "http",
+					scheme: "bearer",
+					bearerFormat: "JWT"
+				};
+				return { bearerAuth: [] };
+			}
+			return { [this.cookieScheme(source.cookie)]: [] };
+		});
+	}
+	cookieScheme(cookie) {
+		const existing = this.cookieSchemeNames.get(cookie);
+		if (existing) return existing;
+		const name = this.cookieSchemeNames.size === 0 ? "cookieAuth" : `cookieAuth_${cookie.replace(/[^A-Za-z0-9._-]/g, "")}`;
+		this.cookieSchemeNames.set(cookie, name);
+		this.schemes[name] = {
+			type: "apiKey",
+			in: "cookie",
+			name: cookie
+		};
+		return name;
+	}
+	hasSchemes() {
+		return Object.keys(this.schemes).length > 0;
+	}
+};
+
+//#endregion
+export { SecuritySchemes, readRouteAuth };
+//# sourceMappingURL=security.mjs.map

package/esm/openapi/security.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.mjs","names":[],"sources":["../../../../../../../core/src/openapi/security.ts"],"sourcesContent":["import type { AuthDescriptor, OpenApiSecurityRequirement, OpenApiSecurityScheme, WarningSink } from \"./types\";\n\n/**\n * The marker `authMiddleware()` attaches to the middleware it returns.\n * Core reads it structurally; it never imports the auth package.\n */\nexport const AUTH_DESCRIPTOR_SYMBOL = Symbol.for(\"warlock.auth\");\n\nfunction isAuthSource(value: unknown): value is AuthDescriptor[\"sources\"][number] {\n  if (value === \"header\") {\n    return true;\n  }\n\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as { cookie?: unknown }).cookie === \"string\" &&\n    (value as { cookie: string }).cookie.length > 0\n  );\n}\n\n/**\n * Validate an auth descriptor. Returns `undefined` for anything that is not\n * `{ sources: (\"header\" | { cookie: string })[], userTypes?: string[] }` with at least one source.\n */\nexport function parseAuthDescriptor(value: unknown): AuthDescriptor | undefined {\n  if (typeof value !== \"object\" || value === null) {\n    return undefined;\n  }\n\n  const { sources, userTypes } = value as { sources?: unknown; userTypes?: unknown };\n\n  if (!Array.isArray(sources) || sources.length === 0 || !sources.every(isAuthSource)) {\n    return undefined;\n  }\n\n  if (userTypes !== undefined && !(Array.isArray(userTypes) && userTypes.every((type) => typeof type === \"string\"))) {\n    return undefined;\n  }\n\n  return { sources: [...sources], userTypes: Array.isArray(userTypes) ? [...userTypes] : [] };\n}\n\n/**\n * Combine the descriptors of every guard on a route (group middleware is already merged into\n * the route): unique sources, union of user types.\n *\n * Middleware without a descriptor is ordinary middleware and is ignored silently. A function\n * that carries a descriptor of the wrong shape is reported through `warn`.\n *\n * @returns `undefined` when the route has no valid auth descriptor.\n */\nexport function readRouteAuth(middleware: unknown, warn: WarningSink): AuthDescriptor | undefined {\n  if (!Array.isArray(middleware)) {\n    return undefined;\n  }\n\n  const sources: AuthDescriptor[\"sources\"] = [];\n  const userTypes: string[] = [];\n  let found = false;\n\n  for (const fn of middleware) {\n    if (typeof fn !== \"function\") {\n      continue;\n    }\n\n    const raw = Reflect.get(fn, AUTH_DESCRIPTOR_SYMBOL);\n\n    if (raw === undefined) {\n      continue;\n    }\n\n    const descriptor = parseAuthDescriptor(raw);\n\n    if (!descriptor) {\n      warn(\"a middleware carries a malformed warlock.auth descriptor; the route is documented without security.\");\n\n      continue;\n    }\n\n    found = true;\n\n    for (const source of descriptor.sources) {\n      const duplicate = sources.some((existing) =>\n        typeof existing === \"string\" || typeof source === \"string\"\n          ? existing === source\n          : existing.cookie === source.cookie,\n      );\n\n      if (!duplicate) {\n        sources.push(source);\n      }\n    }\n\n    for (const type of descriptor.userTypes) {\n      if (!userTypes.includes(type)) {\n        userTypes.push(type);\n      }\n    }\n  }\n\n  return found ? { sources, userTypes } : undefined;\n}\n\n/**\n * Collects the security schemes the routes actually use and turns descriptors into\n * per-operation requirements. A dual header + cookie guard is an OR: one requirement each.\n */\nexport class SecuritySchemes {\n  public readonly schemes: Record<string, OpenApiSecurityScheme> = {};\n\n  private readonly cookieSchemeNames = new Map<string, string>();\n\n  public requirementsFor(descriptor: AuthDescriptor): OpenApiSecurityRequirement[] {\n    return descriptor.sources.map((source) => {\n      if (source === \"header\") {\n        this.schemes.bearerAuth = { type: \"http\", scheme: \"bearer\", bearerFormat: \"JWT\" };\n\n        return { bearerAuth: [] };\n      }\n\n      const name = this.cookieScheme(source.cookie);\n\n      return { [name]: [] };\n    });\n  }\n\n  private cookieScheme(cookie: string): string {\n    const existing = this.cookieSchemeNames.get(cookie);\n\n    if (existing) {\n      return existing;\n    }\n\n    // The first cookie keeps the conventional name; a second, different cookie gets its own.\n    const name =\n      this.cookieSchemeNames.size === 0 ? \"cookieAuth\" : `cookieAuth_${cookie.replace(/[^A-Za-z0-9._-]/g, \"\")}`;\n\n    this.cookieSchemeNames.set(cookie, name);\n    this.schemes[name] = { type: \"apiKey\", in: \"cookie\", name: cookie };\n\n    return name;\n  }\n\n  public hasSchemes(): boolean {\n    return Object.keys(this.schemes).length > 0;\n  }\n}\n"],"mappings":";;;;;AAMA,MAAa,yBAAyB,OAAO,IAAI,cAAc;AAE/D,SAAS,aAAa,OAA4D;CAChF,IAAI,UAAU,UACZ,OAAO;CAGT,OACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAA+B,WAAW,YACjD,MAA6B,OAAO,SAAS;AAElD;;;;;AAMA,SAAgB,oBAAoB,OAA4C;CAC9E,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC;CAGF,MAAM,EAAE,SAAS,cAAc;CAE/B,IAAI,CAAC,MAAM,QAAQ,OAAO,KAAK,QAAQ,WAAW,KAAK,CAAC,QAAQ,MAAM,YAAY,GAChF;CAGF,IAAI,cAAc,UAAa,EAAE,MAAM,QAAQ,SAAS,KAAK,UAAU,OAAO,SAAS,OAAO,SAAS,QAAQ,IAC7G;CAGF,OAAO;EAAE,SAAS,CAAC,GAAG,OAAO;EAAG,WAAW,MAAM,QAAQ,SAAS,IAAI,CAAC,GAAG,SAAS,IAAI,CAAC;CAAE;AAC5F;;;;;;;;;;AAWA,SAAgB,cAAc,YAAqB,MAA+C;CAChG,IAAI,CAAC,MAAM,QAAQ,UAAU,GAC3B;CAGF,MAAM,UAAqC,CAAC;CAC5C,MAAM,YAAsB,CAAC;CAC7B,IAAI,QAAQ;CAEZ,KAAK,MAAM,MAAM,YAAY;EAC3B,IAAI,OAAO,OAAO,YAChB;EAGF,MAAM,MAAM,QAAQ,IAAI,IAAI,sBAAsB;EAElD,IAAI,QAAQ,QACV;EAGF,MAAM,aAAa,oBAAoB,GAAG;EAE1C,IAAI,CAAC,YAAY;GACf,KAAK,qGAAqG;GAE1G;EACF;EAEA,QAAQ;EAER,KAAK,MAAM,UAAU,WAAW,SAO9B,IAAI,CANc,QAAQ,MAAM,aAC9B,OAAO,aAAa,YAAY,OAAO,WAAW,WAC9C,aAAa,SACb,SAAS,WAAW,OAAO,MAGpB,GACX,QAAQ,KAAK,MAAM;EAIvB,KAAK,MAAM,QAAQ,WAAW,WAC5B,IAAI,CAAC,UAAU,SAAS,IAAI,GAC1B,UAAU,KAAK,IAAI;CAGzB;CAEA,OAAO,QAAQ;EAAE;EAAS;CAAU,IAAI;AAC1C;;;;;AAMA,IAAa,kBAAb,MAA6B;;iBACsC,CAAC;2CAE7B,IAAI,IAAoB;;CAE7D,AAAO,gBAAgB,YAA0D;EAC/E,OAAO,WAAW,QAAQ,KAAK,WAAW;GACxC,IAAI,WAAW,UAAU;IACvB,KAAK,QAAQ,aAAa;KAAE,MAAM;KAAQ,QAAQ;KAAU,cAAc;IAAM;IAEhF,OAAO,EAAE,YAAY,CAAC,EAAE;GAC1B;GAIA,OAAO,GAFM,KAAK,aAAa,OAAO,MAEzB,IAAI,CAAC,EAAE;EACtB,CAAC;CACH;CAEA,AAAQ,aAAa,QAAwB;EAC3C,MAAM,WAAW,KAAK,kBAAkB,IAAI,MAAM;EAElD,IAAI,UACF,OAAO;EAIT,MAAM,OACJ,KAAK,kBAAkB,SAAS,IAAI,eAAe,cAAc,OAAO,QAAQ,oBAAoB,EAAE;EAExG,KAAK,kBAAkB,IAAI,QAAQ,IAAI;EACvC,KAAK,QAAQ,QAAQ;GAAE,MAAM;GAAU,IAAI;GAAU,MAAM;EAAO;EAElE,OAAO;CACT;CAEA,AAAO,aAAsB;EAC3B,OAAO,OAAO,KAAK,KAAK,OAAO,CAAC,CAAC,SAAS;CAC5C;AACF"}

package/esm/openapi/types.d.mts

@@ -0,0 +1,119 @@
+import { Route } from "../router/types.mjs";
+
+//#region ../core/src/openapi/types.d.ts
+/**
+ * A JSON Schema fragment (OpenAPI 3.1 schemas are JSON Schema 2020-12).
+ */
+type OpenApiSchema = Record<string, unknown>;
+type OpenApiParameter = {
+  name: string;
+  in: "path" | "query" | "header" | "cookie";
+  required?: boolean;
+  description?: string;
+  style?: "deepObject";
+  explode?: boolean;
+  schema: OpenApiSchema;
+};
+type OpenApiRequestBody = {
+  required?: boolean;
+  content: Record<string, {
+    schema: OpenApiSchema;
+  }>;
+};
+type OpenApiResponse = {
+  description: string;
+  content?: Record<string, {
+    schema: OpenApiSchema;
+  }>;
+};
+type OpenApiSecurityRequirement = Record<string, string[]>;
+type OpenApiOperation = {
+  operationId: string;
+  summary?: string;
+  description?: string;
+  tags?: string[];
+  parameters?: OpenApiParameter[];
+  requestBody?: OpenApiRequestBody;
+  responses: Record<string, OpenApiResponse>;
+  security?: OpenApiSecurityRequirement[];
+};
+type OpenApiSecurityScheme = {
+  type: "http";
+  scheme: "bearer";
+  bearerFormat?: string;
+} | {
+  type: "apiKey";
+  in: "cookie";
+  name: string;
+};
+type OpenApiComponents = {
+  schemas?: Record<string, OpenApiSchema>;
+  securitySchemes?: Record<string, OpenApiSecurityScheme>;
+};
+type OpenApiDocument = {
+  openapi: "3.1.0";
+  jsonSchemaDialect: string;
+  info: {
+    title: string;
+    version: string;
+    description?: string;
+  };
+  servers?: {
+    url: string;
+  }[];
+  tags?: {
+    name: string;
+  }[];
+  paths: Record<string, Record<string, OpenApiOperation>>;
+  components?: OpenApiComponents;
+};
+/**
+ * The `validation.response` configuration keys that shape a failed-validation response.
+ * Every key is optional; the documented defaults apply to the missing ones.
+ */
+type OpenApiValidationResponseConfig = {
+  errors?: string;
+  inputKey?: string;
+  inputError?: string;
+  status?: number;
+};
+/**
+ * Everything the builder needs besides the routes. Plain values only, so the same call
+ * serves the CLI child and the in-process dev path.
+ */
+type OpenApiContext = {
+  info: {
+    title: string;
+    version: string;
+    description?: string;
+  }; /** Absolute server URLs, first is the default. */
+  servers?: string[]; /** Also document page (SSR) routes. Defaults to `false`. */
+  includePages?: boolean;
+  /**
+   * Name a resource class for `components.schemas`, usually its export name
+   * (`UserResource`). Return `undefined` for an unknown resource: it is named
+   * `Resource1`, `Resource2`, ... in encounter order.
+   */
+  resolveResourceName?: (resource: unknown) => string | undefined; /** The app's `validation.response` config value. */
+  validationResponse?: OpenApiValidationResponseConfig;
+};
+type OpenApiBuildResult = {
+  document: OpenApiDocument;
+  warnings: string[];
+};
+/** The slice of a route the builder reads. A full `Route` satisfies it. */
+type OpenApiRouteInput = Pick<Route, "method" | "path" | "handler"> & Partial<Pick<Route, "name" | "label" | "description" | "middleware" | "isPage" | "sourceFile">>;
+/**
+ * The descriptor `authMiddleware()` attaches under `Symbol.for("warlock.auth")`.
+ * Read structurally and validated; core never imports the auth package.
+ */
+type AuthDescriptor = {
+  sources: ("header" | {
+    cookie: string;
+  })[];
+  userTypes: string[];
+};
+type WarningSink = (message: string) => void;
+//#endregion
+export { AuthDescriptor, OpenApiBuildResult, OpenApiComponents, OpenApiContext, OpenApiDocument, OpenApiOperation, OpenApiParameter, OpenApiRequestBody, OpenApiResponse, OpenApiRouteInput, OpenApiSchema, OpenApiSecurityRequirement, OpenApiSecurityScheme, OpenApiValidationResponseConfig, WarningSink };
+//# sourceMappingURL=types.d.mts.map

package/esm/openapi/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../core/src/openapi/types.ts"],"mappings":";;;;;AAKA;KAAY,aAAA,GAAgB,MAAM;AAAA,KAEtB,gBAAA;EACV,IAAA;EACA,EAAA;EACA,QAAA;EACA,WAAA;EACA,KAAA;EACA,OAAA;EACA,MAAA,EAAQ,aAAa;AAAA;AAAA,KAGX,kBAAA;EACV,QAAA;EACA,OAAA,EAAS,MAAM;IAAW,MAAA,EAAQ,aAAA;EAAA;AAAA;AAAA,KAGxB,eAAA;EACV,WAAA;EACA,OAAA,GAAU,MAAM;IAAW,MAAA,EAAQ,aAAA;EAAA;AAAA;AAAA,KAGzB,0BAAA,GAA6B,MAAM;AAAA,KAEnC,gBAAA;EACV,WAAA;EACA,OAAA;EACA,WAAA;EACA,IAAA;EACA,UAAA,GAAa,gBAAA;EACb,WAAA,GAAc,kBAAA;EACd,SAAA,EAAW,MAAA,SAAe,eAAA;EAC1B,QAAA,GAAW,0BAAA;AAAA;AAAA,KAGD,qBAAA;EACN,IAAA;EAAc,MAAA;EAAkB,YAAA;AAAA;EAChC,IAAA;EAAgB,EAAA;EAAc,IAAA;AAAA;AAAA,KAExB,iBAAA;EACV,OAAA,GAAU,MAAA,SAAe,aAAA;EACzB,eAAA,GAAkB,MAAA,SAAe,qBAAA;AAAA;AAAA,KAGvB,eAAA;EACV,OAAA;EACA,iBAAA;EACA,IAAA;IAAQ,KAAA;IAAe,OAAA;IAAiB,WAAA;EAAA;EACxC,OAAA;IAAY,GAAA;EAAA;EACZ,IAAA;IAAS,IAAA;EAAA;EACT,KAAA,EAAO,MAAA,SAAe,MAAA,SAAe,gBAAA;EACrC,UAAA,GAAa,iBAAA;AAAA;;;;;KAOH,+BAAA;EACV,MAAA;EACA,QAAA;EACA,UAAA;EACA,MAAA;AAAA;;;;;KAOU,cAAA;EACV,IAAA;IAAQ,KAAA;IAAe,OAAA;IAAiB,WAAA;EAAA,GA/Bb;EAiC3B,OAAA,aAhCyB;EAkCzB,YAAA;EAjCiC;;;;;EAuCjC,mBAAA,IAAuB,QAAA,kCAxCE;EA0CzB,kBAAA,GAAqB,+BAA+B;AAAA;AAAA,KAG1C,kBAAA;EACV,QAAA,EAAU,eAAe;EACzB,QAAA;AAAA;;KAIU,iBAAA,GAAoB,IAAA,CAAK,KAAA,mCACnC,OAAA,CACE,IAAA,CAAK,KAAA;;;;;KAOG,cAAA;EACV,OAAA;IAAuB,MAAA;EAAA;EACvB,SAAA;AAAA;AAAA,KAGU,WAAA,IAAe,OAAe"}

package/esm/production/registration-child-runner.mjs

@@ -0,0 +1,139 @@
+import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { fork } from "node:child_process";
+
+//#region ../core/src/production/registration-child-runner.ts
+const DEFAULT_TIMEOUT_MS = 3e4;
+const MAX_DIAGNOSTIC_BYTES = 16384;
+/** Message a registration child sends when it fails. Shared by every result kind. */
+const REGISTRATION_ERROR_MESSAGE = "route-registration:error";
+/** Message a registration child sends before it imports each module. Shared by every result kind. */
+const REGISTRATION_PROGRESS_MESSAGE = "route-registration:progress";
+/**
+* Run the compiled registration child in a fresh process and wait for its result.
+*
+* This is the fork / IPC / timeout / diagnostics plumbing shared by the route snapshot and
+* the OpenAPI document: the child is forked, sent one request, and must answer with exactly
+* one result message (or an error message) and exit 0. The timeout names the module the
+* child was still importing; the last 16 KiB of child stdout/stderr are attached to failures.
+*/
+function runRegistrationChild(options) {
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const startedAt = Date.now();
+	const forkProcess = options.forkProcess ?? defaultForkProcess;
+	const entry = options.childEntry ?? (options.forkProcess ? "<injected-route-registration-child>" : resolveCompiledChildEntry());
+	return new Promise((resolve, reject) => {
+		const child = forkProcess(entry, { cwd: options.cwd });
+		let settled = false;
+		let received;
+		let stdout = "";
+		let stderr = "";
+		let pendingModule;
+		const append = (current, chunk) => {
+			const remaining = MAX_DIAGNOSTIC_BYTES - Buffer.byteLength(current);
+			return remaining <= 0 ? current : current + chunk.toString("utf8", 0, remaining);
+		};
+		const finish = (error, result) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			if (child.connected) child.disconnect?.();
+			if (error) {
+				child.kill?.();
+				reject(error);
+			} else resolve(result);
+		};
+		child.stdout?.on("data", (chunk) => {
+			stdout = append(stdout, chunk);
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr = append(stderr, chunk);
+		});
+		const timeout = setTimeout(() => {
+			const elapsedMs = Date.now() - startedAt;
+			finish(/* @__PURE__ */ new Error(`Route registration child timed out after ${elapsedMs}ms${pendingModule ? ` while registering ${pendingModule}` : ""}.${formatDiagnostics(stdout, stderr)}`));
+		}, timeoutMs);
+		timeout.unref?.();
+		child.on("error", (error) => {
+			finish(/* @__PURE__ */ new Error(`Could not start route registration child: ${error.message}${formatDiagnostics(stdout, stderr)}`));
+		});
+		child.on("message", (message) => {
+			if (!isChildMessage(message, options.resultMessageType)) return;
+			if (message.type === "route-registration:error") {
+				finish(/* @__PURE__ */ new Error(`Route registration child failed: ${String(message.message)}${formatDiagnostics(stdout, stderr)}`));
+				return;
+			}
+			if (message.type === "route-registration:progress") {
+				pendingModule = String(message.module);
+				return;
+			}
+			try {
+				const result = options.readResult(message);
+				if (received) {
+					finish(/* @__PURE__ */ new Error(`Route registration child sent more than one ${options.resultNoun}.`));
+					return;
+				}
+				received = { value: result };
+			} catch (error) {
+				finish(error);
+			}
+		});
+		child.on("close", (code) => {
+			if (settled) return;
+			if (code === 0 && received) {
+				finish(void 0, received.value);
+				return;
+			}
+			finish(/* @__PURE__ */ new Error(`Route registration child exited ${code ?? "by signal"} without a valid ${options.resultNoun}.${formatDiagnostics(stdout, stderr)}`));
+		});
+		if (!child.send) {
+			finish(/* @__PURE__ */ new Error("Route registration child did not provide an IPC send channel."));
+			return;
+		}
+		child.send(options.request);
+	});
+}
+function defaultForkProcess(entry, options) {
+	return fork(entry, [], {
+		cwd: options.cwd,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe",
+			"ipc"
+		],
+		windowsHide: true
+	});
+}
+/** Resolve from Core's package root, not an assumed bundler-preserved dirname. */
+function resolveCompiledChildEntry() {
+	let directory = path.dirname(fileURLToPath(import.meta.url));
+	while (directory !== path.dirname(directory)) {
+		const packageJson = path.join(directory, "package.json");
+		if (existsSync(packageJson)) try {
+			if (JSON.parse(readFileSync(packageJson, "utf8")).name === "@warlock.js/core") {
+				const child = path.join(directory, "esm", "production", "route-registration-child.mjs");
+				if (existsSync(child)) return child;
+				throw new Error(`@warlock.js/core is missing its compiled route-registration child at ${child}. Reinstall a complete package.`);
+			}
+		} catch (error) {
+			if (error instanceof Error && error.message.includes("route-registration child")) throw error;
+		}
+		directory = path.dirname(directory);
+	}
+	throw new Error("Could not locate @warlock.js/core package root for the route-registration child.");
+}
+function isChildMessage(value, resultMessageType) {
+	if (typeof value !== "object" || value === null || !("type" in value)) return false;
+	const type = value.type;
+	return type === resultMessageType || type === "route-registration:error" || type === "route-registration:progress";
+}
+function formatDiagnostics(stdout, stderr) {
+	if (!stdout && !stderr) return "";
+	return `\nChild stdout:\n${stdout}\nChild stderr:\n${stderr}`;
+}
+
+//#endregion
+export { runRegistrationChild };
+//# sourceMappingURL=registration-child-runner.mjs.map

package/esm/production/registration-child-runner.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration-child-runner.mjs","names":[],"sources":["../../../../../../../core/src/production/registration-child-runner.ts"],"sourcesContent":["import { fork, type ChildProcess, type Serializable } from \"node:child_process\";\nimport { existsSync, readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nconst DEFAULT_TIMEOUT_MS = 30_000;\nconst MAX_DIAGNOSTIC_BYTES = 16_384;\n\n/** Message a registration child sends when it fails. Shared by every result kind. */\nexport const REGISTRATION_ERROR_MESSAGE = \"route-registration:error\";\n\n/** Message a registration child sends before it imports each module. Shared by every result kind. */\nexport const REGISTRATION_PROGRESS_MESSAGE = \"route-registration:progress\";\n\nexport type RegistrationChildProcess = Pick<\n  ChildProcess,\n  \"send\" | \"kill\" | \"disconnect\" | \"on\" | \"stdout\" | \"stderr\" | \"connected\"\n>;\n\nexport type RegistrationChildForker = (\n  entry: string,\n  options: { cwd: string },\n) => RegistrationChildProcess;\n\nexport type RegistrationChildRunOptions<TResult> = Readonly<{\n  cwd: string;\n  timeoutMs?: number;\n  childEntry?: string;\n  /**\n   * Test seam. An injected fork is a protocol seam, not an installation check, so the\n   * compiled child is not resolved when it is set.\n   */\n  forkProcess?: RegistrationChildForker;\n  /** The single IPC request the child receives after it starts. */\n  request: Serializable;\n  /** `type` of the one message that carries the result (for example `route-registration:snapshot`). */\n  resultMessageType: string;\n  /** What the result is called in error messages (\"snapshot\", \"document\"). */\n  resultNoun: string;\n  /**\n   * Validate and freeze the result message. Throw to reject the run with that error.\n   */\n  readResult: (message: Record<string, unknown>) => TResult;\n}>;\n\n/**\n * Run the compiled registration child in a fresh process and wait for its result.\n *\n * This is the fork / IPC / timeout / diagnostics plumbing shared by the route snapshot and\n * the OpenAPI document: the child is forked, sent one request, and must answer with exactly\n * one result message (or an error message) and exit 0. The timeout names the module the\n * child was still importing; the last 16 KiB of child stdout/stderr are attached to failures.\n */\nexport function runRegistrationChild<TResult>(\n  options: RegistrationChildRunOptions<TResult>,\n): Promise<TResult> {\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const startedAt = Date.now();\n  const forkProcess = options.forkProcess ?? defaultForkProcess;\n  const entry =\n    options.childEntry ??\n    (options.forkProcess ? \"<injected-route-registration-child>\" : resolveCompiledChildEntry());\n\n  return new Promise<TResult>((resolve, reject) => {\n    const child = forkProcess(entry, { cwd: options.cwd });\n    let settled = false;\n    let received: { value: TResult } | undefined;\n    let stdout = \"\";\n    let stderr = \"\";\n    let pendingModule: string | undefined;\n\n    const append = (current: string, chunk: Buffer) => {\n      const remaining = MAX_DIAGNOSTIC_BYTES - Buffer.byteLength(current);\n\n      return remaining <= 0 ? current : current + chunk.toString(\"utf8\", 0, remaining);\n    };\n\n    const finish = (error?: Error, result?: TResult) => {\n      if (settled) {\n        return;\n      }\n\n      settled = true;\n      clearTimeout(timeout);\n\n      if (child.connected) {\n        child.disconnect?.();\n      }\n\n      if (error) {\n        child.kill?.();\n        reject(error);\n      } else {\n        resolve(result as TResult);\n      }\n    };\n\n    child.stdout?.on(\"data\", (chunk: Buffer) => {\n      stdout = append(stdout, chunk);\n    });\n    child.stderr?.on(\"data\", (chunk: Buffer) => {\n      stderr = append(stderr, chunk);\n    });\n\n    const timeout = setTimeout(() => {\n      const elapsedMs = Date.now() - startedAt;\n\n      finish(\n        new Error(\n          `Route registration child timed out after ${elapsedMs}ms${pendingModule ? ` while registering ${pendingModule}` : \"\"}.${formatDiagnostics(stdout, stderr)}`,\n        ),\n      );\n    }, timeoutMs);\n    timeout.unref?.();\n\n    child.on(\"error\", (error) => {\n      finish(\n        new Error(\n          `Could not start route registration child: ${error.message}${formatDiagnostics(stdout, stderr)}`,\n        ),\n      );\n    });\n\n    child.on(\"message\", (message: unknown) => {\n      if (!isChildMessage(message, options.resultMessageType)) {\n        return;\n      }\n\n      if (message.type === REGISTRATION_ERROR_MESSAGE) {\n        finish(\n          new Error(\n            `Route registration child failed: ${String(message.message)}${formatDiagnostics(stdout, stderr)}`,\n          ),\n        );\n\n        return;\n      }\n\n      if (message.type === REGISTRATION_PROGRESS_MESSAGE) {\n        pendingModule = String(message.module);\n\n        return;\n      }\n\n      try {\n        const result = options.readResult(message);\n\n        if (received) {\n          finish(new Error(`Route registration child sent more than one ${options.resultNoun}.`));\n\n          return;\n        }\n\n        received = { value: result };\n      } catch (error) {\n        finish(error as Error);\n      }\n    });\n\n    child.on(\"close\", (code) => {\n      if (settled) {\n        return;\n      }\n\n      if (code === 0 && received) {\n        finish(undefined, received.value);\n\n        return;\n      }\n\n      finish(\n        new Error(\n          `Route registration child exited ${code ?? \"by signal\"} without a valid ${options.resultNoun}.${formatDiagnostics(stdout, stderr)}`,\n        ),\n      );\n    });\n\n    if (!child.send) {\n      finish(new Error(\"Route registration child did not provide an IPC send channel.\"));\n\n      return;\n    }\n\n    child.send(options.request);\n  });\n}\n\nfunction defaultForkProcess(entry: string, options: { cwd: string }): RegistrationChildProcess {\n  const forkOptions: NonNullable<Parameters<typeof fork>[2]> & { windowsHide?: boolean } = {\n    cwd: options.cwd,\n    stdio: [\"ignore\", \"pipe\", \"pipe\", \"ipc\"],\n    windowsHide: true,\n  };\n\n  return fork(entry, [], forkOptions);\n}\n\n/** Resolve from Core's package root, not an assumed bundler-preserved dirname. */\nfunction resolveCompiledChildEntry(): string {\n  let directory = path.dirname(fileURLToPath(import.meta.url));\n\n  while (directory !== path.dirname(directory)) {\n    const packageJson = path.join(directory, \"package.json\");\n\n    if (existsSync(packageJson)) {\n      try {\n        if (JSON.parse(readFileSync(packageJson, \"utf8\")).name === \"@warlock.js/core\") {\n          const child = path.join(directory, \"esm\", \"production\", \"route-registration-child.mjs\");\n\n          if (existsSync(child)) {\n            return child;\n          }\n\n          throw new Error(\n            `@warlock.js/core is missing its compiled route-registration child at ${child}. Reinstall a complete package.`,\n          );\n        }\n      } catch (error) {\n        if (error instanceof Error && error.message.includes(\"route-registration child\")) {\n          throw error;\n        }\n      }\n    }\n\n    directory = path.dirname(directory);\n  }\n\n  throw new Error(\n    \"Could not locate @warlock.js/core package root for the route-registration child.\",\n  );\n}\n\nfunction isChildMessage(\n  value: unknown,\n  resultMessageType: string,\n): value is Record<string, unknown> & { type: string } {\n  if (typeof value !== \"object\" || value === null || !(\"type\" in value)) {\n    return false;\n  }\n\n  const type = (value as { type?: unknown }).type;\n\n  return (\n    type === resultMessageType ||\n    type === REGISTRATION_ERROR_MESSAGE ||\n    type === REGISTRATION_PROGRESS_MESSAGE\n  );\n}\n\nfunction formatDiagnostics(stdout: string, stderr: string): string {\n  if (!stdout && !stderr) {\n    return \"\";\n  }\n\n  return `\\nChild stdout:\\n${stdout}\\nChild stderr:\\n${stderr}`;\n}\n"],"mappings":";;;;;;AAKA,MAAM,qBAAqB;AAC3B,MAAM,uBAAuB;;AAG7B,MAAa,6BAA6B;;AAG1C,MAAa,gCAAgC;;;;;;;;;AAyC7C,SAAgB,qBACd,SACkB;CAClB,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,YAAY,KAAK,IAAI;CAC3B,MAAM,cAAc,QAAQ,eAAe;CAC3C,MAAM,QACJ,QAAQ,eACP,QAAQ,cAAc,wCAAwC,0BAA0B;CAE3F,OAAO,IAAI,SAAkB,SAAS,WAAW;EAC/C,MAAM,QAAQ,YAAY,OAAO,EAAE,KAAK,QAAQ,IAAI,CAAC;EACrD,IAAI,UAAU;EACd,IAAI;EACJ,IAAI,SAAS;EACb,IAAI,SAAS;EACb,IAAI;EAEJ,MAAM,UAAU,SAAiB,UAAkB;GACjD,MAAM,YAAY,uBAAuB,OAAO,WAAW,OAAO;GAElE,OAAO,aAAa,IAAI,UAAU,UAAU,MAAM,SAAS,QAAQ,GAAG,SAAS;EACjF;EAEA,MAAM,UAAU,OAAe,WAAqB;GAClD,IAAI,SACF;GAGF,UAAU;GACV,aAAa,OAAO;GAEpB,IAAI,MAAM,WACR,MAAM,aAAa;GAGrB,IAAI,OAAO;IACT,MAAM,OAAO;IACb,OAAO,KAAK;GACd,OACE,QAAQ,MAAiB;EAE7B;EAEA,MAAM,QAAQ,GAAG,SAAS,UAAkB;GAC1C,SAAS,OAAO,QAAQ,KAAK;EAC/B,CAAC;EACD,MAAM,QAAQ,GAAG,SAAS,UAAkB;GAC1C,SAAS,OAAO,QAAQ,KAAK;EAC/B,CAAC;EAED,MAAM,UAAU,iBAAiB;GAC/B,MAAM,YAAY,KAAK,IAAI,IAAI;GAE/B,uBACE,IAAI,MACF,4CAA4C,UAAU,IAAI,gBAAgB,sBAAsB,kBAAkB,GAAG,GAAG,kBAAkB,QAAQ,MAAM,GAC1J,CACF;EACF,GAAG,SAAS;EACZ,QAAQ,QAAQ;EAEhB,MAAM,GAAG,UAAU,UAAU;GAC3B,uBACE,IAAI,MACF,6CAA6C,MAAM,UAAU,kBAAkB,QAAQ,MAAM,GAC/F,CACF;EACF,CAAC;EAED,MAAM,GAAG,YAAY,YAAqB;GACxC,IAAI,CAAC,eAAe,SAAS,QAAQ,iBAAiB,GACpD;GAGF,IAAI,QAAQ,qCAAqC;IAC/C,uBACE,IAAI,MACF,oCAAoC,OAAO,QAAQ,OAAO,IAAI,kBAAkB,QAAQ,MAAM,GAChG,CACF;IAEA;GACF;GAEA,IAAI,QAAQ,wCAAwC;IAClD,gBAAgB,OAAO,QAAQ,MAAM;IAErC;GACF;GAEA,IAAI;IACF,MAAM,SAAS,QAAQ,WAAW,OAAO;IAEzC,IAAI,UAAU;KACZ,uBAAO,IAAI,MAAM,+CAA+C,QAAQ,WAAW,EAAE,CAAC;KAEtF;IACF;IAEA,WAAW,EAAE,OAAO,OAAO;GAC7B,SAAS,OAAO;IACd,OAAO,KAAc;GACvB;EACF,CAAC;EAED,MAAM,GAAG,UAAU,SAAS;GAC1B,IAAI,SACF;GAGF,IAAI,SAAS,KAAK,UAAU;IAC1B,OAAO,QAAW,SAAS,KAAK;IAEhC;GACF;GAEA,uBACE,IAAI,MACF,mCAAmC,QAAQ,YAAY,mBAAmB,QAAQ,WAAW,GAAG,kBAAkB,QAAQ,MAAM,GAClI,CACF;EACF,CAAC;EAED,IAAI,CAAC,MAAM,MAAM;GACf,uBAAO,IAAI,MAAM,+DAA+D,CAAC;GAEjF;EACF;EAEA,MAAM,KAAK,QAAQ,OAAO;CAC5B,CAAC;AACH;AAEA,SAAS,mBAAmB,OAAe,SAAoD;CAO7F,OAAO,KAAK,OAAO,CAAC,GAAG;EALrB,KAAK,QAAQ;EACb,OAAO;GAAC;GAAU;GAAQ;GAAQ;EAAK;EACvC,aAAa;CAGkB,CAAC;AACpC;;AAGA,SAAS,4BAAoC;CAC3C,IAAI,YAAY,KAAK,QAAQ,cAAc,OAAO,KAAK,GAAG,CAAC;CAE3D,OAAO,cAAc,KAAK,QAAQ,SAAS,GAAG;EAC5C,MAAM,cAAc,KAAK,KAAK,WAAW,cAAc;EAEvD,IAAI,WAAW,WAAW,GACxB,IAAI;GACF,IAAI,KAAK,MAAM,aAAa,aAAa,MAAM,CAAC,CAAC,CAAC,SAAS,oBAAoB;IAC7E,MAAM,QAAQ,KAAK,KAAK,WAAW,OAAO,cAAc,8BAA8B;IAEtF,IAAI,WAAW,KAAK,GAClB,OAAO;IAGT,MAAM,IAAI,MACR,wEAAwE,MAAM,gCAChF;GACF;EACF,SAAS,OAAO;GACd,IAAI,iBAAiB,SAAS,MAAM,QAAQ,SAAS,0BAA0B,GAC7E,MAAM;EAEV;EAGF,YAAY,KAAK,QAAQ,SAAS;CACpC;CAEA,MAAM,IAAI,MACR,kFACF;AACF;AAEA,SAAS,eACP,OACA,mBACqD;CACrD,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,EAAE,UAAU,QAC7D,OAAO;CAGT,MAAM,OAAQ,MAA6B;CAE3C,OACE,SAAS,qBACT,uCACA;AAEJ;AAEA,SAAS,kBAAkB,QAAgB,QAAwB;CACjE,IAAI,CAAC,UAAU,CAAC,QACd,OAAO;CAGT,OAAO,oBAAoB,OAAO,mBAAmB;AACvD"}

package/esm/production/route-registration-child.mjs

@@ -1,12 +1,14 @@
 import { appPath } from "../utils/paths.mjs";
 import { Application } from "../application/application.mjs";
-import { router } from "../router/router.mjs";
 import "../application/index.mjs";
 import { loadEnvironmentFiles } from "../utils/load-environment.mjs";
 import { bootstrap } from "../bootstrap.mjs";
 import { warlockConfigManager } from "../warlock-config/warlock-config.manager.mjs";
 import { filesOrchestrator } from "../dev-server/files-orchestrator.mjs";
 import { loadConfigFiles } from "../config/load-config-files.mjs";
+import { collectNamedApiRoutesWithResponses } from "../router/named-api-routes-with-responses.mjs";
+import { OPENAPI_RESULT_MESSAGE, parseOpenApiChildOptions } from "../openapi/openapi-protocol.mjs";
+import { buildOpenApiForChild } from "../openapi/openapi-child-output.mjs";
 import { fileExistsAsync } from "@warlock.js/fs";
 
 //#region ../core/src/production/route-registration-child.ts
@@ -30,11 +32,35 @@ process.once("message", async (message) => {
 			await filesOrchestrator.moduleLoader.loadModule(file, "model");
 		}
 		await filesOrchestrator.moduleLoader.loadAll({ onBeforeLoad: (file) => sendProgress(file.relativePath) });
+		if (request.openapi) {
+			const { document, warnings } = await buildOpenApiForChild({
+				cwd: request.cwd,
+				files: filesOrchestrator.files.values(),
+				request: request.openapi,
+				onWarn: (warning) => {
+					process.stderr.write(`[warlock] ${warning}\n`);
+				}
+			});
+			await sendAndExit({
+				type: OPENAPI_RESULT_MESSAGE,
+				result: {
+					version: 1,
+					document,
+					warnings
+				}
+			});
+		}
 		await sendAndExit({
 			type: "route-registration:snapshot",
 			snapshot: {
 				version: PROTOCOL_VERSION,
-				routes: router.getNamedApiRoutes()
+				routes: await collectNamedApiRoutesWithResponses({
+					appRoot: request.cwd,
+					files: filesOrchestrator.files.values(),
+					onWarn: (warning) => {
+						process.stderr.write(`[warlock] ${warning}\n`);
+					}
+				})
 			}
 		});
 	} catch (error) {
@@ -46,6 +72,8 @@ process.once("message", async (message) => {
 });
 function validateRequest(value) {
 	if (typeof value !== "object" || value === null || value.version !== PROTOCOL_VERSION || typeof value.cwd !== "string" || !isOptionalEnvironment(value.environment) || !isOptionalRuntimeStrategy(value.runtimeStrategy)) throw new Error("Route registration child received an invalid protocol request.");
+	const openapi = value.openapi;
+	if (openapi !== void 0) parseOpenApiChildOptions(openapi);
 	return value;
 }
 function isOptionalEnvironment(value) {