@warlock.js/core 5.29.0 → 5.31.0

package/esm/storage/utils/mime.d.mts

@@ -1,4 +1,4 @@
-//#region ../core/src/storage/utils/mime.d.ts
+//#region ../../packages/core/src/storage/utils/mime.d.ts
 /**
  * Get MIME type from file path or extension
  *

package/esm/storage/utils/mime.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"mime.d.mts","names":[],"sources":["../../../../../../../../core/src/storage/utils/mime.ts"],"mappings":";;AAcA;;;;AAAwC;iBAAxB,WAAA,CAAY,IAAY;;;;cAO3B,SAAA;EAAA"}
+{"version":3,"file":"mime.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/storage/utils/mime.ts"],"mappings":";;AAcA;;;;AAAwC;iBAAxB,WAAA,CAAY,IAAY;;;;cAO3B,SAAA;EAAA"}

package/esm/storage/utils/mime.mjs

@@ -1,6 +1,6 @@
 import mime from "mime";
 
-//#region ../core/src/storage/utils/mime.ts
+//#region ../../packages/core/src/storage/utils/mime.ts
 /**
 * MIME type utilities
 *

package/esm/storage/utils/mime.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mime.mjs","names":[],"sources":["../../../../../../../../core/src/storage/utils/mime.ts"],"sourcesContent":["/**\n * MIME type utilities\n *\n * This module wraps the mime package to avoid type conflicts\n * with @types/send which has its own @types/mime dependency.\n */\nimport mime from \"mime\";\n\n/**\n * Get MIME type from file path or extension\n *\n * @param path - File path or extension\n * @returns MIME type or \"application/octet-stream\" if unknown\n */\nexport function getMimeType(path: string): string {\n  return mime.getType(path) || \"application/octet-stream\";\n}\n\n/**\n * Common MIME type constants\n */\nexport const MimeTypes = {\n  // Images\n  jpeg: \"image/jpeg\",\n  png: \"image/png\",\n  gif: \"image/gif\",\n  webp: \"image/webp\",\n  svg: \"image/svg+xml\",\n  ico: \"image/x-icon\",\n\n  // Documents\n  pdf: \"application/pdf\",\n  txt: \"text/plain\",\n  html: \"text/html\",\n  css: \"text/css\",\n  js: \"application/javascript\",\n  json: \"application/json\",\n  xml: \"application/xml\",\n\n  // Archives\n  zip: \"application/zip\",\n  gzip: \"application/gzip\",\n\n  // Media\n  mp3: \"audio/mpeg\",\n  mp4: \"video/mp4\",\n  webm: \"video/webm\",\n  ogg: \"audio/ogg\",\n\n  // Binary\n  binary: \"application/octet-stream\",\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;AAcA,SAAgB,YAAY,MAAsB;CAChD,OAAO,KAAK,QAAQ,IAAI,KAAK;AAC/B;;;;AAKA,MAAa,YAAY;CAEvB,MAAM;CACN,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CACL,KAAK;CAGL,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CACL,IAAI;CACJ,MAAM;CACN,KAAK;CAGL,KAAK;CACL,MAAM;CAGN,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CAGL,QAAQ;AACV"}
+{"version":3,"file":"mime.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/storage/utils/mime.ts"],"sourcesContent":["/**\n * MIME type utilities\n *\n * This module wraps the mime package to avoid type conflicts\n * with @types/send which has its own @types/mime dependency.\n */\nimport mime from \"mime\";\n\n/**\n * Get MIME type from file path or extension\n *\n * @param path - File path or extension\n * @returns MIME type or \"application/octet-stream\" if unknown\n */\nexport function getMimeType(path: string): string {\n  return mime.getType(path) || \"application/octet-stream\";\n}\n\n/**\n * Common MIME type constants\n */\nexport const MimeTypes = {\n  // Images\n  jpeg: \"image/jpeg\",\n  png: \"image/png\",\n  gif: \"image/gif\",\n  webp: \"image/webp\",\n  svg: \"image/svg+xml\",\n  ico: \"image/x-icon\",\n\n  // Documents\n  pdf: \"application/pdf\",\n  txt: \"text/plain\",\n  html: \"text/html\",\n  css: \"text/css\",\n  js: \"application/javascript\",\n  json: \"application/json\",\n  xml: \"application/xml\",\n\n  // Archives\n  zip: \"application/zip\",\n  gzip: \"application/gzip\",\n\n  // Media\n  mp3: \"audio/mpeg\",\n  mp4: \"video/mp4\",\n  webm: \"video/webm\",\n  ogg: \"audio/ogg\",\n\n  // Binary\n  binary: \"application/octet-stream\",\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;AAcA,SAAgB,YAAY,MAAsB;CAChD,OAAO,KAAK,QAAQ,IAAI,KAAK;AAC/B;;;;AAKA,MAAa,YAAY;CAEvB,MAAM;CACN,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CACL,KAAK;CAGL,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CACL,IAAI;CACJ,MAAM;CACN,KAAK;CAGL,KAAK;CACL,MAAM;CAGN,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CAGL,QAAQ;AACV"}

package/esm/storage/utils/safe-fetch.d.mts

@@ -1,6 +1,6 @@
 import { isPrivateOrReservedIp } from "./classify-ip-address.mjs";
 
