@warlock.js/core 5.26.0 → 5.28.0

package/esm/openapi/build-openapi-document.d.mts

@@ -0,0 +1,17 @@
+import { OpenApiBuildResult, OpenApiContext, OpenApiRouteInput } from "./types.mjs";
+
+//#region ../core/src/openapi/build-openapi-document.d.ts
+/** `jsonSchemaDialect` of every document: OpenAPI 3.1 schemas are JSON Schema 2020-12. */
+declare const OPENAPI_JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+/**
+ * Build an OpenAPI 3.1 document from registered routes.
+ *
+ * Pure: it reads the routes it is given (`router.list()` in the app), converts Seal schemas
+ * with `toJsonSchema("draft-2020-12")` and returns plain JSON plus the gaps it found as
+ * `warnings`. It never throws for a single route it cannot document; that route is
+ * documented as far as possible and a warning explains what was left out.
+ */
+declare function buildOpenApiDocument(routes: readonly OpenApiRouteInput[], context: OpenApiContext): OpenApiBuildResult;
+//#endregion
+export { OPENAPI_JSON_SCHEMA_DIALECT, buildOpenApiDocument };
+//# sourceMappingURL=build-openapi-document.d.mts.map

package/esm/openapi/build-openapi-document.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-openapi-document.d.mts","names":[],"sources":["../../../../../../../core/src/openapi/build-openapi-document.ts"],"mappings":";;;;cA2Ba,2BAAA;AAAb;;;;AAAwC;AA8BxC;;;AA9BA,iBA8BgB,oBAAA,CACd,MAAA,WAAiB,iBAAA,IACjB,OAAA,EAAS,cAAA,GACR,kBAAA"}

package/esm/openapi/build-openapi-document.mjs

@@ -0,0 +1,124 @@
+import { buildDeclaredResponses } from "./response-schemas.mjs";
+import { buildUnauthorizedResponse, buildValidationFailedResponse, resolveValidationResponse } from "./error-responses.mjs";
+import { buildOperationId, expandMethods, firstSegmentTag, toOpenApiPath } from "./paths.mjs";
+import { buildRequestParts } from "./request-schemas.mjs";
+import { SchemaRegistry } from "./schema-registry.mjs";
+import { SecuritySchemes, readRouteAuth } from "./security.mjs";
+
+//#region ../core/src/openapi/build-openapi-document.ts
+/** `jsonSchemaDialect` of every document: OpenAPI 3.1 schemas are JSON Schema 2020-12. */
+const OPENAPI_JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+const UNSAFE_METHODS = [
+	"post",
+	"put",
+	"patch",
+	"delete"
+];
+function describeAuth(auth, method) {
+	const lines = [];
+	if (auth.userTypes.length > 0) lines.push(`Requires an authenticated user of type: ${auth.userTypes.join(", ")}.`);
+	if (auth.sources.some((source) => typeof source !== "string") && UNSAFE_METHODS.includes(method)) lines.push("When authenticating with the cookie, the request must also carry a same-origin Origin or Referer header (CSRF guard).");
+	return lines;
+}
+/**
+* Build an OpenAPI 3.1 document from registered routes.
+*
+* Pure: it reads the routes it is given (`router.list()` in the app), converts Seal schemas
+* with `toJsonSchema("draft-2020-12")` and returns plain JSON plus the gaps it found as
+* `warnings`. It never throws for a single route it cannot document; that route is
+* documented as far as possible and a warning explains what was left out.
+*/
+function buildOpenApiDocument(routes, context) {
+	const warnings = [];
+	const registry = new SchemaRegistry(context.resolveResourceName, (message) => warnings.push(message));
+	const security = new SecuritySchemes();
+	const validationShape = resolveValidationResponse(context.validationResponse);
+	const paths = {};
+	const tags = /* @__PURE__ */ new Set();
+	const operationIds = /* @__PURE__ */ new Set();
+	for (const route of routes) {
+		if (route.isPage && !context.includePages) continue;
+		const methods = expandMethods(route.method);
+		const label = `${String(route.method).toUpperCase()} ${route.path}`;
+		const warn = (message) => warnings.push(`${label}: ${message}`);
+		if (methods.length === 0) {
+			warn(`unsupported method "${String(route.method)}", route skipped.`);
+			continue;
+		}
+		const handler = route.handler;
+		const validation = handler?.validation;
+		const auth = readRouteAuth(route.middleware, warn);
+		const tag = firstSegmentTag(route.path);
+		const pathKey = toOpenApiPath(route.path);
+		if (validation?.validate) warn("validation.validate is custom middleware and is not documented.");
+		for (const method of methods) {
+			paths[pathKey] ??= {};
+			if (paths[pathKey][method]) {
+				warn(`${method.toUpperCase()} ${pathKey} is already documented by an earlier route; this one is skipped.`);
+				continue;
+			}
+			let operationId = buildOperationId(route.name, method, route.path, methods.length > 1);
+			if (operationIds.has(operationId)) {
+				let suffix = 2;
+				while (operationIds.has(`${operationId}_${suffix}`)) suffix++;
+				warn(`operationId "${operationId}" is already used; renamed to "${operationId}_${suffix}".`);
+				operationId = `${operationId}_${suffix}`;
+			}
+			operationIds.add(operationId);
+			const description = [route.description ?? handler?.description, ...auth ? describeAuth(auth, method) : []].filter((line) => typeof line === "string" && line.length > 0);
+			const request = buildRequestParts({
+				method,
+				path: route.path,
+				validation,
+				warn
+			});
+			const responses = route.isPage ? { "200": {
+				description: "HTML page",
+				content: { "text/html": { schema: { type: "string" } } }
+			} } : buildDeclaredResponses(handler?.responseSchema, registry, warn);
+			if (!Object.keys(responses).some((status) => status.startsWith("2"))) responses["200"] = { description: "Successful response" };
+			if (validation?.schema) {
+				const failed = buildValidationFailedResponse(validationShape, registry);
+				responses[failed.status] ??= failed.response;
+			}
+			if (auth) responses["401"] ??= buildUnauthorizedResponse(registry);
+			if (tag) tags.add(tag);
+			const operation = {
+				operationId,
+				...route.label ? { summary: route.label } : {},
+				...description.length > 0 ? { description: description.join("\n\n") } : {},
+				...tag ? { tags: [tag] } : {},
+				...request.parameters.length > 0 ? { parameters: request.parameters } : {},
+				...request.requestBody ? { requestBody: request.requestBody } : {},
+				responses: sortResponses(responses),
+				...auth ? { security: security.requirementsFor(auth) } : {}
+			};
+			paths[pathKey][method] = operation;
+		}
+	}
+	const document = {
+		openapi: "3.1.0",
+		jsonSchemaDialect: OPENAPI_JSON_SCHEMA_DIALECT,
+		info: { ...context.info },
+		...context.servers && context.servers.length > 0 ? { servers: context.servers.map((url) => ({ url })) } : {},
+		...tags.size > 0 ? { tags: [...tags].sort().map((name) => ({ name })) } : {},
+		paths
+	};
+	const hasSchemas = Object.keys(registry.schemas).length > 0;
+	if (hasSchemas || security.hasSchemes()) {
+		document.components = {};
+		if (hasSchemas) document.components.schemas = registry.schemas;
+		if (security.hasSchemes()) document.components.securitySchemes = security.schemes;
+	}
+	return {
+		document,
+		warnings: [...new Set(warnings)]
+	};
+}
+function sortResponses(responses) {
+	return Object.fromEntries(Object.entries(responses).sort(([first], [second]) => first.localeCompare(second)));
+}
+
+//#endregion
+export { OPENAPI_JSON_SCHEMA_DIALECT, buildOpenApiDocument };
+//# sourceMappingURL=build-openapi-document.mjs.map

