@lunora/errors 0.0.1 → 1.0.0-alpha.2

package/dist/index.d.mts

@@ -0,0 +1,340 @@
+/**
+* The central Lunora error catalog — the single source of truth mapping a
+* machine-readable `code` to its transport `status`, a short human `title`, and
+* (where useful) an actionable Markdown `hint` plus a `docsUrl`.
+*
+* This table is consumed everywhere an error is surfaced: the runtime/DO wire
+* mappers (status), the client SDK (code discrimination), the CLI renderer and
+* the Vite overlay (hint), and the Studio UI (title + hint + docs link). It also
+* absorbs the former `@lunora/codegen` "solutions" table (see {@link MESSAGE_SOLUTIONS})
+* so codegen build-time errors — which are thrown as plain messages into
+* generated code and lose their class identity before a consumer sees them —
+* keep their message-matched hints.
+*/
+/** Markdown hint: a single string or an array of lines. Shape matches `@visulima/error`'s `hint`. */
+type ErrorHint = string | 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 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";
+  };
+  /**
+  * 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>;
+/**
+* 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;
+/**
+* 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 {@link 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;
+}
+/** True when `error` carries the Lunora transport shape (string `code` + numeric `status`). */
+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 { 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, findSolutionByMessage, flattenHint, invariant, isInternalCode, isLunoraError, resolveHint, toErrorBody, unreachable };

package/dist/index.d.ts

@@ -0,0 +1,340 @@
+/**
+* The central Lunora error catalog — the single source of truth mapping a
+* machine-readable `code` to its transport `status`, a short human `title`, and
+* (where useful) an actionable Markdown `hint` plus a `docsUrl`.
+*
+* This table is consumed everywhere an error is surfaced: the runtime/DO wire
+* mappers (status), the client SDK (code discrimination), the CLI renderer and
+* the Vite overlay (hint), and the Studio UI (title + hint + docs link). It also
+* absorbs the former `@lunora/codegen` "solutions" table (see {@link MESSAGE_SOLUTIONS})
+* so codegen build-time errors — which are thrown as plain messages into
+* generated code and lose their class identity before a consumer sees them —
+* keep their message-matched hints.
+*/
+/** Markdown hint: a single string or an array of lines. Shape matches `@visulima/error`'s `hint`. */
+type ErrorHint = string | 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 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";
+  };
+  /**
+  * 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>;
+/**
+* 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;
+/**
+* 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 {@link 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;
+}
+/** True when `error` carries the Lunora transport shape (string `code` + numeric `status`). */
+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 { 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, findSolutionByMessage, flattenHint, invariant, isInternalCode, isLunoraError, resolveHint, toErrorBody, unreachable };

package/dist/index.mjs

@@ -0,0 +1,5 @@
+export { LunoraError } from './packem_shared/LunoraError-Dg03M4uC.mjs';
+export { ERROR_CATALOG, MESSAGE_SOLUTIONS, findSolutionByMessage, flattenHint, isInternalCode, resolveHint } from './packem_shared/ERROR_CATALOG-DAg3Unhb.mjs';
+export { isLunoraError } from './packem_shared/isLunoraError-BvsoKcWE.mjs';
+export { invariant, unreachable } from './packem_shared/invariant-BsrkuTaN.mjs';
+export { toErrorBody } from './packem_shared/toErrorBody-BbR2r6pO.mjs';