-//#region ../core/src/storage/utils/safe-fetch.d.ts
+//#region ../../packages/core/src/storage/utils/safe-fetch.d.ts
 /**
  * Options controlling a guarded outbound fetch. Every field is optional;
  * {@link resolveFetchPolicy} fills safe defaults. The defaults are

package/esm/storage/utils/safe-fetch.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"safe-fetch.d.mts","names":[],"sources":["../../../../../../../../core/src/storage/utils/safe-fetch.ts"],"mappings":";;;;;AAoCA;;;;;KAAY,gBAAA;EAaV;;;;EARA,iBAAA;EAkBoB;AA2GtB;;;;EAvHE,QAAA,WAwHQ;EAtHR,SAAA;EAwHA;;;;EAnHA,cAAA;EA2IoB;;;;EAtIpB,KAAA,UAAe,KAAK;AAAA;;;;;;KA2GV,eAAA;EACV,MAAA,EAAQ,MAAM;EACd,WAAA;EACA,MAAA;EACA,UAAA;EACA,EAAA;AAAA;;;;;;;;;;;;;;;;;;;;iBAsBoB,iBAAA,CACpB,MAAA,UACA,OAAA,GAAS,gBAAA,GACR,OAAA,CAAQ,eAAA"}
+{"version":3,"file":"safe-fetch.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/storage/utils/safe-fetch.ts"],"mappings":";;;;;AAoCA;;;;;KAAY,gBAAA;EAaV;;;;EARA,iBAAA;EAkBoB;AA2GtB;;;;EAvHE,QAAA,WAwHQ;EAtHR,SAAA;EAwHA;;;;EAnHA,cAAA;EA2IoB;;;;EAtIpB,KAAA,UAAe,KAAK;AAAA;;;;;;KA2GV,eAAA;EACV,MAAA,EAAQ,MAAM;EACd,WAAA;EACA,MAAA;EACA,UAAA;EACA,EAAA;AAAA;;;;;;;;;;;;;;;;;;;;iBAsBoB,iBAAA,CACpB,MAAA,UACA,OAAA,GAAS,gBAAA,GACR,OAAA,CAAQ,eAAA"}

package/esm/storage/utils/safe-fetch.mjs

@@ -3,7 +3,7 @@ import { isPrivateOrReservedIp } from "./classify-ip-address.mjs";
 import { lookup } from "node:dns/promises";
 import { isIP } from "node:net";
 
-//#region ../core/src/storage/utils/safe-fetch.ts
+//#region ../../packages/core/src/storage/utils/safe-fetch.ts
 /**
 * SSRF / resource-exhaustion guard for storage's outbound downloads
 * (`putFromUrl`).

package/esm/storage/utils/safe-fetch.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"safe-fetch.mjs","names":[],"sources":["../../../../../../../../core/src/storage/utils/safe-fetch.ts"],"sourcesContent":["import { lookup } from \"node:dns/promises\";\nimport { isIP } from \"node:net\";\nimport { isPrivateOrReservedIp } from \"./classify-ip-address\";\nimport { StorageError } from \"./storage-error\";\n\n/**\n * SSRF / resource-exhaustion guard for storage's outbound downloads\n * (`putFromUrl`).\n *\n * NOTE: this MIRRORS `@warlock.js/ai`'s `src/security/private-ip.ts` and\n * `src/security/outbound-policy.ts`. It is duplicated here intentionally\n * because `@warlock.js/core` cannot depend on `@warlock.js/ai`. Pending\n * extraction of a shared security package, keep the two copies in sync.\n */\n\n/** 50 MiB — default cap on a downloaded body (storage files run larger than AI payloads). */\nconst DEFAULT_MAX_BYTES = 50 * 1024 * 1024;\n/** 30s — default per-request timeout. */\nconst DEFAULT_TIMEOUT_MS = 30_000;\n/**\n * Cap on the number of re-validated redirect hops. Mirrors\n * `@warlock.js/ai`'s `DEFAULT_MAX_REDIRECTS`\n * (ai/src/security/outbound-policy.ts:15).\n */\nconst DEFAULT_MAX_REDIRECTS = 5;\n\n/** 3xx statuses whose `Location` a follow re-issues — mirrors ai/src/security/outbound-policy.ts:18. */\nconst REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);\n\n/**\n * Options controlling a guarded outbound fetch. Every field is optional;\n * {@link resolveFetchPolicy} fills safe defaults. The defaults are\n * deliberately strict (https+http, private-IP deny ON, 30s timeout,\n * 50 MiB cap) so a caller that does not tune them still gets a hardened\n * request.\n */\nexport type SafeFetchOptions = {\n  /**\n   * Whether to ALLOW private / loopback / link-local / metadata hosts.\n   * Default `false` — the SSRF guard is on (private hosts are denied).\n   */\n  allowPrivateHosts?: boolean;\n  /**\n   * Maximum response body size in bytes. A declared `content-length` over\n   * this fails fast; otherwise the body is read with a running cap and the\n   * stream is aborted on overflow. Default `52_428_800` (50 MiB).\n   */\n  maxBytes?: number;\n  /** Per-request timeout in milliseconds. Default `30_000`. */\n  timeoutMs?: number;\n  /**\n   * URL schemes permitted for the request, compared case-insensitively.\n   * Default `[\"https\", \"http\"]`.\n   */\n  allowedSchemes?: string[];\n  /**\n   * Injected `fetch` implementation (for tests or proxies). Defaults to the\n   * global `fetch`.\n   */\n  fetch?: typeof fetch;\n};\n\n/** {@link SafeFetchOptions} with every default resolved — never partial. */\ntype ResolvedFetchPolicy = {\n  allowPrivateHosts: boolean;\n  maxBytes: number;\n  timeoutMs: number;\n  allowedSchemes: string[];\n  fetch: typeof fetch;\n};\n\n/**\n * Fill a {@link SafeFetchOptions} with strict defaults: https+http,\n * private-IP deny on, 30s timeout, 50 MiB cap, global `fetch`.\n */\nfunction resolveFetchPolicy(options: SafeFetchOptions = {}): ResolvedFetchPolicy {\n  return {\n    allowPrivateHosts: options.allowPrivateHosts ?? false,\n    maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,\n    timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    allowedSchemes: options.allowedSchemes ?? [\"https\", \"http\"],\n    fetch: options.fetch ?? globalThis.fetch,\n  };\n}\n\nexport { isPrivateOrReservedIp };\n\n/** Strip the `[ ]` IPv6 brackets `URL.hostname` keeps. */\nfunction stripBrackets(host: string): string {\n  return host.startsWith(\"[\") && host.endsWith(\"]\") ? host.slice(1, -1) : host;\n}\n\n/**\n * Reject when `host` is — or resolves to — a private / reserved address.\n * IP literals are checked directly; hostnames are resolved via DNS and every\n * returned address is checked (a public name pointing inward is caught). A\n * resolution failure fails closed.\n */\nasync function assertHostNotPrivate(host: string, rawUrl: string): Promise<void> {\n  if (isIP(host) !== 0) {\n    if (isPrivateOrReservedIp(host)) {\n      throw new StorageError(`outbound request blocked — \"${host}\" is a private/reserved address`, {\n        context: { url: rawUrl, address: host },\n      });\n    }\n    return;\n  }\n\n  let addresses: Array<{ address: string }>;\n  try {\n    addresses = await lookup(host, { all: true });\n  } catch (cause) {\n    throw new StorageError(\n      `outbound request blocked — could not resolve host \"${host}\" to verify it is public`,\n      { cause, context: { url: rawUrl, host } },\n    );\n  }\n\n  for (const { address } of addresses) {\n    if (isPrivateOrReservedIp(address)) {\n      throw new StorageError(\n        `outbound request blocked — host \"${host}\" resolves to a private/reserved address (${address})`,\n        { context: { url: rawUrl, host, address } },\n      );\n    }\n  }\n}\n\n/**\n * Validate a URL against the policy BEFORE any network call: scheme\n * allowlist and (when private hosts are not allowed) a DNS resolution that\n * rejects private / loopback / link-local / metadata addresses — the SSRF\n * guard. Returns the parsed `URL` on success; throws {@link StorageError}\n * otherwise.\n */\nasync function assertUrlAllowed(rawUrl: string, policy: ResolvedFetchPolicy): Promise<URL> {\n  let url: URL;\n  try {\n    url = new URL(rawUrl);\n  } catch {\n    throw new StorageError(`outbound request blocked — invalid URL: ${rawUrl}`, {\n      context: { url: rawUrl },\n    });\n  }\n\n  const scheme = url.protocol.replace(/:$/, \"\").toLowerCase();\n  if (!policy.allowedSchemes.some((s) => s.toLowerCase() === scheme)) {\n    throw new StorageError(\n      `outbound request blocked — scheme \"${scheme}\" is not allowed (allowed: ${policy.allowedSchemes.join(\", \")})`,\n      { context: { url: rawUrl, scheme } },\n    );\n  }\n\n  if (!policy.allowPrivateHosts) {\n    const host = stripBrackets(url.hostname);\n    await assertHostNotPrivate(host, rawUrl);\n  }\n\n  return url;\n}\n\n/**\n * Result of {@link safeFetchToBuffer}: the (capped) body plus the response's\n * content-type, so callers can derive a MIME type and enforce a non-empty\n * content-type check.\n */\nexport type SafeFetchResult = {\n  buffer: Buffer;\n  contentType: string | null;\n  status: number;\n  statusText: string;\n  ok: boolean;\n};\n\n/**\n * SSRF-guarded download: validates the URL (scheme allowlist + post-DNS\n * private-IP deny), performs the request with a timeout via\n * `AbortController`, then streams the body with a hard byte cap — aborting\n * the moment the running total exceeds `maxBytes`. A declared\n * `content-length` over the cap fails fast.\n *\n * Redirects are NEVER delegated to the platform: every hop is issued with\n * `redirect: \"manual\"` and its `Location` is re-run through\n * {@link assertUrlAllowed} — including the DNS-resolution private-IP check\n * — before being followed (capped at {@link DEFAULT_MAX_REDIRECTS}), so a\n * 3xx from an allowed host cannot smuggle the request to a private /\n * metadata target. Mirrors `@warlock.js/ai`'s `guardedFetch`\n * (ai/src/security/outbound-policy.ts:188-284); duplicated per this\n * module's file-header note since core cannot depend on ai.\n *\n * @throws {StorageError} On a blocked URL (initial or redirect target),\n * a redirect-hop bound overflow, timeout, or oversized body.\n */\nexport async function safeFetchToBuffer(\n  rawUrl: string,\n  options: SafeFetchOptions = {},\n): Promise<SafeFetchResult> {\n  const policy = resolveFetchPolicy(options);\n  let url = await assertUrlAllowed(rawUrl, policy);\n\n  const controller = new AbortController();\n  const timer = setTimeout(() => {\n    controller.abort(\n      new StorageError(`outbound request timed out after ${policy.timeoutMs}ms`, {\n        context: { url: rawUrl, timeoutMs: policy.timeoutMs },\n      }),\n    );\n  }, policy.timeoutMs);\n\n  try {\n    let response: Response;\n\n    for (let hop = 0; ; hop++) {\n      response = await policy.fetch(url, { signal: controller.signal, redirect: \"manual\" });\n\n      const location = response.headers.get(\"location\");\n      if (!REDIRECT_STATUSES.has(response.status) || location === null) {\n        break;\n      }\n\n      if (hop >= DEFAULT_MAX_REDIRECTS) {\n        throw new StorageError(\n          `outbound request blocked — more than ${DEFAULT_MAX_REDIRECTS} redirects`,\n          { context: { url: rawUrl, maxRedirects: DEFAULT_MAX_REDIRECTS } },\n        );\n      }\n\n      let target: URL;\n      try {\n        target = new URL(location, url);\n      } catch {\n        throw new StorageError(\n          `outbound request blocked — invalid redirect Location: ${location}`,\n          {\n            context: { url: url.toString(), location },\n          },\n        );\n      }\n\n      // Discard the interim body so the connection can be reused.\n      if (response.body) {\n        await response.body.cancel().catch(() => undefined);\n      }\n\n      // The redirect target gets the SAME scheme + private-IP validation\n      // (incl. DNS resolution) as the initial URL — this is what closes\n      // the redirect-based SSRF bypass: a 302 from an allowed host to\n      // 169.254.169.254 is re-validated here, not blindly followed.\n      url = await assertUrlAllowed(target.toString(), policy);\n    }\n\n    const declared = Number(response.headers.get(\"content-length\"));\n    if (Number.isFinite(declared) && declared > policy.maxBytes) {\n      throw new StorageError(\n        `outbound response body too large — declared ${declared} bytes exceeds the ${policy.maxBytes}-byte cap`,\n        { context: { url: rawUrl, declared, maxBytes: policy.maxBytes } },\n      );\n    }\n\n    const buffer = await readBodyCapped(response, policy.maxBytes, rawUrl);\n\n    return {\n      buffer,\n      contentType: response.headers.get(\"content-type\"),\n      status: response.status,\n      statusText: response.statusText,\n      ok: response.ok,\n    };\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\n/**\n * Read a response body into a Buffer with a hard byte cap. The stream is\n * read chunk-by-chunk and cancelled the moment the running total exceeds\n * `maxBytes`. Throws {@link StorageError} on overflow.\n */\nasync function readBodyCapped(\n  response: Response,\n  maxBytes: number,\n  rawUrl: string,\n): Promise<Buffer> {\n  if (!response.body) {\n    const arrayBuffer = await response.arrayBuffer();\n    if (arrayBuffer.byteLength > maxBytes) {\n      throw new StorageError(`outbound response body exceeded the ${maxBytes}-byte cap`, {\n        context: { url: rawUrl, maxBytes },\n      });\n    }\n    return Buffer.from(arrayBuffer);\n  }\n\n  const reader = response.body.getReader();\n  const chunks: Uint8Array[] = [];\n  let total = 0;\n\n  for (;;) {\n    const { done, value } = await reader.read();\n    if (done) {\n      break;\n    }\n    if (!value) {\n      continue;\n    }\n\n    total += value.byteLength;\n    if (total > maxBytes) {\n      await reader.cancel();\n      throw new StorageError(`outbound response body exceeded the ${maxBytes}-byte cap`, {\n        context: { url: rawUrl, maxBytes },\n      });\n    }\n    chunks.push(value);\n  }\n\n  return Buffer.concat(chunks);\n}\n"],"mappings":"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"}
+{"version":3,"file":"safe-fetch.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/storage/utils/safe-fetch.ts"],"sourcesContent":["import { lookup } from \"node:dns/promises\";\nimport { isIP } from \"node:net\";\nimport { isPrivateOrReservedIp } from \"./classify-ip-address\";\nimport { StorageError } from \"./storage-error\";\n\n/**\n * SSRF / resource-exhaustion guard for storage's outbound downloads\n * (`putFromUrl`).\n *\n * NOTE: this MIRRORS `@warlock.js/ai`'s `src/security/private-ip.ts` and\n * `src/security/outbound-policy.ts`. It is duplicated here intentionally\n * because `@warlock.js/core` cannot depend on `@warlock.js/ai`. Pending\n * extraction of a shared security package, keep the two copies in sync.\n */\n\n/** 50 MiB — default cap on a downloaded body (storage files run larger than AI payloads). */\nconst DEFAULT_MAX_BYTES = 50 * 1024 * 1024;\n/** 30s — default per-request timeout. */\nconst DEFAULT_TIMEOUT_MS = 30_000;\n/**\n * Cap on the number of re-validated redirect hops. Mirrors\n * `@warlock.js/ai`'s `DEFAULT_MAX_REDIRECTS`\n * (ai/src/security/outbound-policy.ts:15).\n */\nconst DEFAULT_MAX_REDIRECTS = 5;\n\n/** 3xx statuses whose `Location` a follow re-issues — mirrors ai/src/security/outbound-policy.ts:18. */\nconst REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);\n\n/**\n * Options controlling a guarded outbound fetch. Every field is optional;\n * {@link resolveFetchPolicy} fills safe defaults. The defaults are\n * deliberately strict (https+http, private-IP deny ON, 30s timeout,\n * 50 MiB cap) so a caller that does not tune them still gets a hardened\n * request.\n */\nexport type SafeFetchOptions = {\n  /**\n   * Whether to ALLOW private / loopback / link-local / metadata hosts.\n   * Default `false` — the SSRF guard is on (private hosts are denied).\n   */\n  allowPrivateHosts?: boolean;\n  /**\n   * Maximum response body size in bytes. A declared `content-length` over\n   * this fails fast; otherwise the body is read with a running cap and the\n   * stream is aborted on overflow. Default `52_428_800` (50 MiB).\n   */\n  maxBytes?: number;\n  /** Per-request timeout in milliseconds. Default `30_000`. */\n  timeoutMs?: number;\n  /**\n   * URL schemes permitted for the request, compared case-insensitively.\n   * Default `[\"https\", \"http\"]`.\n   */\n  allowedSchemes?: string[];\n  /**\n   * Injected `fetch` implementation (for tests or proxies). Defaults to the\n   * global `fetch`.\n   */\n  fetch?: typeof fetch;\n};\n\n/** {@link SafeFetchOptions} with every default resolved — never partial. */\ntype ResolvedFetchPolicy = {\n  allowPrivateHosts: boolean;\n  maxBytes: number;\n  timeoutMs: number;\n  allowedSchemes: string[];\n  fetch: typeof fetch;\n};\n\n/**\n * Fill a {@link SafeFetchOptions} with strict defaults: https+http,\n * private-IP deny on, 30s timeout, 50 MiB cap, global `fetch`.\n */\nfunction resolveFetchPolicy(options: SafeFetchOptions = {}): ResolvedFetchPolicy {\n  return {\n    allowPrivateHosts: options.allowPrivateHosts ?? false,\n    maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,\n    timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    allowedSchemes: options.allowedSchemes ?? [\"https\", \"http\"],\n    fetch: options.fetch ?? globalThis.fetch,\n  };\n}\n\nexport { isPrivateOrReservedIp };\n\n/** Strip the `[ ]` IPv6 brackets `URL.hostname` keeps. */\nfunction stripBrackets(host: string): string {\n  return host.startsWith(\"[\") && host.endsWith(\"]\") ? host.slice(1, -1) : host;\n}\n\n/**\n * Reject when `host` is — or resolves to — a private / reserved address.\n * IP literals are checked directly; hostnames are resolved via DNS and every\n * returned address is checked (a public name pointing inward is caught). A\n * resolution failure fails closed.\n */\nasync function assertHostNotPrivate(host: string, rawUrl: string): Promise<void> {\n  if (isIP(host) !== 0) {\n    if (isPrivateOrReservedIp(host)) {\n      throw new StorageError(`outbound request blocked — \"${host}\" is a private/reserved address`, {\n        context: { url: rawUrl, address: host },\n      });\n    }\n    return;\n  }\n\n  let addresses: Array<{ address: string }>;\n  try {\n    addresses = await lookup(host, { all: true });\n  } catch (cause) {\n    throw new StorageError(\n      `outbound request blocked — could not resolve host \"${host}\" to verify it is public`,\n      { cause, context: { url: rawUrl, host } },\n    );\n  }\n\n  for (const { address } of addresses) {\n    if (isPrivateOrReservedIp(address)) {\n      throw new StorageError(\n        `outbound request blocked — host \"${host}\" resolves to a private/reserved address (${address})`,\n        { context: { url: rawUrl, host, address } },\n      );\n    }\n  }\n}\n\n/**\n * Validate a URL against the policy BEFORE any network call: scheme\n * allowlist and (when private hosts are not allowed) a DNS resolution that\n * rejects private / loopback / link-local / metadata addresses — the SSRF\n * guard. Returns the parsed `URL` on success; throws {@link StorageError}\n * otherwise.\n */\nasync function assertUrlAllowed(rawUrl: string, policy: ResolvedFetchPolicy): Promise<URL> {\n  let url: URL;\n  try {\n    url = new URL(rawUrl);\n  } catch {\n    throw new StorageError(`outbound request blocked — invalid URL: ${rawUrl}`, {\n      context: { url: rawUrl },\n    });\n  }\n\n  const scheme = url.protocol.replace(/:$/, \"\").toLowerCase();\n  if (!policy.allowedSchemes.some((s) => s.toLowerCase() === scheme)) {\n    throw new StorageError(\n      `outbound request blocked — scheme \"${scheme}\" is not allowed (allowed: ${policy.allowedSchemes.join(\", \")})`,\n      { context: { url: rawUrl, scheme } },\n    );\n  }\n\n  if (!policy.allowPrivateHosts) {\n    const host = stripBrackets(url.hostname);\n    await assertHostNotPrivate(host, rawUrl);\n  }\n\n  return url;\n}\n\n/**\n * Result of {@link safeFetchToBuffer}: the (capped) body plus the response's\n * content-type, so callers can derive a MIME type and enforce a non-empty\n * content-type check.\n */\nexport type SafeFetchResult = {\n  buffer: Buffer;\n  contentType: string | null;\n  status: number;\n  statusText: string;\n  ok: boolean;\n};\n\n/**\n * SSRF-guarded download: validates the URL (scheme allowlist + post-DNS\n * private-IP deny), performs the request with a timeout via\n * `AbortController`, then streams the body with a hard byte cap — aborting\n * the moment the running total exceeds `maxBytes`. A declared\n * `content-length` over the cap fails fast.\n *\n * Redirects are NEVER delegated to the platform: every hop is issued with\n * `redirect: \"manual\"` and its `Location` is re-run through\n * {@link assertUrlAllowed} — including the DNS-resolution private-IP check\n * — before being followed (capped at {@link DEFAULT_MAX_REDIRECTS}), so a\n * 3xx from an allowed host cannot smuggle the request to a private /\n * metadata target. Mirrors `@warlock.js/ai`'s `guardedFetch`\n * (ai/src/security/outbound-policy.ts:188-284); duplicated per this\n * module's file-header note since core cannot depend on ai.\n *\n * @throws {StorageError} On a blocked URL (initial or redirect target),\n * a redirect-hop bound overflow, timeout, or oversized body.\n */\nexport async function safeFetchToBuffer(\n  rawUrl: string,\n  options: SafeFetchOptions = {},\n): Promise<SafeFetchResult> {\n  const policy = resolveFetchPolicy(options);\n  let url = await assertUrlAllowed(rawUrl, policy);\n\n  const controller = new AbortController();\n  const timer = setTimeout(() => {\n    controller.abort(\n      new StorageError(`outbound request timed out after ${policy.timeoutMs}ms`, {\n        context: { url: rawUrl, timeoutMs: policy.timeoutMs },\n      }),\n    );\n  }, policy.timeoutMs);\n\n  try {\n    let response: Response;\n\n    for (let hop = 0; ; hop++) {\n      response = await policy.fetch(url, { signal: controller.signal, redirect: \"manual\" });\n\n      const location = response.headers.get(\"location\");\n      if (!REDIRECT_STATUSES.has(response.status) || location === null) {\n        break;\n      }\n\n      if (hop >= DEFAULT_MAX_REDIRECTS) {\n        throw new StorageError(\n          `outbound request blocked — more than ${DEFAULT_MAX_REDIRECTS} redirects`,\n          { context: { url: rawUrl, maxRedirects: DEFAULT_MAX_REDIRECTS } },\n        );\n      }\n\n      let target: URL;\n      try {\n        target = new URL(location, url);\n      } catch {\n        throw new StorageError(\n          `outbound request blocked — invalid redirect Location: ${location}`,\n          {\n            context: { url: url.toString(), location },\n          },\n        );\n      }\n\n      // Discard the interim body so the connection can be reused.\n      if (response.body) {\n        await response.body.cancel().catch(() => undefined);\n      }\n\n      // The redirect target gets the SAME scheme + private-IP validation\n      // (incl. DNS resolution) as the initial URL — this is what closes\n      // the redirect-based SSRF bypass: a 302 from an allowed host to\n      // 169.254.169.254 is re-validated here, not blindly followed.\n      url = await assertUrlAllowed(target.toString(), policy);\n    }\n\n    const declared = Number(response.headers.get(\"content-length\"));\n    if (Number.isFinite(declared) && declared > policy.maxBytes) {\n      throw new StorageError(\n        `outbound response body too large — declared ${declared} bytes exceeds the ${policy.maxBytes}-byte cap`,\n        { context: { url: rawUrl, declared, maxBytes: policy.maxBytes } },\n      );\n    }\n\n    const buffer = await readBodyCapped(response, policy.maxBytes, rawUrl);\n\n    return {\n      buffer,\n      contentType: response.headers.get(\"content-type\"),\n      status: response.status,\n      statusText: response.statusText,\n      ok: response.ok,\n    };\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\n/**\n * Read a response body into a Buffer with a hard byte cap. The stream is\n * read chunk-by-chunk and cancelled the moment the running total exceeds\n * `maxBytes`. Throws {@link StorageError} on overflow.\n */\nasync function readBodyCapped(\n  response: Response,\n  maxBytes: number,\n  rawUrl: string,\n): Promise<Buffer> {\n  if (!response.body) {\n    const arrayBuffer = await response.arrayBuffer();\n    if (arrayBuffer.byteLength > maxBytes) {\n      throw new StorageError(`outbound response body exceeded the ${maxBytes}-byte cap`, {\n        context: { url: rawUrl, maxBytes },\n      });\n    }\n    return Buffer.from(arrayBuffer);\n  }\n\n  const reader = response.body.getReader();\n  const chunks: Uint8Array[] = [];\n  let total = 0;\n\n  for (;;) {\n    const { done, value } = await reader.read();\n    if (done) {\n      break;\n    }\n    if (!value) {\n      continue;\n    }\n\n    total += value.byteLength;\n    if (total > maxBytes) {\n      await reader.cancel();\n      throw new StorageError(`outbound response body exceeded the ${maxBytes}-byte cap`, {\n        context: { url: rawUrl, maxBytes },\n      });\n    }\n    chunks.push(value);\n  }\n\n  return Buffer.concat(chunks);\n}\n"],"mappings":"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"}