package/esm/openapi/build-openapi-document.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-openapi-document.mjs","names":[],"sources":["../../../../../../../core/src/openapi/build-openapi-document.ts"],"sourcesContent":["import {\n  buildUnauthorizedResponse,\n  buildValidationFailedResponse,\n  resolveValidationResponse,\n} from \"./error-responses\";\nimport {\n  buildOperationId,\n  expandMethods,\n  firstSegmentTag,\n  toOpenApiPath,\n  type OpenApiMethod,\n} from \"./paths\";\nimport { buildRequestParts } from \"./request-schemas\";\nimport { buildDeclaredResponses } from \"./response-schemas\";\nimport { SchemaRegistry } from \"./schema-registry\";\nimport { readRouteAuth, SecuritySchemes } from \"./security\";\nimport type {\n  AuthDescriptor,\n  OpenApiBuildResult,\n  OpenApiContext,\n  OpenApiDocument,\n  OpenApiOperation,\n  OpenApiResponse,\n  OpenApiRouteInput,\n} from \"./types\";\n\n/** `jsonSchemaDialect` of every document: OpenAPI 3.1 schemas are JSON Schema 2020-12. */\nexport const OPENAPI_JSON_SCHEMA_DIALECT = \"https://json-schema.org/draft/2020-12/schema\";\n\nconst UNSAFE_METHODS: readonly OpenApiMethod[] = [\"post\", \"put\", \"patch\", \"delete\"];\n\nfunction describeAuth(auth: AuthDescriptor, method: OpenApiMethod): string[] {\n  const lines: string[] = [];\n\n  if (auth.userTypes.length > 0) {\n    lines.push(`Requires an authenticated user of type: ${auth.userTypes.join(\", \")}.`);\n  }\n\n  const usesCookie = auth.sources.some((source) => typeof source !== \"string\");\n\n  if (usesCookie && UNSAFE_METHODS.includes(method)) {\n    lines.push(\n      \"When authenticating with the cookie, the request must also carry a same-origin Origin or Referer header (CSRF guard).\",\n    );\n  }\n\n  return lines;\n}\n\n/**\n * Build an OpenAPI 3.1 document from registered routes.\n *\n * Pure: it reads the routes it is given (`router.list()` in the app), converts Seal schemas\n * with `toJsonSchema(\"draft-2020-12\")` and returns plain JSON plus the gaps it found as\n * `warnings`. It never throws for a single route it cannot document; that route is\n * documented as far as possible and a warning explains what was left out.\n */\nexport function buildOpenApiDocument(\n  routes: readonly OpenApiRouteInput[],\n  context: OpenApiContext,\n): OpenApiBuildResult {\n  const warnings: string[] = [];\n  const registry = new SchemaRegistry(context.resolveResourceName, (message) => warnings.push(message));\n  const security = new SecuritySchemes();\n  const validationShape = resolveValidationResponse(context.validationResponse);\n  const paths: OpenApiDocument[\"paths\"] = {};\n  const tags = new Set<string>();\n  const operationIds = new Set<string>();\n\n  for (const route of routes) {\n    if (route.isPage && !context.includePages) {\n      continue;\n    }\n\n    const methods = expandMethods(route.method);\n    const label = `${String(route.method).toUpperCase()} ${route.path}`;\n    const warn = (message: string) => warnings.push(`${label}: ${message}`);\n\n    if (methods.length === 0) {\n      warn(`unsupported method \"${String(route.method)}\", route skipped.`);\n\n      continue;\n    }\n\n    const handler = route.handler as OpenApiRouteInput[\"handler\"] | undefined;\n    const validation = handler?.validation;\n    const auth = readRouteAuth(route.middleware, warn);\n    const tag = firstSegmentTag(route.path);\n    const pathKey = toOpenApiPath(route.path);\n\n    if (validation?.validate) {\n      warn(\"validation.validate is custom middleware and is not documented.\");\n    }\n\n    for (const method of methods) {\n      paths[pathKey] ??= {};\n\n      if (paths[pathKey][method]) {\n        warn(`${method.toUpperCase()} ${pathKey} is already documented by an earlier route; this one is skipped.`);\n\n        continue;\n      }\n\n      let operationId = buildOperationId(route.name, method, route.path, methods.length > 1);\n\n      if (operationIds.has(operationId)) {\n        let suffix = 2;\n\n        while (operationIds.has(`${operationId}_${suffix}`)) {\n          suffix++;\n        }\n\n        warn(`operationId \"${operationId}\" is already used; renamed to \"${operationId}_${suffix}\".`);\n        operationId = `${operationId}_${suffix}`;\n      }\n\n      operationIds.add(operationId);\n\n      const description = [\n        route.description ?? handler?.description,\n        ...(auth ? describeAuth(auth, method) : []),\n      ].filter((line): line is string => typeof line === \"string\" && line.length > 0);\n\n      const request = buildRequestParts({ method, path: route.path, validation, warn });\n\n      const responses: Record<string, OpenApiResponse> = route.isPage\n        ? { \"200\": { description: \"HTML page\", content: { \"text/html\": { schema: { type: \"string\" } } } } }\n        : buildDeclaredResponses(handler?.responseSchema, registry, warn);\n\n      if (!Object.keys(responses).some((status) => status.startsWith(\"2\"))) {\n        responses[\"200\"] = { description: \"Successful response\" };\n      }\n\n      if (validation?.schema) {\n        const failed = buildValidationFailedResponse(validationShape, registry);\n\n        responses[failed.status] ??= failed.response;\n      }\n\n      if (auth) {\n        responses[\"401\"] ??= buildUnauthorizedResponse(registry);\n      }\n\n      if (tag) {\n        tags.add(tag);\n      }\n\n      // Built in reading order: identity, prose, inputs, outputs, security.\n      const operation: OpenApiOperation = {\n        operationId,\n        ...(route.label ? { summary: route.label } : {}),\n        ...(description.length > 0 ? { description: description.join(\"\\n\\n\") } : {}),\n        ...(tag ? { tags: [tag] } : {}),\n        ...(request.parameters.length > 0 ? { parameters: request.parameters } : {}),\n        ...(request.requestBody ? { requestBody: request.requestBody } : {}),\n        responses: sortResponses(responses),\n        ...(auth ? { security: security.requirementsFor(auth) } : {}),\n      };\n\n      paths[pathKey][method] = operation;\n    }\n  }\n\n  // Keys in reading order: header, servers, tags, paths, components.\n  const document: OpenApiDocument = {\n    openapi: \"3.1.0\",\n    jsonSchemaDialect: OPENAPI_JSON_SCHEMA_DIALECT,\n    info: { ...context.info },\n    ...(context.servers && context.servers.length > 0\n      ? { servers: context.servers.map((url) => ({ url })) }\n      : {}),\n    ...(tags.size > 0 ? { tags: [...tags].sort().map((name) => ({ name })) } : {}),\n    paths,\n  };\n\n  const hasSchemas = Object.keys(registry.schemas).length > 0;\n\n  if (hasSchemas || security.hasSchemes()) {\n    document.components = {};\n\n    if (hasSchemas) {\n      document.components.schemas = registry.schemas;\n    }\n\n    if (security.hasSchemes()) {\n      document.components.securitySchemes = security.schemes;\n    }\n  }\n\n  return { document, warnings: [...new Set(warnings)] };\n}\n\nfunction sortResponses(responses: Record<string, OpenApiResponse>): Record<string, OpenApiResponse> {\n  return Object.fromEntries(\n    Object.entries(responses).sort(([first], [second]) => first.localeCompare(second)),\n  );\n}\n"],"mappings":"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"}

