@warlock.js/core 4.10.0 → 4.12.0

package/esm/generations/stubs.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"stubs.mjs","names":[],"sources":["../../../../../../../core/src/generations/stubs.ts"],"sourcesContent":["export const accessConfigStub = `import { type AccessConfigurations } from \"@warlock.js/access\";\r\nimport { DatabaseAccessResolver } from \"app/access/services/access-resolver\";\r\n\r\n/**\r\n * Authorization configuration — read by @warlock.js/access on boot.\r\n *\r\n * The resolver is the one required piece: it tells the engine how to read a\r\n * user's roles + permissions. The ejected DatabaseAccessResolver reads roles\r\n * from the user_roles table and maps them through the roles catalog table (so\r\n * roles + their permissions are managed at runtime, in the DB).\r\n *\r\n * For a fixed, code-defined catalog with no tables, swap in DefaultAccessResolver:\r\n *   import { DefaultAccessResolver } from \"@warlock.js/access\";\r\n *   resolver: new DefaultAccessResolver({ admin: [\"*\"], editor: [\"orders.*\"] }),\r\n *\r\n * Multi-tenant? Add a \\`resolveTenant()\\` to the resolver to read the active\r\n * tenant from the request; checks then scope to it automatically.\r\n */\r\nconst access: AccessConfigurations = {\r\n  resolver: new DatabaseAccessResolver(),\r\n\r\n  // Cache resolved permission sets (default \"10m\").\r\n  // cache: { ttl: \"10m\" },\r\n};\r\n\r\nexport default access;\r\n`;\r\n\r\nexport const aiConfigStub = `import type { AIConfig } from \"@warlock.js/ai\";\r\n\r\n// >>> warlock:ai-packages (auto-managed) >>>\r\n// Satellite packages augment the \"ai\" object on import — e.g. ai.workspace,\r\n// ai.tools / ai.mcp, and panoptic's ai.config({ panoptic }) wiring. The command\r\n// \"warlock add ai-workspace | ai-tools | ai-panoptic\" adds the matching\r\n// side-effect import below; keep them so the augmentation + runtime registration\r\n// load before the ai connector applies this config.\r\n// <<< warlock:ai-packages <<<\r\n\r\n/**\r\n * AI configuration — applied on boot by the ai connector, which calls\r\n * ai.config(...) with the object below. Cross-cutting defaults live here\r\n * (shared cache / snapshot stores, observability); per-call options always win.\r\n *\r\n * Wire a default model from a provider you installed, e.g.:\r\n *   import { OpenAISDK } from \"@warlock.js/ai-openai\";\r\n *   const openai = OpenAISDK({ apiKey: env(\"OPENAI_API_KEY\") });\r\n *   // then pass openai.model({ name: \"gpt-4o-mini\" }) into your agents.\r\n */\r\nconst ai: Partial<AIConfig> = {\r\n  // Default cache driver for cache-backed AI features (semantic cache, rag / memory vector stores).\r\n  // defaultStore: cache.driver(\"redis\", { client }),\r\n\r\n  // Observability — requires \"warlock add ai-panoptic\". Exporters + the local dashboard.\r\n  // panoptic: { exporters: [], dashboard: false, observeAll: false },\r\n};\r\n\r\nexport default ai;\r\n`;\r\n\r\nexport const accessRoleModelStub = `import { Model, RegisterModel } from \"@warlock.js/cascade\";\r\nimport { type Infer, v } from \"@warlock.js/seal\";\r\n\r\n/**\r\n * Validation schema for the roles catalog — mirrors the migration columns\r\n * (snake_case). Each row is a role name plus the permission strings it grants;\r\n * wildcards work (\"orders.*\", \"*\"). The DatabaseAccessResolver maps a user's\r\n * assigned role names through this table to their effective permissions.\r\n */\r\nexport const roleSchema = v.object({\r\n  name: v.string(),\r\n  permissions: v.array(v.string()).default([]),\r\n});\r\n\r\nexport type RoleSchema = Infer<typeof roleSchema>;\r\n\r\n/**\r\n * The roles catalog — role name → the permissions it grants. Managed at runtime\r\n * (admins add roles + edit their permissions), unlike a fixed code map. Read by\r\n * DatabaseAccessResolver.resolvePermissions to expand a user's roles to permissions.\r\n */\r\n@RegisterModel()\r\nexport class Role extends Model<RoleSchema> {\r\n  public static table = \"roles\";\r\n\r\n  public static schema = roleSchema;\r\n\r\n  /** The permission strings this role grants. */\r\n  public get permissions(): string[] {\r\n    return this.get<string[]>(\"permissions\", []);\r\n  }\r\n}\r\n`;\r\n\r\nexport const accessRoleModelIndexStub = `export * from \"./role.model\";\r\n`;\r\n\r\nexport const accessRoleMigrationStub = `import { arrayText, Migration, text } from \"@warlock.js/cascade\";\r\nimport { Role } from \"../role.model\";\r\n\r\n/**\r\n * Roles catalog table. \\`name\\` is unique (one row per role); \\`permissions\\` is a\r\n * text array of the permission strings the role grants.\r\n */\r\nexport default Migration.create(Role, {\r\n  name: text().notNullable().unique(),\r\n  permissions: arrayText().nullable(),\r\n});\r\n`;\r\n\r\nexport const accessUserRoleModelStub = `import { access } from \"@warlock.js/access\";\r\nimport type { Auth } from \"@warlock.js/auth\";\r\nimport { Model, RegisterModel } from \"@warlock.js/cascade\";\r\nimport { type Infer, v } from \"@warlock.js/seal\";\r\n\r\n/**\r\n * Validation schema for a role assignment — mirrors the migration columns\r\n * (snake_case). \\`tenant\\` is nullable: a null tenant is a GLOBAL assignment.\r\n */\r\nexport const userRoleSchema = v.object({\r\n  user_id: v.string(),\r\n  user_type: v.string(),\r\n  role: v.string(),\r\n  tenant: v.string().optional(),\r\n});\r\n\r\nexport type UserRoleSchema = Infer<typeof userRoleSchema>;\r\n\r\n/**\r\n * The role-assignment table — which roles a user holds, optionally per tenant.\r\n * Read by DatabaseAccessResolver.resolveRoles; mutated via the statics below.\r\n * \\`assign\\` / \\`revoke\\` flush the cached permission set automatically, so callers\r\n * never need to call \\`access.flush(user, tenant)\\` themselves.\r\n */\r\n@RegisterModel()\r\nexport class UserRole extends Model<UserRoleSchema> {\r\n  public static table = \"user_roles\";\r\n\r\n  public static schema = userRoleSchema;\r\n\r\n  /**\r\n   * Role names assigned to the user in the given tenant.\r\n   *\r\n   * An unresolved tenant (\\`undefined\\`) scopes to GLOBAL roles only — the rows\r\n   * stored with no tenant (\\`null\\`) — never the union across every tenant. The\r\n   * union would be a privilege-escalation: a user who is \\`owner\\` in one tenant\r\n   * must not be treated as \\`owner\\` everywhere just because a check didn't carry\r\n   * a tenant. This mirrors how \\`assign(user, role)\\` stores a global row.\r\n   */\r\n  public static async rolesFor(user: Auth, tenant?: string): Promise<string[]> {\r\n    const rows = await this.query()\r\n      .where({\r\n        user_id: user.id,\r\n        user_type: user.userType,\r\n        tenant: tenant ?? null,\r\n      })\r\n      .get();\r\n\r\n    // De-dupe so a duplicate row (a concurrent assign that slipped past the\r\n    // existence check) can't distort the resolved set.\r\n    return [...new Set(rows.map((row) => row.get(\"role\") as string))];\r\n  }\r\n\r\n  /**\r\n   * Assign a role to the user. No-op if the assignment already exists.\r\n   * Flushes the user's cached permission set automatically.\r\n   */\r\n  public static async assign(user: Auth, role: string, tenant?: string): Promise<void> {\r\n    const existing = await this.first({\r\n      user_id: user.id,\r\n      user_type: user.userType,\r\n      role,\r\n      tenant: tenant ?? null,\r\n    });\r\n\r\n    if (existing) return;\r\n\r\n    await this.create({\r\n      user_id: user.id,\r\n      user_type: user.userType,\r\n      role,\r\n      tenant,\r\n    });\r\n\r\n    await access.flush(user, tenant);\r\n  }\r\n\r\n  /**\r\n   * Remove a role assignment from the user.\r\n   * Flushes the user's cached permission set automatically.\r\n   */\r\n  public static async revoke(user: Auth, role: string, tenant?: string): Promise<void> {\r\n    await this.delete({\r\n      user_id: user.id,\r\n      user_type: user.userType,\r\n      role,\r\n      tenant: tenant ?? null,\r\n    });\r\n\r\n    await access.flush(user, tenant);\r\n  }\r\n}\r\n`;\r\n\r\nexport const accessUserRoleModelIndexStub = `export * from \"./user-role.model\";\r\n`;\r\n\r\nexport const accessUserRoleMigrationStub = `import { Migration, text, uuid } from \"@warlock.js/cascade\";\r\nimport { UserRole } from \"../user-role.model\";\r\n\r\n/**\r\n * Role-assignment table. \\`user_id\\` is a UUID — override this migration if your\r\n * user ids are integers. The composite index powers the per-user (per-tenant)\r\n * lookup the resolver runs on every check.\r\n */\r\nexport default Migration.create(\r\n  UserRole,\r\n  {\r\n    user_id: uuid().notNullable().index(),\r\n    user_type: text().notNullable(),\r\n    role: text().notNullable().index(),\r\n    tenant: text().nullable().index(),\r\n  },\r\n  {\r\n    index: [{ columns: [\"user_id\", \"user_type\", \"tenant\"] }],\r\n  },\r\n);\r\n`;\r\n\r\nexport const accessResolverStub = `import type { AccessResolver } from \"@warlock.js/access\";\r\nimport type { Auth } from \"@warlock.js/auth\";\r\nimport { Role } from \"app/access/models/role\";\r\nimport { UserRole } from \"app/access/models/user-role\";\r\n\r\n/**\r\n * The app's access adapter — connects @warlock.js/access to the ejected role\r\n * tables. Roles come from the user_roles assignment table; permissions are\r\n * expanded by mapping those role names through the roles catalog table. Both\r\n * are managed at runtime (in the DB), so admins can add roles + edit their\r\n * permissions without a deploy.\r\n *\r\n * The engine owns the hard parts (wildcard matching, caching, fail-closed); this\r\n * resolver only fetches — keep it dumb, never cache inside it.\r\n */\r\nexport class DatabaseAccessResolver implements AccessResolver {\r\n  /** The role names this user holds (powers \\`hasRole\\` / \\`hasAnyRole\\`). */\r\n  public async resolveRoles(user: Auth, tenant?: string): Promise<string[]> {\r\n    return UserRole.rolesFor(user, tenant);\r\n  }\r\n\r\n  /** The effective permission strings this user has (powers \\`can\\` / \\`authorize\\`). */\r\n  public async resolvePermissions(user: Auth, tenant?: string): Promise<string[]> {\r\n    const names = await this.resolveRoles(user, tenant);\r\n\r\n    if (names.length === 0) return [];\r\n\r\n    const roles = await Role.query().whereIn(\"name\", names).get();\r\n\r\n    // Flatten + de-dupe so two roles granting the same permission yield one entry.\r\n    return [...new Set(roles.flatMap((role) => role.permissions))];\r\n  }\r\n\r\n  /**\r\n   * Optional. Resolve the ambient tenant when a check doesn't pass one\r\n   * explicitly — derive it from the authenticated user (safer than reading\r\n   * client request input, which a caller could spoof). Uncomment + adapt for a\r\n   * multi-tenant app (single-tenant apps leave this off and return undefined).\r\n   */\r\n  // public resolveTenant(user: Auth): string | undefined {\r\n  //   return user.get(\"organization_id\");\r\n  // }\r\n}\r\n`;\r\n\r\nexport const socketConfigStub = `import type { SocketOptions } from \"@warlock.js/core\";\r\n\r\n/**\r\n * Socket.IO configuration — read by the framework's socket connector\r\n * on boot. When the HTTP server is running the socket server attaches\r\n * to it; otherwise it listens on its own configured port.\r\n *\r\n * Remove this file to disable the socket server entirely.\r\n */\r\nexport default {\r\n  options: {\r\n    cors: {\r\n      origin: \"*\",\r\n    },\r\n  },\r\n} as SocketOptions;\r\n`;\r\n\r\nexport const communicatorsConfigStub = `import { env } from \"@mongez/dotenv\";\r\nimport type { BrokerConfigurations, RabbitMQClientOptions } from \"@warlock.js/herald\";\r\n\r\nconst heraldConfigurations: BrokerConfigurations<RabbitMQClientOptions> = {\r\n  driver: \"rabbitmq\",\r\n  name: \"default\",\r\n  isDefault: true,\r\n\r\n  // ============================================================================\r\n  // Connection Settings\r\n  // ============================================================================\r\n\r\n  host: env(\"RABBITMQ_HOST\", \"localhost\"),\r\n  port: env(\"RABBITMQ_PORT\", 5672),\r\n  username: env(\"RABBITMQ_USERNAME\", \"guest\"),\r\n  password: env(\"RABBITMQ_PASSWORD\", \"guest\"),\r\n  vhost: env(\"RABBITMQ_VHOST\", \"/\"),\r\n\r\n  // Or use connection URI (takes precedence over host/port)\r\n  // uri: env(\"RABBITMQ_URL\"),\r\n\r\n  // ============================================================================\r\n  // Connection Options\r\n  // ============================================================================\r\n\r\n  /** Heartbeat interval in seconds */\r\n  heartbeat: 60,\r\n\r\n  /** Connection timeout in milliseconds */\r\n  connectionTimeout: 10000,\r\n\r\n  /** Enable automatic reconnection on disconnect */\r\n  reconnect: true,\r\n\r\n  /** Delay between reconnection attempts in milliseconds */\r\n  reconnectDelay: 5_000,\r\n\r\n  // ============================================================================\r\n  // Consumer Options\r\n  // ============================================================================\r\n\r\n  /** Default prefetch count (number of unacknowledged messages per consumer) */\r\n  prefetch: 10,\r\n\r\n  // ============================================================================\r\n  // Client Options (Native amqplib options)\r\n  // ============================================================================\r\n  // These options are passed directly to amqplib.connect()\r\n  // for low-level configuration like frame size, TLS, socket options, etc.\r\n  // ============================================================================\r\n  clientOptions: {\r\n    // Frame max size in bytes (0 = no limit)\r\n    // frameMax: 0,\r\n\r\n    // Channel max (0 = unlimited)\r\n    // channelMax: 0,\r\n\r\n    // Socket options\r\n    socket: {\r\n      // Enable TCP keep-alive\r\n      keepAlive: true,\r\n\r\n      // Disable Nagle's algorithm for lower latency\r\n      noDelay: true,\r\n\r\n      // Socket timeout (in addition to heartbeat)\r\n      // timeout: 30000,\r\n    },\r\n\r\n    // TLS/SSL options (uncomment for secure connections)\r\n    // socket: {\r\n    //   ca: fs.readFileSync('/path/to/ca.pem'),\r\n    //   cert: fs.readFileSync('/path/to/cert.pem'),\r\n    //   key: fs.readFileSync('/path/to/key.pem'),\r\n    //   rejectUnauthorized: true,\r\n    // },\r\n  },\r\n};\r\n\r\nexport default heraldConfigurations;\r\n`;\r\n\r\nexport const notificationsConfigStub = `import { type NotificationConfig, inApp, mailChannel } from \"@warlock.js/notifications\";\r\nimport { Notification } from \"app/notifications/notification.model\";\r\n\r\n/**\r\n * Notifications configuration. Auto-loaded from src/config on boot — the\r\n * framework's notifications connector reads this default export and hands it to\r\n * setNotificationConfig, so this file stays declarative (no side-effect call).\r\n *\r\n * Each channel is payload-typed, so notify.mail(...) / notify.database(...)\r\n * and defineNotification are type-checked against the registry.\r\n *\r\n * Channels enabled here:\r\n *   - mail     wraps @warlock.js/core sendMail; route is notifiable.email.\r\n *              The \"from\" address defaults to config/mail.ts; override per\r\n *              channel with mailChannel({ from: \"no-reply@yourapp.com\" }).\r\n *   - database in-app store backed by the Notification model. The \"inApp\"\r\n *              facade exposes the recipient-scoped read API: listUnread,\r\n *              countUnread, markAsRead, dismiss, ...\r\n *\r\n * Async delivery (.queue()) is OPTIONAL: run \"npx warlock add herald\",\r\n * import { heraldQueue } from \"@warlock.js/notifications\", and uncomment the\r\n * queue line below.\r\n */\r\nconst config: NotificationConfig = {\r\n  channels: {\r\n    mail: mailChannel(),\r\n    database: inApp.configure({ model: Notification }),\r\n  },\r\n\r\n  // Async queue — requires @warlock.js/herald (npx warlock add herald):\r\n  // queue: heraldQueue(),\r\n};\r\n\r\nexport default config;\r\n`;\r\n\r\nexport const notificationModelStub = `import { RegisterModel } from \"@warlock.js/cascade\";\r\nimport { DatabaseNotification, type NotificationColumnMap } from \"@warlock.js/notifications\";\r\nimport { v } from \"@warlock.js/seal\";\r\n\r\n/**\r\n * Validation schema for the notifications table — mirrors the migration\r\n * columns (snake_case). Cascade validates + casts every write against it:\r\n * nullable columns use .nullish() (may be absent or null), and payload is\r\n * free-form JSON. Keep this in sync with the migration + columnMap when you\r\n * add or rename columns.\r\n */\r\nconst notificationSchema = v.object({\r\n  user_id: v.string(),\r\n  type: v.string(),\r\n  title: v.string(),\r\n  body: v.string().nullish(),\r\n  payload: v.record(v.any()).nullish(),\r\n  read_at: v.date().nullish(),\r\n  idempotency_key: v.string().nullish(),\r\n});\r\n\r\n/**\r\n * In-app notification model.\r\n *\r\n * Extends the package's DatabaseNotification base, which provides the stable\r\n * accessors (recipientId, tenantId, isRead, readAt, markRead) — all derived\r\n * from the columnMap below. The read/write API lives on the inApp facade\r\n * (configured in config/notifications.ts); you rarely touch this class directly.\r\n */\r\n@RegisterModel()\r\nexport class Notification extends DatabaseNotification {\r\n  public static table = \"notifications\";\r\n  public static schema = notificationSchema;\r\n\r\n  /**\r\n   * Maps the in-app store's roles to your columns. This default is\r\n   * single-tenant + read_at-only. Add tenant: \"organization_id\" for\r\n   * multi-tenant; use isRead: \"is_read\" (instead of, or alongside, readAt) to\r\n   * track a boolean read flag. The migration + accessors all follow this map.\r\n   */\r\n  public static columnMap: NotificationColumnMap = { readAt: \"read_at\" };\r\n}\r\n`;\r\n\r\nexport const notificationMigrationStub = `import { Migration } from \"@warlock.js/cascade\";\r\nimport { notificationColumns } from \"@warlock.js/notifications\";\r\nimport { Notification } from \"../notification.model\";\r\n\r\n/**\r\n * Notifications table.\r\n *\r\n * Columns come from notificationColumns(Notification) — the recipient / tenant\r\n * / read-state names follow the model's columnMap; type / title / body /\r\n * payload / idempotency_key are fixed. Spread it to add your own columns\r\n * (remember to mirror them in the model schema):\r\n *\r\n *   import { uuid } from \"@warlock.js/cascade\";\r\n *\r\n *   export default Migration.create(Notification, {\r\n *     ...notificationColumns(Notification),\r\n *     // category_id: uuid().index().nullable(),\r\n *   });\r\n */\r\nexport default Migration.create(Notification, notificationColumns(Notification));\r\n`;\r\n\r\nexport const notificationControllersStub = `import { type Request, type RequestHandler, type Response } from \"@warlock.js/core\";\r\nimport { inApp } from \"@warlock.js/notifications\";\r\n\r\n/**\r\n * The authenticated user's notification HTTP surface — thin wrappers over the\r\n * recipient-scoped \\`inApp\\` facade (a foreign id can never touch another user's\r\n * rows). Notifications are produced by domain events, never over HTTP, so there\r\n * is no create. Trim or split these as your app grows.\r\n */\r\n\r\n/** GET /notifications — list, most recent first (page / limit / type / unread via query). */\r\nexport const listNotificationsController: RequestHandler = async (\r\n  request: Request,\r\n  response: Response,\r\n) => {\r\n  const { data, pagination } = await inApp.list(request.user!, request.all());\r\n\r\n  return response.success({ notifications: data, pagination });\r\n};\r\n\r\nlistNotificationsController.description = \"List notifications\";\r\n\r\n/** GET /notifications/unread-count — drives the bell badge. */\r\nexport const unreadNotificationsCountController: RequestHandler = async (\r\n  request: Request,\r\n  response: Response,\r\n) => {\r\n  const count = await inApp.countUnread(request.user!);\r\n\r\n  return response.success({ count });\r\n};\r\n\r\nunreadNotificationsCountController.description = \"Unread notifications count\";\r\n\r\n/** PATCH /notifications/:id/read — mark one read, return the updated row. */\r\nexport const markNotificationReadController: RequestHandler = async (\r\n  request: Request,\r\n  response: Response,\r\n) => {\r\n  const id = request.input(\"id\");\r\n\r\n  await inApp.markAsRead(request.user!, id);\r\n  const notification = await inApp.find(request.user!, id);\r\n\r\n  return response.success({ notification });\r\n};\r\n\r\nmarkNotificationReadController.description = \"Mark notification read\";\r\n\r\n/** PATCH /notifications/read-all — mark every unread one read. */\r\nexport const markAllNotificationsReadController: RequestHandler = async (\r\n  request: Request,\r\n  response: Response,\r\n) => {\r\n  const count = await inApp.markAsRead(request.user!);\r\n\r\n  return response.success({ count });\r\n};\r\n\r\nmarkAllNotificationsReadController.description = \"Mark all notifications read\";\r\n\r\n/** DELETE /notifications — dismiss all for the user. */\r\nexport const clearNotificationsController: RequestHandler = async (\r\n  request: Request,\r\n  response: Response,\r\n) => {\r\n  await inApp.dismiss(request.user!);\r\n\r\n  return response.noContent();\r\n};\r\n\r\nclearNotificationsController.description = \"Clear notifications\";\r\n\r\n/** DELETE /notifications/:id — dismiss one. */\r\nexport const deleteNotificationController: RequestHandler = async (\r\n  request: Request,\r\n  response: Response,\r\n) => {\r\n  await inApp.dismiss(request.user!, request.input(\"id\"));\r\n\r\n  return response.noContent();\r\n};\r\n\r\ndeleteNotificationController.description = \"Delete notification\";\r\n`;\r\n\r\nexport const notificationRoutesStub = `import { authMiddleware } from \"@warlock.js/auth\";\r\nimport { router } from \"@warlock.js/core\";\r\nimport {\r\n  clearNotificationsController,\r\n  deleteNotificationController,\r\n  listNotificationsController,\r\n  markAllNotificationsReadController,\r\n  markNotificationReadController,\r\n  unreadNotificationsCountController,\r\n} from \"./controllers/notifications.controller\";\r\n\r\n/**\r\n * Notification routes — the authenticated user's read + dismiss surface.\r\n *\r\n * Notifications are produced by domain events (never created over HTTP), so\r\n * there is no POST. Every route is gated by \\`authMiddleware\\` and recipient-\r\n * scoped by \\`inApp\\` (a foreign id touches zero rows). Delete any endpoint you\r\n * don't need; if your app reads notifications over sockets/GraphQL instead,\r\n * delete this file + the controllers entirely.\r\n */\r\nrouter.group({ prefix: \"/notifications\", middleware: [authMiddleware([])] }, () => {\r\n  router.get(\"/\", listNotificationsController);\r\n  router.get(\"/unread-count\", unreadNotificationsCountController);\r\n  router.patch(\"/read-all\", markAllNotificationsReadController);\r\n  router.patch(\"/:id/read\", markNotificationReadController);\r\n  router.delete(\"/\", clearNotificationsController);\r\n  router.delete(\"/:id\", deleteNotificationController);\r\n});\r\n`;\r\n"],"mappings":";AAAA,MAAa,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BhC,MAAa,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+B5B,MAAa,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCnC,MAAa,2BAA2B;;AAGxC,MAAa,0BAA0B;;;;;;;;;;;;AAavC,MAAa,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8FvC,MAAa,+BAA+B;;AAG5C,MAAa,8BAA8B;;;;;;;;;;;;;;;;;;;;;AAsB3C,MAAa,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6ClC,MAAa,mBAAmB;;;;;;;;;;;;;;;;;AAkBhC,MAAa,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkFvC,MAAa,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCvC,MAAa,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CrC,MAAa,4BAA4B;;;;;;;;;;;;;;;;;;;;;AAsBzC,MAAa,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsF3C,MAAa,yBAAyB"}
+{"version":3,"file":"stubs.mjs","names":[],"sources":["../../../../../../../core/src/generations/stubs.ts"],"sourcesContent":["export const accessConfigStub = `import { type AccessConfigurations } from \"@warlock.js/access\";\r\nimport { DatabaseAccessResolver } from \"app/access/services/access-resolver\";\r\n\r\n/**\r\n * Authorization configuration — read by @warlock.js/access on boot.\r\n *\r\n * The resolver is the one required piece: it tells the engine how to read a\r\n * user's roles + permissions. The ejected DatabaseAccessResolver reads roles\r\n * from the user_roles table and maps them through the roles catalog table (so\r\n * roles + their permissions are managed at runtime, in the DB).\r\n *\r\n * For a fixed, code-defined catalog with no tables, swap in DefaultAccessResolver:\r\n *   import { DefaultAccessResolver } from \"@warlock.js/access\";\r\n *   resolver: new DefaultAccessResolver({ admin: [\"*\"], editor: [\"orders.*\"] }),\r\n *\r\n * Multi-tenant? Add a \\`resolveTenant()\\` to the resolver to read the active\r\n * tenant from the request; checks then scope to it automatically.\r\n */\r\nconst access: AccessConfigurations = {\r\n  resolver: new DatabaseAccessResolver(),\r\n\r\n  // Cache resolved permission sets (default \"10m\").\r\n  // cache: { ttl: \"10m\" },\r\n};\r\n\r\nexport default access;\r\n`;\r\n\r\nexport const aiConfigStub = `import type { AIConfig } from \"@warlock.js/ai\";\r\n\r\n// >>> warlock:ai-packages (auto-managed) >>>\r\n// Satellite packages augment the \"ai\" object on import — e.g. ai.workspace,\r\n// ai.tools / ai.mcp, and panoptic's ai.config({ panoptic }) wiring. The command\r\n// \"warlock add ai-workspace | ai-tools | ai-panoptic\" adds the matching\r\n// side-effect import below; keep them so the augmentation + runtime registration\r\n// load before the ai connector applies this config.\r\n// <<< warlock:ai-packages <<<\r\n\r\n/**\r\n * AI configuration — applied on boot by the ai connector, which calls\r\n * ai.config(...) with the object below. Cross-cutting defaults live here\r\n * (shared cache / snapshot stores, observability); per-call options always win.\r\n *\r\n * Wire a default model from a provider you installed, e.g.:\r\n *   import { OpenAISDK } from \"@warlock.js/ai-openai\";\r\n *   const openai = OpenAISDK({ apiKey: env(\"OPENAI_API_KEY\") });\r\n *   // then pass openai.model({ name: \"gpt-4o-mini\" }) into your agents.\r\n */\r\nconst ai: Partial<AIConfig> = {\r\n  // Default cache driver for cache-backed AI features (semantic cache, rag / memory vector stores).\r\n  // defaultStore: cache.driver(\"redis\", { client }),\r\n\r\n  // Observability — requires \"warlock add ai-panoptic\". Exporters + the local dashboard.\r\n  // panoptic: { exporters: [], dashboard: false, observeAll: false },\r\n};\r\n\r\nexport default ai;\r\n`;\r\n\r\nexport const accessRoleModelStub = `import { Model, RegisterModel } from \"@warlock.js/cascade\";\r\nimport { type Infer, v } from \"@warlock.js/seal\";\r\n\r\n/**\r\n * Validation schema for the roles catalog — mirrors the migration columns\r\n * (snake_case). Each row is a role name plus the permission strings it grants;\r\n * wildcards work (\"orders.*\", \"*\"). The DatabaseAccessResolver maps a user's\r\n * assigned role names through this table to their effective permissions.\r\n */\r\nexport const roleSchema = v.object({\r\n  name: v.string(),\r\n  permissions: v.array(v.string()).default([]),\r\n});\r\n\r\nexport type RoleSchema = Infer<typeof roleSchema>;\r\n\r\n/**\r\n * The roles catalog — role name → the permissions it grants. Managed at runtime\r\n * (admins add roles + edit their permissions), unlike a fixed code map. Read by\r\n * DatabaseAccessResolver.resolvePermissions to expand a user's roles to permissions.\r\n */\r\n@RegisterModel()\r\nexport class Role extends Model<RoleSchema> {\r\n  public static table = \"roles\";\r\n\r\n  public static schema = roleSchema;\r\n\r\n  /** The permission strings this role grants. */\r\n  public get permissions(): string[] {\r\n    return this.get<string[]>(\"permissions\", []);\r\n  }\r\n}\r\n`;\r\n\r\nexport const accessRoleModelIndexStub = `export * from \"./role.model\";\r\n`;\r\n\r\nexport const accessRoleMigrationStub = `import { arrayText, Migration, text } from \"@warlock.js/cascade\";\r\nimport { Role } from \"../role.model\";\r\n\r\n/**\r\n * Roles catalog table. \\`name\\` is unique (one row per role); \\`permissions\\` is a\r\n * text array of the permission strings the role grants.\r\n */\r\nexport default Migration.create(Role, {\r\n  name: text().notNullable().unique(),\r\n  permissions: arrayText().nullable(),\r\n});\r\n`;\r\n\r\nexport const accessUserRoleModelStub = `import { access } from \"@warlock.js/access\";\r\nimport type { Auth } from \"@warlock.js/auth\";\r\nimport { Model, RegisterModel } from \"@warlock.js/cascade\";\r\nimport { type Infer, v } from \"@warlock.js/seal\";\r\n\r\n/**\r\n * Validation schema for a role assignment — mirrors the migration columns\r\n * (snake_case). \\`tenant\\` is nullable: a null tenant is a GLOBAL assignment.\r\n */\r\nexport const userRoleSchema = v.object({\r\n  user_id: v.string(),\r\n  user_type: v.string(),\r\n  role: v.string(),\r\n  tenant: v.string().optional(),\r\n});\r\n\r\nexport type UserRoleSchema = Infer<typeof userRoleSchema>;\r\n\r\n/**\r\n * The role-assignment table — which roles a user holds, optionally per tenant.\r\n * Read by DatabaseAccessResolver.resolveRoles; mutated via the statics below.\r\n * \\`assign\\` / \\`revoke\\` flush the cached permission set automatically, so callers\r\n * never need to call \\`access.flush(user, tenant)\\` themselves.\r\n */\r\n@RegisterModel()\r\nexport class UserRole extends Model<UserRoleSchema> {\r\n  public static table = \"user_roles\";\r\n\r\n  public static schema = userRoleSchema;\r\n\r\n  /**\r\n   * Role names assigned to the user in the given tenant.\r\n   *\r\n   * An unresolved tenant (\\`undefined\\`) scopes to GLOBAL roles only — the rows\r\n   * stored with no tenant (\\`null\\`) — never the union across every tenant. The\r\n   * union would be a privilege-escalation: a user who is \\`owner\\` in one tenant\r\n   * must not be treated as \\`owner\\` everywhere just because a check didn't carry\r\n   * a tenant. This mirrors how \\`assign(user, role)\\` stores a global row.\r\n   */\r\n  public static async rolesFor(user: Auth, tenant?: string): Promise<string[]> {\r\n    const rows = await this.query()\r\n      .where({\r\n        user_id: user.id,\r\n        user_type: user.userType,\r\n        tenant: tenant ?? null,\r\n      })\r\n      .get();\r\n\r\n    // De-dupe so a duplicate row (a concurrent assign that slipped past the\r\n    // existence check) can't distort the resolved set.\r\n    return [...new Set(rows.map((row) => row.get(\"role\") as string))];\r\n  }\r\n\r\n  /**\r\n   * Assign a role to the user. No-op if the assignment already exists.\r\n   * Flushes the user's cached permission set automatically.\r\n   */\r\n  public static async assign(user: Auth, role: string, tenant?: string): Promise<void> {\r\n    const existing = await this.first({\r\n      user_id: user.id,\r\n      user_type: user.userType,\r\n      role,\r\n      tenant: tenant ?? null,\r\n    });\r\n\r\n    if (existing) return;\r\n\r\n    await this.create({\r\n      user_id: user.id,\r\n      user_type: user.userType,\r\n      role,\r\n      tenant,\r\n    });\r\n\r\n    await access.flush(user, tenant);\r\n  }\r\n\r\n  /**\r\n   * Remove a role assignment from the user.\r\n   * Flushes the user's cached permission set automatically.\r\n   */\r\n  public static async revoke(user: Auth, role: string, tenant?: string): Promise<void> {\r\n    await this.delete({\r\n      user_id: user.id,\r\n      user_type: user.userType,\r\n      role,\r\n      tenant: tenant ?? null,\r\n    });\r\n\r\n    await access.flush(user, tenant);\r\n  }\r\n}\r\n`;\r\n\r\nexport const accessUserRoleModelIndexStub = `export * from \"./user-role.model\";\r\n`;\r\n\r\nexport const accessUserRoleMigrationStub = `import { Migration, text, uuid } from \"@warlock.js/cascade\";\r\nimport { UserRole } from \"../user-role.model\";\r\n\r\n/**\r\n * Role-assignment table. \\`user_id\\` is a UUID — override this migration if your\r\n * user ids are integers. The composite index powers the per-user (per-tenant)\r\n * lookup the resolver runs on every check.\r\n */\r\nexport default Migration.create(\r\n  UserRole,\r\n  {\r\n    user_id: uuid().notNullable().index(),\r\n    user_type: text().notNullable(),\r\n    role: text().notNullable().index(),\r\n    tenant: text().nullable().index(),\r\n  },\r\n  {\r\n    index: [{ columns: [\"user_id\", \"user_type\", \"tenant\"] }],\r\n  },\r\n);\r\n`;\r\n\r\nexport const accessResolverStub = `import type { AccessResolver } from \"@warlock.js/access\";\r\nimport type { Auth } from \"@warlock.js/auth\";\r\nimport { Role } from \"app/access/models/role\";\r\nimport { UserRole } from \"app/access/models/user-role\";\r\n\r\n/**\r\n * The app's access adapter — connects @warlock.js/access to the ejected role\r\n * tables. Roles come from the user_roles assignment table; permissions are\r\n * expanded by mapping those role names through the roles catalog table. Both\r\n * are managed at runtime (in the DB), so admins can add roles + edit their\r\n * permissions without a deploy.\r\n *\r\n * The engine owns the hard parts (wildcard matching, caching, fail-closed); this\r\n * resolver only fetches — keep it dumb, never cache inside it.\r\n */\r\nexport class DatabaseAccessResolver implements AccessResolver {\r\n  /** The role names this user holds (powers \\`hasRole\\` / \\`hasAnyRole\\`). */\r\n  public async resolveRoles(user: Auth, tenant?: string): Promise<string[]> {\r\n    return UserRole.rolesFor(user, tenant);\r\n  }\r\n\r\n  /** The effective permission strings this user has (powers \\`can\\` / \\`authorize\\`). */\r\n  public async resolvePermissions(user: Auth, tenant?: string): Promise<string[]> {\r\n    const names = await this.resolveRoles(user, tenant);\r\n\r\n    if (names.length === 0) return [];\r\n\r\n    const roles = await Role.query().whereIn(\"name\", names).get();\r\n\r\n    // Flatten + de-dupe so two roles granting the same permission yield one entry.\r\n    return [...new Set(roles.flatMap((role) => role.permissions))];\r\n  }\r\n\r\n  /**\r\n   * Optional. Resolve the ambient tenant when a check doesn't pass one\r\n   * explicitly — derive it from the authenticated user (safer than reading\r\n   * client request input, which a caller could spoof). Uncomment + adapt for a\r\n   * multi-tenant app (single-tenant apps leave this off and return undefined).\r\n   */\r\n  // public resolveTenant(user: Auth): string | undefined {\r\n  //   return user.get(\"organization_id\");\r\n  // }\r\n}\r\n`;\r\n\r\nexport const socketConfigStub = `import type { SocketOptions } from \"@warlock.js/core\";\r\n\r\n/**\r\n * Socket.IO configuration — read by the framework's socket connector\r\n * on boot. When the HTTP server is running the socket server attaches\r\n * to it; otherwise it listens on its own configured port.\r\n *\r\n * Remove this file to disable the socket server entirely.\r\n */\r\nexport default {\r\n  options: {\r\n    cors: {\r\n      origin: \"*\",\r\n    },\r\n  },\r\n} as SocketOptions;\r\n`;\r\n\r\nexport const communicatorsConfigStub = `import { env } from \"@warlock.js/core\";\r\nimport type { BrokerConfigurations, RabbitMQClientOptions } from \"@warlock.js/herald\";\r\n\r\nconst heraldConfigurations: BrokerConfigurations<RabbitMQClientOptions> = {\r\n  driver: \"rabbitmq\",\r\n  name: \"default\",\r\n  isDefault: true,\r\n\r\n  // ============================================================================\r\n  // Connection Settings\r\n  // ============================================================================\r\n\r\n  host: env(\"RABBITMQ_HOST\", \"localhost\"),\r\n  port: env(\"RABBITMQ_PORT\", 5672),\r\n  username: env(\"RABBITMQ_USERNAME\", \"guest\"),\r\n  password: env(\"RABBITMQ_PASSWORD\", \"guest\"),\r\n  vhost: env(\"RABBITMQ_VHOST\", \"/\"),\r\n\r\n  // Or use connection URI (takes precedence over host/port)\r\n  // uri: env(\"RABBITMQ_URL\"),\r\n\r\n  // ============================================================================\r\n  // Connection Options\r\n  // ============================================================================\r\n\r\n  /** Heartbeat interval in seconds */\r\n  heartbeat: 60,\r\n\r\n  /** Connection timeout in milliseconds */\r\n  connectionTimeout: 10000,\r\n\r\n  /** Enable automatic reconnection on disconnect */\r\n  reconnect: true,\r\n\r\n  /** Delay between reconnection attempts in milliseconds */\r\n  reconnectDelay: 5_000,\r\n\r\n  // ============================================================================\r\n  // Consumer Options\r\n  // ============================================================================\r\n\r\n  /** Default prefetch count (number of unacknowledged messages per consumer) */\r\n  prefetch: 10,\r\n\r\n  // ============================================================================\r\n  // Client Options (Native amqplib options)\r\n  // ============================================================================\r\n  // These options are passed directly to amqplib.connect()\r\n  // for low-level configuration like frame size, TLS, socket options, etc.\r\n  // ============================================================================\r\n  clientOptions: {\r\n    // Frame max size in bytes (0 = no limit)\r\n    // frameMax: 0,\r\n\r\n    // Channel max (0 = unlimited)\r\n    // channelMax: 0,\r\n\r\n    // Socket options\r\n    socket: {\r\n      // Enable TCP keep-alive\r\n      keepAlive: true,\r\n\r\n      // Disable Nagle's algorithm for lower latency\r\n      noDelay: true,\r\n\r\n      // Socket timeout (in addition to heartbeat)\r\n      // timeout: 30000,\r\n    },\r\n\r\n    // TLS/SSL options (uncomment for secure connections)\r\n    // socket: {\r\n    //   ca: fs.readFileSync('/path/to/ca.pem'),\r\n    //   cert: fs.readFileSync('/path/to/cert.pem'),\r\n    //   key: fs.readFileSync('/path/to/key.pem'),\r\n    //   rejectUnauthorized: true,\r\n    // },\r\n  },\r\n};\r\n\r\nexport default heraldConfigurations;\r\n`;\r\n\r\nexport const notificationsConfigStub = `import { type NotificationConfig, inApp, mailChannel } from \"@warlock.js/notifications\";\r\nimport { Notification } from \"app/notifications/notification.model\";\r\n\r\n/**\r\n * Notifications configuration. Auto-loaded from src/config on boot — the\r\n * framework's notifications connector reads this default export and hands it to\r\n * setNotificationConfig, so this file stays declarative (no side-effect call).\r\n *\r\n * Each channel is payload-typed, so notify.mail(...) / notify.database(...)\r\n * and defineNotification are type-checked against the registry.\r\n *\r\n * Channels enabled here:\r\n *   - mail     wraps @warlock.js/core sendMail; route is notifiable.email.\r\n *              The \"from\" address defaults to config/mail.ts; override per\r\n *              channel with mailChannel({ from: \"no-reply@yourapp.com\" }).\r\n *   - database in-app store backed by the Notification model. The \"inApp\"\r\n *              facade exposes the recipient-scoped read API: listUnread,\r\n *              countUnread, markAsRead, dismiss, ...\r\n *\r\n * Async delivery (.queue()) is OPTIONAL: run \"npx warlock add herald\",\r\n * import { heraldQueue } from \"@warlock.js/notifications\", and uncomment the\r\n * queue line below.\r\n */\r\nconst config: NotificationConfig = {\r\n  channels: {\r\n    mail: mailChannel(),\r\n    database: inApp.configure({ model: Notification }),\r\n  },\r\n\r\n  // Async queue — requires @warlock.js/herald (npx warlock add herald):\r\n  // queue: heraldQueue(),\r\n};\r\n\r\nexport default config;\r\n`;\r\n\r\nexport const notificationModelStub = `import { RegisterModel } from \"@warlock.js/cascade\";\r\nimport { DatabaseNotification, type NotificationColumnMap } from \"@warlock.js/notifications\";\r\nimport { v } from \"@warlock.js/seal\";\r\n\r\n/**\r\n * Validation schema for the notifications table — mirrors the migration\r\n * columns (snake_case). Cascade validates + casts every write against it:\r\n * nullable columns use .nullish() (may be absent or null), and payload is\r\n * free-form JSON. Keep this in sync with the migration + columnMap when you\r\n * add or rename columns.\r\n */\r\nconst notificationSchema = v.object({\r\n  user_id: v.string(),\r\n  type: v.string(),\r\n  title: v.string(),\r\n  body: v.string().nullish(),\r\n  payload: v.record(v.any()).nullish(),\r\n  read_at: v.date().nullish(),\r\n  idempotency_key: v.string().nullish(),\r\n});\r\n\r\n/**\r\n * In-app notification model.\r\n *\r\n * Extends the package's DatabaseNotification base, which provides the stable\r\n * accessors (recipientId, tenantId, isRead, readAt, markRead) — all derived\r\n * from the columnMap below. The read/write API lives on the inApp facade\r\n * (configured in config/notifications.ts); you rarely touch this class directly.\r\n */\r\n@RegisterModel()\r\nexport class Notification extends DatabaseNotification {\r\n  public static table = \"notifications\";\r\n  public static schema = notificationSchema;\r\n\r\n  /**\r\n   * Maps the in-app store's roles to your columns. This default is\r\n   * single-tenant + read_at-only. Add tenant: \"organization_id\" for\r\n   * multi-tenant; use isRead: \"is_read\" (instead of, or alongside, readAt) to\r\n   * track a boolean read flag. The migration + accessors all follow this map.\r\n   */\r\n  public static columnMap: NotificationColumnMap = { readAt: \"read_at\" };\r\n}\r\n`;\r\n\r\nexport const notificationMigrationStub = `import { Migration } from \"@warlock.js/cascade\";\r\nimport { notificationColumns } from \"@warlock.js/notifications\";\r\nimport { Notification } from \"../notification.model\";\r\n\r\n/**\r\n * Notifications table.\r\n *\r\n * Columns come from notificationColumns(Notification) — the recipient / tenant\r\n * / read-state names follow the model's columnMap; type / title / body /\r\n * payload / idempotency_key are fixed. Spread it to add your own columns\r\n * (remember to mirror them in the model schema):\r\n *\r\n *   import { uuid } from \"@warlock.js/cascade\";\r\n *\r\n *   export default Migration.create(Notification, {\r\n *     ...notificationColumns(Notification),\r\n *     // category_id: uuid().index().nullable(),\r\n *   });\r\n */\r\nexport default Migration.create(Notification, notificationColumns(Notification));\r\n`;\r\n\r\nexport const notificationControllersStub = `import { type Request, type RequestHandler, type Response } from \"@warlock.js/core\";\r\nimport { inApp } from \"@warlock.js/notifications\";\r\n\r\n/**\r\n * The authenticated user's notification HTTP surface — thin wrappers over the\r\n * recipient-scoped \\`inApp\\` facade (a foreign id can never touch another user's\r\n * rows). Notifications are produced by domain events, never over HTTP, so there\r\n * is no create. Trim or split these as your app grows.\r\n */\r\n\r\n/** GET /notifications — list, most recent first (page / limit / type / unread via query). */\r\nexport const listNotificationsController: RequestHandler = async (\r\n  request: Request,\r\n  response: Response,\r\n) => {\r\n  const { data, pagination } = await inApp.list(request.user!, request.all());\r\n\r\n  return response.success({ notifications: data, pagination });\r\n};\r\n\r\nlistNotificationsController.description = \"List notifications\";\r\n\r\n/** GET /notifications/unread-count — drives the bell badge. */\r\nexport const unreadNotificationsCountController: RequestHandler = async (\r\n  request: Request,\r\n  response: Response,\r\n) => {\r\n  const count = await inApp.countUnread(request.user!);\r\n\r\n  return response.success({ count });\r\n};\r\n\r\nunreadNotificationsCountController.description = \"Unread notifications count\";\r\n\r\n/** PATCH /notifications/:id/read — mark one read, return the updated row. */\r\nexport const markNotificationReadController: RequestHandler = async (\r\n  request: Request,\r\n  response: Response,\r\n) => {\r\n  const id = request.input(\"id\");\r\n\r\n  await inApp.markAsRead(request.user!, id);\r\n  const notification = await inApp.find(request.user!, id);\r\n\r\n  return response.success({ notification });\r\n};\r\n\r\nmarkNotificationReadController.description = \"Mark notification read\";\r\n\r\n/** PATCH /notifications/read-all — mark every unread one read. */\r\nexport const markAllNotificationsReadController: RequestHandler = async (\r\n  request: Request,\r\n  response: Response,\r\n) => {\r\n  const count = await inApp.markAsRead(request.user!);\r\n\r\n  return response.success({ count });\r\n};\r\n\r\nmarkAllNotificationsReadController.description = \"Mark all notifications read\";\r\n\r\n/** DELETE /notifications — dismiss all for the user. */\r\nexport const clearNotificationsController: RequestHandler = async (\r\n  request: Request,\r\n  response: Response,\r\n) => {\r\n  await inApp.dismiss(request.user!);\r\n\r\n  return response.noContent();\r\n};\r\n\r\nclearNotificationsController.description = \"Clear notifications\";\r\n\r\n/** DELETE /notifications/:id — dismiss one. */\r\nexport const deleteNotificationController: RequestHandler = async (\r\n  request: Request,\r\n  response: Response,\r\n) => {\r\n  await inApp.dismiss(request.user!, request.input(\"id\"));\r\n\r\n  return response.noContent();\r\n};\r\n\r\ndeleteNotificationController.description = \"Delete notification\";\r\n`;\r\n\r\nexport const notificationRoutesStub = `import { authMiddleware } from \"@warlock.js/auth\";\r\nimport { router } from \"@warlock.js/core\";\r\nimport {\r\n  clearNotificationsController,\r\n  deleteNotificationController,\r\n  listNotificationsController,\r\n  markAllNotificationsReadController,\r\n  markNotificationReadController,\r\n  unreadNotificationsCountController,\r\n} from \"./controllers/notifications.controller\";\r\n\r\n/**\r\n * Notification routes — the authenticated user's read + dismiss surface.\r\n *\r\n * Notifications are produced by domain events (never created over HTTP), so\r\n * there is no POST. Every route is gated by \\`authMiddleware\\` and recipient-\r\n * scoped by \\`inApp\\` (a foreign id touches zero rows). Delete any endpoint you\r\n * don't need; if your app reads notifications over sockets/GraphQL instead,\r\n * delete this file + the controllers entirely.\r\n */\r\nrouter.group({ prefix: \"/notifications\", middleware: [authMiddleware([])] }, () => {\r\n  router.get(\"/\", listNotificationsController);\r\n  router.get(\"/unread-count\", unreadNotificationsCountController);\r\n  router.patch(\"/read-all\", markAllNotificationsReadController);\r\n  router.patch(\"/:id/read\", markNotificationReadController);\r\n  router.delete(\"/\", clearNotificationsController);\r\n  router.delete(\"/:id\", deleteNotificationController);\r\n});\r\n`;\r\n"],"mappings":";AAAA,MAAa,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BhC,MAAa,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+B5B,MAAa,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCnC,MAAa,2BAA2B;;AAGxC,MAAa,0BAA0B;;;;;;;;;;;;AAavC,MAAa,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8FvC,MAAa,+BAA+B;;AAG5C,MAAa,8BAA8B;;;;;;;;;;;;;;;;;;;;;AAsB3C,MAAa,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6ClC,MAAa,mBAAmB;;;;;;;;;;;;;;;;;AAkBhC,MAAa,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkFvC,MAAa,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCvC,MAAa,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CrC,MAAa,4BAA4B;;;;;;;;;;;;;;;;;;;;;AAsBzC,MAAa,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsF3C,MAAa,yBAAyB"}