package/esm/storage/utils/storage-capability-error.d.mts

@@ -1,6 +1,6 @@
 import { StorageError } from "./storage-error.mjs";
 
-//#region ../core/src/storage/utils/storage-capability-error.d.ts
+//#region ../../packages/core/src/storage/utils/storage-capability-error.d.ts
 /**
  * Thrown when an operation needs an optional driver capability that the
  * active driver does not implement (e.g. `putIfAbsent()` on a driver that

package/esm/storage/utils/storage-capability-error.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-capability-error.d.mts","names":[],"sources":["../../../../../../../../core/src/storage/utils/storage-capability-error.ts"],"mappings":";;;;;AAUA;;;;;;cAAa,sBAAA,SAA+B,YAAY;;;;WAItC,UAAA;EAOyC;;;EAAA,SAFzC,UAAA;cAEG,UAAA,UAAoB,UAAA;AAAA"}
+{"version":3,"file":"storage-capability-error.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/storage/utils/storage-capability-error.ts"],"mappings":";;;;;AAUA;;;;;;cAAa,sBAAA,SAA+B,YAAY;;;;WAItC,UAAA;EAOyC;;;EAAA,SAFzC,UAAA;cAEG,UAAA,UAAoB,UAAA;AAAA"}

package/esm/storage/utils/storage-capability-error.mjs

@@ -1,6 +1,6 @@
 import { StorageError } from "./storage-error.mjs";
 
-//#region ../core/src/storage/utils/storage-capability-error.ts
+//#region ../../packages/core/src/storage/utils/storage-capability-error.ts
 /**
 * Thrown when an operation needs an optional driver capability that the
 * active driver does not implement (e.g. `putIfAbsent()` on a driver that

package/esm/storage/utils/storage-capability-error.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"storage-capability-error.mjs","names":[],"sources":["../../../../../../../../core/src/storage/utils/storage-capability-error.ts"],"sourcesContent":["import { StorageError } from \"./storage-error\";\n\n/**\n * Thrown when an operation needs an optional driver capability that the\n * active driver does not implement (e.g. `putIfAbsent()` on a driver that\n * cannot guarantee an atomic create-if-absent).\n *\n * Callers can probe first (`storage.supportsPutIfAbsent()`) or branch on\n * `instanceof StorageCapabilityError`.\n */\nexport class StorageCapabilityError extends StorageError {\n  /**\n   * The missing capability (e.g. \"putIfAbsent\").\n   */\n  public readonly capability: string;\n\n  /**\n   * Name of the driver that lacks the capability.\n   */\n  public readonly driverName: string;\n\n  public constructor(capability: string, driverName: string) {\n    super(\n      `Storage driver \"${driverName}\" does not support \"${capability}\". ` +\n        `Use a driver that implements it, or check supportsPutIfAbsent() first.`,\n      { context: { capability, driver: driverName } },\n    );\n    this.name = \"StorageCapabilityError\";\n    this.capability = capability;\n    this.driverName = driverName;\n  }\n}\n"],"mappings":";;;;;;;;;;;AAUA,IAAa,yBAAb,cAA4C,aAAa;CAWvD,AAAO,YAAY,YAAoB,YAAoB;EACzD,MACE,mBAAmB,WAAW,sBAAsB,WAAW,4EAE/D,EAAE,SAAS;GAAE;GAAY,QAAQ;EAAW,EAAE,CAChD;EACA,KAAK,OAAO;EACZ,KAAK,aAAa;EAClB,KAAK,aAAa;CACpB;AACF"}
+{"version":3,"file":"storage-capability-error.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/storage/utils/storage-capability-error.ts"],"sourcesContent":["import { StorageError } from \"./storage-error\";\n\n/**\n * Thrown when an operation needs an optional driver capability that the\n * active driver does not implement (e.g. `putIfAbsent()` on a driver that\n * cannot guarantee an atomic create-if-absent).\n *\n * Callers can probe first (`storage.supportsPutIfAbsent()`) or branch on\n * `instanceof StorageCapabilityError`.\n */\nexport class StorageCapabilityError extends StorageError {\n  /**\n   * The missing capability (e.g. \"putIfAbsent\").\n   */\n  public readonly capability: string;\n\n  /**\n   * Name of the driver that lacks the capability.\n   */\n  public readonly driverName: string;\n\n  public constructor(capability: string, driverName: string) {\n    super(\n      `Storage driver \"${driverName}\" does not support \"${capability}\". ` +\n        `Use a driver that implements it, or check supportsPutIfAbsent() first.`,\n      { context: { capability, driver: driverName } },\n    );\n    this.name = \"StorageCapabilityError\";\n    this.capability = capability;\n    this.driverName = driverName;\n  }\n}\n"],"mappings":";;;;;;;;;;;AAUA,IAAa,yBAAb,cAA4C,aAAa;CAWvD,AAAO,YAAY,YAAoB,YAAoB;EACzD,MACE,mBAAmB,WAAW,sBAAsB,WAAW,4EAE/D,EAAE,SAAS;GAAE;GAAY,QAAQ;EAAW,EAAE,CAChD;EACA,KAAK,OAAO;EACZ,KAAK,aAAa;EAClB,KAAK,aAAa;CACpB;AACF"}

