@lunora/errors 0.0.1 → 1.0.0-alpha.10

package/dist/index.d.ts

@@ -0,0 +1,444 @@
+/** Markdown hint: a single string or an array of lines. Shape matches `@visulima/error`'s `hint`. */
+type ErrorHint = string | ReadonlyArray<string>;
+/** A catalog entry: the fixed metadata for one error `code`. */
+interface ErrorCatalogEntry {
+  /** Optional URL to deeper docs for this error. */
+  docsUrl?: string;
+  /** Optional actionable fix, authored as Markdown (rendered by CLI/overlay/Studio). */
+  hint?: ErrorHint;
+  /**
+   * When `true`, this code's `message` must NOT cross the wire — an internal
+   * failure or unhandled invariant may carry SQL fragments, file paths, or
+   * internal identifiers. The transport mappers emit a generic message for
+   * these (and log the real one server-side). See {@link isInternalCode}.
+   */
+  internal?: boolean;
+  /** HTTP/RPC status this code maps to on the wire. */
+  status: number;
+  /** Short, human-readable summary. */
+  title: string;
+}
+/**
+ * Every well-known Lunora error code. Domain packages may throw additional
+ * codes (passing an explicit `status`); those are added here as their package is
+ * migrated. The keys of this object form the {@link LunoraErrorCode} union.
+ */
+declare const ERROR_CATALOG: {
+  readonly BAD_REQUEST: {
+    readonly status: 400;
+    readonly title: "Bad request";
+  };
+  readonly UNAUTHORIZED: {
+    readonly status: 401;
+    readonly title: "Unauthorized";
+  };
+  readonly FORBIDDEN: {
+    readonly status: 403;
+    readonly title: "Forbidden";
+  };
+  readonly NOT_FOUND: {
+    readonly status: 404;
+    readonly title: "Not found";
+  };
+  readonly CONFLICT: {
+    readonly hint: readonly ["Another write changed this row while your mutation was running (optimistic concurrency conflict).", "", "Re-read the row and retry the mutation with the fresh value. Lunora serializes a DO's mutations, so a persistent conflict usually means the handler conflicts **with itself** (e.g. a trigger or cascade touching the same row) — split that work rather than adding a retry loop."];
+    readonly status: 409;
+    readonly title: "Conflict";
+  };
+  readonly NOT_UNIQUE: {
+    readonly hint: readonly ["`.unique()` matched more than one document — it expects the query to identify at most one row.", "", "- If several matches are legitimate, use `.first()` (take one) or `.collect()` (take all) instead.", "- Otherwise tighten the query (e.g. filter on a unique/indexed field) so it can only match one row."];
+    readonly status: 400;
+    readonly title: "Query matched more than one document";
+  };
+  readonly VALIDATION_ERROR: {
+    readonly status: 400;
+    readonly title: "Validation failed";
+  };
+  readonly TOO_MANY_REQUESTS: {
+    readonly status: 429;
+    readonly title: "Too many requests";
+  };
+  readonly UNPROCESSABLE: {
+    readonly status: 422;
+    readonly title: "Unprocessable";
+  };
+  readonly NOT_IMPLEMENTED: {
+    readonly status: 501;
+    readonly title: "Not implemented";
+  };
+  /** RPC/REST dispatch codes emitted by the runtime + Durable Object router. */
+  readonly FUNCTION_NOT_FOUND: {
+    readonly status: 404;
+    readonly title: "Function not found";
+  };
+  readonly METHOD_NOT_ALLOWED: {
+    readonly status: 405;
+    readonly title: "Method not allowed";
+  };
+  readonly PAYLOAD_TOO_LARGE: {
+    readonly status: 413;
+    readonly title: "Payload too large";
+  };
+  /** Free-form internal failure — redacted to a generic message on the wire. */
+  readonly INTERNAL: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "Internal error";
+  };
+  /** Alias of {@link ERROR_CATALOG.INTERNAL} kept for `@lunora/server`'s historical code name. */
+  readonly INTERNAL_SERVER_ERROR: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "Internal error";
+  };
+  /** Non-mappable throw crossed the RPC boundary. */
+  readonly RPC_FAILED: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "Internal error";
+  };
+  readonly COUNT_RLS_UNSUPPORTED: {
+    readonly status: 422;
+    readonly title: "count() is unsupported under an RLS policy";
+  };
+  readonly MASK_UNSUPPORTED: {
+    readonly status: 422;
+    readonly title: "Aggregation over a masked column is unsupported";
+  };
+  readonly RELATION_PREDICATE_UNSUPPORTED: {
+    readonly status: 422;
+    readonly title: "Relation predicate is unsupported in a write policy";
+  };
+  readonly RLS_REQUIRED: {
+    readonly hint: readonly ["This table is secure-by-default: it has no `.public()` marker and no RLS policy resolved for the caller, so the read fails closed.", "", "Add a read policy with `.rls(...)`, or mark the table `.public()` if it is intentionally world-readable."];
+    readonly status: 403;
+    readonly title: "RLS policy required";
+  };
+  readonly RUN_DEPTH_EXCEEDED: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "Run depth exceeded";
+  };
+  readonly TRANSACTION_LIMIT_EXCEEDED: {
+    readonly hint: readonly ["A single mutation may only read and write a bounded amount before it is stopped.", "", "Narrow the read with an index (`.withIndex(...)`) instead of scanning the table, or split the write across several mutations — for a large backfill use `defineMigration` + `lunora migrate up`, which batches and checkpoints for you.", "", "The ceilings are deliberately conservative — they exist to stop one request taking down the whole shard. A deployment that genuinely needs bigger transactions can raise them by overriding the `transactionLimits()` seam on its generated shard class."];
+    readonly status: 413;
+    readonly title: "Transaction limit exceeded";
+  };
+  readonly MIGRATION_NOT_FOUND: {
+    readonly status: 404;
+    readonly title: "Data migration not found";
+  };
+  readonly UNKNOWN_TABLE: {
+    readonly status: 404;
+    readonly title: "Unknown table";
+  };
+  readonly GLOBAL_TABLE_NOT_EDITABLE: {
+    readonly status: 400;
+    readonly title: "Global table is not editable";
+  };
+  readonly SHARD_ERROR: {
+    readonly status: 503;
+    readonly title: "Shard error";
+  };
+  readonly SHARD_UNAVAILABLE: {
+    readonly status: 503;
+    readonly title: "Shard unavailable";
+  };
+  readonly OFFLINE_IDENTITY_CHANGED: {
+    readonly status: 409;
+    readonly title: "Offline identity changed";
+  };
+  /** Package-specific codes. Build-time-only — never cross the RPC wire, so deliberately not `internal`. */
+  readonly CODEGEN_DIAGNOSTIC: {
+    readonly status: 500;
+    readonly title: "Codegen diagnostic";
+  };
+  /** Build-time-only — never crosses the RPC wire, so deliberately not `internal`. */
+  readonly SCHEMA_SNAPSHOT_PARSE: {
+    readonly status: 500;
+    readonly title: "Schema snapshot parse error";
+  };
+  /** Runtime-reachable (env.ts): message enumerates failing env key names — redact on the wire. */
+  readonly ENV_INVALID: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "Invalid environment";
+  };
+  /** Runtime-reachable (auth/middleware.ts): message carries auth-wiring guidance — redact on the wire. */
+  readonly AUTH_HEADERS_MISSING: {
+    readonly internal: true;
+    readonly status: 500;
+    readonly title: "Auth headers missing";
+  };
+  /**
+   * Signup rejected by `@lunora/auth`'s email-domain gate — a disposable/throwaway
+   * provider (or a caller deny-list hit). Client-safe: the message names only the
+   * offending domain class, never a secret, so it is echoed rather than redacted.
+   */
+  readonly EMAIL_DOMAIN_BLOCKED: {
+    readonly hint: readonly ["This address's domain is on the disposable/throwaway blocklist (or your configured deny-list).", "", "Sign up with a permanent mailbox. To tune the policy, pass `blockDisposable` / `allowDomains` / `denyDomains` to `emailGate(...)` (`@lunora/auth/email-guard`)."];
+    readonly status: 400;
+    readonly title: "Email domain not allowed";
+  };
+  /**
+   * Opt-in MX verification (`@lunora/auth/email-guard`, `mx: true`) found no mail
+   * exchanger for the address's domain, so mail to it would never deliver.
+   * Client-safe: names only the domain, no secret.
+   */
+  readonly EMAIL_UNDELIVERABLE: {
+    readonly hint: readonly ["The address's domain publishes no MX (or fallback A/AAAA) records, so it can't receive mail.", "", "Check for a typo in the domain. MX verification is opt-in (`mx: true`) and needs DNS — leave it off on the edge path if DNS is unavailable."];
+    readonly status: 400;
+    readonly title: "Email domain cannot receive mail";
+  };
+  /**
+   * Upstream Cloudflare API failures surfaced from an action. The message
+   * carries the upstream response body (Cloudflare's own error text — trusted
+   * infra, not user input), so it is echoed rather than redacted. `status`
+   * here is a fallback; each throw passes the actual upstream HTTP status.
+   */
+  readonly ANALYTICS_SQL_ERROR: {
+    readonly status: 502;
+    readonly title: "Analytics Engine SQL API error";
+  };
+  readonly R2_SQL_ERROR: {
+    readonly status: 502;
+    readonly title: "R2 SQL API error";
+  };
+  readonly WORKFLOWS_REST_ERROR: {
+    readonly status: 502;
+    readonly title: "Cloudflare Workflows REST API error";
+  };
+};
+/** A well-known Lunora error code (a key of {@link ERROR_CATALOG}). */
+type LunoraErrorCode = keyof typeof ERROR_CATALOG;
+/**
+ * True when `code` is an internal/redacted code — an internal failure or
+ * unhandled invariant whose `message` must NOT cross the wire (it may carry SQL
+ * fragments, file paths, or internal identifiers). Derived from the catalog's
+ * `internal` flag so the redaction posture stays in one place (the table).
+ * Throwing a `LunoraError` with any non-internal code is the author's vouch that
+ * its message is client-safe; an unknown/unregistered code is treated as safe.
+ */
+declare const isInternalCode: (code: string) => boolean;
+/**
+ * A message-matched solution for errors that reach a consumer without a `code`
+ * — chiefly `@lunora/codegen` build errors, which are thrown as plain messages
+ * into generated code (and flattened to `{ message }` by the Vite overlay), so
+ * the message text is the only stable join key. Ordered most- to least-specific;
+ * the first matching rule wins.
+ */
+interface Solution {
+  /** Markdown body shown under the header. */
+  body: string;
+  /** Short header for the solution. */
+  header: string;
+  /** Stable id (used in DEBUG logs and tests). */
+  id: string;
+}
+/** A {@link Solution} plus its message matcher. */
+interface SolutionRule extends Solution {
+  /** True when this rule recognizes the error message. */
+  test: (message: string) => boolean;
+}
+/**
+ * Message-matched solutions (migrated verbatim from the former
+ * `@lunora/codegen` solutions table). Re-exported by `@lunora/codegen` as
+ * `LUNORA_SOLUTION_RULES` for backward compatibility.
+ */
+declare const MESSAGE_SOLUTIONS: ReadonlyArray<SolutionRule>;
+/**
+ * One documented Cloudflare **platform** error — an edge/origin (5xx) or
+ * Cloudflare-service (1xxx) failure surfaced in an error *message* rather than
+ * thrown by Lunora as a coded `LunoraError`. These reach a Lunora app as
+ * plain text: a Worker that fetches a Cloudflare-fronted origin sees `Error 522`,
+ * a deploy that throws surfaces as `Error 1101`, and so on. The fields are the
+ * curated facts a grounded explainer elaborates on — never invents beyond.
+ */
+interface CloudflarePlatformError {
+  /** Documented likely causes (a short, comma-joined clause). */
+  causes: string;
+  /** The numeric Cloudflare error code, as it appears in the message (e.g. `"522"`, `"1101"`). */
+  code: string;
+  /** Canonical Cloudflare support-docs URL for this error's family. */
+  docsUrl: string;
+  /** Which docs family the code belongs to — shown in the "see docs" line. */
+  family: "1xxx" | "5xx";
+  /** The documented remediation. */
+  fix: string;
+  /** One-line summary of what the code means. */
+  summary: string;
+  /** Cloudflare's short name for the code (e.g. `"Connection timed out"`). */
+  title: string;
+}
+/**
+ * The curated Cloudflare platform-error table. Sourced from Cloudflare's official
+ * support docs — the codes surfaced to app authors on Workers/DO deployments (the
+ * origin-connection 52x family and the Worker/DNS/security 1xxx family). `1101`
+ * (a Worker threw) and `1102` (a Worker exceeded CPU) are the most Lunora-relevant.
+ */
+declare const CLOUDFLARE_PLATFORM_ERRORS: ReadonlyArray<CloudflarePlatformError>;
+/**
+ * Recognize a Cloudflare platform-error {@link CloudflarePlatformError} in a raw
+ * error message, conservatively: the message must carry Cloudflare's own
+ * `Error &lt;code>` phrasing, or mention `cloudflare` alongside the standalone
+ * code. That keeps a bare number (`expected 520 items`) from false-matching a 5xx
+ * code, at the cost of missing a context-free code — the safe trade for a
+ * grounded hint. Returns the matched code's {@link Solution}, or `undefined`.
+ *
+ * Matching runs in two passes, strongest first: Cloudflare's own `Error &lt;code>`
+ * phrasing is unambiguous, so it must win over the weaker "mentions cloudflare
+ * near some number" heuristic regardless of table order. A single pass let a weak
+ * match on an earlier entry beat an explicit match on a later one — `"Cloudflare
+ * Error 1102: exceeded after 524 ms"` resolved to 524, and that wrong grounded
+ * fix is exactly what the explainer prompt is built from.
+ */
+declare const findCloudflarePlatformSolution: (message: string) => Solution | undefined;
+/**
+ * Flatten a Markdown hint to plain text for a terminal / non-Markdown surface:
+ * drop code-fence markers and strip inline `**bold**` / `` `code` `` emphasis.
+ * Shared by the CLI renderer and the Studio `ErrorAlert` so the two can't drift.
+ */
+declare const flattenHint: (hint: ErrorHint) => string;
+/**
+ * Find the first message-matched {@link Solution} for `message`, or `undefined`
+ * if none recognize it. Re-exported by `@lunora/codegen` as `findLunoraSolution`.
+ */
+declare const findSolutionByMessage: (message: string) => Solution | undefined;
+/**
+ * Find a solution for `message` across BOTH Lunora's own rules and the curated
+ * Cloudflare platform-error table — the lookup the Studio Issues panel and the
+ * `explainIssue` grounding use.
+ *
+ * Deliberately separate from {@link findSolutionByMessage} rather than folded into
+ * it. That function is on `resolveHint`, and therefore on `toErrorBody` — the
+ * envelope builder for every failed request. Most `ERROR_CATALOG` entries
+ * carry no `hint`, so folding the platform table in there meant an ordinary
+ * `BAD_REQUEST` whose message merely mentioned "cloudflare" near a number shipped
+ * zone-configuration guidance ("review the zone's Firewall/WAF and IP Access
+ * Rules") to unauthenticated browsers. The same fold put the table on the CLI
+ * renderer and the Vite overlay, and on `toErrorBody`'s hot path.
+ *
+ * Platform errors are operator-facing context for an already-persisted Issue, so
+ * the operator-facing surfaces opt in here and the wire path stays Lunora-only.
+ */
+declare const findIssueSolution: (message: string) => Solution | undefined;
+/**
+ * Resolve an actionable hint for an error: prefer a hint carried on the error
+ * (or its `code`'s catalog entry), then fall back to a message match. Returns
+ * `undefined` when nothing recognizes it.
+ */
+declare const resolveHint: (input: {
+  code?: string;
+  hint?: ErrorHint;
+  message?: string;
+} | string) => ErrorHint | undefined;
+/** Source location for an error (mirrors `@visulima/error`'s `ErrorLocation`). */
+interface ErrorLocation {
+  column?: number;
+  file?: string;
+  line?: number;
+}
+/** Options for {@link LunoraError}. Explicit values override the catalog defaults. */
+interface LunoraErrorOptions {
+  /** Underlying error/value that triggered this one. */
+  cause?: unknown;
+  /** Structured, JSON+wire-encodable payload surfaced to the client alongside `code`. */
+  data?: unknown;
+  /** Link to deeper docs for this error. */
+  docsUrl?: string;
+  /** Actionable fix (Markdown). Defaults to the catalog entry's hint. */
+  hint?: ErrorHint;
+  /** Source location, when known (e.g. a codegen/schema diagnostic). */
+  location?: ErrorLocation;
+  /** Override the error `name` (e.g. a subclass like `"ConflictError"`). */
+  name?: string;
+  /** Override the transport status. Defaults to the catalog entry's status, else 500. */
+  status?: number;
+  /** Override the short title. Defaults to the catalog entry's title. */
+  title?: string;
+}
+/**
+ * A code string: a well-known {@link LunoraErrorCode} (with autocomplete) or any
+ * package-specific code not yet in the catalog.
+ */
+type LunoraErrorCodeInput = LunoraErrorCode | (string & {});
+declare class LunoraError extends Error {
+  /**
+   * Discriminator recognised by `@visulima/error`'s `renderError`/`isVisulimaError`
+   * (`error.type === "VisulimaError"`), so a `LunoraError` renders like a native
+   * `VisulimaError` — hint and all.
+   */
+  readonly type = "VisulimaError";
+  /** Actionable fix (Markdown), rendered by the CLI/overlay/Studio. */
+  readonly hint: ErrorHint | undefined;
+  /** Short, human-readable summary (separate from `message`). */
+  readonly title: string | undefined;
+  /** Source location, when known (mirrors `VisulimaError.loc`). */
+  readonly loc: ErrorLocation | undefined;
+  /** Machine-readable reason, keyed into `ERROR_CATALOG`. */
+  readonly code: string;
+  /** HTTP/RPC status for the transport mappers. */
+  readonly status: number;
+  /** Optional link to deeper docs. */
+  readonly docsUrl: string | undefined;
+  /** Optional structured payload propagated verbatim to the client. */
+  readonly data: unknown;
+  constructor(code: LunoraErrorCodeInput, message?: string, options?: LunoraErrorOptions);
+}
+/** The wire-relevant shape of a Lunora error (a real `LunoraError` or a wire-decoded twin). */
+interface LunoraErrorLike extends Error {
+  code: string;
+  data?: unknown;
+  docsUrl?: string;
+  hint?: ErrorHint;
+  status: number;
+  /** Wire brand that distinguishes real `LunoraError`s from foreign errors. */
+  type: "VisulimaError";
+}
+/**
+ * True when `error` carries the Lunora transport shape (string `code` + numeric
+ * `status` + the `VisulimaError` brand). The `type` brand is what distinguishes
+ * a real `LunoraError` (or its wire-decoded twin) from a foreign error that
+ * happens to carry `code`/`status` — see plan 119 for the full rationale.
+ */
+declare const isLunoraError: (error: unknown) => error is LunoraErrorLike;
+/** Throw an `INTERNAL` {@link LunoraError} when `condition` is falsy. */
+declare const invariant: (condition: unknown, message: string) => asserts condition;
+/** Throw an `INTERNAL` {@link LunoraError} for an unreachable branch. */
+declare const unreachable: (message: string) => never;
+/** The client-facing error envelope body. */
+interface ErrorBody {
+  code: string;
+  data?: unknown;
+  docsUrl?: string;
+  hint?: ErrorHint;
+  message: string;
+}
+interface ToErrorBodyOptions {
+  /**
+   * Wire-encode a `LunoraError`'s structured `data` for the client (so a
+   * `bigint`/`bytes` inside it survives). Omit to drop `data` from the body.
+   */
+  encodeData?: (data: unknown) => unknown;
+  /** Code for an unrecognized (non-`LunoraError`) throw. Default `"INTERNAL"`. */
+  fallbackCode?: string;
+  /** Message sent when the error is redacted (internal-coded or unrecognized). Default `"Internal error"`. */
+  redactedMessage?: string;
+}
+interface ToErrorBodyResult {
+  body: ErrorBody;
+  /** True when the message was redacted — the caller should log the raw error server-side. */
+  redacted: boolean;
+  /** HTTP/RPC status. */
+  status: number;
+}
+/**
+ * Turn a thrown value into an {@link ErrorBody} + status, applying the redaction
+ * invariant. A `LunoraError` with a non-internal code is echoed with its
+ * `message`, resolved `hint`, `docsUrl`, and (when `encodeData` is given) its
+ * `data`. An internal-coded `LunoraError` keeps its `code`/`status` but its
+ * message is replaced with `redactedMessage`. Anything else becomes a generic
+ * `fallbackCode`/500. When `redacted` is `true`, log the raw error server-side.
+ */
+declare const toErrorBody: (error: unknown, options?: ToErrorBodyOptions) => ToErrorBodyResult;
+export { CLOUDFLARE_PLATFORM_ERRORS, type CloudflarePlatformError, ERROR_CATALOG, type ErrorBody, type ErrorCatalogEntry, type ErrorHint, type ErrorLocation, LunoraError, type LunoraErrorCode, type LunoraErrorCodeInput, type LunoraErrorLike, type LunoraErrorOptions, MESSAGE_SOLUTIONS, type Solution, type SolutionRule, type ToErrorBodyOptions, type ToErrorBodyResult, findCloudflarePlatformSolution, findIssueSolution, findSolutionByMessage, flattenHint, invariant, isInternalCode, isLunoraError, resolveHint, toErrorBody, unreachable };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{LunoraError as e}from"./packem_shared/LunoraError-Bi0eJQ64.mjs";import{CLOUDFLARE_PLATFORM_ERRORS as t,ERROR_CATALOG as i,MESSAGE_SOLUTIONS as a,findCloudflarePlatformSolution as f,findIssueSolution as l,findSolutionByMessage as u,flattenHint as E,isInternalCode as R,resolveHint as S}from"./packem_shared/CLOUDFLARE_PLATFORM_ERRORS-AwchC1Yo.mjs";import{isLunoraError as L}from"./packem_shared/isLunoraError-Dvew97xn.mjs";import{invariant as d,unreachable as m}from"./packem_shared/invariant-HTyw4bqA.mjs";import{toErrorBody as x}from"./packem_shared/toErrorBody-Bodp1HTL.mjs";export{t as CLOUDFLARE_PLATFORM_ERRORS,i as ERROR_CATALOG,e as LunoraError,a as MESSAGE_SOLUTIONS,f as findCloudflarePlatformSolution,l as findIssueSolution,u as findSolutionByMessage,E as flattenHint,d as invariant,R as isInternalCode,L as isLunoraError,S as resolveHint,x as toErrorBody,m as unreachable};