package/esm/http/config.mjs

@@ -1,4 +1,4 @@
-import baseConfig from "@mongez/config";
+import config from "@mongez/config";
 import { get } from "@mongez/reinforcements";
 
 //#region ../core/src/http/config.ts
@@ -18,7 +18,7 @@ const defaultHttpConfigurations = {
 * Get http configurations for the given key
 */
 function httpConfig(key) {
-	return baseConfig.get(`http.${key}`, get(defaultHttpConfigurations, key));
+	return config.get(`http.${key}`, get(defaultHttpConfigurations, key));
 }
 
 //#endregion

package/esm/http/config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"config.mjs","names":["config"],"sources":["../../../../../../../core/src/http/config.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { get } from \"@mongez/reinforcements\";\nimport type { HttpConfigurations } from \"./types\";\n\n/**\n * Default http configurations\n */\nexport const defaultHttpConfigurations: HttpConfigurations = {\n  port: 3000,\n  host: \"0.0.0.0\",\n  middleware: {\n    all: [],\n    only: {\n      middleware: [],\n    },\n    except: {\n      middleware: [],\n    },\n  },\n};\n\n/**\n * Get http configurations for the given key\n */\nexport function httpConfig(key: string): any {\n  return config.get(`http.${key}`, get(defaultHttpConfigurations, key));\n}\n"],"mappings":";;;;;;;AAOA,MAAa,4BAAgD;CAC3D,MAAM;CACN,MAAM;CACN,YAAY;EACV,KAAK,CAAC;EACN,MAAM,EACJ,YAAY,CAAC,EACf;EACA,QAAQ,EACN,YAAY,CAAC,EACf;CACF;AACF;;;;AAKA,SAAgB,WAAW,KAAkB;CAC3C,OAAOA,WAAO,IAAI,QAAQ,OAAO,IAAI,2BAA2B,GAAG,CAAC;AACtE"}
+{"version":3,"file":"config.mjs","names":[],"sources":["../../../../../../../core/src/http/config.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { get } from \"@mongez/reinforcements\";\nimport type { HttpConfigurations } from \"./types\";\n\n/**\n * Default http configurations\n */\nexport const defaultHttpConfigurations: HttpConfigurations = {\n  port: 3000,\n  host: \"0.0.0.0\",\n  middleware: {\n    all: [],\n    only: {\n      middleware: [],\n    },\n    except: {\n      middleware: [],\n    },\n  },\n};\n\n/**\n * Get http configurations for the given key\n */\nexport function httpConfig(key: string): any {\n  return config.get(`http.${key}`, get(defaultHttpConfigurations, key));\n}\n"],"mappings":";;;;;;;AAOA,MAAa,4BAAgD;CAC3D,MAAM;CACN,MAAM;CACN,YAAY;EACV,KAAK,CAAC;EACN,MAAM,EACJ,YAAY,CAAC,EACf;EACA,QAAQ,EACN,YAAY,CAAC,EACf;CACF;AACF;;;;AAKA,SAAgB,WAAW,KAAkB;CAC3C,OAAO,OAAO,IAAI,QAAQ,OAAO,IAAI,2BAA2B,GAAG,CAAC;AACtE"}