package/esm/storage/utils/storage-error.d.mts

@@ -1,4 +1,4 @@
-//#region ../core/src/storage/utils/storage-error.d.ts
+//#region ../../packages/core/src/storage/utils/storage-error.d.ts
 /**
  * Base error for the storage subsystem.
  *

package/esm/storage/utils/storage-error.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-error.d.mts","names":[],"sources":["../../../../../../../../core/src/storage/utils/storage-error.ts"],"mappings":";;AAYA;;;;;;;;AAEkB;AAOlB;;KATY,mBAAA;EACV,KAAA;EACA,OAAA,GAAU,MAAM;AAAA;;;;;cAOL,YAAA,SAAqB,KAAA;EASN;;;EAAA,SALV,KAAA;EAOoB;;AAA6B;EAA7B,SAFpB,OAAA,GAAU,MAAA;cAEP,OAAA,UAAiB,OAAA,GAAU,mBAAA;AAAA"}
+{"version":3,"file":"storage-error.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/storage/utils/storage-error.ts"],"mappings":";;AAYA;;;;;;;;AAEkB;AAOlB;;KATY,mBAAA;EACV,KAAA;EACA,OAAA,GAAU,MAAM;AAAA;;;;;cAOL,YAAA,SAAqB,KAAA;EASN;;;EAAA,SALV,KAAA;EAOoB;;AAA6B;EAA7B,SAFpB,OAAA,GAAU,MAAA;cAEP,OAAA,UAAiB,OAAA,GAAU,mBAAA;AAAA"}

package/esm/storage/utils/storage-error.mjs

@@ -1,4 +1,4 @@
-//#region ../core/src/storage/utils/storage-error.ts
+//#region ../../packages/core/src/storage/utils/storage-error.ts
 /**
 * Error thrown by storage drivers for refused or invalid operations
 * (path-traversal attempts, blocked outbound fetches, oversized downloads).

package/esm/storage/utils/storage-error.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"storage-error.mjs","names":[],"sources":["../../../../../../../../core/src/storage/utils/storage-error.ts"],"sourcesContent":["/**\n * Base error for the storage subsystem.\n *\n * The storage drivers historically threw bare `Error`s. The security\n * guards added to the local and cloud drivers (path-traversal containment,\n * SSRF-guarded `putFromUrl`) need a named, catchable error so callers can\n * branch on `instanceof StorageError` instead of string-matching messages.\n *\n * `context` is a free-form diagnostic bag (offending location, host, URL)\n * mirroring the convention used by `@warlock.js/ai`'s error classes — it is\n * for logs and telemetry, treated as opaque by consumers.\n */\nexport type StorageErrorOptions = {\n  cause?: unknown;\n  context?: Record<string, unknown>;\n};\n\n/**\n * Error thrown by storage drivers for refused or invalid operations\n * (path-traversal attempts, blocked outbound fetches, oversized downloads).\n */\nexport class StorageError extends Error {\n  /**\n   * Optional original thrown value preserved through re-wrapping.\n   */\n  public readonly cause?: unknown;\n\n  /**\n   * Optional free-form diagnostic bag (location, host, url, …).\n   */\n  public readonly context?: Record<string, unknown>;\n\n  public constructor(message: string, options?: StorageErrorOptions) {\n    super(message);\n    this.name = \"StorageError\";\n    this.cause = options?.cause;\n    this.context = options?.context;\n  }\n}\n"],"mappings":";;;;;AAqBA,IAAa,eAAb,cAAkC,MAAM;CAWtC,AAAO,YAAY,SAAiB,SAA+B;EACjE,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,QAAQ,SAAS;EACtB,KAAK,UAAU,SAAS;CAC1B;AACF"}
+{"version":3,"file":"storage-error.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/storage/utils/storage-error.ts"],"sourcesContent":["/**\n * Base error for the storage subsystem.\n *\n * The storage drivers historically threw bare `Error`s. The security\n * guards added to the local and cloud drivers (path-traversal containment,\n * SSRF-guarded `putFromUrl`) need a named, catchable error so callers can\n * branch on `instanceof StorageError` instead of string-matching messages.\n *\n * `context` is a free-form diagnostic bag (offending location, host, URL)\n * mirroring the convention used by `@warlock.js/ai`'s error classes — it is\n * for logs and telemetry, treated as opaque by consumers.\n */\nexport type StorageErrorOptions = {\n  cause?: unknown;\n  context?: Record<string, unknown>;\n};\n\n/**\n * Error thrown by storage drivers for refused or invalid operations\n * (path-traversal attempts, blocked outbound fetches, oversized downloads).\n */\nexport class StorageError extends Error {\n  /**\n   * Optional original thrown value preserved through re-wrapping.\n   */\n  public readonly cause?: unknown;\n\n  /**\n   * Optional free-form diagnostic bag (location, host, url, …).\n   */\n  public readonly context?: Record<string, unknown>;\n\n  public constructor(message: string, options?: StorageErrorOptions) {\n    super(message);\n    this.name = \"StorageError\";\n    this.cause = options?.cause;\n    this.context = options?.context;\n  }\n}\n"],"mappings":";;;;;AAqBA,IAAa,eAAb,cAAkC,MAAM;CAWtC,AAAO,YAAY,SAAiB,SAA+B;EACjE,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,QAAQ,SAAS;EACtB,KAAK,UAAU,SAAS;CAC1B;AACF"}