package/esm/openapi/cast-schema.mjs

@@ -0,0 +1,89 @@
+//#region ../core/src/openapi/cast-schema.ts
+/**
+* JSON Schema of the DEFAULT date output of a resource field (`iso`, `format`, `timestamp`
+* and `humanTime` on; `timezone`, `locale` and `offset` off), matching `BaseCastOutput<"date">`.
+*/
+const DEFAULT_DATE_SCHEMA = {
+	type: "object",
+	properties: {
+		iso: {
+			type: "string",
+			format: "date-time"
+		},
+		format: { type: "string" },
+		timestamp: { type: "number" },
+		humanTime: { type: "string" }
+	},
+	required: [
+		"iso",
+		"format",
+		"timestamp",
+		"humanTime"
+	]
+};
+function baseCastSchema(base) {
+	switch (base) {
+		case "string":
+		case "localized": return { type: "string" };
+		case "url":
+		case "uploadsUrl":
+		case "storageUrl": return {
+			type: "string",
+			format: "uri"
+		};
+		case "number":
+		case "float": return { type: "number" };
+		case "int": return { type: "integer" };
+		case "boolean": return { type: "boolean" };
+		case "object": return { type: "object" };
+		case "array": return { type: "array" };
+		case "date": return structuredClone(DEFAULT_DATE_SCHEMA);
+		default: return;
+	}
+}
+/**
+* Make a schema accept `null` too, the 3.1 way: `type: [T, "null"]`. A schema without a plain
+* `type` (a `$ref`, `{}`) is wrapped in `anyOf` with `{ type: "null" }`.
+*/
+function makeNullable(schema) {
+	if (typeof schema.type === "string") return {
+		...schema,
+		type: [schema.type, "null"]
+	};
+	if (Array.isArray(schema.type)) return schema.type.includes("null") ? schema : {
+		...schema,
+		type: [...schema.type, "null"]
+	};
+	return { anyOf: [schema, { type: "null" }] };
+}
+/**
+* JSON Schema of a resource cast string, suffixes included (`"string"`, `"number?"`,
+* `"string[]"`, `"date[]?"`). `?` means "always present, value or null"; `[]` wraps the base
+* in an array, and with `?` it is the array that may be null.
+*
+* @returns `undefined` for a cast this mapper does not know.
+*/
+function castToJsonSchema(cast) {
+	let base = cast;
+	let nullable = false;
+	let isArray = false;
+	if (base.endsWith("?")) {
+		nullable = true;
+		base = base.slice(0, -1);
+	}
+	if (base.endsWith("[]")) {
+		isArray = true;
+		base = base.slice(0, -2);
+	}
+	const baseSchema = baseCastSchema(base);
+	if (!baseSchema) return;
+	const shaped = isArray ? {
+		type: "array",
+		items: baseSchema
+	} : baseSchema;
+	return nullable ? makeNullable(shaped) : shaped;
+}
+
+//#endregion
+export { castToJsonSchema };
+//# sourceMappingURL=cast-schema.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cast-schema.mjs","names":[],"sources":["../../../../../../../core/src/openapi/cast-schema.ts"],"sourcesContent":["import type { OpenApiSchema } from \"./types\";\n\n/**\n * JSON Schema of the DEFAULT date output of a resource field (`iso`, `format`, `timestamp`\n * and `humanTime` on; `timezone`, `locale` and `offset` off), matching `BaseCastOutput<\"date\">`.\n */\nconst DEFAULT_DATE_SCHEMA: OpenApiSchema = {\n  type: \"object\",\n  properties: {\n    iso: { type: \"string\", format: \"date-time\" },\n    format: { type: \"string\" },\n    timestamp: { type: \"number\" },\n    humanTime: { type: \"string\" },\n  },\n  required: [\"iso\", \"format\", \"timestamp\", \"humanTime\"],\n};\n\nfunction baseCastSchema(base: string): OpenApiSchema | undefined {\n  switch (base) {\n    case \"string\":\n    case \"localized\":\n      return { type: \"string\" };\n    case \"url\":\n    case \"uploadsUrl\":\n    case \"storageUrl\":\n      return { type: \"string\", format: \"uri\" };\n    case \"number\":\n    case \"float\":\n      return { type: \"number\" };\n    case \"int\":\n      return { type: \"integer\" };\n    case \"boolean\":\n      return { type: \"boolean\" };\n    case \"object\":\n      return { type: \"object\" };\n    case \"array\":\n      return { type: \"array\" };\n    case \"date\":\n      return structuredClone(DEFAULT_DATE_SCHEMA);\n    default:\n      return undefined;\n  }\n}\n\n/**\n * Make a schema accept `null` too, the 3.1 way: `type: [T, \"null\"]`. A schema without a plain\n * `type` (a `$ref`, `{}`) is wrapped in `anyOf` with `{ type: \"null\" }`.\n */\nexport function makeNullable(schema: OpenApiSchema): OpenApiSchema {\n  if (typeof schema.type === \"string\") {\n    return { ...schema, type: [schema.type, \"null\"] };\n  }\n\n  if (Array.isArray(schema.type)) {\n    return schema.type.includes(\"null\") ? schema : { ...schema, type: [...schema.type, \"null\"] };\n  }\n\n  return { anyOf: [schema, { type: \"null\" }] };\n}\n\n/**\n * JSON Schema of a resource cast string, suffixes included (`\"string\"`, `\"number?\"`,\n * `\"string[]\"`, `\"date[]?\"`). `?` means \"always present, value or null\"; `[]` wraps the base\n * in an array, and with `?` it is the array that may be null.\n *\n * @returns `undefined` for a cast this mapper does not know.\n */\nexport function castToJsonSchema(cast: string): OpenApiSchema | undefined {\n  let base = cast;\n  let nullable = false;\n  let isArray = false;\n\n  if (base.endsWith(\"?\")) {\n    nullable = true;\n    base = base.slice(0, -1);\n  }\n\n  if (base.endsWith(\"[]\")) {\n    isArray = true;\n    base = base.slice(0, -2);\n  }\n\n  const baseSchema = baseCastSchema(base);\n\n  if (!baseSchema) {\n    return undefined;\n  }\n\n  const shaped: OpenApiSchema = isArray ? { type: \"array\", items: baseSchema } : baseSchema;\n\n  return nullable ? makeNullable(shaped) : shaped;\n}\n"],"mappings":";;;;;AAMA,MAAM,sBAAqC;CACzC,MAAM;CACN,YAAY;EACV,KAAK;GAAE,MAAM;GAAU,QAAQ;EAAY;EAC3C,QAAQ,EAAE,MAAM,SAAS;EACzB,WAAW,EAAE,MAAM,SAAS;EAC5B,WAAW,EAAE,MAAM,SAAS;CAC9B;CACA,UAAU;EAAC;EAAO;EAAU;EAAa;CAAW;AACtD;AAEA,SAAS,eAAe,MAAyC;CAC/D,QAAQ,MAAR;EACE,KAAK;EACL,KAAK,aACH,OAAO,EAAE,MAAM,SAAS;EAC1B,KAAK;EACL,KAAK;EACL,KAAK,cACH,OAAO;GAAE,MAAM;GAAU,QAAQ;EAAM;EACzC,KAAK;EACL,KAAK,SACH,OAAO,EAAE,MAAM,SAAS;EAC1B,KAAK,OACH,OAAO,EAAE,MAAM,UAAU;EAC3B,KAAK,WACH,OAAO,EAAE,MAAM,UAAU;EAC3B,KAAK,UACH,OAAO,EAAE,MAAM,SAAS;EAC1B,KAAK,SACH,OAAO,EAAE,MAAM,QAAQ;EACzB,KAAK,QACH,OAAO,gBAAgB,mBAAmB;EAC5C,SACE;CACJ;AACF;;;;;AAMA,SAAgB,aAAa,QAAsC;CACjE,IAAI,OAAO,OAAO,SAAS,UACzB,OAAO;EAAE,GAAG;EAAQ,MAAM,CAAC,OAAO,MAAM,MAAM;CAAE;CAGlD,IAAI,MAAM,QAAQ,OAAO,IAAI,GAC3B,OAAO,OAAO,KAAK,SAAS,MAAM,IAAI,SAAS;EAAE,GAAG;EAAQ,MAAM,CAAC,GAAG,OAAO,MAAM,MAAM;CAAE;CAG7F,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,EAAE;AAC7C;;;;;;;;AASA,SAAgB,iBAAiB,MAAyC;CACxE,IAAI,OAAO;CACX,IAAI,WAAW;CACf,IAAI,UAAU;CAEd,IAAI,KAAK,SAAS,GAAG,GAAG;EACtB,WAAW;EACX,OAAO,KAAK,MAAM,GAAG,EAAE;CACzB;CAEA,IAAI,KAAK,SAAS,IAAI,GAAG;EACvB,UAAU;EACV,OAAO,KAAK,MAAM,GAAG,EAAE;CACzB;CAEA,MAAM,aAAa,eAAe,IAAI;CAEtC,IAAI,CAAC,YACH;CAGF,MAAM,SAAwB,UAAU;EAAE,MAAM;EAAS,OAAO;CAAW,IAAI;CAE/E,OAAO,WAAW,aAAa,MAAM,IAAI;AAC3C"}