package/esm/http/createHttpApplication.mjs

@@ -4,7 +4,7 @@ import { router } from "../router/router.mjs";
 import "../router/index.mjs";
 import { registerHttpPlugins } from "./plugins.mjs";
 import { getHttpServer, startHttpServer } from "./server.mjs";
-import baseConfig from "@mongez/config";
+import config from "@mongez/config";
 import { log } from "@warlock.js/logger";
 
 //#region ../core/src/http/createHttpApplication.ts
@@ -19,7 +19,7 @@ async function createHttpApplication() {
 			port,
 			host: httpConfig("host")
 		});
-		const baseUrl = baseConfig.get("app.baseUrl");
+		const baseUrl = config.get("app.baseUrl");
 		setBaseUrl(baseUrl);
 		log.success("http", "server", `Server is listening on ${baseUrl}`);
 	} catch (error) {

package/esm/http/createHttpApplication.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"createHttpApplication.mjs","names":["config"],"sources":["../../../../../../../core/src/http/createHttpApplication.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { log } from \"@warlock.js/logger\";\nimport { router } from \"../router\";\nimport { setBaseUrl } from \"../utils/urls\";\nimport { httpConfig } from \"./config\";\nimport { registerHttpPlugins } from \"./plugins\";\nimport { getHttpServer, startHttpServer } from \"./server\";\n\nexport async function createHttpApplication() {\n  const server = startHttpServer();\n\n  await registerHttpPlugins(server);\n\n  router.scan(server);\n\n  const port = httpConfig(\"port\");\n\n  try {\n    log.info(\"http\", \"server\", \"Connecting to the server\");\n    // 👇🏻 We can use the url of the server\n    await server.listen({\n      port,\n      host: httpConfig(\"host\"),\n    });\n\n    const baseUrl = config.get(\"app.baseUrl\");\n\n    // update base url\n    setBaseUrl(baseUrl);\n\n    log.success(\"http\", \"server\", `Server is listening on ${baseUrl}`);\n  } catch (error) {\n    log.error(\"http\", \"server\", error);\n\n    process.exit(1); // stop the process, exit with error\n  }\n}\n\nexport async function stopHttpApplication() {\n  log.info(\"http\", \"server\", \"Stopping the server\");\n  const server = getHttpServer();\n\n  await server?.close();\n\n  log.success(\"http\", \"server\", \"Server is stopped\");\n}\n"],"mappings":";;;;;;;;;;AAQA,eAAsB,wBAAwB;CAC5C,MAAM,SAAS,gBAAgB;CAE/B,MAAM,oBAAoB,MAAM;CAEhC,OAAO,KAAK,MAAM;CAElB,MAAM,OAAO,WAAW,MAAM;CAE9B,IAAI;EACF,IAAI,KAAK,QAAQ,UAAU,0BAA0B;EAErD,MAAM,OAAO,OAAO;GAClB;GACA,MAAM,WAAW,MAAM;EACzB,CAAC;EAED,MAAM,UAAUA,WAAO,IAAI,aAAa;EAGxC,WAAW,OAAO;EAElB,IAAI,QAAQ,QAAQ,UAAU,0BAA0B,SAAS;CACnE,SAAS,OAAO;EACd,IAAI,MAAM,QAAQ,UAAU,KAAK;EAEjC,QAAQ,KAAK,CAAC;CAChB;AACF;AAEA,eAAsB,sBAAsB;CAC1C,IAAI,KAAK,QAAQ,UAAU,qBAAqB;CAGhD,MAFe,cAEJ,CAAC,EAAE,MAAM;CAEpB,IAAI,QAAQ,QAAQ,UAAU,mBAAmB;AACnD"}
+{"version":3,"file":"createHttpApplication.mjs","names":[],"sources":["../../../../../../../core/src/http/createHttpApplication.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { log } from \"@warlock.js/logger\";\nimport { router } from \"../router\";\nimport { setBaseUrl } from \"../utils/urls\";\nimport { httpConfig } from \"./config\";\nimport { registerHttpPlugins } from \"./plugins\";\nimport { getHttpServer, startHttpServer } from \"./server\";\n\nexport async function createHttpApplication() {\n  const server = startHttpServer();\n\n  await registerHttpPlugins(server);\n\n  router.scan(server);\n\n  const port = httpConfig(\"port\");\n\n  try {\n    log.info(\"http\", \"server\", \"Connecting to the server\");\n    // 👇🏻 We can use the url of the server\n    await server.listen({\n      port,\n      host: httpConfig(\"host\"),\n    });\n\n    const baseUrl = config.get(\"app.baseUrl\");\n\n    // update base url\n    setBaseUrl(baseUrl);\n\n    log.success(\"http\", \"server\", `Server is listening on ${baseUrl}`);\n  } catch (error) {\n    log.error(\"http\", \"server\", error);\n\n    process.exit(1); // stop the process, exit with error\n  }\n}\n\nexport async function stopHttpApplication() {\n  log.info(\"http\", \"server\", \"Stopping the server\");\n  const server = getHttpServer();\n\n  await server?.close();\n\n  log.success(\"http\", \"server\", \"Server is stopped\");\n}\n"],"mappings":";;;;;;;;;;AAQA,eAAsB,wBAAwB;CAC5C,MAAM,SAAS,gBAAgB;CAE/B,MAAM,oBAAoB,MAAM;CAEhC,OAAO,KAAK,MAAM;CAElB,MAAM,OAAO,WAAW,MAAM;CAE9B,IAAI;EACF,IAAI,KAAK,QAAQ,UAAU,0BAA0B;EAErD,MAAM,OAAO,OAAO;GAClB;GACA,MAAM,WAAW,MAAM;EACzB,CAAC;EAED,MAAM,UAAU,OAAO,IAAI,aAAa;EAGxC,WAAW,OAAO;EAElB,IAAI,QAAQ,QAAQ,UAAU,0BAA0B,SAAS;CACnE,SAAS,OAAO;EACd,IAAI,MAAM,QAAQ,UAAU,KAAK;EAEjC,QAAQ,KAAK,CAAC;CAChB;AACF;AAEA,eAAsB,sBAAsB;CAC1C,IAAI,KAAK,QAAQ,UAAU,qBAAqB;CAGhD,MAFe,cAEJ,CAAC,EAAE,MAAM;CAEpB,IAAI,QAAQ,QAAQ,UAAU,mBAAmB;AACnD"}