package/esm/storage/utils/storage-not-initialized-error.d.mts

@@ -1,4 +1,4 @@
-//#region ../core/src/storage/utils/storage-not-initialized-error.d.ts
+//#region ../../packages/core/src/storage/utils/storage-not-initialized-error.d.ts
 /**
  * Thrown when storage is accessed (e.g. `storage.put(...)`) before it has
  * been initialized in this process — no context driver and no default
@@ -13,6 +13,8 @@
  * `null`. This error names that cause and the fix directly instead.
  */
 declare class StorageNotInitializedError extends Error {
+  /** Stable Warlock error code; `warlock explain WL2006` prints the fix. */
+  readonly code = "WL2006";
   constructor(options?: {
     cause?: unknown;
   });

package/esm/storage/utils/storage-not-initialized-error.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-not-initialized-error.d.mts","names":[],"sources":["../../../../../../../../core/src/storage/utils/storage-not-initialized-error.ts"],"mappings":";;AAaA;;;;;;;;;AACkD;;;cADrC,0BAAA,SAAmC,KAAK;cAChC,OAAA;IAAY,KAAA;EAAA;AAAA"}
+{"version":3,"file":"storage-not-initialized-error.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/storage/utils/storage-not-initialized-error.ts"],"mappings":";;AAaA;;;;;;;;;;AAIkD;;cAJrC,0BAAA,SAAmC,KAAK;;WAEnC,IAAA;cAEG,OAAA;IAAY,KAAA;EAAA;AAAA"}

package/esm/storage/utils/storage-not-initialized-error.mjs