package/esm/openapi/collect-openapi-document.mjs

@@ -0,0 +1,40 @@
+import { runRegistrationChild } from "../production/registration-child-runner.mjs";
+import { OPENAPI_RESULT_MESSAGE, parseOpenApiChildResult } from "./openapi-protocol.mjs";
+
+//#region ../core/src/openapi/collect-openapi-document.ts
+/**
+* Build the app's OpenAPI document in a fresh process.
+*
+* Uses the same registration child as `warlock build` (it imports the route modules without
+* booting connectors) in OpenAPI mode: the document is built inside the child, where the Seal
+* schemas and resource classes live, and only the finished JSON crosses IPC.
+*/
+function collectOpenApiDocument(options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	const openapi = {
+		version: 1,
+		...options.title !== void 0 ? { title: options.title } : {},
+		...options.server !== void 0 ? { server: options.server } : {},
+		...options.includePages !== void 0 ? { includePages: options.includePages } : {}
+	};
+	return runRegistrationChild({
+		cwd,
+		timeoutMs: options.timeoutMs,
+		childEntry: options.childEntry,
+		forkProcess: options.forkProcess,
+		request: {
+			version: 1,
+			cwd,
+			environment: options.environment,
+			runtimeStrategy: options.runtimeStrategy,
+			openapi
+		},
+		resultMessageType: OPENAPI_RESULT_MESSAGE,
+		resultNoun: "document",
+		readResult: (message) => parseOpenApiChildResult(message.result)
+	});
+}
+
+//#endregion
+export { collectOpenApiDocument };
+//# sourceMappingURL=collect-openapi-document.mjs.map

package/esm/openapi/collect-openapi-document.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-openapi-document.mjs","names":[],"sources":["../../../../../../../core/src/openapi/collect-openapi-document.ts"],"sourcesContent":["import {\n  runRegistrationChild,\n  type RegistrationChildForker,\n} from \"../production/registration-child-runner\";\nimport type { Environment, RuntimeStrategy } from \"../utils/environment\";\nimport {\n  OPENAPI_PROTOCOL_VERSION,\n  OPENAPI_RESULT_MESSAGE,\n  parseOpenApiChildResult,\n  type OpenApiChildRequestOptions,\n  type OpenApiChildResult,\n} from \"./openapi-protocol\";\n\nexport type CollectOpenApiDocumentOptions = Readonly<{\n  cwd?: string;\n  environment?: Environment;\n  runtimeStrategy?: RuntimeStrategy;\n  timeoutMs?: number;\n  childEntry?: string;\n  forkProcess?: RegistrationChildForker;\n  title?: string;\n  server?: string;\n  includePages?: boolean;\n}>;\n\n/**\n * Build the app's OpenAPI document in a fresh process.\n *\n * Uses the same registration child as `warlock build` (it imports the route modules without\n * booting connectors) in OpenAPI mode: the document is built inside the child, where the Seal\n * schemas and resource classes live, and only the finished JSON crosses IPC.\n */\nexport function collectOpenApiDocument(\n  options: CollectOpenApiDocumentOptions = {},\n): Promise<OpenApiChildResult> {\n  const cwd = options.cwd ?? process.cwd();\n  const openapi: OpenApiChildRequestOptions = {\n    version: OPENAPI_PROTOCOL_VERSION,\n    ...(options.title !== undefined ? { title: options.title } : {}),\n    ...(options.server !== undefined ? { server: options.server } : {}),\n    ...(options.includePages !== undefined ? { includePages: options.includePages } : {}),\n  };\n\n  return runRegistrationChild<OpenApiChildResult>({\n    cwd,\n    timeoutMs: options.timeoutMs,\n    childEntry: options.childEntry,\n    forkProcess: options.forkProcess,\n    request: {\n      version: 1,\n      cwd,\n      environment: options.environment,\n      runtimeStrategy: options.runtimeStrategy,\n      openapi,\n    },\n    resultMessageType: OPENAPI_RESULT_MESSAGE,\n    resultNoun: \"document\",\n    readResult: (message) => parseOpenApiChildResult(message.result),\n  });\n}\n"],"mappings":";;;;;;;;;;;AAgCA,SAAgB,uBACd,UAAyC,CAAC,GACb;CAC7B,MAAM,MAAM,QAAQ,OAAO,QAAQ,IAAI;CACvC,MAAM,UAAsC;EAC1C;EACA,GAAI,QAAQ,UAAU,SAAY,EAAE,OAAO,QAAQ,MAAM,IAAI,CAAC;EAC9D,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;EACjE,GAAI,QAAQ,iBAAiB,SAAY,EAAE,cAAc,QAAQ,aAAa,IAAI,CAAC;CACrF;CAEA,OAAO,qBAAyC;EAC9C;EACA,WAAW,QAAQ;EACnB,YAAY,QAAQ;EACpB,aAAa,QAAQ;EACrB,SAAS;GACP,SAAS;GACT;GACA,aAAa,QAAQ;GACrB,iBAAiB,QAAQ;GACzB;EACF;EACA,mBAAmB;EACnB,YAAY;EACZ,aAAa,YAAY,wBAAwB,QAAQ,MAAM;CACjE,CAAC;AACH"}

package/esm/openapi/development-openapi-provider.d.mts