package/esm/http/index.d.mts

@@ -25,4 +25,5 @@ import { anyMatch, ipMatches } from "./middleware/utils/cidr-match.mjs";
 import { buildIdempotencyCacheKey, hashBody, isValidIdempotencyKey } from "./middleware/utils/idempotency-key.mjs";
 import { parseSize } from "./middleware/utils/parse-size.mjs";
 import { registerHttpPlugins } from "./plugins.mjs";
+import { PortInUseError, assertPortIsAvailable, isPortAvailable } from "./port-preflight.mjs";
 import { RequestContextStore, requestContext, useCurrentUser, useRequest, useRequestStore } from "./context/request-context.mjs";

package/esm/http/index.mjs

@@ -19,5 +19,6 @@ import { anyMatch, ipMatches } from "./middleware/utils/cidr-match.mjs";
 import { parseSize } from "./middleware/utils/parse-size.mjs";
 import { middleware } from "./middleware/middleware-list.mjs";
 import "./middleware/index.mjs";
+import { PortInUseError, assertPortIsAvailable, isPortAvailable } from "./port-preflight.mjs";
 
 export {  };

package/esm/http/middleware/idempotency.middleware.mjs

@@ -1,7 +1,7 @@
 import { t } from "./inject-request-context.mjs";
 import { HttpErrorCodes } from "../error-codes.mjs";
 import { buildIdempotencyCacheKey, hashBody, isValidIdempotencyKey } from "./utils/idempotency-key.mjs";
-import baseConfig from "@mongez/config";
+import config from "@mongez/config";
 import { log } from "@warlock.js/logger";
 import { cache } from "@warlock.js/cache";
 