@@ -1,4 +1,4 @@
-//#region ../core/src/storage/utils/storage-not-initialized-error.ts
+//#region ../../packages/core/src/storage/utils/storage-not-initialized-error.ts
 /**
 * Thrown when storage is accessed (e.g. `storage.put(...)`) before it has
 * been initialized in this process — no context driver and no default
@@ -15,6 +15,7 @@
 var StorageNotInitializedError = class extends Error {
 	constructor(options) {
 		super("Storage is not initialized in this process. This happens when the `storage` connector never ran, so `Storage.init()` was never called.\n\nCheck that `src/config/storage.ts` exists. If this is a custom CLI command, add \"storage\" to its `preload.connectors` list so the connector runs before your command's action executes.", options);
+		this.code = "WL2006";
 		this.name = "StorageNotInitializedError";
 	}
 };

package/esm/storage/utils/storage-not-initialized-error.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"storage-not-initialized-error.mjs","names":[],"sources":["../../../../../../../../core/src/storage/utils/storage-not-initialized-error.ts"],"sourcesContent":["/**\n * Thrown when storage is accessed (e.g. `storage.put(...)`) before it has\n * been initialized in this process — no context driver and no default\n * driver resolved yet.\n *\n * Previously this fell through to a bare `null` `activeDriver`, and the\n * first thing every call site did with it was read `.name` or call a\n * method on it, surfacing as `TypeError: Cannot read properties of null\n * (reading 'name')` deep inside `Storage#put()`. That told the caller\n * nothing about the real cause: the `storage` connector never ran in this\n * process, so `Storage#init()` was never called and `_driver` stayed\n * `null`. This error names that cause and the fix directly instead.\n */\nexport class StorageNotInitializedError extends Error {\n  public constructor(options?: { cause?: unknown }) {\n    super(\n      \"Storage is not initialized in this process. This happens when the `storage` \" +\n        \"connector never ran, so `Storage.init()` was never called.\\n\\n\" +\n        \"Check that `src/config/storage.ts` exists. If this is a custom CLI command, \" +\n        'add \"storage\" to its `preload.connectors` list so the connector runs before ' +\n        \"your command's action executes.\",\n      options,\n    );\n\n    this.name = \"StorageNotInitializedError\";\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,IAAa,6BAAb,cAAgD,MAAM;CACpD,AAAO,YAAY,SAA+B;EAChD,MACE,uUAKA,OACF;EAEA,KAAK,OAAO;CACd;AACF"}
+{"version":3,"file":"storage-not-initialized-error.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/storage/utils/storage-not-initialized-error.ts"],"sourcesContent":["/**\n * Thrown when storage is accessed (e.g. `storage.put(...)`) before it has\n * been initialized in this process — no context driver and no default\n * driver resolved yet.\n *\n * Previously this fell through to a bare `null` `activeDriver`, and the\n * first thing every call site did with it was read `.name` or call a\n * method on it, surfacing as `TypeError: Cannot read properties of null\n * (reading 'name')` deep inside `Storage#put()`. That told the caller\n * nothing about the real cause: the `storage` connector never ran in this\n * process, so `Storage#init()` was never called and `_driver` stayed\n * `null`. This error names that cause and the fix directly instead.\n */\nexport class StorageNotInitializedError extends Error {\n  /** Stable Warlock error code; `warlock explain WL2006` prints the fix. */\n  public readonly code = \"WL2006\";\n\n  public constructor(options?: { cause?: unknown }) {\n    super(\n      \"Storage is not initialized in this process. This happens when the `storage` \" +\n        \"connector never ran, so `Storage.init()` was never called.\\n\\n\" +\n        \"Check that `src/config/storage.ts` exists. If this is a custom CLI command, \" +\n        'add \"storage\" to its `preload.connectors` list so the connector runs before ' +\n        \"your command's action executes.\",\n      options,\n    );\n\n    this.name = \"StorageNotInitializedError\";\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,IAAa,6BAAb,cAAgD,MAAM;CAIpD,AAAO,YAAY,SAA+B;EAChD,MACE,uUAKA,OACF;cAVqB;EAYrB,KAAK,OAAO;CACd;AACF"}

package/esm/tests/authenticated-test-client.d.mts

@@ -0,0 +1,32 @@
+import { TestRequestClient, testDelete, testGet, testPatch, testPost, testPut, testRequest } from "./test-helpers.mjs";
+
+//#region ../../packages/core/src/tests/authenticated-test-client.d.ts
+/** Structural auth contract: an Auth model satisfies this without a runtime auth import. */
+interface TestAuthenticableUser {
+  generateAccessToken(): Promise<{
+    token: string;
+  }>;
+  removeAccessToken(token: string): Promise<void>;
+}
+/** An isolated HTTP client using one real issued access token. */
+type AuthenticatedTestClient = {
+  request: typeof testRequest;
+  get: typeof testGet;
+  post: typeof testPost;
+  put: typeof testPut;
+  patch: typeof testPatch;
+  delete: typeof testDelete; /** Revoke only this client's token; fixtures still own their user/data cleanup. */
+  dispose(): Promise<void>;
+};
+/**
+ * Issue a real persisted access token and bind it to this client's requests.
+ * Authentication middleware still verifies every request; no globals or bypasses
+ * are installed. The bound identity takes precedence over per-request headers.
+ *
+ * Requests go to the shared test server, or through `client` — e.g. the one
+ * `createTestHttpServer()` returns (its own `actingAs()` passes it).
+ */
+declare function actingAs(user: TestAuthenticableUser, client?: TestRequestClient): Promise<AuthenticatedTestClient>;
+//#endregion
+export { AuthenticatedTestClient, TestAuthenticableUser, actingAs };
+//# sourceMappingURL=authenticated-test-client.d.mts.map

package/esm/tests/authenticated-test-client.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticated-test-client.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/tests/authenticated-test-client.ts"],"mappings":";;;;UAaiB,qBAAA;EACf,mBAAA,IAAuB,OAAA;IAAU,KAAA;EAAA;EACjC,iBAAA,CAAkB,KAAA,WAAgB,OAAO;AAAA;;KAI/B,uBAAA;EACV,OAAA,SAAgB,WAAA;EAChB,GAAA,SAAY,OAAA;EACZ,IAAA,SAAa,QAAA;EACb,GAAA,SAAY,OAAA;EACZ,KAAA,SAAc,SAAA;EACd,MAAA,SAAe,UAAA,EANkB;EAQjC,OAAA,IAAW,OAAA;AAAA;;;;;;;;;iBAWS,QAAA,CACpB,IAAA,EAAM,qBAAA,EACN,MAAA,GAAQ,iBAAA,GACP,OAAA,CAAQ,uBAAA"}

package/esm/tests/authenticated-test-client.mjs

@@ -0,0 +1,40 @@
+import { createTestRequestClient, getTestServerUrl } from "./test-helpers.mjs";
+
+//#region ../../packages/core/src/tests/authenticated-test-client.ts
+/**
+* Issue a real persisted access token and bind it to this client's requests.
+* Authentication middleware still verifies every request; no globals or bypasses
+* are installed. The bound identity takes precedence over per-request headers.
+*
+* Requests go to the shared test server, or through `client` — e.g. the one
+* `createTestHttpServer()` returns (its own `actingAs()` passes it).
+*/
+async function actingAs(user, client = createTestRequestClient(getTestServerUrl)) {
+	if (process.env.NODE_ENV !== "test") throw new Error(`actingAs() requires NODE_ENV="test", but received NODE_ENV=${JSON.stringify(process.env.NODE_ENV)}. Set NODE_ENV=test before creating a test client.`);
+	const { token } = await user.generateAccessToken();
+	if (!token.trim()) {
+		await user.removeAccessToken(token).catch(() => void 0);
+		throw new Error("actingAs() requires a non-empty access token.");
+	}
+	const authorized = (options = {}) => {
+		const headers = new Headers(options.headers);
+		headers.set("authorization", `Bearer ${token}`);
+		return {
+			...options,
+			headers
+		};
+	};
+	return {
+		request: (path, options) => client.request(path, authorized(options)),
+		get: (path, options) => client.get(path, authorized(options)),
+		post: (path, body, options) => client.post(path, body, authorized(options)),
+		put: (path, body, options) => client.put(path, body, authorized(options)),
+		patch: (path, body, options) => client.patch(path, body, authorized(options)),
+		delete: (path, options) => client.delete(path, authorized(options)),
+		dispose: () => user.removeAccessToken(token)
+	};
+}
+
+//#endregion
+export { actingAs };
+//# sourceMappingURL=authenticated-test-client.mjs.map

package/esm/tests/authenticated-test-client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticated-test-client.mjs","names":[],"sources":["../../../../../../../../packages/core/src/tests/authenticated-test-client.ts"],"sourcesContent":["import {\n  type TestRequestClient,\n  createTestRequestClient,\n  getTestServerUrl,\n  type testDelete,\n  type testGet,\n  type testPatch,\n  type testPost,\n  type testPut,\n  type testRequest,\n} from \"./test-helpers\";\n\n/** Structural auth contract: an Auth model satisfies this without a runtime auth import. */\nexport interface TestAuthenticableUser {\n  generateAccessToken(): Promise<{ token: string }>;\n  removeAccessToken(token: string): Promise<void>;\n}\n\n/** An isolated HTTP client using one real issued access token. */\nexport type AuthenticatedTestClient = {\n  request: typeof testRequest;\n  get: typeof testGet;\n  post: typeof testPost;\n  put: typeof testPut;\n  patch: typeof testPatch;\n  delete: typeof testDelete;\n  /** Revoke only this client's token; fixtures still own their user/data cleanup. */\n  dispose(): Promise<void>;\n};\n\n/**\n * Issue a real persisted access token and bind it to this client's requests.\n * Authentication middleware still verifies every request; no globals or bypasses\n * are installed. The bound identity takes precedence over per-request headers.\n *\n * Requests go to the shared test server, or through `client` — e.g. the one\n * `createTestHttpServer()` returns (its own `actingAs()` passes it).\n */\nexport async function actingAs(\n  user: TestAuthenticableUser,\n  client: TestRequestClient = createTestRequestClient(getTestServerUrl),\n): Promise<AuthenticatedTestClient> {\n  if (process.env.NODE_ENV !== \"test\") {\n    throw new Error(\n      `actingAs() requires NODE_ENV=\"test\", but received NODE_ENV=${JSON.stringify(process.env.NODE_ENV)}. Set NODE_ENV=test before creating a test client.`,\n    );\n  }\n  const { token } = await user.generateAccessToken();\n  if (!token.trim()) {\n    await user.removeAccessToken(token).catch(() => undefined);\n    throw new Error(\"actingAs() requires a non-empty access token.\");\n  }\n\n  const authorized = (options: RequestInit = {}): RequestInit => {\n    const headers = new Headers(options.headers);\n    headers.set(\"authorization\", `Bearer ${token}`);\n    return { ...options, headers };\n  };\n\n  return {\n    request: (path, options) => client.request(path, authorized(options)),\n    get: (path, options) => client.get(path, authorized(options)),\n    post: (path, body, options) => client.post(path, body, authorized(options)),\n    put: (path, body, options) => client.put(path, body, authorized(options)),\n    patch: (path, body, options) => client.patch(path, body, authorized(options)),\n    delete: (path, options) => client.delete(path, authorized(options)),\n    dispose: () => user.removeAccessToken(token),\n  };\n}\n"],"mappings":";;;;;;;;;;;AAsCA,eAAsB,SACpB,MACA,SAA4B,wBAAwB,gBAAgB,GAClC;CAClC,IAAI,QAAQ,IAAI,aAAa,QAC3B,MAAM,IAAI,MACR,8DAA8D,KAAK,UAAU,QAAQ,IAAI,QAAQ,EAAE,mDACrG;CAEF,MAAM,EAAE,UAAU,MAAM,KAAK,oBAAoB;CACjD,IAAI,CAAC,MAAM,KAAK,GAAG;EACjB,MAAM,KAAK,kBAAkB,KAAK,CAAC,CAAC,YAAY,MAAS;EACzD,MAAM,IAAI,MAAM,+CAA+C;CACjE;CAEA,MAAM,cAAc,UAAuB,CAAC,MAAmB;EAC7D,MAAM,UAAU,IAAI,QAAQ,QAAQ,OAAO;EAC3C,QAAQ,IAAI,iBAAiB,UAAU,OAAO;EAC9C,OAAO;GAAE,GAAG;GAAS;EAAQ;CAC/B;CAEA,OAAO;EACL,UAAU,MAAM,YAAY,OAAO,QAAQ,MAAM,WAAW,OAAO,CAAC;EACpE,MAAM,MAAM,YAAY,OAAO,IAAI,MAAM,WAAW,OAAO,CAAC;EAC5D,OAAO,MAAM,MAAM,YAAY,OAAO,KAAK,MAAM,MAAM,WAAW,OAAO,CAAC;EAC1E,MAAM,MAAM,MAAM,YAAY,OAAO,IAAI,MAAM,MAAM,WAAW,OAAO,CAAC;EACxE,QAAQ,MAAM,MAAM,YAAY,OAAO,MAAM,MAAM,MAAM,WAAW,OAAO,CAAC;EAC5E,SAAS,MAAM,YAAY,OAAO,OAAO,MAAM,WAAW,OAAO,CAAC;EAClE,eAAe,KAAK,kBAAkB,KAAK;CAC7C;AACF"}

package/esm/tests/factories.d.mts

@@ -0,0 +1,59 @@
+import { ChildModel, Model, ModelSchema } from "@warlock.js/cascade";
+
+//#region ../../packages/core/src/tests/factories.d.ts
+/** A model's schema type. */
+type SchemaOf<TModel extends Model> = TModel extends Model<infer TSchema> ? TSchema : ModelSchema;
+/** The attributes a model is created from: a partial of its schema, as `Model.create()` takes. */
+type FactoryAttributes<TModel extends Model> = Partial<SchemaOf<TModel>>;
+/**
+ * Deterministic values for one record, derived only from its sequence number:
+ * the n-th record a factory builds is the same on every run, with no faker
+ * and no randomness.
+ */
+type FactorySeed = {
+  /** 1 for the first record this factory builds, 2 for the second, ... */readonly sequence: number; /** Position within the current `makeMany()` / `createMany()` call, from 0. */
+  readonly index: number; /** `"<prefix> <sequence>"`, e.g. `text("Post")` → `"Post 3"`. */
+  text(prefix?: string): string; /** `"<prefix><sequence>@example.test"`, e.g. `"user3@example.test"`. */
+  email(prefix?: string): string; /** A valid v4-shaped UUID numbered by the sequence. */
+  uuid(): string; /** 2026-01-01T00:00:00Z plus `offsetDays` days. */
+  date(offsetDays?: number): Date; /** An integer in `[min, max]`, cycling with the sequence. */
+  number(min?: number, max?: number): number; /** One of `values`, cycling with the sequence. */
+  pick<T>(values: readonly T[]): T;
+};
+/** Overrides: a partial, or a function of the seed returning one. */
+type FactoryOverrides<TAttributes> = Partial<TAttributes> | ((seed: FactorySeed) => Partial<TAttributes>);
+/** A named variation, applied on top of the definition (and earlier states). */
+type FactoryState<TAttributes> = (seed: FactorySeed, attributes: TAttributes) => Partial<TAttributes>;
+type Factory<TModel extends Model, TAttributes = FactoryAttributes<TModel>> = {
+  /** Build attributes without saving anything — no database needed. */make(overrides?: FactoryOverrides<TAttributes>): TAttributes; /** Build `count` attribute sets without saving anything. */
+  makeMany(count: number, overrides?: FactoryOverrides<TAttributes>): TAttributes[]; /** Create and save one record through `Model.create()`. */
+  create(overrides?: FactoryOverrides<TAttributes>): Promise<TModel>; /** Create and save `count` records, one `Model.create()` each, in order. */
+  create(count: number, overrides?: FactoryOverrides<TAttributes>): Promise<TModel[]>; /** Same as `create(count, overrides)`. */
+  createMany(count: number, overrides?: FactoryOverrides<TAttributes>): Promise<TModel[]>; /** Register a named state on this factory; returns the factory for chaining. */
+  state(name: string, state: FactoryState<TAttributes>): Factory<TModel, TAttributes>; /** A factory that applies the named states, in order, on top of the definition. */
+  with(...states: string[]): Factory<TModel, TAttributes>; /** Restart this factory's sequence at 1. */
+  resetSequence(): void;
+};
+/** Restart every factory's sequence, e.g. in `beforeEach`. */
+declare function resetFactorySequences(): void;
+/**
+ * Define a model factory: deterministic attributes for tests and seeders.
+ *
+ * `make()` builds attributes only (no database), `create()` saves through the
+ * model's own `create()`, so casts, defaults, hooks and events all run.
+ *
+ * @example
+ * export const userFactory = defineFactory(User, (seed) => ({
+ *   name: seed.text("User"),
+ *   email: seed.email(),
+ *   password: "test-password",
+ * })).state("admin", () => ({ role: "admin" }));
+ *
+ * const body = userFactory.make({ name: "Ada" });   // { name: "Ada", email: "user1@example.test", ... }
+ * const admin = await userFactory.with("admin").create();
+ * const users = await userFactory.create(3);
+ */
+declare function defineFactory<TModel extends Model>(model: ChildModel<TModel>, definition: (seed: FactorySeed) => FactoryAttributes<TModel>): Factory<TModel>;
+//#endregion
+export { Factory, FactoryAttributes, FactoryOverrides, FactorySeed, FactoryState, defineFactory, resetFactorySequences };
+//# sourceMappingURL=factories.d.mts.map