@@ -0,0 +1,28 @@
+import { PostmanCollection, PostmanCollectionOptions } from "./postman/postman-types.mjs";
+import { OpenApiBuildResult } from "./types.mjs";
+
+//#region ../core/src/openapi/development-openapi-provider.d.ts
+type DevelopmentOpenApiProvider = () => Promise<OpenApiBuildResult>;
+type DevelopmentPostmanResult = {
+  collection: PostmanCollection;
+  warnings: string[];
+};
+/**
+ * Called by the dev server at startup. The builder lives under `dev-server/`, so the
+ * production entry never reaches it; this registry is the only thing the root exports.
+ */
+declare function registerDevelopmentOpenApiProvider(build: DevelopmentOpenApiProvider): void;
+/**
+ * The OpenAPI document for the routes registered in this process, built by the dev
+ * server's provider. Throws outside `warlock dev`, where no provider is registered.
+ */
+declare function getDevelopmentOpenApiDocument(): Promise<OpenApiBuildResult>;
+/**
+ * The Postman collection (v2.1.0) for the routes registered in this process: the development
+ * OpenAPI document run through `openApiToPostmanCollection`, so both always agree. Throws
+ * outside `warlock dev`, like `getDevelopmentOpenApiDocument`.
+ */
+declare function getDevelopmentPostmanCollection(options?: PostmanCollectionOptions): Promise<DevelopmentPostmanResult>;
+//#endregion
+export { DevelopmentPostmanResult, getDevelopmentOpenApiDocument, getDevelopmentPostmanCollection, registerDevelopmentOpenApiProvider };
+//# sourceMappingURL=development-openapi-provider.d.mts.map

package/esm/openapi/development-openapi-provider.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"development-openapi-provider.d.mts","names":[],"sources":["../../../../../../../core/src/openapi/development-openapi-provider.ts"],"mappings":";;;;KAIK,0BAAA,SAAmC,OAAO,CAAC,kBAAA;AAAA,KAEpC,wBAAA;EACV,UAAA,EAAY,iBAAiB;EAC7B,QAAA;AAAA;;AAJgE;AAElE;;iBAWgB,kCAAA,CAAmC,KAAiC,EAA1B,0BAA0B;;;;;iBAQ9D,6BAAA,IAAiC,OAAO,CAAC,kBAAA;AAjBrD;AASV;;;;AATU,iBAgCY,+BAAA,CACpB,OAAA,GAAS,wBAAA,GACR,OAAA,CAAQ,wBAAA"}

package/esm/openapi/development-openapi-provider.mjs

@@ -0,0 +1,35 @@
+import { openApiToPostmanCollection } from "./postman/openapi-to-postman-collection.mjs";
+
+//#region ../core/src/openapi/development-openapi-provider.ts
+let provider;
+/**
+* Called by the dev server at startup. The builder lives under `dev-server/`, so the
+* production entry never reaches it; this registry is the only thing the root exports.
+*/
+function registerDevelopmentOpenApiProvider(build) {
+	provider = build;
+}
+/**
+* The OpenAPI document for the routes registered in this process, built by the dev
+* server's provider. Throws outside `warlock dev`, where no provider is registered.
+*/
+async function getDevelopmentOpenApiDocument() {
+	if (!provider) throw new Error("No development OpenAPI provider is registered; the API docs are only available under `warlock dev`.");
+	return provider();
+}
+/**
+* The Postman collection (v2.1.0) for the routes registered in this process: the development
+* OpenAPI document run through `openApiToPostmanCollection`, so both always agree. Throws
+* outside `warlock dev`, like `getDevelopmentOpenApiDocument`.
+*/
+async function getDevelopmentPostmanCollection(options = {}) {
+	const { document, warnings } = await getDevelopmentOpenApiDocument();
+	return {
+		collection: openApiToPostmanCollection(document, options),
+		warnings
+	};
+}
+
+//#endregion
+export { getDevelopmentOpenApiDocument, getDevelopmentPostmanCollection, registerDevelopmentOpenApiProvider };
+//# sourceMappingURL=development-openapi-provider.mjs.map

package/esm/openapi/development-openapi-provider.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"development-openapi-provider.mjs","names":[],"sources":["../../../../../../../core/src/openapi/development-openapi-provider.ts"],"sourcesContent":["import { openApiToPostmanCollection } from \"./postman/openapi-to-postman-collection\";\nimport type { PostmanCollection, PostmanCollectionOptions } from \"./postman/postman-types\";\nimport type { OpenApiBuildResult } from \"./types\";\n\ntype DevelopmentOpenApiProvider = () => Promise<OpenApiBuildResult>;\n\nexport type DevelopmentPostmanResult = {\n  collection: PostmanCollection;\n  warnings: string[];\n};\n\nlet provider: DevelopmentOpenApiProvider | undefined;\n\n/**\n * Called by the dev server at startup. The builder lives under `dev-server/`, so the\n * production entry never reaches it; this registry is the only thing the root exports.\n */\nexport function registerDevelopmentOpenApiProvider(build: DevelopmentOpenApiProvider): void {\n  provider = build;\n}\n\n/**\n * The OpenAPI document for the routes registered in this process, built by the dev\n * server's provider. Throws outside `warlock dev`, where no provider is registered.\n */\nexport async function getDevelopmentOpenApiDocument(): Promise<OpenApiBuildResult> {\n  if (!provider) {\n    throw new Error(\n      \"No development OpenAPI provider is registered; the API docs are only available under `warlock dev`.\",\n    );\n  }\n\n  return provider();\n}\n\n/**\n * The Postman collection (v2.1.0) for the routes registered in this process: the development\n * OpenAPI document run through `openApiToPostmanCollection`, so both always agree. Throws\n * outside `warlock dev`, like `getDevelopmentOpenApiDocument`.\n */\nexport async function getDevelopmentPostmanCollection(\n  options: PostmanCollectionOptions = {},\n): Promise<DevelopmentPostmanResult> {\n  const { document, warnings } = await getDevelopmentOpenApiDocument();\n\n  return { collection: openApiToPostmanCollection(document, options), warnings };\n}\n"],"mappings":";;;AAWA,IAAI;;;;;AAMJ,SAAgB,mCAAmC,OAAyC;CAC1F,WAAW;AACb;;;;;AAMA,eAAsB,gCAA6D;CACjF,IAAI,CAAC,UACH,MAAM,IAAI,MACR,qGACF;CAGF,OAAO,SAAS;AAClB;;;;;;AAOA,eAAsB,gCACpB,UAAoC,CAAC,GACF;CACnC,MAAM,EAAE,UAAU,aAAa,MAAM,8BAA8B;CAEnE,OAAO;EAAE,YAAY,2BAA2B,UAAU,OAAO;EAAG;CAAS;AAC/E"}

package/esm/openapi/error-responses.mjs

@@ -0,0 +1,67 @@
+import { describeStatus } from "./response-schemas.mjs";
+
+//#region ../core/src/openapi/error-responses.ts
+const DEFAULT_VALIDATION_RESPONSE = {
+	errors: "errors",
+	inputKey: "input",
+	inputError: "error",
+	status: 422
+};
+/**
+* The `validation.response` config over its documented defaults, as `Response.failedSchema`
+* reads it.
+*/
+function resolveValidationResponse(config) {
+	const merged = { ...DEFAULT_VALIDATION_RESPONSE };
+	if (typeof config?.errors === "string" && config.errors) merged.errors = config.errors;
+	if (typeof config?.inputKey === "string" && config.inputKey) merged.inputKey = config.inputKey;
+	if (typeof config?.inputError === "string" && config.inputError) merged.inputError = config.inputError;
+	if (typeof config?.status === "number" && Number.isInteger(config.status)) merged.status = config.status;
+	return merged;
+}
+/**
+* The failed-validation response: `{ [errors]: [{ [inputKey]: string, [inputError]: string }] }`
+* under the configured status. The body is a shared component, emitted once.
+*/
+function buildValidationFailedResponse(shape, registry) {
+	const ref = registry.shared("ValidationFailed", {
+		type: "object",
+		properties: { [shape.errors]: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					[shape.inputKey]: { type: "string" },
+					[shape.inputError]: { type: "string" }
+				},
+				required: [shape.inputKey, shape.inputError]
+			}
+		} },
+		required: [shape.errors]
+	});
+	return {
+		status: String(shape.status),
+		response: {
+			description: describeStatus("422"),
+			content: { "application/json": { schema: ref } }
+		}
+	};
+}
+/**
+* The 401 response of a guarded route: the conventional `{ error: string }` body.
+*/
+function buildUnauthorizedResponse(registry) {
+	const ref = registry.shared("Unauthorized", {
+		type: "object",
+		properties: { error: { type: "string" } },
+		required: ["error"]
+	});
+	return {
+		description: describeStatus("401"),
+		content: { "application/json": { schema: ref } }
+	};
+}
+
+//#endregion
+export { buildUnauthorizedResponse, buildValidationFailedResponse, resolveValidationResponse };
+//# sourceMappingURL=error-responses.mjs.map