@@ -44,10 +44,10 @@ const DEFAULT_METHODS = [
 */
 function idempotencyMiddleware(options = {}) {
 	return async (request, response) => {
-		const headerName = options.headerName || baseConfig.get("http.idempotency.headerName", "Idempotency-Key");
-		const methods = options.methods || baseConfig.get("http.idempotency.methods", DEFAULT_METHODS);
-		const ttl = options.ttl || baseConfig.get("http.idempotency.ttl", 86400);
-		const driverName = options.driver || baseConfig.get("http.idempotency.driver");
+		const headerName = options.headerName || config.get("http.idempotency.headerName", "Idempotency-Key");
+		const methods = options.methods || config.get("http.idempotency.methods", DEFAULT_METHODS);
+		const ttl = options.ttl || config.get("http.idempotency.ttl", 86400);
+		const driverName = options.driver || config.get("http.idempotency.driver");
 		if (!methods.includes(request.method.toUpperCase())) return;
 		const idempotencyKey = request.header(headerName.toLowerCase());
 		if (!idempotencyKey) return;

package/esm/http/middleware/idempotency.middleware.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"idempotency.middleware.mjs","names":["config"],"sources":["../../../../../../../../core/src/http/middleware/idempotency.middleware.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { cache } from \"@warlock.js/cache\";\nimport { log } from \"@warlock.js/logger\";\nimport type { Middleware } from \"../../router\";\nimport { HttpErrorCodes } from \"../error-codes\";\nimport type { Response } from \"../response\";\nimport { t } from \"./inject-request-context\";\nimport {\n  buildIdempotencyCacheKey,\n  hashBody,\n  isValidIdempotencyKey,\n} from \"./utils/idempotency-key\";\n\n/**\n * Options for the idempotency middleware.\n */\nexport type IdempotencyOptions = {\n  /**\n   * Cache TTL in seconds. Falls back to `http.idempotency.ttl`, then `86400` (24h).\n   */\n  ttl?: number;\n  /**\n   * Header name carrying the client's key. Falls back to\n   * `http.idempotency.headerName`, then `\"Idempotency-Key\"`.\n   */\n  headerName?: string;\n  /**\n   * HTTP methods eligible for idempotency. Falls back to\n   * `http.idempotency.methods`, then `[\"POST\",\"PUT\",\"PATCH\",\"DELETE\"]`.\n   * Safe methods (GET/HEAD) are skipped regardless.\n   */\n  methods?: string[];\n  /**\n   * Cache driver name. Falls back to `http.idempotency.driver`, then the\n   * default driver of the cache manager.\n   */\n  driver?: string;\n};\n\ntype CachedResponse = {\n  status: number;\n  body: unknown;\n  bodyHash: string;\n  contentType?: string;\n};\n\nconst DEFAULT_METHODS = [\"POST\", \"PUT\", \"PATCH\", \"DELETE\"];\n\n/**\n * Dedupe non-idempotent writes by an `Idempotency-Key` header — same key,\n * same body, within TTL → cached replay; same key, different body → 422\n * `IdempotencyKeyConflict`.\n *\n * **Must run after `authMiddleware`** — the cache key is scoped per-user\n * (`idem:{userType}:{userId}:{key}`) so user A can't replay user B's key.\n * Anonymous requests fall back to IP scope.\n *\n * The replay sets `Idempotent-Replay: true` on the response for easy\n * client-side / observability detection.\n *\n * Eligible methods default to POST/PUT/PATCH/DELETE. GET/HEAD pass through\n * even with the header set (RFC: safe methods are already idempotent).\n *\n * @example\n * import { authMiddleware } from \"@warlock.js/auth\";\n * import { middleware } from \"@warlock.js/core\";\n *\n * router.post(\"/orders\", createOrderController, {\n *   middleware: [authMiddleware(\"client\"), middleware.idempotency()],\n * });\n *\n * router.post(\"/ai/summarize\", summarizeController, {\n *   middleware: [\n *     authMiddleware(\"client\"),\n *     middleware.idempotency({ ttl: 60 * 60 }), // 1h is enough for client retries\n *   ],\n * });\n */\nexport function idempotencyMiddleware(options: IdempotencyOptions = {}): Middleware {\n  return async (request, response) => {\n    const headerName =\n      options.headerName ||\n      config.get(\"http.idempotency.headerName\", \"Idempotency-Key\");\n    const methods =\n      options.methods || config.get(\"http.idempotency.methods\", DEFAULT_METHODS);\n    const ttl = options.ttl || config.get(\"http.idempotency.ttl\", 86400);\n    const driverName = options.driver || config.get(\"http.idempotency.driver\");\n\n    if (!methods.includes(request.method.toUpperCase())) return;\n\n    const idempotencyKey = request.header(headerName.toLowerCase());\n\n    if (!idempotencyKey) return;\n\n    if (!isValidIdempotencyKey(idempotencyKey)) {\n      return response.badRequest({\n        error: t(\"http.idempotencyKeyInvalid\"),\n        errorCode: HttpErrorCodes.IdempotencyKeyInvalid,\n      });\n    }\n\n    const cacheDriver = driverName ? await cache.use(driverName) : cache;\n    const cacheKey = buildIdempotencyCacheKey(request, idempotencyKey);\n    const bodyHash = hashBody(request.body);\n\n    const cached = (await cacheDriver.get(cacheKey)) as CachedResponse | null;\n\n    if (cached) {\n      if (cached.bodyHash !== bodyHash) {\n        return response.unprocessableEntity({\n          error: t(\"http.idempotencyKeyConflict\"),\n          errorCode: HttpErrorCodes.IdempotencyKeyConflict,\n        });\n      }\n\n      response.header(\"Idempotent-Replay\", \"true\");\n\n      return response.replay({\n        status: cached.status,\n        body: cached.body,\n        contentType: cached.contentType,\n      });\n    }\n\n    response.onSent((sentResponse: Response) => {\n      // Don't cache server errors — clients should be able to retry past a 5xx.\n      // 4xx are deterministic outcomes of the request, so caching is fine.\n      if (sentResponse.statusCode >= 500) return;\n\n      const sentContentType = sentResponse.contentType;\n\n      // `set` is fire-and-forget inside `onSent`; without a `.catch` a rejected\n      // write (e.g. Redis down) would surface as an unhandledRejection.\n      cacheDriver\n        .set(\n          cacheKey,\n          {\n            status: sentResponse.statusCode,\n            body: sentResponse.parsedBody,\n            bodyHash,\n            contentType: typeof sentContentType === \"string\" ? sentContentType : undefined,\n          },\n          ttl,\n        )\n        .catch((error: unknown) => {\n          log.error(\"idempotency-middleware\", \"set\", error);\n        });\n    });\n  };\n}\n"],"mappings":";;;;;;;;AA8CA,MAAM,kBAAkB;CAAC;CAAQ;CAAO;CAAS;AAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCzD,SAAgB,sBAAsB,UAA8B,CAAC,GAAe;CAClF,OAAO,OAAO,SAAS,aAAa;EAClC,MAAM,aACJ,QAAQ,cACRA,WAAO,IAAI,+BAA+B,iBAAiB;EAC7D,MAAM,UACJ,QAAQ,WAAWA,WAAO,IAAI,4BAA4B,eAAe;EAC3E,MAAM,MAAM,QAAQ,OAAOA,WAAO,IAAI,wBAAwB,KAAK;EACnE,MAAM,aAAa,QAAQ,UAAUA,WAAO,IAAI,yBAAyB;EAEzE,IAAI,CAAC,QAAQ,SAAS,QAAQ,OAAO,YAAY,CAAC,GAAG;EAErD,MAAM,iBAAiB,QAAQ,OAAO,WAAW,YAAY,CAAC;EAE9D,IAAI,CAAC,gBAAgB;EAErB,IAAI,CAAC,sBAAsB,cAAc,GACvC,OAAO,SAAS,WAAW;GACzB,OAAO,EAAE,4BAA4B;GACrC;EACF,CAAC;EAGH,MAAM,cAAc,aAAa,MAAM,MAAM,IAAI,UAAU,IAAI;EAC/D,MAAM,WAAW,yBAAyB,SAAS,cAAc;EACjE,MAAM,WAAW,SAAS,QAAQ,IAAI;EAEtC,MAAM,SAAU,MAAM,YAAY,IAAI,QAAQ;EAE9C,IAAI,QAAQ;GACV,IAAI,OAAO,aAAa,UACtB,OAAO,SAAS,oBAAoB;IAClC,OAAO,EAAE,6BAA6B;IACtC;GACF,CAAC;GAGH,SAAS,OAAO,qBAAqB,MAAM;GAE3C,OAAO,SAAS,OAAO;IACrB,QAAQ,OAAO;IACf,MAAM,OAAO;IACb,aAAa,OAAO;GACtB,CAAC;EACH;EAEA,SAAS,QAAQ,iBAA2B;GAG1C,IAAI,aAAa,cAAc,KAAK;GAEpC,MAAM,kBAAkB,aAAa;GAIrC,YACG,IACC,UACA;IACE,QAAQ,aAAa;IACrB,MAAM,aAAa;IACnB;IACA,aAAa,OAAO,oBAAoB,WAAW,kBAAkB;GACvE,GACA,GACF,CAAC,CACA,OAAO,UAAmB;IACzB,IAAI,MAAM,0BAA0B,OAAO,KAAK;GAClD,CAAC;EACL,CAAC;CACH;AACF"}
+{"version":3,"file":"idempotency.middleware.mjs","names":[],"sources":["../../../../../../../../core/src/http/middleware/idempotency.middleware.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { cache } from \"@warlock.js/cache\";\nimport { log } from \"@warlock.js/logger\";\nimport type { Middleware } from \"../../router\";\nimport { HttpErrorCodes } from \"../error-codes\";\nimport type { Response } from \"../response\";\nimport { t } from \"./inject-request-context\";\nimport {\n  buildIdempotencyCacheKey,\n  hashBody,\n  isValidIdempotencyKey,\n} from \"./utils/idempotency-key\";\n\n/**\n * Options for the idempotency middleware.\n */\nexport type IdempotencyOptions = {\n  /**\n   * Cache TTL in seconds. Falls back to `http.idempotency.ttl`, then `86400` (24h).\n   */\n  ttl?: number;\n  /**\n   * Header name carrying the client's key. Falls back to\n   * `http.idempotency.headerName`, then `\"Idempotency-Key\"`.\n   */\n  headerName?: string;\n  /**\n   * HTTP methods eligible for idempotency. Falls back to\n   * `http.idempotency.methods`, then `[\"POST\",\"PUT\",\"PATCH\",\"DELETE\"]`.\n   * Safe methods (GET/HEAD) are skipped regardless.\n   */\n  methods?: string[];\n  /**\n   * Cache driver name. Falls back to `http.idempotency.driver`, then the\n   * default driver of the cache manager.\n   */\n  driver?: string;\n};\n\ntype CachedResponse = {\n  status: number;\n  body: unknown;\n  bodyHash: string;\n  contentType?: string;\n};\n\nconst DEFAULT_METHODS = [\"POST\", \"PUT\", \"PATCH\", \"DELETE\"];\n\n/**\n * Dedupe non-idempotent writes by an `Idempotency-Key` header — same key,\n * same body, within TTL → cached replay; same key, different body → 422\n * `IdempotencyKeyConflict`.\n *\n * **Must run after `authMiddleware`** — the cache key is scoped per-user\n * (`idem:{userType}:{userId}:{key}`) so user A can't replay user B's key.\n * Anonymous requests fall back to IP scope.\n *\n * The replay sets `Idempotent-Replay: true` on the response for easy\n * client-side / observability detection.\n *\n * Eligible methods default to POST/PUT/PATCH/DELETE. GET/HEAD pass through\n * even with the header set (RFC: safe methods are already idempotent).\n *\n * @example\n * import { authMiddleware } from \"@warlock.js/auth\";\n * import { middleware } from \"@warlock.js/core\";\n *\n * router.post(\"/orders\", createOrderController, {\n *   middleware: [authMiddleware(\"client\"), middleware.idempotency()],\n * });\n *\n * router.post(\"/ai/summarize\", summarizeController, {\n *   middleware: [\n *     authMiddleware(\"client\"),\n *     middleware.idempotency({ ttl: 60 * 60 }), // 1h is enough for client retries\n *   ],\n * });\n */\nexport function idempotencyMiddleware(options: IdempotencyOptions = {}): Middleware {\n  return async (request, response) => {\n    const headerName =\n      options.headerName ||\n      config.get(\"http.idempotency.headerName\", \"Idempotency-Key\");\n    const methods =\n      options.methods || config.get(\"http.idempotency.methods\", DEFAULT_METHODS);\n    const ttl = options.ttl || config.get(\"http.idempotency.ttl\", 86400);\n    const driverName = options.driver || config.get(\"http.idempotency.driver\");\n\n    if (!methods.includes(request.method.toUpperCase())) return;\n\n    const idempotencyKey = request.header(headerName.toLowerCase());\n\n    if (!idempotencyKey) return;\n\n    if (!isValidIdempotencyKey(idempotencyKey)) {\n      return response.badRequest({\n        error: t(\"http.idempotencyKeyInvalid\"),\n        errorCode: HttpErrorCodes.IdempotencyKeyInvalid,\n      });\n    }\n\n    const cacheDriver = driverName ? await cache.use(driverName) : cache;\n    const cacheKey = buildIdempotencyCacheKey(request, idempotencyKey);\n    const bodyHash = hashBody(request.body);\n\n    const cached = (await cacheDriver.get(cacheKey)) as CachedResponse | null;\n\n    if (cached) {\n      if (cached.bodyHash !== bodyHash) {\n        return response.unprocessableEntity({\n          error: t(\"http.idempotencyKeyConflict\"),\n          errorCode: HttpErrorCodes.IdempotencyKeyConflict,\n        });\n      }\n\n      response.header(\"Idempotent-Replay\", \"true\");\n\n      return response.replay({\n        status: cached.status,\n        body: cached.body,\n        contentType: cached.contentType,\n      });\n    }\n\n    response.onSent((sentResponse: Response) => {\n      // Don't cache server errors — clients should be able to retry past a 5xx.\n      // 4xx are deterministic outcomes of the request, so caching is fine.\n      if (sentResponse.statusCode >= 500) return;\n\n      const sentContentType = sentResponse.contentType;\n\n      // `set` is fire-and-forget inside `onSent`; without a `.catch` a rejected\n      // write (e.g. Redis down) would surface as an unhandledRejection.\n      cacheDriver\n        .set(\n          cacheKey,\n          {\n            status: sentResponse.statusCode,\n            body: sentResponse.parsedBody,\n            bodyHash,\n            contentType: typeof sentContentType === \"string\" ? sentContentType : undefined,\n          },\n          ttl,\n        )\n        .catch((error: unknown) => {\n          log.error(\"idempotency-middleware\", \"set\", error);\n        });\n    });\n  };\n}\n"],"mappings":";;;;;;;;AA8CA,MAAM,kBAAkB;CAAC;CAAQ;CAAO;CAAS;AAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCzD,SAAgB,sBAAsB,UAA8B,CAAC,GAAe;CAClF,OAAO,OAAO,SAAS,aAAa;EAClC,MAAM,aACJ,QAAQ,cACR,OAAO,IAAI,+BAA+B,iBAAiB;EAC7D,MAAM,UACJ,QAAQ,WAAW,OAAO,IAAI,4BAA4B,eAAe;EAC3E,MAAM,MAAM,QAAQ,OAAO,OAAO,IAAI,wBAAwB,KAAK;EACnE,MAAM,aAAa,QAAQ,UAAU,OAAO,IAAI,yBAAyB;EAEzE,IAAI,CAAC,QAAQ,SAAS,QAAQ,OAAO,YAAY,CAAC,GAAG;EAErD,MAAM,iBAAiB,QAAQ,OAAO,WAAW,YAAY,CAAC;EAE9D,IAAI,CAAC,gBAAgB;EAErB,IAAI,CAAC,sBAAsB,cAAc,GACvC,OAAO,SAAS,WAAW;GACzB,OAAO,EAAE,4BAA4B;GACrC;EACF,CAAC;EAGH,MAAM,cAAc,aAAa,MAAM,MAAM,IAAI,UAAU,IAAI;EAC/D,MAAM,WAAW,yBAAyB,SAAS,cAAc;EACjE,MAAM,WAAW,SAAS,QAAQ,IAAI;EAEtC,MAAM,SAAU,MAAM,YAAY,IAAI,QAAQ;EAE9C,IAAI,QAAQ;GACV,IAAI,OAAO,aAAa,UACtB,OAAO,SAAS,oBAAoB;IAClC,OAAO,EAAE,6BAA6B;IACtC;GACF,CAAC;GAGH,SAAS,OAAO,qBAAqB,MAAM;GAE3C,OAAO,SAAS,OAAO;IACrB,QAAQ,OAAO;IACf,MAAM,OAAO;IACb,aAAa,OAAO;GACtB,CAAC;EACH;EAEA,SAAS,QAAQ,iBAA2B;GAG1C,IAAI,aAAa,cAAc,KAAK;GAEpC,MAAM,kBAAkB,aAAa;GAIrC,YACG,IACC,UACA;IACE,QAAQ,aAAa;IACrB,MAAM,aAAa;IACnB;IACA,aAAa,OAAO,oBAAoB,WAAW,kBAAkB;GACvE,GACA,GACF,CAAC,CACA,OAAO,UAAmB;IACzB,IAAI,MAAM,0BAA0B,OAAO,KAAK;GAClD,CAAC;EACL,CAAC;CACH;AACF"}

package/esm/http/middleware/inject-request-context.mjs

@@ -2,7 +2,7 @@ import { environment } from "../../utils/environment.mjs";
 import { requestContext, useRequestStore } from "../context/request-context.mjs";
 import "../../utils/index.mjs";
 import { BadRequestError, ForbiddenError, HttpError, ResourceNotFoundError, ServerError, UnAuthorizedError } from "../errors/errors.mjs";
-import baseConfig from "@mongez/config";
+import config from "@mongez/config";
 import { trans } from "@mongez/localization";
 import { DatabaseWriterValidationError } from "@warlock.js/cascade";
 import { contextManager } from "@warlock.js/context";
@@ -22,7 +22,7 @@ import { contextManager } from "@warlock.js/context";
 * Skip when `http.requestId.enabled` is explicitly false.
 */
 function stampRequestIdHeader(request, response) {
-	const requestIdConfig = baseConfig.get("http.requestId", {});
+	const requestIdConfig = config.get("http.requestId", {});
 	if (requestIdConfig.enabled === false) return;
 	const headerName = requestIdConfig.header || "X-Request-Id";
 	response.header(headerName, request.id);

package/esm/http/middleware/inject-request-context.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"inject-request-context.mjs","names":["config","requestContextInstance"],"sources":["../../../../../../../../core/src/http/middleware/inject-request-context.ts"],"sourcesContent":["/**\r\n * Request Context Middleware\r\n *\r\n * Creates a unified context for each request using the ContextManager.\r\n * All framework contexts (request, storage, database) are available throughout the request lifecycle.\r\n */\r\nimport { trans } from \"@mongez/localization\";\r\nimport { GenericObject } from \"@mongez/reinforcements\";\r\nimport { DatabaseWriterValidationError } from \"@warlock.js/cascade\";\r\nimport { contextManager } from \"@warlock.js/context\";\r\nimport config from \"@mongez/config\";\r\nimport { environment } from \"../../utils\";\r\nimport {\r\n  requestContext as requestContextInstance,\r\n  useRequestStore,\r\n} from \"../context/request-context\";\r\nimport {\r\n  BadRequestError,\r\n  ForbiddenError,\r\n  HttpError,\r\n  ResourceNotFoundError,\r\n  ServerError,\r\n  UnAuthorizedError,\r\n} from \"../errors\";\r\nimport { type Request } from \"../request\";\r\nimport { type Response } from \"../response\";\r\nimport { type ReturnedResponse } from \"./../types\";\r\n\r\n// Contexts are now registered in core/context/init-contexts.ts via initializeContexts()\r\n\r\n/**\r\n * Echo `request.id` back as a response header so the FE / proxies / log\r\n * aggregators can correlate by the same value the server logs against.\r\n *\r\n * Reads the header name from `http.requestId.header` (default `X-Request-Id`).\r\n * Skip when `http.requestId.enabled` is explicitly false.\r\n */\r\nfunction stampRequestIdHeader(request: Request, response: Response) {\r\n  const requestIdConfig = config.get(\"http.requestId\", {} as Record<string, any>);\r\n\r\n  if (requestIdConfig.enabled === false) return;\r\n\r\n  const headerName = requestIdConfig.header || \"X-Request-Id\";\r\n\r\n  response.header(headerName, request.id);\r\n}\r\n\r\n/**\r\n * Create request store and execute middleware + handler\r\n *\r\n * Runs all registered contexts together using ContextManager.\r\n */\r\nexport function createRequestStore(\r\n  request: Request<any>,\r\n  response: Response,\r\n): Promise<ReturnedResponse> {\r\n  stampRequestIdHeader(request, response);\r\n\r\n  // Build all context stores using the immutable API\r\n  // Each context defines its own store initialization via buildStore()\r\n  const httpContextStore = contextManager.buildStores({ request, response });\r\n\r\n  // Run all contexts together!\r\n  return contextManager.runAll(httpContextStore, async () => {\r\n    try {\r\n      // Run middleware chain\r\n      const result = await request.runMiddleware();\r\n\r\n      if (result) {\r\n        return result as ReturnedResponse;\r\n      }\r\n\r\n      // Execute route handler\r\n      request.trigger(\"executingAction\", request.route);\r\n\r\n      const handler = request.getHandler();\r\n\r\n      request.log(\"Executing Handler\", \"info\");\r\n\r\n      const output = await handler(request, response);\r\n\r\n      request.log(\"Handler Executed Successfully\", \"success\");\r\n\r\n      request.trigger(\"executedAction\", request.route);\r\n\r\n      return output as ReturnedResponse;\r\n    } catch (error: any) {\r\n      request.log(`${error.constructor.name}: Request failed: ${error.message}`, \"error\");\r\n      return handleRequestError(error, response);\r\n    }\r\n  });\r\n}\r\n\r\n/**\r\n * Handle request errors\r\n * @internal\r\n */\r\nfunction handleRequestError(error: any, response: Response): ReturnedResponse {\r\n  if (error instanceof HttpError) {\r\n    const payload: GenericObject = {\r\n      error: error.message,\r\n    };\r\n    if (error.payload) {\r\n      payload.payload = error.payload;\r\n    }\r\n\r\n    if (environment() === \"development\") {\r\n      payload.stack = error.stack;\r\n    }\r\n\r\n    return response.setStatusCode(error.status).send(payload);\r\n  }\r\n\r\n  if (error instanceof ResourceNotFoundError) {\r\n    return response.notFound({\r\n      error: error.message,\r\n      ...error.payload,\r\n    });\r\n  }\r\n\r\n  if (error instanceof UnAuthorizedError) {\r\n    return response.unauthorized({\r\n      error: error.message,\r\n      ...error.payload,\r\n    });\r\n  }\r\n\r\n  if (error instanceof ForbiddenError) {\r\n    return response.forbidden({\r\n      error: error.message,\r\n      ...error.payload,\r\n    });\r\n  }\r\n\r\n  if (error instanceof BadRequestError) {\r\n    return response.badRequest({\r\n      error: error.message,\r\n      ...error.payload,\r\n    });\r\n  }\r\n\r\n  if (error instanceof DatabaseWriterValidationError) {\r\n    return response.badRequest({\r\n      errors: error.errors,\r\n    });\r\n  }\r\n\r\n  if (error instanceof ServerError) {\r\n    return response.serverError({\r\n      error: error.message,\r\n      ...error.payload,\r\n    });\r\n  }\r\n\r\n  console.log(error);\r\n\r\n  return response.badRequest({\r\n    error: error.message,\r\n    ...error.payload,\r\n  });\r\n}\r\n\r\n/**\r\n * Translate a keyword (uses request context for locale)\r\n */\r\nexport function t(keyword: string, placeholders?: any) {\r\n  return (\r\n    requestContextInstance.getRequest()?.trans(keyword, placeholders) ||\r\n    trans(keyword, placeholders)\r\n  );\r\n}\r\n\r\n/**\r\n * Get or compute a value from the request cache\r\n *\r\n * If the value exists in request, return it.\r\n * Otherwise, execute callback, store result in request, and return it.\r\n */\r\nexport async function fromRequest<T>(\r\n  key: string,\r\n  callback: (request?: Request) => Promise<T>,\r\n): Promise<T> {\r\n  const { request } = useRequestStore();\r\n\r\n  if (!request) return await callback();\r\n\r\n  if (request[key]) return request[key];\r\n\r\n  request[key] = await callback(request);\r\n\r\n  return request[key];\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAqCA,SAAS,qBAAqB,SAAkB,UAAoB;CAClE,MAAM,kBAAkBA,WAAO,IAAI,kBAAkB,CAAC,CAAwB;CAE9E,IAAI,gBAAgB,YAAY,OAAO;CAEvC,MAAM,aAAa,gBAAgB,UAAU;CAE7C,SAAS,OAAO,YAAY,QAAQ,EAAE;AACxC;;;;;;AAOA,SAAgB,mBACd,SACA,UAC2B;CAC3B,qBAAqB,SAAS,QAAQ;CAItC,MAAM,mBAAmB,eAAe,YAAY;EAAE;EAAS;CAAS,CAAC;CAGzE,OAAO,eAAe,OAAO,kBAAkB,YAAY;EACzD,IAAI;GAEF,MAAM,SAAS,MAAM,QAAQ,cAAc;GAE3C,IAAI,QACF,OAAO;GAIT,QAAQ,QAAQ,mBAAmB,QAAQ,KAAK;GAEhD,MAAM,UAAU,QAAQ,WAAW;GAEnC,QAAQ,IAAI,qBAAqB,MAAM;GAEvC,MAAM,SAAS,MAAM,QAAQ,SAAS,QAAQ;GAE9C,QAAQ,IAAI,iCAAiC,SAAS;GAEtD,QAAQ,QAAQ,kBAAkB,QAAQ,KAAK;GAE/C,OAAO;EACT,SAAS,OAAY;GACnB,QAAQ,IAAI,GAAG,MAAM,YAAY,KAAK,oBAAoB,MAAM,WAAW,OAAO;GAClF,OAAO,mBAAmB,OAAO,QAAQ;EAC3C;CACF,CAAC;AACH;;;;;AAMA,SAAS,mBAAmB,OAAY,UAAsC;CAC5E,IAAI,iBAAiB,WAAW;EAC9B,MAAM,UAAyB,EAC7B,OAAO,MAAM,QACf;EACA,IAAI,MAAM,SACR,QAAQ,UAAU,MAAM;EAG1B,IAAI,YAAY,MAAM,eACpB,QAAQ,QAAQ,MAAM;EAGxB,OAAO,SAAS,cAAc,MAAM,MAAM,CAAC,CAAC,KAAK,OAAO;CAC1D;CAEA,IAAI,iBAAiB,uBACnB,OAAO,SAAS,SAAS;EACvB,OAAO,MAAM;EACb,GAAG,MAAM;CACX,CAAC;CAGH,IAAI,iBAAiB,mBACnB,OAAO,SAAS,aAAa;EAC3B,OAAO,MAAM;EACb,GAAG,MAAM;CACX,CAAC;CAGH,IAAI,iBAAiB,gBACnB,OAAO,SAAS,UAAU;EACxB,OAAO,MAAM;EACb,GAAG,MAAM;CACX,CAAC;CAGH,IAAI,iBAAiB,iBACnB,OAAO,SAAS,WAAW;EACzB,OAAO,MAAM;EACb,GAAG,MAAM;CACX,CAAC;CAGH,IAAI,iBAAiB,+BACnB,OAAO,SAAS,WAAW,EACzB,QAAQ,MAAM,OAChB,CAAC;CAGH,IAAI,iBAAiB,aACnB,OAAO,SAAS,YAAY;EAC1B,OAAO,MAAM;EACb,GAAG,MAAM;CACX,CAAC;CAGH,QAAQ,IAAI,KAAK;CAEjB,OAAO,SAAS,WAAW;EACzB,OAAO,MAAM;EACb,GAAG,MAAM;CACX,CAAC;AACH;;;;AAKA,SAAgB,EAAE,SAAiB,cAAoB;CACrD,OACEC,eAAuB,WAAW,CAAC,EAAE,MAAM,SAAS,YAAY,KAChE,MAAM,SAAS,YAAY;AAE/B;;;;;;;AAQA,eAAsB,YACpB,KACA,UACY;CACZ,MAAM,EAAE,YAAY,gBAAgB;CAEpC,IAAI,CAAC,SAAS,OAAO,MAAM,SAAS;CAEpC,IAAI,QAAQ,MAAM,OAAO,QAAQ;CAEjC,QAAQ,OAAO,MAAM,SAAS,OAAO;CAErC,OAAO,QAAQ;AACjB"}
+{"version":3,"file":"inject-request-context.mjs","names":["requestContextInstance"],"sources":["../../../../../../../../core/src/http/middleware/inject-request-context.ts"],"sourcesContent":["/**\r\n * Request Context Middleware\r\n *\r\n * Creates a unified context for each request using the ContextManager.\r\n * All framework contexts (request, storage, database) are available throughout the request lifecycle.\r\n */\r\nimport { trans } from \"@mongez/localization\";\r\nimport { GenericObject } from \"@mongez/reinforcements\";\r\nimport { DatabaseWriterValidationError } from \"@warlock.js/cascade\";\r\nimport { contextManager } from \"@warlock.js/context\";\r\nimport config from \"@mongez/config\";\r\nimport { environment } from \"../../utils\";\r\nimport {\r\n  requestContext as requestContextInstance,\r\n  useRequestStore,\r\n} from \"../context/request-context\";\r\nimport {\r\n  BadRequestError,\r\n  ForbiddenError,\r\n  HttpError,\r\n  ResourceNotFoundError,\r\n  ServerError,\r\n  UnAuthorizedError,\r\n} from \"../errors\";\r\nimport { type Request } from \"../request\";\r\nimport { type Response } from \"../response\";\r\nimport { type ReturnedResponse } from \"./../types\";\r\n\r\n// Contexts are now registered in core/context/init-contexts.ts via initializeContexts()\r\n\r\n/**\r\n * Echo `request.id` back as a response header so the FE / proxies / log\r\n * aggregators can correlate by the same value the server logs against.\r\n *\r\n * Reads the header name from `http.requestId.header` (default `X-Request-Id`).\r\n * Skip when `http.requestId.enabled` is explicitly false.\r\n */\r\nfunction stampRequestIdHeader(request: Request, response: Response) {\r\n  const requestIdConfig = config.get(\"http.requestId\", {} as Record<string, any>);\r\n\r\n  if (requestIdConfig.enabled === false) return;\r\n\r\n  const headerName = requestIdConfig.header || \"X-Request-Id\";\r\n\r\n  response.header(headerName, request.id);\r\n}\r\n\r\n/**\r\n * Create request store and execute middleware + handler\r\n *\r\n * Runs all registered contexts together using ContextManager.\r\n */\r\nexport function createRequestStore(\r\n  request: Request<any>,\r\n  response: Response,\r\n): Promise<ReturnedResponse> {\r\n  stampRequestIdHeader(request, response);\r\n\r\n  // Build all context stores using the immutable API\r\n  // Each context defines its own store initialization via buildStore()\r\n  const httpContextStore = contextManager.buildStores({ request, response });\r\n\r\n  // Run all contexts together!\r\n  return contextManager.runAll(httpContextStore, async () => {\r\n    try {\r\n      // Run middleware chain\r\n      const result = await request.runMiddleware();\r\n\r\n      if (result) {\r\n        return result as ReturnedResponse;\r\n      }\r\n\r\n      // Execute route handler\r\n      request.trigger(\"executingAction\", request.route);\r\n\r\n      const handler = request.getHandler();\r\n\r\n      request.log(\"Executing Handler\", \"info\");\r\n\r\n      const output = await handler(request, response);\r\n\r\n      request.log(\"Handler Executed Successfully\", \"success\");\r\n\r\n      request.trigger(\"executedAction\", request.route);\r\n\r\n      return output as ReturnedResponse;\r\n    } catch (error: any) {\r\n      request.log(`${error.constructor.name}: Request failed: ${error.message}`, \"error\");\r\n      return handleRequestError(error, response);\r\n    }\r\n  });\r\n}\r\n\r\n/**\r\n * Handle request errors\r\n * @internal\r\n */\r\nfunction handleRequestError(error: any, response: Response): ReturnedResponse {\r\n  if (error instanceof HttpError) {\r\n    const payload: GenericObject = {\r\n      error: error.message,\r\n    };\r\n    if (error.payload) {\r\n      payload.payload = error.payload;\r\n    }\r\n\r\n    if (environment() === \"development\") {\r\n      payload.stack = error.stack;\r\n    }\r\n\r\n    return response.setStatusCode(error.status).send(payload);\r\n  }\r\n\r\n  if (error instanceof ResourceNotFoundError) {\r\n    return response.notFound({\r\n      error: error.message,\r\n      ...error.payload,\r\n    });\r\n  }\r\n\r\n  if (error instanceof UnAuthorizedError) {\r\n    return response.unauthorized({\r\n      error: error.message,\r\n      ...error.payload,\r\n    });\r\n  }\r\n\r\n  if (error instanceof ForbiddenError) {\r\n    return response.forbidden({\r\n      error: error.message,\r\n      ...error.payload,\r\n    });\r\n  }\r\n\r\n  if (error instanceof BadRequestError) {\r\n    return response.badRequest({\r\n      error: error.message,\r\n      ...error.payload,\r\n    });\r\n  }\r\n\r\n  if (error instanceof DatabaseWriterValidationError) {\r\n    return response.badRequest({\r\n      errors: error.errors,\r\n    });\r\n  }\r\n\r\n  if (error instanceof ServerError) {\r\n    return response.serverError({\r\n      error: error.message,\r\n      ...error.payload,\r\n    });\r\n  }\r\n\r\n  console.log(error);\r\n\r\n  return response.badRequest({\r\n    error: error.message,\r\n    ...error.payload,\r\n  });\r\n}\r\n\r\n/**\r\n * Translate a keyword (uses request context for locale)\r\n */\r\nexport function t(keyword: string, placeholders?: any) {\r\n  return (\r\n    requestContextInstance.getRequest()?.trans(keyword, placeholders) ||\r\n    trans(keyword, placeholders)\r\n  );\r\n}\r\n\r\n/**\r\n * Get or compute a value from the request cache\r\n *\r\n * If the value exists in request, return it.\r\n * Otherwise, execute callback, store result in request, and return it.\r\n */\r\nexport async function fromRequest<T>(\r\n  key: string,\r\n  callback: (request?: Request) => Promise<T>,\r\n): Promise<T> {\r\n  const { request } = useRequestStore();\r\n\r\n  if (!request) return await callback();\r\n\r\n  if (request[key]) return request[key];\r\n\r\n  request[key] = await callback(request);\r\n\r\n  return request[key];\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAqCA,SAAS,qBAAqB,SAAkB,UAAoB;CAClE,MAAM,kBAAkB,OAAO,IAAI,kBAAkB,CAAC,CAAwB;CAE9E,IAAI,gBAAgB,YAAY,OAAO;CAEvC,MAAM,aAAa,gBAAgB,UAAU;CAE7C,SAAS,OAAO,YAAY,QAAQ,EAAE;AACxC;;;;;;AAOA,SAAgB,mBACd,SACA,UAC2B;CAC3B,qBAAqB,SAAS,QAAQ;CAItC,MAAM,mBAAmB,eAAe,YAAY;EAAE;EAAS;CAAS,CAAC;CAGzE,OAAO,eAAe,OAAO,kBAAkB,YAAY;EACzD,IAAI;GAEF,MAAM,SAAS,MAAM,QAAQ,cAAc;GAE3C,IAAI,QACF,OAAO;GAIT,QAAQ,QAAQ,mBAAmB,QAAQ,KAAK;GAEhD,MAAM,UAAU,QAAQ,WAAW;GAEnC,QAAQ,IAAI,qBAAqB,MAAM;GAEvC,MAAM,SAAS,MAAM,QAAQ,SAAS,QAAQ;GAE9C,QAAQ,IAAI,iCAAiC,SAAS;GAEtD,QAAQ,QAAQ,kBAAkB,QAAQ,KAAK;GAE/C,OAAO;EACT,SAAS,OAAY;GACnB,QAAQ,IAAI,GAAG,MAAM,YAAY,KAAK,oBAAoB,MAAM,WAAW,OAAO;GAClF,OAAO,mBAAmB,OAAO,QAAQ;EAC3C;CACF,CAAC;AACH;;;;;AAMA,SAAS,mBAAmB,OAAY,UAAsC;CAC5E,IAAI,iBAAiB,WAAW;EAC9B,MAAM,UAAyB,EAC7B,OAAO,MAAM,QACf;EACA,IAAI,MAAM,SACR,QAAQ,UAAU,MAAM;EAG1B,IAAI,YAAY,MAAM,eACpB,QAAQ,QAAQ,MAAM;EAGxB,OAAO,SAAS,cAAc,MAAM,MAAM,CAAC,CAAC,KAAK,OAAO;CAC1D;CAEA,IAAI,iBAAiB,uBACnB,OAAO,SAAS,SAAS;EACvB,OAAO,MAAM;EACb,GAAG,MAAM;CACX,CAAC;CAGH,IAAI,iBAAiB,mBACnB,OAAO,SAAS,aAAa;EAC3B,OAAO,MAAM;EACb,GAAG,MAAM;CACX,CAAC;CAGH,IAAI,iBAAiB,gBACnB,OAAO,SAAS,UAAU;EACxB,OAAO,MAAM;EACb,GAAG,MAAM;CACX,CAAC;CAGH,IAAI,iBAAiB,iBACnB,OAAO,SAAS,WAAW;EACzB,OAAO,MAAM;EACb,GAAG,MAAM;CACX,CAAC;CAGH,IAAI,iBAAiB,+BACnB,OAAO,SAAS,WAAW,EACzB,QAAQ,MAAM,OAChB,CAAC;CAGH,IAAI,iBAAiB,aACnB,OAAO,SAAS,YAAY;EAC1B,OAAO,MAAM;EACb,GAAG,MAAM;CACX,CAAC;CAGH,QAAQ,IAAI,KAAK;CAEjB,OAAO,SAAS,WAAW;EACzB,OAAO,MAAM;EACb,GAAG,MAAM;CACX,CAAC;AACH;;;;AAKA,SAAgB,EAAE,SAAiB,cAAoB;CACrD,OACEA,eAAuB,WAAW,CAAC,EAAE,MAAM,SAAS,YAAY,KAChE,MAAM,SAAS,YAAY;AAE/B;;;;;;;AAQA,eAAsB,YACpB,KACA,UACY;CACZ,MAAM,EAAE,YAAY,gBAAgB;CAEpC,IAAI,CAAC,SAAS,OAAO,MAAM,SAAS;CAEpC,IAAI,QAAQ,MAAM,OAAO,QAAQ;CAEjC,QAAQ,OAAO,MAAM,SAAS,OAAO;CAErC,OAAO,QAAQ;AACjB"}

package/esm/http/middleware/maintenance.middleware.mjs

@@ -1,6 +1,6 @@
 import { t } from "./inject-request-context.mjs";
 import { HttpErrorCodes } from "../error-codes.mjs";
-import baseConfig from "@mongez/config";
+import config from "@mongez/config";
 
 //#region ../core/src/http/middleware/maintenance.middleware.ts
 function isAllowlisted(path, patterns) {
@@ -31,11 +31,11 @@ function isAllowlisted(path, patterns) {
 */
 function maintenanceMiddleware(options = {}) {
 	return (request, response) => {
-		if (!baseConfig.get("http.maintenance.enabled", false)) return;
-		const allowlist = options.allowlist || baseConfig.get("http.maintenance.allowlist", ["/health"]);
+		if (!config.get("http.maintenance.enabled", false)) return;
+		const allowlist = options.allowlist || config.get("http.maintenance.allowlist", ["/health"]);
 		const pathname = request.path.split("?")[0];
 		if (isAllowlisted(pathname, allowlist)) return;
-		const retryAfter = options.retryAfter || baseConfig.get("http.maintenance.retryAfter", 60);
+		const retryAfter = options.retryAfter || config.get("http.maintenance.retryAfter", 60);
 		response.header("Retry-After", retryAfter);
 		return response.serviceUnavailable({
 			error: options.errorMessage || t("http.maintenance"),

package/esm/http/middleware/maintenance.middleware.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"maintenance.middleware.mjs","names":["config"],"sources":["../../../../../../../../core/src/http/middleware/maintenance.middleware.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport type { Middleware } from \"../../router\";\nimport { HttpErrorCodes } from \"../error-codes\";\nimport { t } from \"./inject-request-context\";\n\n/**\n * Options for the maintenance middleware.\n */\nexport type MaintenanceOptions = {\n  /**\n   * Path prefixes (ending in `*`) or exact paths to bypass even when\n   * maintenance is on. Falls back to `http.maintenance.allowlist`, then\n   * `[\"/health\"]`.\n   *\n   * @example\n   * allowlist: [\"/health\", \"/admin/*\", \"/webhooks/stripe\"]\n   */\n  allowlist?: string[];\n  /**\n   * Seconds advertised in the `Retry-After` header. Falls back to\n   * `http.maintenance.retryAfter`, then `60`.\n   */\n  retryAfter?: number;\n  /**\n   * Override the default error message.\n   */\n  errorMessage?: string;\n};\n\nfunction isAllowlisted(path: string, patterns: string[]) {\n  return patterns.some((pattern) => {\n    if (pattern.endsWith(\"*\")) {\n      return path.startsWith(pattern.slice(0, -1));\n    }\n\n    return path === pattern;\n  });\n}\n\n/**\n * Return 503 + `Retry-After` for every request when `http.maintenance.enabled`\n * is true, except for paths matching the allowlist.\n *\n * Designed for app-wide registration via `http.middleware.all`. Toggled via\n * config — flipping the flag requires a restart (no runtime hot-flip yet).\n * Allowlist defaults to `[\"/health\"]` so health checks still pass during\n * planned downtime.\n *\n * @example\n * // src/config/http.ts\n * import { middleware } from \"@warlock.js/core\";\n *\n * export default {\n *   maintenance: { enabled: env(\"MAINTENANCE_MODE\") === \"true\" },\n *   middleware: {\n *     all: [middleware.maintenance({ allowlist: [\"/health\", \"/admin/*\"] })],\n *   },\n * };\n */\nexport function maintenanceMiddleware(options: MaintenanceOptions = {}): Middleware {\n  return (request, response) => {\n    const enabled = config.get(\"http.maintenance.enabled\", false);\n\n    if (!enabled) return;\n\n    const allowlist =\n      options.allowlist || config.get(\"http.maintenance.allowlist\", [\"/health\"]);\n\n    // `request.path` includes the query string, but allowlist entries are\n    // path-only (\"/webhooks/stripe\"), so strip the query before matching —\n    // otherwise \"/webhooks/stripe?sig=...\" never matches its exact entry.\n    const pathname = request.path.split(\"?\")[0];\n\n    if (isAllowlisted(pathname, allowlist)) return;\n\n    const retryAfter =\n      options.retryAfter || config.get(\"http.maintenance.retryAfter\", 60);\n\n    response.header(\"Retry-After\", retryAfter);\n\n    return response.serviceUnavailable({\n      error: options.errorMessage || t(\"http.maintenance\"),\n      errorCode: HttpErrorCodes.Maintenance,\n    });\n  };\n}\n"],"mappings":";;;;;AA6BA,SAAS,cAAc,MAAc,UAAoB;CACvD,OAAO,SAAS,MAAM,YAAY;EAChC,IAAI,QAAQ,SAAS,GAAG,GACtB,OAAO,KAAK,WAAW,QAAQ,MAAM,GAAG,EAAE,CAAC;EAG7C,OAAO,SAAS;CAClB,CAAC;AACH;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,sBAAsB,UAA8B,CAAC,GAAe;CAClF,QAAQ,SAAS,aAAa;EAG5B,IAAI,CAFYA,WAAO,IAAI,4BAA4B,KAE5C,GAAG;EAEd,MAAM,YACJ,QAAQ,aAAaA,WAAO,IAAI,8BAA8B,CAAC,SAAS,CAAC;EAK3E,MAAM,WAAW,QAAQ,KAAK,MAAM,GAAG,CAAC,CAAC;EAEzC,IAAI,cAAc,UAAU,SAAS,GAAG;EAExC,MAAM,aACJ,QAAQ,cAAcA,WAAO,IAAI,+BAA+B,EAAE;EAEpE,SAAS,OAAO,eAAe,UAAU;EAEzC,OAAO,SAAS,mBAAmB;GACjC,OAAO,QAAQ,gBAAgB,EAAE,kBAAkB;GACnD;EACF,CAAC;CACH;AACF"}
+{"version":3,"file":"maintenance.middleware.mjs","names":[],"sources":["../../../../../../../../core/src/http/middleware/maintenance.middleware.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport type { Middleware } from \"../../router\";\nimport { HttpErrorCodes } from \"../error-codes\";\nimport { t } from \"./inject-request-context\";\n\n/**\n * Options for the maintenance middleware.\n */\nexport type MaintenanceOptions = {\n  /**\n   * Path prefixes (ending in `*`) or exact paths to bypass even when\n   * maintenance is on. Falls back to `http.maintenance.allowlist`, then\n   * `[\"/health\"]`.\n   *\n   * @example\n   * allowlist: [\"/health\", \"/admin/*\", \"/webhooks/stripe\"]\n   */\n  allowlist?: string[];\n  /**\n   * Seconds advertised in the `Retry-After` header. Falls back to\n   * `http.maintenance.retryAfter`, then `60`.\n   */\n  retryAfter?: number;\n  /**\n   * Override the default error message.\n   */\n  errorMessage?: string;\n};\n\nfunction isAllowlisted(path: string, patterns: string[]) {\n  return patterns.some((pattern) => {\n    if (pattern.endsWith(\"*\")) {\n      return path.startsWith(pattern.slice(0, -1));\n    }\n\n    return path === pattern;\n  });\n}\n\n/**\n * Return 503 + `Retry-After` for every request when `http.maintenance.enabled`\n * is true, except for paths matching the allowlist.\n *\n * Designed for app-wide registration via `http.middleware.all`. Toggled via\n * config — flipping the flag requires a restart (no runtime hot-flip yet).\n * Allowlist defaults to `[\"/health\"]` so health checks still pass during\n * planned downtime.\n *\n * @example\n * // src/config/http.ts\n * import { middleware } from \"@warlock.js/core\";\n *\n * export default {\n *   maintenance: { enabled: env(\"MAINTENANCE_MODE\") === \"true\" },\n *   middleware: {\n *     all: [middleware.maintenance({ allowlist: [\"/health\", \"/admin/*\"] })],\n *   },\n * };\n */\nexport function maintenanceMiddleware(options: MaintenanceOptions = {}): Middleware {\n  return (request, response) => {\n    const enabled = config.get(\"http.maintenance.enabled\", false);\n\n    if (!enabled) return;\n\n    const allowlist =\n      options.allowlist || config.get(\"http.maintenance.allowlist\", [\"/health\"]);\n\n    // `request.path` includes the query string, but allowlist entries are\n    // path-only (\"/webhooks/stripe\"), so strip the query before matching —\n    // otherwise \"/webhooks/stripe?sig=...\" never matches its exact entry.\n    const pathname = request.path.split(\"?\")[0];\n\n    if (isAllowlisted(pathname, allowlist)) return;\n\n    const retryAfter =\n      options.retryAfter || config.get(\"http.maintenance.retryAfter\", 60);\n\n    response.header(\"Retry-After\", retryAfter);\n\n    return response.serviceUnavailable({\n      error: options.errorMessage || t(\"http.maintenance\"),\n      errorCode: HttpErrorCodes.Maintenance,\n    });\n  };\n}\n"],"mappings":";;;;;AA6BA,SAAS,cAAc,MAAc,UAAoB;CACvD,OAAO,SAAS,MAAM,YAAY;EAChC,IAAI,QAAQ,SAAS,GAAG,GACtB,OAAO,KAAK,WAAW,QAAQ,MAAM,GAAG,EAAE,CAAC;EAG7C,OAAO,SAAS;CAClB,CAAC;AACH;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,sBAAsB,UAA8B,CAAC,GAAe;CAClF,QAAQ,SAAS,aAAa;EAG5B,IAAI,CAFY,OAAO,IAAI,4BAA4B,KAE5C,GAAG;EAEd,MAAM,YACJ,QAAQ,aAAa,OAAO,IAAI,8BAA8B,CAAC,SAAS,CAAC;EAK3E,MAAM,WAAW,QAAQ,KAAK,MAAM,GAAG,CAAC,CAAC;EAEzC,IAAI,cAAc,UAAU,SAAS,GAAG;EAExC,MAAM,aACJ,QAAQ,cAAc,OAAO,IAAI,+BAA+B,EAAE;EAEpE,SAAS,OAAO,eAAe,UAAU;EAEzC,OAAO,SAAS,mBAAmB;GACjC,OAAO,QAAQ,gBAAgB,EAAE,kBAAkB;GACnD;EACF,CAAC;CACH;AACF"}

package/esm/http/plugins.mjs

@@ -1,6 +1,6 @@
 import { rootPath } from "../utils/paths.mjs";
 import "../utils/index.mjs";
-import baseConfig from "@mongez/config";
+import config from "@mongez/config";
 import fastifyMultipart from "@fastify/multipart";
 
 //#region ../core/src/http/plugins.ts
@@ -10,25 +10,25 @@ const defaultCorsOptions = {
 };
 async function registerHttpPlugins(server) {
 	server.register(import("@fastify/rate-limit"), {
-		max: baseConfig.get("http.rateLimit.max", 60),
-		timeWindow: baseConfig.get("http.rateLimit.duration", 60 * 1e3)
+		max: config.get("http.rateLimit.max", 60),
+		timeWindow: config.get("http.rateLimit.duration", 60 * 1e3)
 	});
 	const corsOptions = {
-		...baseConfig.get("http.cors", {}),
+		...config.get("http.cors", {}),
 		...defaultCorsOptions
 	};
 	server.register(import("@fastify/cors"), corsOptions);
 	server.register(fastifyMultipart, {
 		attachFieldsToBody: true,
-		limits: { fileSize: baseConfig.get("http.fileUploadLimit", 10 * 1024 * 1024) }
+		limits: { fileSize: config.get("http.fileUploadLimit", 10 * 1024 * 1024) }
 	});
 	server.register(import("@fastify/static"), {
-		root: baseConfig.get("storage.publicRoot", rootPath("public")),
-		prefix: baseConfig.get("storage.publicPrefix", "/public/")
+		root: config.get("storage.publicRoot", rootPath("public")),
+		prefix: config.get("storage.publicPrefix", "/public/")
 	});
 	server.register(import("@fastify/cookie"), {
-		secret: baseConfig.get("http.cookies.secret"),
-		parseOptions: baseConfig.get("http.cookies.options", {})
+		secret: config.get("http.cookies.secret"),
+		parseOptions: config.get("http.cookies.options", {})
 	});
 }
 

package/esm/http/plugins.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"plugins.mjs","names":["config"],"sources":["../../../../../../../core/src/http/plugins.ts"],"sourcesContent":["import type { FastifyCorsOptions } from \"@fastify/cors\";\nimport fastifyMultipart from \"@fastify/multipart\";\nimport config from \"@mongez/config\";\nimport { rootPath } from \"../utils\";\nimport type { FastifyInstance } from \"./server\";\n\nconst defaultCorsOptions: FastifyCorsOptions = {\n  origin: \"*\",\n  methods: \"*\",\n};\n\nexport async function registerHttpPlugins(server: FastifyInstance) {\n  // 👇🏻 register rate-limit plugin\n  server.register(import(\"@fastify/rate-limit\"), {\n    // max requests per time window\n    max: config.get(\"http.rateLimit.max\", 60),\n    // maximum time that is will allow max requests\n    timeWindow: config.get(\"http.rateLimit.duration\", 60 * 1000),\n  });\n\n  // 👇🏻 register cors plugin\n  const corsOptions: FastifyCorsOptions | undefined = {\n    ...config.get(\"http.cors\", {}),\n    ...defaultCorsOptions,\n  };\n\n  server.register(import(\"@fastify/cors\"), corsOptions);\n\n  // 👇🏻 import multipart plugin\n  server.register(fastifyMultipart, {\n    attachFieldsToBody: true,\n    limits: {\n      // file size could be up to 10MB\n      fileSize: config.get(\"http.fileUploadLimit\", 10 * 1024 * 1024),\n    },\n  });\n\n  server.register(import(\"@fastify/static\"), {\n    root: config.get(\"storage.publicRoot\", rootPath(\"public\")),\n    prefix: config.get(\"storage.publicPrefix\", \"/public/\"),\n  });\n\n  // 👇🏻 register cookie plugin\n  server.register(import(\"@fastify/cookie\"), {\n    secret: config.get(\"http.cookies.secret\"), // Optional: allow signed cookies\n    parseOptions: config.get(\"http.cookies.options\", {}),\n  });\n}\n"],"mappings":";;;;;;AAMA,MAAM,qBAAyC;CAC7C,QAAQ;CACR,SAAS;AACX;AAEA,eAAsB,oBAAoB,QAAyB;CAEjE,OAAO,SAAS,OAAO,wBAAwB;EAE7C,KAAKA,WAAO,IAAI,sBAAsB,EAAE;EAExC,YAAYA,WAAO,IAAI,2BAA2B,KAAK,GAAI;CAC7D,CAAC;CAGD,MAAM,cAA8C;EAClD,GAAGA,WAAO,IAAI,aAAa,CAAC,CAAC;EAC7B,GAAG;CACL;CAEA,OAAO,SAAS,OAAO,kBAAkB,WAAW;CAGpD,OAAO,SAAS,kBAAkB;EAChC,oBAAoB;EACpB,QAAQ,EAEN,UAAUA,WAAO,IAAI,wBAAwB,KAAK,OAAO,IAAI,EAC/D;CACF,CAAC;CAED,OAAO,SAAS,OAAO,oBAAoB;EACzC,MAAMA,WAAO,IAAI,sBAAsB,SAAS,QAAQ,CAAC;EACzD,QAAQA,WAAO,IAAI,wBAAwB,UAAU;CACvD,CAAC;CAGD,OAAO,SAAS,OAAO,oBAAoB;EACzC,QAAQA,WAAO,IAAI,qBAAqB;EACxC,cAAcA,WAAO,IAAI,wBAAwB,CAAC,CAAC;CACrD,CAAC;AACH"}
+{"version":3,"file":"plugins.mjs","names":[],"sources":["../../../../../../../core/src/http/plugins.ts"],"sourcesContent":["import type { FastifyCorsOptions } from \"@fastify/cors\";\nimport fastifyMultipart from \"@fastify/multipart\";\nimport config from \"@mongez/config\";\nimport { rootPath } from \"../utils\";\nimport type { FastifyInstance } from \"./server\";\n\nconst defaultCorsOptions: FastifyCorsOptions = {\n  origin: \"*\",\n  methods: \"*\",\n};\n\nexport async function registerHttpPlugins(server: FastifyInstance) {\n  // 👇🏻 register rate-limit plugin\n  server.register(import(\"@fastify/rate-limit\"), {\n    // max requests per time window\n    max: config.get(\"http.rateLimit.max\", 60),\n    // maximum time that is will allow max requests\n    timeWindow: config.get(\"http.rateLimit.duration\", 60 * 1000),\n  });\n\n  // 👇🏻 register cors plugin\n  const corsOptions: FastifyCorsOptions | undefined = {\n    ...config.get(\"http.cors\", {}),\n    ...defaultCorsOptions,\n  };\n\n  server.register(import(\"@fastify/cors\"), corsOptions);\n\n  // 👇🏻 import multipart plugin\n  server.register(fastifyMultipart, {\n    attachFieldsToBody: true,\n    limits: {\n      // file size could be up to 10MB\n      fileSize: config.get(\"http.fileUploadLimit\", 10 * 1024 * 1024),\n    },\n  });\n\n  server.register(import(\"@fastify/static\"), {\n    root: config.get(\"storage.publicRoot\", rootPath(\"public\")),\n    prefix: config.get(\"storage.publicPrefix\", \"/public/\"),\n  });\n\n  // 👇🏻 register cookie plugin\n  server.register(import(\"@fastify/cookie\"), {\n    secret: config.get(\"http.cookies.secret\"), // Optional: allow signed cookies\n    parseOptions: config.get(\"http.cookies.options\", {}),\n  });\n}\n"],"mappings":";;;;;;AAMA,MAAM,qBAAyC;CAC7C,QAAQ;CACR,SAAS;AACX;AAEA,eAAsB,oBAAoB,QAAyB;CAEjE,OAAO,SAAS,OAAO,wBAAwB;EAE7C,KAAK,OAAO,IAAI,sBAAsB,EAAE;EAExC,YAAY,OAAO,IAAI,2BAA2B,KAAK,GAAI;CAC7D,CAAC;CAGD,MAAM,cAA8C;EAClD,GAAG,OAAO,IAAI,aAAa,CAAC,CAAC;EAC7B,GAAG;CACL;CAEA,OAAO,SAAS,OAAO,kBAAkB,WAAW;CAGpD,OAAO,SAAS,kBAAkB;EAChC,oBAAoB;EACpB,QAAQ,EAEN,UAAU,OAAO,IAAI,wBAAwB,KAAK,OAAO,IAAI,EAC/D;CACF,CAAC;CAED,OAAO,SAAS,OAAO,oBAAoB;EACzC,MAAM,OAAO,IAAI,sBAAsB,SAAS,QAAQ,CAAC;EACzD,QAAQ,OAAO,IAAI,wBAAwB,UAAU;CACvD,CAAC;CAGD,OAAO,SAAS,OAAO,oBAAoB;EACzC,QAAQ,OAAO,IAAI,qBAAqB;EACxC,cAAc,OAAO,IAAI,wBAAwB,CAAC,CAAC;CACrD,CAAC;AACH"}

package/esm/http/port-preflight.d.mts

@@ -0,0 +1,34 @@
+//#region ../core/src/http/port-preflight.d.ts
+/**
+ * Raised when a port the framework is about to bind is already taken.
+ *
+ * Carries the port and host so a caller can report them without parsing the
+ * message, and its message is the developer-facing instruction — the whole
+ * point of preflighting is that nobody has to decode a raw `EADDRINUSE`.
+ */
+declare class PortInUseError extends Error {
+  readonly port: number;
+  readonly host: string;
+  constructor(port: number, host: string);
+}
+/**
+ * Probe a TCP port by attempting a bind and immediately releasing it.
+ *
+ * @returns `true` when the port is free, `false` when it is taken or the
+ * process is not allowed to bind it. Any other bind failure is re-thrown —
+ * an unreadable network error must not be reported as "port in use".
+ */
+declare function isPortAvailable(port: number, host?: string): Promise<boolean>;
+/**
+ * Assert a port is free before something binds it.
+ *
+ * Run this ahead of the actual `listen()` so a collision surfaces as an
+ * instruction the developer can act on, instead of a raw `EADDRINUSE` thrown
+ * from deep inside the HTTP stack.
+ *
+ * @throws {PortInUseError} when the port is taken.
+ */
+declare function assertPortIsAvailable(port: number, host?: string): Promise<void>;
+//#endregion
+export { PortInUseError, assertPortIsAvailable, isPortAvailable };
+//# sourceMappingURL=port-preflight.d.mts.map

package/esm/http/port-preflight.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-preflight.d.mts","names":[],"sources":["../../../../../../../core/src/http/port-preflight.ts"],"mappings":";;AAcA;;;;;;cAAa,cAAA,SAAuB,KAAK;EAAA,SAErB,IAAA;EAAA,SACA,IAAA;cADA,IAAA,UACA,IAAA;AAAA;AAAY;AAiBhC;;;;;;AAjBgC,iBAiBhB,eAAA,CACd,IAAA,UACA,IAAA,YACC,OAAO;;AAAA;AAmCV;;;;;;;iBAAsB,qBAAA,CACpB,IAAA,UACA,IAAA,YACC,OAAO"}

package/esm/http/port-preflight.mjs

@@ -0,0 +1,66 @@
+import { createServer } from "node:net";
+
+//#region ../core/src/http/port-preflight.ts
+/**
+* Host used when the caller has no configured bind host.
+*/
+const DEFAULT_PROBE_HOST = "localhost";
+/**
+* Raised when a port the framework is about to bind is already taken.
+*
+* Carries the port and host so a caller can report them without parsing the
+* message, and its message is the developer-facing instruction — the whole
+* point of preflighting is that nobody has to decode a raw `EADDRINUSE`.
+*/
+var PortInUseError = class extends Error {
+	constructor(port, host) {
+		super(`Port ${port} is already in use on ${host}. Stop the dev server (or whatever else is listening on port ${port}) and run again, or start on a free port — e.g. startHttpTestServer({ port: ${port + 1} }).`);
+		this.port = port;
+		this.host = host;
+		this.name = "PortInUseError";
+	}
+};
+/**
+* Probe a TCP port by attempting a bind and immediately releasing it.
+*
+* @returns `true` when the port is free, `false` when it is taken or the
+* process is not allowed to bind it. Any other bind failure is re-thrown —
+* an unreadable network error must not be reported as "port in use".
+*/
+function isPortAvailable(port, host = DEFAULT_PROBE_HOST) {
+	return new Promise((resolve, reject) => {
+		const probe = createServer();
+		probe.unref();
+		probe.once("error", (error) => {
+			if (error.code === "EADDRINUSE" || error.code === "EACCES") {
+				resolve(false);
+				return;
+			}
+			reject(error);
+		});
+		probe.once("listening", () => {
+			probe.close(() => resolve(true));
+		});
+		probe.listen({
+			port,
+			host,
+			exclusive: true
+		});
+	});
+}
+/**
+* Assert a port is free before something binds it.
+*
+* Run this ahead of the actual `listen()` so a collision surfaces as an
+* instruction the developer can act on, instead of a raw `EADDRINUSE` thrown
+* from deep inside the HTTP stack.
+*
+* @throws {PortInUseError} when the port is taken.
+*/
+async function assertPortIsAvailable(port, host = DEFAULT_PROBE_HOST) {
+	if (!await isPortAvailable(port, host)) throw new PortInUseError(port, host);
+}
+
+//#endregion
+export { PortInUseError, assertPortIsAvailable, isPortAvailable };
+//# sourceMappingURL=port-preflight.mjs.map

package/esm/http/port-preflight.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-preflight.mjs","names":[],"sources":["../../../../../../../core/src/http/port-preflight.ts"],"sourcesContent":["import { createServer } from \"node:net\";\n\n/**\n * Host used when the caller has no configured bind host.\n */\nconst DEFAULT_PROBE_HOST = \"localhost\";\n\n/**\n * Raised when a port the framework is about to bind is already taken.\n *\n * Carries the port and host so a caller can report them without parsing the\n * message, and its message is the developer-facing instruction — the whole\n * point of preflighting is that nobody has to decode a raw `EADDRINUSE`.\n */\nexport class PortInUseError extends Error {\n  public constructor(\n    public readonly port: number,\n    public readonly host: string,\n  ) {\n    super(\n      `Port ${port} is already in use on ${host}. Stop the dev server (or whatever else is listening on port ${port}) and run again, or start on a free port — e.g. startHttpTestServer({ port: ${port + 1} }).`,\n    );\n\n    this.name = \"PortInUseError\";\n  }\n}\n\n/**\n * Probe a TCP port by attempting a bind and immediately releasing it.\n *\n * @returns `true` when the port is free, `false` when it is taken or the\n * process is not allowed to bind it. Any other bind failure is re-thrown —\n * an unreadable network error must not be reported as \"port in use\".\n */\nexport function isPortAvailable(\n  port: number,\n  host: string = DEFAULT_PROBE_HOST,\n): Promise<boolean> {\n  return new Promise((resolve, reject) => {\n    const probe = createServer();\n\n    probe.unref();\n\n    probe.once(\"error\", (error: NodeJS.ErrnoException) => {\n      if (error.code === \"EADDRINUSE\" || error.code === \"EACCES\") {\n        resolve(false);\n\n        return;\n      }\n\n      reject(error);\n    });\n\n    probe.once(\"listening\", () => {\n      probe.close(() => resolve(true));\n    });\n\n    // `exclusive` refuses a shared bind, which is what makes the probe honest:\n    // with load balancing enabled a second bind on a served port can succeed.\n    probe.listen({ port, host, exclusive: true });\n  });\n}\n\n/**\n * Assert a port is free before something binds it.\n *\n * Run this ahead of the actual `listen()` so a collision surfaces as an\n * instruction the developer can act on, instead of a raw `EADDRINUSE` thrown\n * from deep inside the HTTP stack.\n *\n * @throws {PortInUseError} when the port is taken.\n */\nexport async function assertPortIsAvailable(\n  port: number,\n  host: string = DEFAULT_PROBE_HOST,\n): Promise<void> {\n  const available = await isPortAvailable(port, host);\n\n  if (!available) {\n    throw new PortInUseError(port, host);\n  }\n}\n"],"mappings":";;;;;;AAKA,MAAM,qBAAqB;;;;;;;;AAS3B,IAAa,iBAAb,cAAoC,MAAM;CACxC,AAAO,YACL,AAAgB,MAChB,AAAgB,MAChB;EACA,MACE,QAAQ,KAAK,wBAAwB,KAAK,+DAA+D,KAAK,8EAA8E,OAAO,EAAE,KACvM;EALgB;EACA;EAMhB,KAAK,OAAO;CACd;AACF;;;;;;;;AASA,SAAgB,gBACd,MACA,OAAe,oBACG;CAClB,OAAO,IAAI,SAAS,SAAS,WAAW;EACtC,MAAM,QAAQ,aAAa;EAE3B,MAAM,MAAM;EAEZ,MAAM,KAAK,UAAU,UAAiC;GACpD,IAAI,MAAM,SAAS,gBAAgB,MAAM,SAAS,UAAU;IAC1D,QAAQ,KAAK;IAEb;GACF;GAEA,OAAO,KAAK;EACd,CAAC;EAED,MAAM,KAAK,mBAAmB;GAC5B,MAAM,YAAY,QAAQ,IAAI,CAAC;EACjC,CAAC;EAID,MAAM,OAAO;GAAE;GAAM;GAAM,WAAW;EAAK,CAAC;CAC9C,CAAC;AACH;;;;;;;;;;AAWA,eAAsB,sBACpB,MACA,OAAe,oBACA;CAGf,IAAI,CAAC,MAFmB,gBAAgB,MAAM,IAAI,GAGhD,MAAM,IAAI,eAAe,MAAM,IAAI;AAEvC"}

package/esm/http/response.mjs

@@ -2,7 +2,7 @@ import { Application } from "../application/application.mjs";
 import { StorageFile } from "../storage/storage-file.mjs";
 import "../storage/index.mjs";
 import { renderReact } from "../react/index.mjs";
-import baseConfig from "@mongez/config";
+import config from "@mongez/config";
 import { log } from "@warlock.js/logger";
 import path from "path";
 import { isIterable, isPlainObject, isScalar } from "@mongez/supportive-is";
@@ -193,7 +193,7 @@ var Response = class Response {
 	* Make a log message
 	*/
 	log(message, level = "info") {
-		if (!baseConfig.get("http.log")) return;
+		if (!config.get("http.log")) return;
 		log.log({
 			module: "response",
 			action: this.route.method + " " + this.route.path.replace("/*", "") + `:${this.request.id}`,
@@ -594,7 +594,7 @@ var Response = class Response {
 	*/
 	cookie(name, value, options = {}) {
 		const { raw, ...cookieOptions } = options;
-		const defaultOptions = baseConfig.get("http.cookies.options", {});
+		const defaultOptions = config.get("http.cookies.options", {});
 		const serializedValue = raw ? String(value) : JSON.stringify(value);
 		this.baseResponse.setCookie(name, serializedValue, {
 			...secureCookieDefaults(),
@@ -610,7 +610,7 @@ var Response = class Response {
 	* response.clearCookie('token', { path: '/' });
 	*/
 	clearCookie(name, options) {
-		const defaultOptions = baseConfig.get("http.cookies.options", {});
+		const defaultOptions = config.get("http.cookies.options", {});
 		this.baseResponse.clearCookie(name, {
 			...defaultOptions,
 			...options
@@ -883,7 +883,7 @@ var Response = class Response {
 	* Mark the response as failed
 	*/
 	failedSchema(result) {
-		const { errors, inputKey, inputError, status } = baseConfig.get("validation.response", {
+		const { errors, inputKey, inputError, status } = config.get("validation.response", {
 			errors: "errors",
 			inputKey: "input",
 			inputError: "error",