package/esm/tests/factories.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factories.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/tests/factories.ts"],"mappings":";;;;KAIK,QAAA,gBAAwB,KAAA,IAAS,MAAA,SAAe,KAAA,kBAAuB,OAAA,GAAU,WAAA;AAJZ;AAAA,KAO9D,iBAAA,gBAAiC,KAAA,IAAS,OAAA,CAAQ,QAAA,CAAS,MAAA;;;;;;KAO3D,WAAA;EAVqF,iFAYtF,QAAA,UAZkB;EAAA,SAclB,KAAA,UAd0C;EAgBnD,IAAA,CAAK,MAAA,oBAhBqE;EAkB1E,KAAA,CAAM,MAAA,oBAlByF;EAoB/F,IAAA,YAjBU;EAmBV,IAAA,CAAK,UAAA,YAAsB,IAAA,EAnBA;EAqB3B,MAAA,CAAO,GAAA,WAAc,GAAA,oBArBgD;EAuBrE,IAAA,IAAQ,MAAA,WAAiB,CAAA,KAAM,CAAA;AAAA;;KAIrB,gBAAA,gBACR,OAAA,CAAQ,WAAA,MACN,IAAA,EAAM,WAAA,KAAgB,OAAA,CAAQ,WAAA;;KAGxB,YAAA,iBACV,IAAA,EAAM,WAAA,EACN,UAAA,EAAY,WAAA,KACT,OAAA,CAAQ,WAAA;AAAA,KAED,OAAA,gBAAuB,KAAA,gBAAqB,iBAAA,CAAkB,MAAA;EArCZ,qEAuC5D,IAAA,CAAK,SAAA,GAAY,gBAAA,CAAiB,WAAA,IAAe,WAAA,EAvC0B;EAyC3E,QAAA,CAAS,KAAA,UAAe,SAAA,GAAY,gBAAA,CAAiB,WAAA,IAAe,WAAA,IAlC1D;EAoCV,MAAA,CAAO,SAAA,GAAY,gBAAA,CAAiB,WAAA,IAAe,OAAA,CAAQ,MAAA,GApCtC;EAsCrB,MAAA,CAAO,KAAA,UAAe,SAAA,GAAY,gBAAA,CAAiB,WAAA,IAAe,OAAA,CAAQ,MAAA,KAtBjD;EAwBzB,UAAA,CAAW,KAAA,UAAe,SAAA,GAAY,gBAAA,CAAiB,WAAA,IAAe,OAAA,CAAQ,MAAA,KAxB9C;EA0BhC,KAAA,CAAM,IAAA,UAAc,KAAA,EAAO,YAAA,CAAa,WAAA,IAAe,OAAA,CAAQ,MAAA,EAAQ,WAAA,GAxC9D;EA0CT,IAAA,IAAQ,MAAA,aAAmB,OAAA,CAAQ,MAAA,EAAQ,WAAA,GAtC3C;EAwCA,aAAA;AAAA;;iBAQc,qBAAA;;;;;;;;;;;;;AAtCkB;AAIlC;;;;iBAuKgB,aAAA,gBAA6B,KAAA,EAC3C,KAAA,EAAO,UAAA,CAAW,MAAA,GAClB,UAAA,GAAa,IAAA,EAAM,WAAA,KAAgB,iBAAA,CAAkB,MAAA,IACpD,OAAA,CAAQ,MAAA"}

package/esm/tests/factories.mjs

@@ -0,0 +1,105 @@
+import { DEFAULT_FAKE_NOW } from "./fakes/clock-fake.mjs";
+
+//#region ../../packages/core/src/tests/factories.ts
+const counters = /* @__PURE__ */ new Set();
+/** Restart every factory's sequence, e.g. in `beforeEach`. */
+function resetFactorySequences() {
+	for (const counter of counters) counter.value = 0;
+}
+function createSeed(sequence, index) {
+	return {
+		sequence,
+		index,
+		text: (prefix = "Text") => `${prefix} ${sequence}`,
+		email: (prefix = "user") => `${prefix}${sequence}@example.test`,
+		uuid: () => `00000000-0000-4000-8000-${String(sequence).padStart(12, "0")}`,
+		date: (offsetDays = 0) => new Date(DEFAULT_FAKE_NOW + offsetDays * 864e5),
+		number: (min = 1, max = 1e3) => {
+			if (max < min) throw new RangeError(`seed.number(${min}, ${max}): max is below min.`);
+			return min + (sequence - 1) % (max - min + 1);
+		},
+		pick: (values) => {
+			const value = values[(sequence - 1) % values.length];
+			if (value === void 0) throw new RangeError("seed.pick() needs at least one value.");
+			return value;
+		}
+	};
+}
+function buildFactory(model, definition, counter, states, applied) {
+	const build = (index, overrides) => {
+		counter.value += 1;
+		const seed = createSeed(counter.value, index);
+		let attributes = { ...definition(seed) };
+		for (const name of applied) {
+			const state = states.get(name);
+			if (!state) throw new Error(`Factory state "${name}" is not defined. Defined states: ${[...states.keys()].join(", ") || "(none)"}.`);
+			attributes = {
+				...attributes,
+				...state(seed, attributes)
+			};
+		}
+		const extra = typeof overrides === "function" ? overrides(seed) : overrides;
+		return {
+			...attributes,
+			...extra
+		};
+	};
+	const assertCount = (count) => {
+		if (!Number.isInteger(count) || count < 0) throw new RangeError(`A factory count must be a non-negative integer, got ${String(count)}.`);
+	};
+	const persist = (attributes) => model.create(attributes);
+	const createMany = async (count, overrides) => {
+		assertCount(count);
+		const records = [];
+		for (let index = 0; index < count; index++) records.push(await persist(build(index, overrides)));
+		return records;
+	};
+	function create(countOrOverrides, overrides) {
+		if (typeof countOrOverrides === "number") return createMany(countOrOverrides, overrides);
+		return persist(build(0, countOrOverrides));
+	}
+	const factory = {
+		make: (overrides) => build(0, overrides),
+		makeMany: (count, overrides) => {
+			assertCount(count);
+			return Array.from({ length: count }, (_, index) => build(index, overrides));
+		},
+		create,
+		createMany,
+		state: (name, state) => {
+			states.set(name, state);
+			return factory;
+		},
+		with: (...names) => buildFactory(model, definition, counter, states, [...applied, ...names]),
+		resetSequence: () => {
+			counter.value = 0;
+		}
+	};
+	return factory;
+}
+/**
+* Define a model factory: deterministic attributes for tests and seeders.
+*
+* `make()` builds attributes only (no database), `create()` saves through the
+* model's own `create()`, so casts, defaults, hooks and events all run.
+*
+* @example
+* export const userFactory = defineFactory(User, (seed) => ({
+*   name: seed.text("User"),
+*   email: seed.email(),
+*   password: "test-password",
+* })).state("admin", () => ({ role: "admin" }));
+*
+* const body = userFactory.make({ name: "Ada" });   // { name: "Ada", email: "user1@example.test", ... }
+* const admin = await userFactory.with("admin").create();
+* const users = await userFactory.create(3);
+*/
+function defineFactory(model, definition) {
+	const counter = { value: 0 };
+	counters.add(counter);
+	return buildFactory(model, definition, counter, /* @__PURE__ */ new Map(), []);
+}
+
+//#endregion
+export { defineFactory, resetFactorySequences };
+//# sourceMappingURL=factories.mjs.map

