@lunora/errors 0.0.1 → 1.0.0-alpha.2

package/dist/packem_shared/ERROR_CATALOG-DAg3Unhb.mjs

@@ -0,0 +1,220 @@
+const ERROR_CATALOG = {
+  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" },
+  /** RPC/REST dispatch codes emitted by the runtime + Durable Object router. */
+  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" },
+  /** Free-form internal failure — redacted to a generic message on the wire. */
+  INTERNAL: { internal: true, status: 500, title: "Internal error" },
+  /** Alias of {@link ERROR_CATALOG.INTERNAL} kept for `@lunora/server`'s historical code name. */
+  INTERNAL_SERVER_ERROR: { internal: true, status: 500, title: "Internal error" },
+  /** Non-mappable throw crossed the RPC boundary. */
+  RPC_FAILED: { internal: true, 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"
+  },
+  SHARD_ERROR: { status: 503, title: "Shard error" },
+  SHARD_UNAVAILABLE: { status: 503, title: "Shard unavailable" },
+  OFFLINE_IDENTITY_CHANGED: { status: 409, title: "Offline identity changed" },
+  /** Package-specific codes. Build-time-only — never cross the RPC wire, so deliberately not `internal`. */
+  CODEGEN_DIAGNOSTIC: { status: 500, title: "Codegen diagnostic" },
+  /** Build-time-only — never crosses the RPC wire, so deliberately not `internal`. */
+  SCHEMA_SNAPSHOT_PARSE: { status: 500, title: "Schema snapshot parse error" },
+  /** Runtime-reachable (env.ts): message enumerates failing env key names — redact on the wire. */
+  ENV_INVALID: { internal: true, status: 500, title: "Invalid environment" },
+  /** Runtime-reachable (auth/middleware.ts): message carries auth-wiring guidance — redact on the wire. */
+  AUTH_HEADERS_MISSING: { internal: true, status: 500, 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.
+   */
+  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" }
+};
+const isInternalCode = (code) => ERROR_CATALOG[code]?.internal === true;
+const MESSAGE_SOLUTIONS = [
+  {
+    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("\n"),
+    header: "No Lunora schema found",
+    id: "lunora-schema-missing",
+    test: (message) => message.includes("defineSchema() not found") || message.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("\n"),
+    header: "`defineSchema()` needs an inline object literal",
+    id: "lunora-schema-not-object-literal",
+    test: (message) => message.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("\n"),
+    header: "Table name is reserved",
+    id: "lunora-table-reserved",
+    test: (message) => message.includes("is reserved") && message.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("\n"),
+    header: "Duplicate table name",
+    id: "lunora-table-duplicate",
+    // Anchor on `.extend(` — the only Lunora throw for this is
+    // `defineSchema(...).extend(...): table "x" already exists …`. Matching a
+    // bare "already exists"/"extension" pair would false-positive on
+    // unrelated forwarded errors (e.g. a "file already exists" + "extension").
+    test: (message) => message.includes("already exists") && message.includes(".extend(")
+  },
+  {
+    body: [
+      '`.jurisdiction(...)` accepts only a **string literal** of `"eu"`, `"us"`, or `"fedramp"`:',
+      "",
+      "```ts",
+      'defineSchema({ /* … */ }).jurisdiction("eu");',
+      "```"
+    ].join("\n"),
+    header: "Invalid `.jurisdiction(...)` value",
+    id: "lunora-jurisdiction",
+    test: (message) => message.includes("unknown jurisdiction") || message.includes("jurisdiction") && message.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("\n"),
+    header: "`unique` must be a literal",
+    id: "lunora-unique-literal",
+    test: (message) => message.includes("must be a literal") && message.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("\n"),
+    header: "Binding not exported by your worker entry",
+    id: "lunora-worker-entry-export-gap",
+    test: (message) => message.includes("not exported by your worker entry")
+  },
+  {
+    // Deliberately NOT ERROR_CATALOG.NOT_UNIQUE.hint: that code (and hint)
+    // describes the read-side `.unique()` multi-match, while this matcher
+    // fires on the WRITE-path message ("unique constraint violation on
+    // <table>") thrown as a CONFLICT by an insert/patch breaching a
+    // `unique` index — a different error class needing insert remediation.
+    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("\n"),
+    header: "Unique constraint violation",
+    id: "lunora-runtime-unique",
+    test: (message) => message.includes("unique constraint violation on")
+  },
+  {
+    body: ERROR_CATALOG.CONFLICT.hint.join("\n"),
+    header: "Optimistic concurrency conflict",
+    id: "lunora-runtime-occ",
+    test: (message) => message.includes("optimistic concurrency conflict")
+  }
+];
+const flattenHint = (hint) => (Array.isArray(hint) ? hint.join("\n") : hint).split("\n").filter((line) => !line.startsWith("```")).join("\n").replaceAll(/\*\*(.+?)\*\*/gu, "$1").replaceAll(/`([^`]+)`/gu, "$1");
+const findSolutionByMessage = (message) => {
+  for (const rule of MESSAGE_SOLUTIONS) {
+    if (rule.test(message)) {
+      return { body: rule.body, header: rule.header, id: rule.id };
+    }
+  }
+  return void 0;
+};
+const resolveHint = (input) => {
+  if (typeof input === "string") {
+    return findSolutionByMessage(input)?.body;
+  }
+  if (input.hint !== void 0) {
+    return input.hint;
+  }
+  if (input.code !== void 0) {
+    const entry = ERROR_CATALOG[input.code];
+    if (entry?.hint !== void 0) {
+      return entry.hint;
+    }
+  }
+  return input.message === void 0 ? void 0 : findSolutionByMessage(input.message)?.body;
+};
+
+export { ERROR_CATALOG, MESSAGE_SOLUTIONS, findSolutionByMessage, flattenHint, isInternalCode, resolveHint };

package/dist/packem_shared/LunoraError-Dg03M4uC.mjs

@@ -0,0 +1,38 @@
+import { ERROR_CATALOG } from './ERROR_CATALOG-DAg3Unhb.mjs';
+
+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.
+   */
+  type = "VisulimaError";
+  /** Actionable fix (Markdown), rendered by the CLI/overlay/Studio. */
+  hint;
+  /** Short, human-readable summary (separate from `message`). */
+  title;
+  /** Source location, when known (mirrors `VisulimaError.loc`). */
+  loc;
+  /** Machine-readable reason, keyed into {@link ERROR_CATALOG}. */
+  code;
+  /** HTTP/RPC status for the transport mappers. */
+  status;
+  /** Optional link to deeper docs. */
+  docsUrl;
+  /** Optional structured payload propagated verbatim to the client. */
+  data;
+  constructor(code, message, options = {}) {
+    const entry = ERROR_CATALOG[code];
+    super(message ?? code, { cause: options.cause });
+    this.name = options.name ?? "LunoraError";
+    this.hint = options.hint ?? entry?.hint;
+    this.title = options.title ?? entry?.title;
+    this.loc = options.location;
+    this.code = code;
+    this.status = options.status ?? entry?.status ?? 500;
+    this.docsUrl = options.docsUrl ?? entry?.docsUrl;
+    this.data = options.data;
+  }
+}
+
+export { LunoraError };

package/dist/packem_shared/invariant-BsrkuTaN.mjs

@@ -0,0 +1,12 @@
+import { LunoraError } from './LunoraError-Dg03M4uC.mjs';
+
+const invariant = (condition, message) => {
+  if (!condition) {
+    throw new LunoraError("INTERNAL", message, { name: "InvariantError" });
+  }
+};
+const unreachable = (message) => {
+  throw new LunoraError("INTERNAL", message, { name: "InvariantError" });
+};
+
+export { invariant, unreachable };

package/dist/packem_shared/isLunoraError-BvsoKcWE.mjs

@@ -0,0 +1,9 @@
+const isLunoraError = (error) => {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const candidate = error;
+  return typeof candidate.code === "string" && typeof candidate.status === "number";
+};
+
+export { isLunoraError };

package/dist/packem_shared/toErrorBody-BbR2r6pO.mjs

@@ -0,0 +1,26 @@
+import { isInternalCode, resolveHint } from './ERROR_CATALOG-DAg3Unhb.mjs';
+import { isLunoraError } from './isLunoraError-BvsoKcWE.mjs';
+
+const toErrorBody = (error, options = {}) => {
+  const redactedMessage = options.redactedMessage ?? "Internal error";
+  if (isLunoraError(error)) {
+    if (isInternalCode(error.code)) {
+      return { body: { code: error.code, message: redactedMessage }, redacted: true, status: error.status };
+    }
+    const body = { code: error.code, message: error.message };
+    if (error.data !== void 0 && options.encodeData !== void 0) {
+      body.data = options.encodeData(error.data);
+    }
+    const hint = resolveHint({ code: error.code, hint: error.hint, message: error.message });
+    if (hint !== void 0) {
+      body.hint = hint;
+    }
+    if (error.docsUrl !== void 0) {
+      body.docsUrl = error.docsUrl;
+    }
+    return { body, redacted: false, status: error.status };
+  }
+  return { body: { code: options.fallbackCode ?? "INTERNAL", message: redactedMessage }, redacted: true, status: 500 };
+};
+
+export { 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.2",
+  "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"
+  }
+}