package/esm/openapi/error-responses.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-responses.mjs","names":[],"sources":["../../../../../../../core/src/openapi/error-responses.ts"],"sourcesContent":["import { describeStatus } from \"./response-schemas\";\nimport type { SchemaRegistry } from \"./schema-registry\";\nimport type { OpenApiResponse, OpenApiValidationResponseConfig } from \"./types\";\n\nconst DEFAULT_VALIDATION_RESPONSE = {\n  errors: \"errors\",\n  inputKey: \"input\",\n  inputError: \"error\",\n  status: 422,\n};\n\nexport type ValidationResponseShape = typeof DEFAULT_VALIDATION_RESPONSE;\n\n/**\n * The `validation.response` config over its documented defaults, as `Response.failedSchema`\n * reads it.\n */\nexport function resolveValidationResponse(\n  config: OpenApiValidationResponseConfig | undefined,\n): ValidationResponseShape {\n  const merged = { ...DEFAULT_VALIDATION_RESPONSE };\n\n  if (typeof config?.errors === \"string\" && config.errors) {\n    merged.errors = config.errors;\n  }\n\n  if (typeof config?.inputKey === \"string\" && config.inputKey) {\n    merged.inputKey = config.inputKey;\n  }\n\n  if (typeof config?.inputError === \"string\" && config.inputError) {\n    merged.inputError = config.inputError;\n  }\n\n  if (typeof config?.status === \"number\" && Number.isInteger(config.status)) {\n    merged.status = config.status;\n  }\n\n  return merged;\n}\n\n/**\n * The failed-validation response: `{ [errors]: [{ [inputKey]: string, [inputError]: string }] }`\n * under the configured status. The body is a shared component, emitted once.\n */\nexport function buildValidationFailedResponse(\n  shape: ValidationResponseShape,\n  registry: SchemaRegistry,\n): { status: string; response: OpenApiResponse } {\n  const ref = registry.shared(\"ValidationFailed\", {\n    type: \"object\",\n    properties: {\n      [shape.errors]: {\n        type: \"array\",\n        items: {\n          type: \"object\",\n          properties: {\n            [shape.inputKey]: { type: \"string\" },\n            [shape.inputError]: { type: \"string\" },\n          },\n          required: [shape.inputKey, shape.inputError],\n        },\n      },\n    },\n    required: [shape.errors],\n  });\n\n  return {\n    status: String(shape.status),\n    response: {\n      description: describeStatus(\"422\"),\n      content: { \"application/json\": { schema: ref } },\n    },\n  };\n}\n\n/**\n * The 401 response of a guarded route: the conventional `{ error: string }` body.\n */\nexport function buildUnauthorizedResponse(registry: SchemaRegistry): OpenApiResponse {\n  const ref = registry.shared(\"Unauthorized\", {\n    type: \"object\",\n    properties: { error: { type: \"string\" } },\n    required: [\"error\"],\n  });\n\n  return {\n    description: describeStatus(\"401\"),\n    content: { \"application/json\": { schema: ref } },\n  };\n}\n"],"mappings":";;;AAIA,MAAM,8BAA8B;CAClC,QAAQ;CACR,UAAU;CACV,YAAY;CACZ,QAAQ;AACV;;;;;AAQA,SAAgB,0BACd,QACyB;CACzB,MAAM,SAAS,EAAE,GAAG,4BAA4B;CAEhD,IAAI,OAAO,QAAQ,WAAW,YAAY,OAAO,QAC/C,OAAO,SAAS,OAAO;CAGzB,IAAI,OAAO,QAAQ,aAAa,YAAY,OAAO,UACjD,OAAO,WAAW,OAAO;CAG3B,IAAI,OAAO,QAAQ,eAAe,YAAY,OAAO,YACnD,OAAO,aAAa,OAAO;CAG7B,IAAI,OAAO,QAAQ,WAAW,YAAY,OAAO,UAAU,OAAO,MAAM,GACtE,OAAO,SAAS,OAAO;CAGzB,OAAO;AACT;;;;;AAMA,SAAgB,8BACd,OACA,UAC+C;CAC/C,MAAM,MAAM,SAAS,OAAO,oBAAoB;EAC9C,MAAM;EACN,YAAY,GACT,MAAM,SAAS;GACd,MAAM;GACN,OAAO;IACL,MAAM;IACN,YAAY;MACT,MAAM,WAAW,EAAE,MAAM,SAAS;MAClC,MAAM,aAAa,EAAE,MAAM,SAAS;IACvC;IACA,UAAU,CAAC,MAAM,UAAU,MAAM,UAAU;GAC7C;EACF,EACF;EACA,UAAU,CAAC,MAAM,MAAM;CACzB,CAAC;CAED,OAAO;EACL,QAAQ,OAAO,MAAM,MAAM;EAC3B,UAAU;GACR,aAAa,eAAe,KAAK;GACjC,SAAS,EAAE,oBAAoB,EAAE,QAAQ,IAAI,EAAE;EACjD;CACF;AACF;;;;AAKA,SAAgB,0BAA0B,UAA2C;CACnF,MAAM,MAAM,SAAS,OAAO,gBAAgB;EAC1C,MAAM;EACN,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,EAAE;EACxC,UAAU,CAAC,OAAO;CACpB,CAAC;CAED,OAAO;EACL,aAAa,eAAe,KAAK;EACjC,SAAS,EAAE,oBAAoB,EAAE,QAAQ,IAAI,EAAE;CACjD;AACF"}

package/esm/openapi/index.d.mts

@@ -0,0 +1,6 @@
+import { PostmanAuth, PostmanAuthEntry, PostmanBody, PostmanCollection, PostmanCollectionOptions, PostmanFolder, PostmanFormParam, PostmanHeader, PostmanItem, PostmanOriginalRequest, PostmanQueryParam, PostmanRequest, PostmanRequestItem, PostmanResponse, PostmanUrl, PostmanVariable } from "./postman/postman-types.mjs";
+import { AuthDescriptor, OpenApiBuildResult, OpenApiComponents, OpenApiContext, OpenApiDocument, OpenApiOperation, OpenApiParameter, OpenApiRequestBody, OpenApiResponse, OpenApiRouteInput, OpenApiSchema, OpenApiSecurityRequirement, OpenApiSecurityScheme, OpenApiValidationResponseConfig, WarningSink } from "./types.mjs";
+import { DevelopmentPostmanResult, getDevelopmentOpenApiDocument, getDevelopmentPostmanCollection, registerDevelopmentOpenApiProvider } from "./development-openapi-provider.mjs";
+import { OPENAPI_JSON_SCHEMA_DIALECT, buildOpenApiDocument } from "./build-openapi-document.mjs";
+import { exampleFromSchema } from "./postman/example-from-schema.mjs";
+import { DEFAULT_POSTMAN_BASE_URL, POSTMAN_COLLECTION_SCHEMA, openApiToPostmanCollection } from "./postman/openapi-to-postman-collection.mjs";