package/esm/tests/factories.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"factories.mjs","names":[],"sources":["../../../../../../../../packages/core/src/tests/factories.ts"],"sourcesContent":["import type { ChildModel, Model, ModelSchema } from \"@warlock.js/cascade\";\nimport { DEFAULT_FAKE_NOW } from \"./fakes/clock-fake\";\n\n/** A model's schema type. */\ntype SchemaOf<TModel extends Model> = TModel extends Model<infer TSchema> ? TSchema : ModelSchema;\n\n/** The attributes a model is created from: a partial of its schema, as `Model.create()` takes. */\nexport type FactoryAttributes<TModel extends Model> = Partial<SchemaOf<TModel>>;\n\n/**\n * Deterministic values for one record, derived only from its sequence number:\n * the n-th record a factory builds is the same on every run, with no faker\n * and no randomness.\n */\nexport type FactorySeed = {\n  /** 1 for the first record this factory builds, 2 for the second, ... */\n  readonly sequence: number;\n  /** Position within the current `makeMany()` / `createMany()` call, from 0. */\n  readonly index: number;\n  /** `\"<prefix> <sequence>\"`, e.g. `text(\"Post\")` → `\"Post 3\"`. */\n  text(prefix?: string): string;\n  /** `\"<prefix><sequence>@example.test\"`, e.g. `\"user3@example.test\"`. */\n  email(prefix?: string): string;\n  /** A valid v4-shaped UUID numbered by the sequence. */\n  uuid(): string;\n  /** 2026-01-01T00:00:00Z plus `offsetDays` days. */\n  date(offsetDays?: number): Date;\n  /** An integer in `[min, max]`, cycling with the sequence. */\n  number(min?: number, max?: number): number;\n  /** One of `values`, cycling with the sequence. */\n  pick<T>(values: readonly T[]): T;\n};\n\n/** Overrides: a partial, or a function of the seed returning one. */\nexport type FactoryOverrides<TAttributes> =\n  | Partial<TAttributes>\n  | ((seed: FactorySeed) => Partial<TAttributes>);\n\n/** A named variation, applied on top of the definition (and earlier states). */\nexport type FactoryState<TAttributes> = (\n  seed: FactorySeed,\n  attributes: TAttributes,\n) => Partial<TAttributes>;\n\nexport type Factory<TModel extends Model, TAttributes = FactoryAttributes<TModel>> = {\n  /** Build attributes without saving anything — no database needed. */\n  make(overrides?: FactoryOverrides<TAttributes>): TAttributes;\n  /** Build `count` attribute sets without saving anything. */\n  makeMany(count: number, overrides?: FactoryOverrides<TAttributes>): TAttributes[];\n  /** Create and save one record through `Model.create()`. */\n  create(overrides?: FactoryOverrides<TAttributes>): Promise<TModel>;\n  /** Create and save `count` records, one `Model.create()` each, in order. */\n  create(count: number, overrides?: FactoryOverrides<TAttributes>): Promise<TModel[]>;\n  /** Same as `create(count, overrides)`. */\n  createMany(count: number, overrides?: FactoryOverrides<TAttributes>): Promise<TModel[]>;\n  /** Register a named state on this factory; returns the factory for chaining. */\n  state(name: string, state: FactoryState<TAttributes>): Factory<TModel, TAttributes>;\n  /** A factory that applies the named states, in order, on top of the definition. */\n  with(...states: string[]): Factory<TModel, TAttributes>;\n  /** Restart this factory's sequence at 1. */\n  resetSequence(): void;\n};\n\ntype SequenceCounter = { value: number };\n\nconst counters = new Set<SequenceCounter>();\n\n/** Restart every factory's sequence, e.g. in `beforeEach`. */\nexport function resetFactorySequences(): void {\n  for (const counter of counters) counter.value = 0;\n}\n\nfunction createSeed(sequence: number, index: number): FactorySeed {\n  return {\n    sequence,\n    index,\n    text: (prefix = \"Text\") => `${prefix} ${sequence}`,\n    email: (prefix = \"user\") => `${prefix}${sequence}@example.test`,\n    uuid: () => `00000000-0000-4000-8000-${String(sequence).padStart(12, \"0\")}`,\n    date: (offsetDays = 0) => new Date(DEFAULT_FAKE_NOW + offsetDays * 86_400_000),\n    number: (min = 1, max = 1000) => {\n      if (max < min) throw new RangeError(`seed.number(${min}, ${max}): max is below min.`);\n\n      return min + ((sequence - 1) % (max - min + 1));\n    },\n    pick: <T>(values: readonly T[]): T => {\n      const value = values[(sequence - 1) % values.length];\n\n      if (value === undefined) throw new RangeError(\"seed.pick() needs at least one value.\");\n\n      return value;\n    },\n  };\n}\n\nfunction buildFactory<TModel extends Model>(\n  model: ChildModel<TModel>,\n  definition: (seed: FactorySeed) => FactoryAttributes<TModel>,\n  counter: SequenceCounter,\n  states: Map<string, FactoryState<FactoryAttributes<TModel>>>,\n  applied: readonly string[],\n): Factory<TModel> {\n  type TAttributes = FactoryAttributes<TModel>;\n\n  const build = (index: number, overrides?: FactoryOverrides<TAttributes>): TAttributes => {\n    counter.value += 1;\n\n    const seed = createSeed(counter.value, index);\n    let attributes: TAttributes = { ...definition(seed) };\n\n    for (const name of applied) {\n      const state = states.get(name);\n\n      if (!state) {\n        throw new Error(\n          `Factory state \"${name}\" is not defined. Defined states: ${[...states.keys()].join(\", \") || \"(none)\"}.`,\n        );\n      }\n\n      attributes = { ...attributes, ...state(seed, attributes) };\n    }\n\n    const extra = typeof overrides === \"function\" ? overrides(seed) : overrides;\n\n    return { ...attributes, ...extra };\n  };\n\n  const assertCount = (count: number): void => {\n    if (!Number.isInteger(count) || count < 0) {\n      throw new RangeError(`A factory count must be a non-negative integer, got ${String(count)}.`);\n    }\n  };\n\n  const persist = (attributes: TAttributes): Promise<TModel> => model.create(attributes);\n\n  const createMany = async (\n    count: number,\n    overrides?: FactoryOverrides<TAttributes>,\n  ): Promise<TModel[]> => {\n    assertCount(count);\n\n    const records: TModel[] = [];\n\n    for (let index = 0; index < count; index++) {\n      records.push(await persist(build(index, overrides)));\n    }\n\n    return records;\n  };\n\n  function create(overrides?: FactoryOverrides<TAttributes>): Promise<TModel>;\n  function create(count: number, overrides?: FactoryOverrides<TAttributes>): Promise<TModel[]>;\n  function create(\n    countOrOverrides?: number | FactoryOverrides<TAttributes>,\n    overrides?: FactoryOverrides<TAttributes>,\n  ): Promise<TModel | TModel[]> {\n    if (typeof countOrOverrides === \"number\") return createMany(countOrOverrides, overrides);\n\n    return persist(build(0, countOrOverrides));\n  }\n\n  const factory: Factory<TModel> = {\n    make: (overrides) => build(0, overrides),\n    makeMany: (count, overrides) => {\n      assertCount(count);\n\n      return Array.from({ length: count }, (_, index) => build(index, overrides));\n    },\n    create,\n    createMany,\n    state: (name, state) => {\n      states.set(name, state);\n\n      return factory;\n    },\n    with: (...names) => buildFactory(model, definition, counter, states, [...applied, ...names]),\n    resetSequence: () => {\n      counter.value = 0;\n    },\n  };\n\n  return factory;\n}\n\n/**\n * Define a model factory: deterministic attributes for tests and seeders.\n *\n * `make()` builds attributes only (no database), `create()` saves through the\n * model's own `create()`, so casts, defaults, hooks and events all run.\n *\n * @example\n * export const userFactory = defineFactory(User, (seed) => ({\n *   name: seed.text(\"User\"),\n *   email: seed.email(),\n *   password: \"test-password\",\n * })).state(\"admin\", () => ({ role: \"admin\" }));\n *\n * const body = userFactory.make({ name: \"Ada\" });   // { name: \"Ada\", email: \"user1@example.test\", ... }\n * const admin = await userFactory.with(\"admin\").create();\n * const users = await userFactory.create(3);\n */\nexport function defineFactory<TModel extends Model>(\n  model: ChildModel<TModel>,\n  definition: (seed: FactorySeed) => FactoryAttributes<TModel>,\n): Factory<TModel> {\n  const counter: SequenceCounter = { value: 0 };\n\n  counters.add(counter);\n\n  return buildFactory<TModel>(model, definition, counter, new Map(), []);\n}\n"],"mappings":"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"}

package/esm/tests/fakes/cache-fake.d.mts

@@ -0,0 +1,29 @@
+import { CacheKey, MemoryCacheDriver } from "@warlock.js/cache";
+
+//#region ../../packages/core/src/tests/fakes/cache-fake.d.ts
+/**
+ * Swaps the cache's current driver for a fresh in-memory one.
+ *
+ * Installed by default in the test environment, so tests never need Redis
+ * and never see another test's keys. Everything goes through the real cache
+ * manager and the real memory driver: TTLs, tags, namespaces and locks behave
+ * as they do in production.
+ *
+ * @example
+ * await getDashboardStats(); // caches under "stats.dashboard"
+ *
+ * await cacheFake.assertHas("stats.dashboard");
+ */
+declare const cacheFake: {
+  /** Start a fresh in-memory store (idempotent: a second call empties it). */install(): Promise<void>; /** Put the previous driver back and drop the in-memory store. */
+  restore(): Promise<void>;
+  isInstalled(): boolean; /** The in-memory driver standing in for the configured one. */
+  driver(): MemoryCacheDriver; /** Empty the store. */
+  clear(): Promise<void>; /** Assert `key` is cached. */
+  assertHas(key: CacheKey): Promise<void>; /** Assert `key` is not cached. */
+  assertMissing(key: CacheKey): Promise<void>; /** Assert `key` holds a value deeply equal to `value`. */
+  assertStored(key: CacheKey, value: unknown): Promise<void>;
+};
+//#endregion
+export { cacheFake };
+//# sourceMappingURL=cache-fake.d.mts.map

package/esm/tests/fakes/cache-fake.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-fake.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tests/fakes/cache-fake.ts"],"mappings":";;;;;AA+BA;;;;;;;;;;;cAAa,SAAA;EAqEwC,uFAnElC,OAAA,QAmEyC;aAjDzC,OAAA;;YAqBP,iBAAA;WAKK,OAAA,QALL;iBAUW,QAAA,GAAW,OAAA,QALjB;qBAcU,QAAA,GAAW,OAAA,QATf;oBAkBG,QAAA,EAAQ,KAAA,YAAmB,OAAA;AAAA"}