package/dist/packem_shared/CLOUDFLARE_PLATFORM_ERRORS-AwchC1Yo.mjs

@@ -0,0 +1,14 @@
+const o="https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/",a="https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/",s={BAD_REQUEST:{status:400,title:"Bad request"},UNAUTHORIZED:{status:401,title:"Unauthorized"},FORBIDDEN:{status:403,title:"Forbidden"},NOT_FOUND:{status:404,title:"Not found"},CONFLICT:{hint:["Another write changed this row while your mutation was running (optimistic concurrency conflict).","","Re-read the row and retry the mutation with the fresh value. Lunora serializes a DO's mutations, so a persistent conflict usually means the handler conflicts **with itself** (e.g. a trigger or cascade touching the same row) — split that work rather than adding a retry loop."],status:409,title:"Conflict"},NOT_UNIQUE:{hint:["`.unique()` matched more than one document — it expects the query to identify at most one row.","","- If several matches are legitimate, use `.first()` (take one) or `.collect()` (take all) instead.","- Otherwise tighten the query (e.g. filter on a unique/indexed field) so it can only match one row."],status:400,title:"Query matched more than one document"},VALIDATION_ERROR:{status:400,title:"Validation failed"},TOO_MANY_REQUESTS:{status:429,title:"Too many requests"},UNPROCESSABLE:{status:422,title:"Unprocessable"},NOT_IMPLEMENTED:{status:501,title:"Not implemented"},FUNCTION_NOT_FOUND:{status:404,title:"Function not found"},METHOD_NOT_ALLOWED:{status:405,title:"Method not allowed"},PAYLOAD_TOO_LARGE:{status:413,title:"Payload too large"},INTERNAL:{internal:!0,status:500,title:"Internal error"},INTERNAL_SERVER_ERROR:{internal:!0,status:500,title:"Internal error"},RPC_FAILED:{internal:!0,status:500,title:"Internal error"},COUNT_RLS_UNSUPPORTED:{status:422,title:"count() is unsupported under an RLS policy"},MASK_UNSUPPORTED:{status:422,title:"Aggregation over a masked column is unsupported"},RELATION_PREDICATE_UNSUPPORTED:{status:422,title:"Relation predicate is unsupported in a write policy"},RLS_REQUIRED:{hint:["This table is secure-by-default: it has no `.public()` marker and no RLS policy resolved for the caller, so the read fails closed.","","Add a read policy with `.rls(...)`, or mark the table `.public()` if it is intentionally world-readable."],status:403,title:"RLS policy required"},RUN_DEPTH_EXCEEDED:{internal:!0,status:500,title:"Run depth exceeded"},TRANSACTION_LIMIT_EXCEEDED:{hint:["A single mutation may only read and write a bounded amount before it is stopped.","","Narrow the read with an index (`.withIndex(...)`) instead of scanning the table, or split the write across several mutations — for a large backfill use `defineMigration` + `lunora migrate up`, which batches and checkpoints for you.","","The ceilings are deliberately conservative — they exist to stop one request taking down the whole shard. A deployment that genuinely needs bigger transactions can raise them by overriding the `transactionLimits()` seam on its generated shard class."],status:413,title:"Transaction limit exceeded"},MIGRATION_NOT_FOUND:{status:404,title:"Data migration not found"},UNKNOWN_TABLE:{status:404,title:"Unknown table"},GLOBAL_TABLE_NOT_EDITABLE:{status:400,title:"Global table is not editable"},SHARD_ERROR:{status:503,title:"Shard error"},SHARD_UNAVAILABLE:{status:503,title:"Shard unavailable"},OFFLINE_IDENTITY_CHANGED:{status:409,title:"Offline identity changed"},CODEGEN_DIAGNOSTIC:{status:500,title:"Codegen diagnostic"},SCHEMA_SNAPSHOT_PARSE:{status:500,title:"Schema snapshot parse error"},ENV_INVALID:{internal:!0,status:500,title:"Invalid environment"},AUTH_HEADERS_MISSING:{internal:!0,status:500,title:"Auth headers missing"},EMAIL_DOMAIN_BLOCKED:{hint:["This address's domain is on the disposable/throwaway blocklist (or your configured deny-list).","","Sign up with a permanent mailbox. To tune the policy, pass `blockDisposable` / `allowDomains` / `denyDomains` to `emailGate(...)` (`@lunora/auth/email-guard`)."],status:400,title:"Email domain not allowed"},EMAIL_UNDELIVERABLE:{hint:["The address's domain publishes no MX (or fallback A/AAAA) records, so it can't receive mail.","","Check for a typo in the domain. MX verification is opt-in (`mx: true`) and needs DNS — leave it off on the edge path if DNS is unavailable."],status:400,title:"Email domain cannot receive mail"},ANALYTICS_SQL_ERROR:{status:502,title:"Analytics Engine SQL API error"},R2_SQL_ERROR:{status:502,title:"R2 SQL API error"},WORKFLOWS_REST_ERROR:{status:502,title:"Cloudflare Workflows REST API error"}},h=e=>Object.hasOwn(s,e)?s[e]:void 0,b=e=>h(e)?.internal===!0,f=[{body:["Lunora codegen couldn't find a schema to generate from.","","Create `lunora/schema.ts` exporting a `defineSchema(...)` call:","","```ts",'import { defineSchema, defineTable, v } from "@lunora/server";',"","export default defineSchema({","  messages: defineTable({ body: v.string() }),","});","```","","Or run `lunora init` to scaffold Lunora (a sample `lunora/schema.ts` included) into your app."].join(`
+`),header:"No Lunora schema found",id:"lunora-schema-missing",test:e=>e.includes("defineSchema() not found")||e.includes("schema.ts not found at")},{body:["`defineSchema(...)` must be called with an **inline object literal** mapping table names to `defineTable(...)`:","","```ts","export default defineSchema({","  todos: defineTable({ title: v.string(), done: v.boolean() }),","});","```","","Codegen reads the schema statically, so it can't follow a variable or a spread — pass the object literal directly."].join(`
+`),header:"`defineSchema()` needs an inline object literal",id:"lunora-schema-not-object-literal",test:e=>e.includes("defineSchema() expects an object literal")},{body:["This table name collides with a built-in `ctx.db` member, so the generated client can't expose it.","","Rename the table to anything that isn't a reserved name (the error lists them) — e.g. `userAccounts` instead of `insert`."].join(`
+`),header:"Table name is reserved",id:"lunora-table-reserved",test:e=>e.includes("is reserved")&&e.includes("ctx.db")},{body:["Two tables resolve to the same name — usually a base table and a schema **extension** both defining it.","","Rename one of them, or drop the duplicate from the extension. Each table name must be unique across `defineSchema(...)` and every `.extend(...)`."].join(`
+`),header:"Duplicate table name",id:"lunora-table-duplicate",test:e=>e.includes("already exists")&&e.includes(".extend(")},{body:['`.jurisdiction(...)` accepts only a **string literal** of `"eu"`, `"us"`, or `"fedramp"`:',"","```ts",'defineSchema({ /* … */ }).jurisdiction("eu");',"```"].join(`
+`),header:"Invalid `.jurisdiction(...)` value",id:"lunora-jurisdiction",test:e=>e.includes("unknown jurisdiction")||e.includes("jurisdiction")&&e.includes('"eu", "us", or "fedramp"')},{body:["The `unique` flag on an index must be a **literal** `true` or `false`, not a computed value — codegen needs to read it statically:","","```ts",'defineTable({ email: v.string() }).index("by_email", ["email"], { unique: true });',"```"].join(`
+`),header:"`unique` must be a literal",id:"lunora-unique-literal",test:e=>e.includes("must be a literal")&&e.includes("unique")},{body:["A declared container/workflow class isn't re-exported by your worker entry, so `wrangler deploy` would reject it.","","Add the generated re-export shown in the error to your worker entry (e.g. `src/index.ts`):","","```ts",'export * from "./lunora/_generated/containers";',"```"].join(`
+`),header:"Binding not exported by your worker entry",id:"lunora-worker-entry-export-gap",test:e=>e.includes("not exported by your worker entry")},{body:["A row with the same value already exists in a `unique` index.","","- If you meant to upsert, use `ctx.db.<table>().upsert(...)` (or `.patch(...)` an existing row) instead of `.insert(...)`.",`- Otherwise pick a value that isn't already taken, and consider surfacing a friendly "already exists" message to the user.`].join(`
+`),header:"Unique constraint violation",id:"lunora-runtime-unique",test:e=>e.includes("unique constraint violation on")},{body:s.CONFLICT.hint.join(`
+`),header:"Optimistic concurrency conflict",id:"lunora-runtime-occ",test:e=>e.includes("optimistic concurrency conflict")}],u=[{causes:"the origin returned an empty, unknown, or malformed response Cloudflare couldn't interpret (often an origin crash or an oversized response header)",code:"520",docsUrl:o,family:"5xx",fix:"check your origin's logs for a crash, ensure it returns a valid HTTP response, and keep response headers under the size limit",summary:"Cloudflare got an unknown/empty response from your origin web server.",title:"Web server returns an unknown error"},{causes:"the origin refused the connection — the web server is down, or a firewall is blocking Cloudflare's IP ranges",code:"521",docsUrl:o,family:"5xx",fix:"confirm the origin process is running and allowlist Cloudflare's published IP ranges in your firewall/security groups",summary:"Cloudflare could not connect to your origin because it refused the connection.",title:"Web server is down"},{causes:"Cloudflare could not establish a TCP connection to the origin in time — the origin is overloaded, a firewall is dropping packets, or the origin IP is wrong",code:"522",docsUrl:o,family:"5xx",fix:"verify the origin is reachable and not overloaded, and that the DNS record points at the correct origin IP",summary:"The connection to your origin timed out before it was established.",title:"Connection timed out"},{causes:"Cloudflare cannot route to the origin at all — a bad DNS record, an origin IP that changed, or invalid routing",code:"523",docsUrl:o,family:"5xx",fix:"verify the DNS A/AAAA record points at a reachable origin IP and that no upstream network is blocking Cloudflare",summary:"Cloudflare could not reach your origin server.",title:"Origin is unreachable"},{causes:"Cloudflare made a TCP connection but the origin did not return an HTTP response within 100 seconds — a slow handler or long-running request",code:"524",docsUrl:o,family:"5xx",fix:"speed up the slow origin handler, or move long work off the request path into a background job (a Durable Object, Queue, or Workflow)",summary:"Cloudflare connected to your origin but it did not respond in time.",title:"A timeout occurred"},{causes:"the TLS handshake between Cloudflare and the origin failed — a missing/invalid origin certificate, or a cipher/SNI mismatch under Full (Strict) SSL",code:"525",docsUrl:o,family:"5xx",fix:"install a valid certificate on the origin and align your Cloudflare SSL/TLS mode with the origin's certificate setup",summary:"The SSL handshake with your origin failed.",title:"SSL handshake failed"},{causes:"Cloudflare could not validate the origin's certificate under Full (Strict) SSL — it is expired, self-signed, or issued for the wrong hostname",code:"526",docsUrl:o,family:"5xx",fix:"install a valid, publicly-trusted certificate on the origin (or use a Cloudflare Origin CA cert), matching the request hostname",summary:"Cloudflare could not validate your origin's SSL certificate.",title:"Invalid SSL certificate"},{causes:"a DNS record points at a Cloudflare IP or another prohibited address instead of your real origin",code:"1000",docsUrl:a,family:"1xxx",fix:"point the DNS record at your real origin IP, not a Cloudflare-owned or loopback address",summary:"DNS points to a prohibited IP.",title:"DNS points to prohibited IP"},{causes:"Cloudflare could not resolve the requested hostname — a Worker fetched an unresolvable host, or a DNS record is misconfigured",code:"1001",docsUrl:a,family:"1xxx",fix:"check the hostname you're requesting and the DNS records for the zone resolve to a valid origin",summary:"Cloudflare could not resolve the origin DNS.",title:"DNS resolution error"},{causes:"a Worker or DNS record targets a restricted IP (for example a Cloudflare-owned or loopback address)",code:"1002",docsUrl:a,family:"1xxx",fix:"change the Worker fetch target or DNS record to a valid, non-restricted origin address",summary:"DNS points to a prohibited IP (Worker/restricted).",title:"DNS points to a prohibited IP"},{causes:"the visitor's IP was blocked by an IP Access Rule, WAF rule, or security configuration on the zone",code:"1006",docsUrl:a,family:"1xxx",fix:"review the zone's Firewall/WAF and IP Access Rules to see why the address was banned, and adjust if it was blocked in error",summary:"Access denied: the visitor's IP has been banned.",title:"Access denied: your IP has been banned"},{causes:"your Worker threw an unhandled JavaScript exception during the request",code:"1101",docsUrl:a,family:"1xxx",fix:"reproduce with `wrangler tail` (or the Workers Logs / Studio Logs panel) to get the stack trace, then handle the throwing code path",summary:"A Worker threw a JavaScript exception.",title:"Worker threw a JavaScript exception"},{causes:"the Worker used more CPU time than a single invocation is allowed — usually a hot loop or heavy synchronous work",code:"1102",docsUrl:a,family:"1xxx",fix:"reduce per-request CPU (optimize hot loops, avoid heavy synchronous work) or offload the heavy work to a Durable Object, Queue, or Workflow",summary:"A Worker exceeded its CPU-time resource limit.",title:"Worker exceeded resource limits"}],l=e=>e!==void 0&&e>="0"&&e<="9",m=(e,t)=>{for(let r=e.indexOf(t);r!==-1;r=e.indexOf(t,r+t.length))if(!l(e[r-1])&&!l(e[r+t.length]))return!0;return!1},g=(e,t)=>{for(const r of[`error ${t}`,`error: ${t}`])for(let i=e.indexOf(r);i!==-1;i=e.indexOf(r,i+r.length))if(!l(e[i+r.length]))return!0;return!1},p=/error|cloudflare/iu,c=e=>({body:[e.summary,"",`**Likely cause:** ${e.causes}.`,"",`**Fix:** ${e.fix}.`,"",`See [Cloudflare's ${e.family} error docs](${e.docsUrl}).`].join(`
+`),header:`Cloudflare Error ${e.code}: ${e.title}`,id:`cloudflare-error-${e.code}`}),y=e=>{if(!p.test(e))return;const t=e.toLowerCase(),r=t.includes("error"),i=t.includes("cloudflare");if(r){for(const n of u)if(g(t,n.code))return c(n)}if(i){for(const n of u)if(m(t,n.code))return c(n)}},x=e=>(typeof e=="string"?e:e.join(`
+`)).split(`
+`).filter(t=>!t.startsWith("```")).join(`
+`).replaceAll(/\*\*(.+?)\*\*/gu,"$1").replaceAll(/`([^`]+)`/gu,"$1"),d=e=>{for(const t of f)if(t.test(e))return{body:t.body,header:t.header,id:t.id}},S=e=>d(e)??y(e),w=e=>{if(typeof e=="string")return d(e)?.body;if(e.hint!==void 0)return e.hint;if(e.code!==void 0){const t=h(e.code);if(t?.hint!==void 0)return t.hint}return e.message===void 0?void 0:d(e.message)?.body};export{u as CLOUDFLARE_PLATFORM_ERRORS,s as ERROR_CATALOG,f as MESSAGE_SOLUTIONS,y as findCloudflarePlatformSolution,S as findIssueSolution,d as findSolutionByMessage,x as flattenHint,h as getCatalogEntry,b as isInternalCode,w as resolveHint};

package/dist/packem_shared/LunoraError-Bi0eJQ64.mjs

@@ -0,0 +1 @@
+import{getCatalogEntry as i}from"./CLOUDFLARE_PLATFORM_ERRORS-AwchC1Yo.mjs";class c extends Error{type="VisulimaError";hint;title;loc;code;status;docsUrl;data;constructor(o,a,t={}){const s=i(o);super(a??o,t.cause===void 0?void 0:{cause:t.cause}),this.name=t.name??"LunoraError",this.hint=t.hint??s?.hint,this.title=t.title??s?.title,this.loc=t.location,this.code=o,this.status=t.status??s?.status??500,this.docsUrl=t.docsUrl??s?.docsUrl,this.data=t.data}}export{c as LunoraError};

package/dist/packem_shared/invariant-HTyw4bqA.mjs

@@ -0,0 +1 @@
+import{LunoraError as n}from"./LunoraError-Bi0eJQ64.mjs";const t=(r,a)=>{if(!r)throw new n("INTERNAL",a,{name:"InvariantError"})},e=r=>{throw new n("INTERNAL",r,{name:"InvariantError"})};export{t as invariant,e as unreachable};

package/dist/packem_shared/isLunoraError-Dvew97xn.mjs

@@ -0,0 +1 @@
+const o=t=>{if(!(t instanceof Error))return!1;const r=t;return r.type==="VisulimaError"&&typeof r.code=="string"&&typeof r.status=="number"};export{o as isLunoraError};

package/dist/packem_shared/toErrorBody-Bodp1HTL.mjs

@@ -0,0 +1 @@
+import{isInternalCode as a,resolveHint as r}from"./CLOUDFLARE_PLATFORM_ERRORS-AwchC1Yo.mjs";import{isLunoraError as c}from"./isLunoraError-Dvew97xn.mjs";const u=(o,d={})=>{const s=d.redactedMessage??"Internal error";if(c(o)){if(a(o.code))return{body:{code:o.code,message:s},redacted:!0,status:o.status};const e={code:o.code,message:o.message};o.data!==void 0&&d.encodeData!==void 0&&(e.data=d.encodeData(o.data));const t=r({code:o.code,hint:o.hint,message:o.message});return t!==void 0&&(e.hint=t),o.docsUrl!==void 0&&(e.docsUrl=o.docsUrl),{body:e,redacted:!1,status:o.status}}return{body:{code:d.fallbackCode??"INTERNAL",message:s},redacted:!0,status:500}};export{u as toErrorBody};

package/package.json

@@ -1,10 +1,50 @@
 {
   "name": "@lunora/errors",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @lunora/errors",
+  "version": "1.0.0-alpha.10",
+  "description": "Unified error layer for Lunora: one LunoraError base + a central catalog of codes, statuses, and actionable hints, rendered across CLI, overlay, Studio, and the client",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "cloudflare",
+    "durable-objects",
+    "error",
+    "error-handling",
+    "hints",
+    "lunora",
+    "workers"
+  ],
+  "homepage": "https://lunora.sh",
+  "bugs": "https://github.com/anolilab/lunora/issues",
+  "license": "FSL-1.1-Apache-2.0",
+  "author": {
+    "name": "Daniel Bannert",
+    "email": "d.bannert@anolilab.de"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anolilab/lunora.git",
+    "directory": "packages/errors"
+  },
+  "files": [
+    "./dist",
+    "README.md",
+    "LICENSE.md",
+    "__assets__"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "^22.15.0 || >=24.11.0"
+  }
+}