package/esm/openapi/index.mjs

@@ -0,0 +1,6 @@
+import { exampleFromSchema } from "./postman/example-from-schema.mjs";
+import { DEFAULT_POSTMAN_BASE_URL, POSTMAN_COLLECTION_SCHEMA, openApiToPostmanCollection } from "./postman/openapi-to-postman-collection.mjs";
+import { getDevelopmentOpenApiDocument, getDevelopmentPostmanCollection, registerDevelopmentOpenApiProvider } from "./development-openapi-provider.mjs";
+import { OPENAPI_JSON_SCHEMA_DIALECT, buildOpenApiDocument } from "./build-openapi-document.mjs";
+
+export {  };

package/esm/openapi/openapi-child-output.mjs

@@ -0,0 +1,57 @@
+import { httpConfig } from "../http/config.mjs";
+import { router } from "../router/router.mjs";
+import { buildOpenApiDocument } from "./build-openapi-document.mjs";
+import { collectResourceExportMap } from "../router/named-api-routes-with-responses.mjs";
+import config from "@mongez/config";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+
+//#region ../core/src/openapi/openapi-child-output.ts
+async function readAppPackage(cwd) {
+	try {
+		return JSON.parse(await readFile(path.join(cwd, "package.json"), "utf8"));
+	} catch {
+		return {};
+	}
+}
+function stringOr(value, fallback) {
+	return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+/**
+* `http://<host>:<port>` from the `http` config. A wildcard bind address is not a place a
+* client can call, so it becomes `localhost`.
+*/
+function resolveDefaultServer() {
+	const host = stringOr(httpConfig("host"), "localhost");
+	const port = httpConfig("port");
+	return `http://${host === "0.0.0.0" || host === "::" ? "localhost" : host}${typeof port === "number" || typeof port === "string" ? `:${port}` : ""}`;
+}
+/**
+* Build the OpenAPI document from the routes registered in THIS process.
+*
+* Runs inside the registration child, after the app's route modules are loaded and config is
+* available. Maps resource classes to their export names, reads `info` from the app
+* `package.json`, the server from the `http` config and the 422 shape from
+* `validation.response`.
+*/
+async function buildOpenApiForChild(options) {
+	const routes = router.list();
+	const resourceMap = routes.some((route) => route.handler?.responseSchema) ? await collectResourceExportMap(options.files, options.onWarn) : void 0;
+	const pkg = await readAppPackage(options.cwd);
+	const validationResponse = config.get("validation.response", {});
+	return buildOpenApiDocument(routes, {
+		info: {
+			title: options.request.title ?? stringOr(pkg.name, "Warlock API"),
+			version: stringOr(pkg.version, "0.0.0"),
+			...typeof pkg.description === "string" && pkg.description ? { description: pkg.description } : {}
+		},
+		servers: [options.request.server ?? resolveDefaultServer()],
+		includePages: options.request.includePages === true,
+		resolveResourceName: (resource) => resourceMap?.get(resource)?.exportName,
+		validationResponse
+	});
+}
+
+//#endregion
+export { buildOpenApiForChild, resolveDefaultServer };
+//# sourceMappingURL=openapi-child-output.mjs.map

package/esm/openapi/openapi-child-output.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-child-output.mjs","names":[],"sources":["../../../../../../../core/src/openapi/openapi-child-output.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { readFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { httpConfig } from \"../http/config\";\nimport {\n  collectResourceExportMap,\n  type ResourceSourceFile,\n} from \"../router/named-api-routes-with-responses\";\nimport { router } from \"../router/router\";\nimport { buildOpenApiDocument } from \"./build-openapi-document\";\nimport type { OpenApiChildRequestOptions } from \"./openapi-protocol\";\nimport type { OpenApiBuildResult, OpenApiValidationResponseConfig } from \"./types\";\n\nexport type BuildOpenApiForChildOptions = Readonly<{\n  /** Application root (the child's cwd). */\n  cwd: string;\n  /** Every source file the orchestrator knows; `*.resource.ts(x)` ones are mapped to exports. */\n  files: Iterable<ResourceSourceFile>;\n  request: OpenApiChildRequestOptions;\n  onWarn?: (message: string) => void;\n}>;\n\ntype AppPackage = { name?: unknown; version?: unknown; description?: unknown };\n\nasync function readAppPackage(cwd: string): Promise<AppPackage> {\n  try {\n    return JSON.parse(await readFile(path.join(cwd, \"package.json\"), \"utf8\")) as AppPackage;\n  } catch {\n    return {};\n  }\n}\n\nfunction stringOr(value: unknown, fallback: string): string {\n  return typeof value === \"string\" && value.length > 0 ? value : fallback;\n}\n\n/**\n * `http://<host>:<port>` from the `http` config. A wildcard bind address is not a place a\n * client can call, so it becomes `localhost`.\n */\nexport function resolveDefaultServer(): string {\n  const host = stringOr(httpConfig(\"host\"), \"localhost\");\n  const port = httpConfig(\"port\");\n  const callable = host === \"0.0.0.0\" || host === \"::\" ? \"localhost\" : host;\n\n  return `http://${callable}${typeof port === \"number\" || typeof port === \"string\" ? `:${port}` : \"\"}`;\n}\n\n/**\n * Build the OpenAPI document from the routes registered in THIS process.\n *\n * Runs inside the registration child, after the app's route modules are loaded and config is\n * available. Maps resource classes to their export names, reads `info` from the app\n * `package.json`, the server from the `http` config and the 422 shape from\n * `validation.response`.\n */\nexport async function buildOpenApiForChild(\n  options: BuildOpenApiForChildOptions,\n): Promise<OpenApiBuildResult> {\n  const routes = router.list();\n  const declaresSchema = routes.some((route) => route.handler?.responseSchema);\n  const resourceMap = declaresSchema\n    ? await collectResourceExportMap(options.files, options.onWarn)\n    : undefined;\n  const pkg = await readAppPackage(options.cwd);\n  const validationResponse = config.get(\n    \"validation.response\",\n    {},\n  ) as OpenApiValidationResponseConfig;\n\n  return buildOpenApiDocument(routes, {\n    info: {\n      title: options.request.title ?? stringOr(pkg.name, \"Warlock API\"),\n      version: stringOr(pkg.version, \"0.0.0\"),\n      ...(typeof pkg.description === \"string\" && pkg.description\n        ? { description: pkg.description }\n        : {}),\n    },\n    servers: [options.request.server ?? resolveDefaultServer()],\n    includePages: options.request.includePages === true,\n    resolveResourceName: (resource) => resourceMap?.get(resource)?.exportName,\n    validationResponse,\n  });\n}\n"],"mappings":";;;;;;;;;AAwBA,eAAe,eAAe,KAAkC;CAC9D,IAAI;EACF,OAAO,KAAK,MAAM,MAAM,SAAS,KAAK,KAAK,KAAK,cAAc,GAAG,MAAM,CAAC;CAC1E,QAAQ;EACN,OAAO,CAAC;CACV;AACF;AAEA,SAAS,SAAS,OAAgB,UAA0B;CAC1D,OAAO,OAAO,UAAU,YAAY,MAAM,SAAS,IAAI,QAAQ;AACjE;;;;;AAMA,SAAgB,uBAA+B;CAC7C,MAAM,OAAO,SAAS,WAAW,MAAM,GAAG,WAAW;CACrD,MAAM,OAAO,WAAW,MAAM;CAG9B,OAAO,UAFU,SAAS,aAAa,SAAS,OAAO,cAAc,OAEzC,OAAO,SAAS,YAAY,OAAO,SAAS,WAAW,IAAI,SAAS;AAClG;;;;;;;;;AAUA,eAAsB,qBACpB,SAC6B;CAC7B,MAAM,SAAS,OAAO,KAAK;CAE3B,MAAM,cADiB,OAAO,MAAM,UAAU,MAAM,SAAS,cAC5B,IAC7B,MAAM,yBAAyB,QAAQ,OAAO,QAAQ,MAAM,IAC5D;CACJ,MAAM,MAAM,MAAM,eAAe,QAAQ,GAAG;CAC5C,MAAM,qBAAqB,OAAO,IAChC,uBACA,CAAC,CACH;CAEA,OAAO,qBAAqB,QAAQ;EAClC,MAAM;GACJ,OAAO,QAAQ,QAAQ,SAAS,SAAS,IAAI,MAAM,aAAa;GAChE,SAAS,SAAS,IAAI,SAAS,OAAO;GACtC,GAAI,OAAO,IAAI,gBAAgB,YAAY,IAAI,cAC3C,EAAE,aAAa,IAAI,YAAY,IAC/B,CAAC;EACP;EACA,SAAS,CAAC,QAAQ,QAAQ,UAAU,qBAAqB,CAAC;EAC1D,cAAc,QAAQ,QAAQ,iBAAiB;EAC/C,sBAAsB,aAAa,aAAa,IAAI,QAAQ,CAAC,EAAE;EAC/D;CACF,CAAC;AACH"}

package/esm/openapi/openapi-protocol.mjs

@@ -0,0 +1,30 @@
+//#region ../core/src/openapi/openapi-protocol.ts
+/** Version of the OpenAPI mode of the registration child protocol. */
+const OPENAPI_PROTOCOL_VERSION = 1;
+/** `type` of the one message the child answers with in OpenAPI mode. */
+const OPENAPI_RESULT_MESSAGE = "openapi-registration:document";
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Validate the `openapi` request field inside the child. Throws on anything unexpected.
+*/
+function parseOpenApiChildOptions(value) {
+	if (!isRecord(value) || value.version !== 1 || !(value.title === void 0 || typeof value.title === "string") || !(value.server === void 0 || typeof value.server === "string") || !(value.includePages === void 0 || typeof value.includePages === "boolean")) throw new Error("Route registration child received an invalid OpenAPI request.");
+	return value;
+}
+/**
+* Validate the result message in the parent. Throws on anything unexpected.
+*/
+function parseOpenApiChildResult(value) {
+	if (!isRecord(value) || value.version !== 1 || !isRecord(value.document) || typeof value.document.openapi !== "string" || !isRecord(value.document.paths) || !Array.isArray(value.warnings) || !value.warnings.every((warning) => typeof warning === "string")) throw new Error("Route registration child sent an invalid OpenAPI document payload.");
+	return Object.freeze({
+		version: 1,
+		document: value.document,
+		warnings: Object.freeze([...value.warnings])
+	});
+}
+
+//#endregion
+export { OPENAPI_RESULT_MESSAGE, parseOpenApiChildOptions, parseOpenApiChildResult };
+//# sourceMappingURL=openapi-protocol.mjs.map

package/esm/openapi/openapi-protocol.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-protocol.mjs","names":[],"sources":["../../../../../../../core/src/openapi/openapi-protocol.ts"],"sourcesContent":["import type { OpenApiDocument } from \"./types\";\n\n/** Version of the OpenAPI mode of the registration child protocol. */\nexport const OPENAPI_PROTOCOL_VERSION = 1;\n\n/** `type` of the one message the child answers with in OpenAPI mode. */\nexport const OPENAPI_RESULT_MESSAGE = \"openapi-registration:document\";\n\n/**\n * The `openapi` field of the registration child request. Its presence switches the child\n * from \"send the route snapshot\" to \"build the OpenAPI document in this process\".\n */\nexport type OpenApiChildRequestOptions = Readonly<{\n  version: typeof OPENAPI_PROTOCOL_VERSION;\n  /** Overrides `info.title` (default: the app `package.json` name). */\n  title?: string;\n  /** Overrides `servers[0].url` (default: built from the `http` config). */\n  server?: string;\n  includePages?: boolean;\n}>;\n\n/** What the child sends back: plain JSON only, never a Seal instance. */\nexport type OpenApiChildResult = Readonly<{\n  version: typeof OPENAPI_PROTOCOL_VERSION;\n  document: OpenApiDocument;\n  warnings: readonly string[];\n}>;\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * Validate the `openapi` request field inside the child. Throws on anything unexpected.\n */\nexport function parseOpenApiChildOptions(value: unknown): OpenApiChildRequestOptions {\n  if (\n    !isRecord(value) ||\n    value.version !== OPENAPI_PROTOCOL_VERSION ||\n    !(value.title === undefined || typeof value.title === \"string\") ||\n    !(value.server === undefined || typeof value.server === \"string\") ||\n    !(value.includePages === undefined || typeof value.includePages === \"boolean\")\n  ) {\n    throw new Error(\"Route registration child received an invalid OpenAPI request.\");\n  }\n\n  return value as OpenApiChildRequestOptions;\n}\n\n/**\n * Validate the result message in the parent. Throws on anything unexpected.\n */\nexport function parseOpenApiChildResult(value: unknown): OpenApiChildResult {\n  if (\n    !isRecord(value) ||\n    value.version !== OPENAPI_PROTOCOL_VERSION ||\n    !isRecord(value.document) ||\n    typeof value.document.openapi !== \"string\" ||\n    !isRecord(value.document.paths) ||\n    !Array.isArray(value.warnings) ||\n    !value.warnings.every((warning) => typeof warning === \"string\")\n  ) {\n    throw new Error(\"Route registration child sent an invalid OpenAPI document payload.\");\n  }\n\n  return Object.freeze({\n    version: OPENAPI_PROTOCOL_VERSION,\n    document: value.document as unknown as OpenApiDocument,\n    warnings: Object.freeze([...(value.warnings as string[])]),\n  });\n}\n"],"mappings":";;AAGA,MAAa,2BAA2B;;AAGxC,MAAa,yBAAyB;AAsBtC,SAAS,SAAS,OAAkD;CAClE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;;;;AAKA,SAAgB,yBAAyB,OAA4C;CACnF,IACE,CAAC,SAAS,KAAK,KACf,MAAM,iBACN,EAAE,MAAM,UAAU,UAAa,OAAO,MAAM,UAAU,aACtD,EAAE,MAAM,WAAW,UAAa,OAAO,MAAM,WAAW,aACxD,EAAE,MAAM,iBAAiB,UAAa,OAAO,MAAM,iBAAiB,YAEpE,MAAM,IAAI,MAAM,+DAA+D;CAGjF,OAAO;AACT;;;;AAKA,SAAgB,wBAAwB,OAAoC;CAC1E,IACE,CAAC,SAAS,KAAK,KACf,MAAM,iBACN,CAAC,SAAS,MAAM,QAAQ,KACxB,OAAO,MAAM,SAAS,YAAY,YAClC,CAAC,SAAS,MAAM,SAAS,KAAK,KAC9B,CAAC,MAAM,QAAQ,MAAM,QAAQ,KAC7B,CAAC,MAAM,SAAS,OAAO,YAAY,OAAO,YAAY,QAAQ,GAE9D,MAAM,IAAI,MAAM,oEAAoE;CAGtF,OAAO,OAAO,OAAO;EACnB;EACA,UAAU,MAAM;EAChB,UAAU,OAAO,OAAO,CAAC,GAAI,MAAM,QAAqB,CAAC;CAC3D,CAAC;AACH"}