okengine 0.20.0 → 0.21.0

package/src/cli/dev-app-runner.ts

@@ -90,7 +90,8 @@ try {
   // `bun --hot` keeps the watcher alive on an uncaught throw, so `oke dev`
   // would wait the full ready timeout after VaultBootError. Exit so the
   // parent sees a dead child immediately.
-  console.error(err);
+  const { formatFatalError } = await import("../term.ts");
+  console.error(formatFatalError(err));
   process.exit(1);
 }
 const handle = createBunRuntime().serve(mod.app, {

package/src/cli/start.ts

@@ -4,6 +4,7 @@
 
 import { resolve } from "node:path";
 import { APP_PORT } from "../runtime/types.ts";
+import { formatFatalError } from "../term.ts";
 
 /** Options for {@link runStart}. */
 export interface StartOptions {
@@ -77,7 +78,7 @@ export async function runStart(options: StartOptions = {}): Promise<number> {
     await import(entry);
     return 0;
   } catch (err) {
-    console.error(err instanceof Error ? err.message : String(err));
+    console.error(formatFatalError(err));
     return 1;
   }
 }

package/src/client/create.ts

@@ -194,14 +194,14 @@ export function flattenRoutes(
 function proxy(transport: Transport, path: readonly string[], ctx: ProxyCtx): unknown {
   const invoke = async (input?: unknown, callOpts?: CallOpts): Promise<ClientResult> => {
     if (path.length < 2) {
+      const message = `Incomplete path: api.${path.join(".") || "?"}(…)`;
       return attachPager(
         {
           data: null,
           error: {
             code: "TransportError" as const,
-            data: {
-              message: `Incomplete path: api.${path.join(".") || "?"}(…)`,
-            },
+            message,
+            data: { message },
           },
         },
         (nextInput) => invoke(nextInput, callOpts),

package/src/client/explain.test.ts

@@ -0,0 +1,252 @@
+/**
+ * Client `explain` / `match` / `matchError` — UX kinds, fields, result matcher.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { explain, match, matchError } from "./explain.ts";
+import type { BuiltinErrorMap } from "../kernel/builtin-errors.ts";
+import type { ClientError } from "./types.ts";
+
+/** Compile-time equality. */
+type Eq<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+type Assert<T extends true> = T;
+
+describe("explain — kinds", () => {
+  test("maps built-in codes", () => {
+    expect(explain({ code: "Unauthorized", data: {} }).kind).toBe("auth");
+    expect(explain({ code: "AuthFailed", data: {} }).kind).toBe("auth");
+    expect(explain({ code: "Forbidden", data: {} }).kind).toBe("permission");
+    expect(explain({ code: "NotFound", data: { id: "n1" } }).kind).toBe("missing");
+    expect(explain({ code: "Conflict", data: {} }).kind).toBe("conflict");
+    expect(explain({ code: "ForeignKey", data: {} }).kind).toBe("conflict");
+    expect(explain({ code: "ValidationError", data: { issues: [] } }).kind).toBe("invalid");
+    expect(explain({ code: "InvalidQuery", data: {} }).kind).toBe("invalid");
+    expect(explain({ code: "UnsupportedMediaType", data: {} }).kind).toBe("invalid");
+    expect(explain({ code: "RateLimited", data: {} }).kind).toBe("limited");
+    expect(explain({ code: "AuthRateLimited", data: {} }).kind).toBe("limited");
+    expect(explain({ code: "ServiceUnavailable", data: {} }).kind).toBe("unavailable");
+    expect(explain({ code: "InternalError", data: {} }).kind).toBe("failed");
+  });
+
+  test("DatabaseError reasons", () => {
+    expect(explain({ code: "DatabaseError", data: { reason: "not_null" } }).kind).toBe("invalid");
+    expect(explain({ code: "DatabaseError", data: { reason: "check" } }).kind).toBe("invalid");
+    expect(explain({ code: "DatabaseError", data: { reason: "invalid" } }).kind).toBe("invalid");
+    expect(explain({ code: "DatabaseError", data: { reason: "too_long" } }).kind).toBe("invalid");
+    expect(explain({ code: "DatabaseError", data: { reason: "out_of_range" } }).kind).toBe(
+      "invalid",
+    );
+    expect(explain({ code: "DatabaseError", data: { reason: "retryable" } }).kind).toBe(
+      "unavailable",
+    );
+    expect(explain({ code: "DatabaseError", data: { reason: "unknown" } }).kind).toBe("failed");
+    expect(explain({ code: "DatabaseError", data: {} }).kind).toBe("failed");
+  });
+
+  test("TransportError 404 is missing; other transport is unavailable", () => {
+    expect(
+      explain({
+        code: "TransportError",
+        data: { message: "Not Found", status: 404 },
+      }).kind,
+    ).toBe("missing");
+    expect(
+      explain({
+        code: "TransportError",
+        data: { message: "offline" },
+      }).kind,
+    ).toBe("unavailable");
+  });
+
+  test("domain codes are failed", () => {
+    expect(explain({ code: "FlightFull", data: { seatsLeft: 0 } }).kind).toBe("failed");
+    expect(explain({ code: "OutOfStock", data: { available: 0 } }).kind).toBe("failed");
+  });
+});
+
+describe("explain — message, retry, fields", () => {
+  test("prefers envelope message, then transport data.message, then code", () => {
+    expect(
+      explain({ code: "NotFound", data: {}, message: "The requested resource was not found." })
+        .message,
+    ).toBe("The requested resource was not found.");
+    expect(
+      explain({ code: "TransportError", data: { message: "HTTP 502", status: 502 } }).message,
+    ).toBe("HTTP 502");
+    expect(explain({ code: "OutOfStock", data: {} }).message).toBe("OutOfStock");
+  });
+
+  test("retryable and retryAfterMs", () => {
+    const limited = explain({ code: "RateLimited", data: { retryAfterMs: 1500 } });
+    expect(limited.retryable).toBe(true);
+    expect(limited.retryAfterMs).toBe(1500);
+    const unavailable = explain({ code: "ServiceUnavailable", data: { retryAfter: 12 } });
+    expect(unavailable.retryable).toBe(true);
+    expect(unavailable.retryAfterMs).toBe(12_000);
+    const missing = explain({ code: "NotFound", data: { id: "n1" } });
+    expect(missing.retryable).toBe(false);
+    expect(missing.retryAfterMs).toBeUndefined();
+  });
+
+  test("ValidationError fields join path; empty path is _", () => {
+    const e = explain({
+      code: "ValidationError",
+      data: {
+        issues: [
+          { message: "Required", path: ["email"] },
+          { message: "Too short", path: ["user", "name"] },
+          { message: "Invalid", path: [] },
+        ],
+      },
+    });
+    expect(e.kind).toBe("invalid");
+    expect(e.fields).toEqual({
+      email: "Required",
+      "user.name": "Too short",
+      _: "Invalid",
+    });
+  });
+});
+
+describe("matchError", () => {
+  type Err = ClientError<{
+    FlightFull: { seatsLeft: number };
+    NotFound: Record<string, never>;
+  }>;
+
+  test("named arm narrows FlightFull data; _ handles the rest", () => {
+    const full: Err = { code: "FlightFull", data: { seatsLeft: 2 } };
+    const seats = matchError(full, {
+      FlightFull: (data) => {
+        type _D = Assert<Eq<typeof data, { seatsLeft: number }>>;
+        const keep: _D = true;
+        expect(keep).toBe(true);
+        return data.seatsLeft;
+      },
+      _: () => -1,
+    });
+    expect(seats).toBe(2);
+
+    const miss: Err = { code: "NotFound", data: {} };
+    const fallback = matchError<Err, string | number>(miss, {
+      FlightFull: (data) => data.seatsLeft,
+      _: (e) => {
+        expect(e.kind).toBe("missing");
+        return e.code;
+      },
+    });
+    expect(fallback).toBe("NotFound");
+  });
+
+  test("kind arm runs when the code is unnamed; code wins over kind", () => {
+    const denied: Err = { code: "NotFound", data: {} };
+    const kindHit = matchError(denied, {
+      missing: (e) => {
+        type _K = Assert<Eq<(typeof e)["kind"], "missing">>;
+        const keep: _K = true;
+        expect(keep).toBe(true);
+        expect(e.kind).toBe("missing");
+        expect(e.code).toBe("NotFound");
+        return e.message;
+      },
+      _: () => "dump",
+    });
+    expect(kindHit).toBe("NotFound");
+
+    const full: Err = { code: "FlightFull", data: { seatsLeft: 3 } };
+    const codeWins = matchError(full, {
+      FlightFull: (data) => data.seatsLeft,
+      failed: () => -2,
+      _: () => -3,
+    });
+    expect(codeWins).toBe(3);
+  });
+
+  test("invalid kind exposes ValidationError fields", () => {
+    const err = {
+      code: "ValidationError",
+      data: { issues: [{ message: "Required", path: ["email"] }] },
+    } as const;
+    const fields = matchError(err, {
+      invalid: (e) => e.fields,
+      _: () => undefined,
+    });
+    expect(fields).toEqual({ email: "Required" });
+  });
+});
+
+describe("match", () => {
+  type Result =
+    | { readonly data: { readonly confirmationCode: string }; readonly error: null }
+    | {
+        readonly data: null;
+        readonly error: ClientError<{
+          FlightFull: { seatsLeft: number };
+          NotFound: Record<string, never>;
+        }>;
+      };
+
+  test("ok arm narrows success data", () => {
+    const result: Result = { data: { confirmationCode: "SK-4812" }, error: null };
+    const code = match(result, {
+      ok: (data) => {
+        type _D = Assert<Eq<typeof data, { readonly confirmationCode: string }>>;
+        const keep: _D = true;
+        expect(keep).toBe(true);
+        return data.confirmationCode;
+      },
+      _: () => "",
+    });
+    expect(code).toBe("SK-4812");
+  });
+
+  test("named code, kind, and _ on one call", () => {
+    const full: Result = {
+      data: null,
+      error: { code: "FlightFull", data: { seatsLeft: 1 } },
+    };
+    expect(
+      match<Result, string>(full, {
+        ok: () => "ok",
+        FlightFull: (data) => `wait:${data.seatsLeft}`,
+        auth: () => "signin",
+        _: (e) => e.message,
+      }),
+    ).toBe("wait:1");
+
+    const missing: Result = { data: null, error: { code: "NotFound", data: {} } };
+    expect(
+      match<Result, string>(missing, {
+        ok: () => "ok",
+        FlightFull: (data) => `wait:${data.seatsLeft}`,
+        missing: (e) => `gone:${e.code}`,
+        _: (e) => e.message,
+      }),
+    ).toBe("gone:NotFound");
+
+    const transport = {
+      data: null,
+      error: { code: "TransportError" as const, data: { message: "offline" } },
+    };
+    expect(
+      match(transport, {
+        ok: () => "ok",
+        unavailable: (e) => {
+          expect(e.retryable).toBe(true);
+          return e.message;
+        },
+        _: () => "dump",
+      }),
+    ).toBe("offline");
+  });
+});
+
+describe("BuiltinErrorMap ValidationError issues", () => {
+  test("issues are { message, path }", () => {
+    type Issue = BuiltinErrorMap["ValidationError"]["issues"][number];
+    type _Msg = Assert<Eq<Issue["message"], string>>;
+    type _Path = Assert<Eq<Issue["path"], ReadonlyArray<string | number>>>;
+    const ok: [_Msg, _Path] = [true, true];
+    expect(ok).toEqual([true, true]);
+  });
+});

package/src/client/explain.ts

@@ -0,0 +1,272 @@
+/**
+ * Collapse unknown flow / transport errors into a small UX kind.
+ *
+ * Import from `okengine/client/explain` (kept off the 5 kB `okengine/client`
+ * edge graph). Prefer {@link match} on the envelope. Name a code when this
+ * screen has special recovery (`FlightFull` → waitlist). Kind arms handle
+ * chrome (`auth` → sign-in). {@link matchError} / {@link match} require `_`
+ * so that dump bucket is never optional.
+ */
+
+/** UX family for toasts, sign-in, forms — not an HTTP status. */
+export type ErrorKind =
+  | "auth"
+  | "permission"
+  | "missing"
+  | "conflict"
+  | "invalid"
+  | "limited"
+  | "unavailable"
+  | "failed";
+
+const ERROR_KINDS: readonly ErrorKind[] = [
+  "auth",
+  "permission",
+  "missing",
+  "conflict",
+  "invalid",
+  "limited",
+  "unavailable",
+  "failed",
+];
+
+const KIND_SET: ReadonlySet<string> = new Set(ERROR_KINDS);
+
+/** Display-ready failure from {@link explain}. */
+export interface ExplainedError {
+  readonly kind: ErrorKind;
+  readonly code: string;
+  /** Envelope message, transport message, or `code` — never empty. */
+  readonly message: string;
+  readonly retryable: boolean;
+  readonly retryAfterMs?: number;
+  /** `ValidationError` path → message (`.`-joined; empty path is `_`). */
+  readonly fields?: Record<string, string>;
+}
+
+/** Input accepted by {@link explain} (flow error or transport). */
+export type ExplainableError = {
+  readonly code: string;
+  readonly data?: unknown;
+  readonly message?: string;
+};
+
+/**
+ * Envelope `{ data, error }` accepted by {@link match}.
+ *
+ * @typeParam O - Success data
+ * @typeParam Err - Failure (flow error or transport)
+ */
+export type MatchableResult<O, Err extends ExplainableError = ExplainableError> =
+  | { readonly data: O; readonly error: null }
+  | { readonly data: null; readonly error: Err };
+
+/**
+ * Cases for {@link matchError}: named codes, optional UX kinds, required `_`.
+ *
+ * Code arms receive typed `data`. Kind arms and `_` receive {@link ExplainedError}.
+ * Dispatch order: named code → kind → `_`. Kind names (`auth`, `failed`, …) are
+ * reserved — they are never treated as domain codes.
+ *
+ * @typeParam Err - Envelope error
+ * @typeParam R - Handler return
+ */
+export type MatchErrorCases<Err extends ExplainableError, R> = {
+  [K in Exclude<Err["code"], ErrorKind | "_">]?: (
+    data: Extract<Err, { readonly code: K }> extends { readonly data: infer D } ? D : unknown,
+  ) => R;
+} & {
+  [K in ErrorKind]?: (explained: ExplainedError & { readonly kind: K }) => R;
+} & {
+  /** Required dump bucket — unknown / unhandled codes and kinds. */
+  readonly _: (explained: ExplainedError) => R;
+};
+
+/**
+ * Cases for {@link match}: required `ok` plus {@link MatchErrorCases}.
+ *
+ * @typeParam O - Success data
+ * @typeParam Err - Envelope error
+ * @typeParam R - Handler return
+ */
+export type MatchResultCases<O, Err extends ExplainableError, R> = {
+  readonly ok: (data: O) => R;
+} & MatchErrorCases<Err, R>;
+
+const KIND: Record<string, ErrorKind> = {
+  Unauthorized: "auth",
+  AuthFailed: "auth",
+  Forbidden: "permission",
+  NotFound: "missing",
+  Conflict: "conflict",
+  ForeignKey: "conflict",
+  ValidationError: "invalid",
+  InvalidQuery: "invalid",
+  UnsupportedMediaType: "invalid",
+  RateLimited: "limited",
+  AuthRateLimited: "limited",
+  ServiceUnavailable: "unavailable",
+  InternalError: "failed",
+};
+
+const INVALID_DB = new Set(["not_null", "check", "invalid", "too_long", "out_of_range"]);
+
+/**
+ * Collapse a flow or transport error into chrome (`kind`, `message`, `fields`).
+ *
+ * Domain codes (`OutOfStock`, `FlightFull`) are `failed` — product UX stays
+ * on `error.code`. Does not throw.
+ *
+ * @param error - Envelope `error` from a {@link MatchableResult}
+ */
+export function explain(error: ExplainableError): ExplainedError {
+  const kind = kindOf(error);
+  const retryable = kind === "unavailable" || kind === "limited";
+  const retryAfterMs = retryable ? retryDelay(error.data) : undefined;
+  const fields = error.code === "ValidationError" ? fieldsOf(error.data) : undefined;
+  return {
+    kind,
+    code: error.code,
+    message: messageOf(error),
+    retryable,
+    ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+    ...(fields !== undefined ? { fields } : {}),
+  };
+}
+
+/**
+ * Run a named code handler, a UX {@link ErrorKind} arm, or `_`.
+ *
+ * `_` is required so store auto-map, transport, and domain codes always have
+ * a path. Named arms narrow `data` (e.g. `FlightFull` → `seatsLeft`). Kind
+ * arms receive {@link ExplainedError} (`auth` → sign-in, `invalid` → fields).
+ *
+ * @param error - Envelope error
+ * @param cases - Optional per-code / per-kind handlers plus required `_`
+ */
+export function matchError<Err extends ExplainableError, R>(
+  error: Err,
+  cases: MatchErrorCases<Err, R>,
+): R {
+  const code = error.code;
+  const codeFn = lookupCode<R>(cases, code);
+  if (codeFn !== undefined) return codeFn(error.data);
+  const explained = explain(error);
+  const kindFn = lookupKind<R>(cases, explained.kind);
+  if (kindFn !== undefined) return kindFn(explained);
+  return cases._(explained);
+}
+
+/**
+ * Run `ok` on success, otherwise the same arms as {@link matchError}.
+ *
+ * One import, one call — no `isOk` then `matchError` split.
+ *
+ * @param result - Envelope `{ data, error }`
+ * @param cases - Required `ok`, optional per-code / per-kind, required `_`
+ */
+export function match<T extends MatchableResult<unknown, ExplainableError>, R>(
+  result: T,
+  cases: MatchResultCases<MatchData<T>, MatchErr<T>, R>,
+): R {
+  if (result.error === null) return cases.ok(result.data as MatchData<T>);
+  return matchError(result.error as MatchErr<T>, cases);
+}
+
+/** Success `data` from a {@link MatchableResult} union (null-error branch only). */
+type MatchData<T> = T extends { readonly error: null; readonly data: infer O } ? O : never;
+
+/** Failure from a {@link MatchableResult} union (`error` excluding `null`). */
+type MatchErr<T> = T extends { readonly error: infer E }
+  ? E extends null
+    ? never
+    : E extends ExplainableError
+      ? E
+      : never
+  : never;
+
+function lookupCode<R>(cases: object, code: string): ((data: unknown) => R) | undefined {
+  if (code === "_" || code === "ok" || KIND_SET.has(code)) return undefined;
+  const handler = (cases as Record<string, unknown>)[code];
+  return typeof handler === "function" ? (handler as (data: unknown) => R) : undefined;
+}
+
+function lookupKind<R>(
+  cases: object,
+  kind: ErrorKind,
+): ((explained: ExplainedError) => R) | undefined {
+  const handler = (cases as Record<string, unknown>)[kind];
+  return typeof handler === "function" ? (handler as (explained: ExplainedError) => R) : undefined;
+}
+
+function kindOf(error: ExplainableError): ErrorKind {
+  if (error.code === "TransportError") {
+    return transportStatus(error.data) === 404 ? "missing" : "unavailable";
+  }
+  if (error.code === "DatabaseError") {
+    const reason = dataReason(error.data);
+    if (reason === "retryable") return "unavailable";
+    if (reason !== undefined && INVALID_DB.has(reason)) return "invalid";
+    return "failed";
+  }
+  return KIND[error.code] ?? "failed";
+}
+
+function messageOf(error: ExplainableError): string {
+  if (typeof error.message === "string" && error.message.length > 0) return error.message;
+  const data = error.data;
+  if (
+    error.code === "TransportError" &&
+    data !== null &&
+    typeof data === "object" &&
+    "message" in data &&
+    typeof (data as { message: unknown }).message === "string" &&
+    (data as { message: string }).message.length > 0
+  ) {
+    return (data as { message: string }).message;
+  }
+  return error.code;
+}
+
+function retryDelay(data: unknown): number | undefined {
+  if (data === null || typeof data !== "object") return undefined;
+  const rec = data as { retryAfterMs?: unknown; retryAfter?: unknown };
+  if (typeof rec.retryAfterMs === "number") return rec.retryAfterMs;
+  if (typeof rec.retryAfter === "number") return rec.retryAfter * 1000;
+  return undefined;
+}
+
+function fieldsOf(data: unknown): Record<string, string> | undefined {
+  if (data === null || typeof data !== "object" || !("issues" in data)) return undefined;
+  const issues = (data as { issues: unknown }).issues;
+  if (!Array.isArray(issues) || issues.length === 0) return undefined;
+  const fields: Record<string, string> = {};
+  for (const issue of issues) {
+    if (issue === null || typeof issue !== "object") continue;
+    const rec = issue as { message?: unknown; path?: unknown };
+    if (typeof rec.message !== "string") continue;
+    fields[pathKey(rec.path)] = rec.message;
+  }
+  return Object.keys(fields).length > 0 ? fields : undefined;
+}
+
+function pathKey(path: unknown): string {
+  if (!Array.isArray(path) || path.length === 0) return "_";
+  const parts: string[] = [];
+  for (const p of path) {
+    if (typeof p === "string" || typeof p === "number") parts.push(String(p));
+  }
+  return parts.length > 0 ? parts.join(".") : "_";
+}
+
+function transportStatus(data: unknown): number | undefined {
+  if (data === null || typeof data !== "object" || !("status" in data)) return undefined;
+  const status = (data as { status: unknown }).status;
+  return typeof status === "number" ? status : undefined;
+}
+
+function dataReason(data: unknown): string | undefined {
+  if (data === null || typeof data !== "object" || !("reason" in data)) return undefined;
+  const reason = (data as { reason: unknown }).reason;
+  return typeof reason === "string" ? reason : undefined;
+}

package/src/client/live.test.ts

@@ -413,6 +413,50 @@ describe("createClient — live", () => {
   });
 });
 
+describe("sseError — envelope message fallback", () => {
+  test("prefers top-level error.message", async () => {
+    const { sseError } = await import("./sse.ts");
+    const err = sseError(
+      401,
+      JSON.stringify({
+        data: null,
+        error: { code: "Unauthorized", message: "Auth required", data: {} },
+      }),
+    );
+    expect(err.message).toBe("Auth required");
+  });
+
+  test("falls back to error.data.message", async () => {
+    const { sseError } = await import("./sse.ts");
+    const err = sseError(
+      401,
+      JSON.stringify({
+        data: null,
+        error: { code: "Unauthorized", data: { message: "Auth required" } },
+      }),
+    );
+    expect(err.message).toBe("Auth required");
+  });
+
+  test("falls back to error.code", async () => {
+    const { sseError } = await import("./sse.ts");
+    const err = sseError(
+      401,
+      JSON.stringify({
+        data: null,
+        error: { code: "Unauthorized" },
+      }),
+    );
+    expect(err.message).toBe("Unauthorized");
+  });
+
+  test("falls back to HTTP status for plain body", async () => {
+    const { sseError } = await import("./sse.ts");
+    const err = sseError(401, "nope");
+    expect(err.message).toBe("nope");
+  });
+});
+
 async function waitFor(pred: () => boolean, ms = 500): Promise<void> {
   const start = Date.now();
   while (!pred()) {

package/src/client/notes-contract.test.ts

@@ -76,6 +76,16 @@ describe("Notes — typeof app carries contracts", () => {
     expect(typeof api.notes.create).toBe("function");
   });
 
+  test("create without errors: bag still types built-in NotFound", () => {
+    const app = oke({ name: "notes" }).adopt({ notes: { create } });
+    const api = createClient<typeof app>("http://localhost:6530");
+    type CreateError = NonNullable<Awaited<ReturnType<typeof api.notes.create>>["error"]>;
+    type NotFoundData = Extract<CreateError, { code: "NotFound" }>["data"];
+    type _Id = Assert<Eq<NotFoundData["id"], string | undefined>>;
+    const ok: [_Id] = [true];
+    expect(ok).toEqual([true]);
+  });
+
   test("Notes client block: createClient<App> narrows data and NotFound", async () => {
     const app = oke({ name: "notes" }).adopt({ notes });
     type App = typeof app;

package/src/client/sse.ts

@@ -124,8 +124,12 @@ export function sseError(status: number, body: string): Error {
     try {
       const json: unknown = JSON.parse(body);
       if (json !== null && typeof json === "object" && "error" in json) {
-        const err = (json as { error?: { code?: string; data?: { message?: string } } }).error;
-        message = err?.data?.message ?? err?.code ?? message;
+        const err = (
+          json as {
+            error?: { code?: string; message?: string; data?: { message?: string } };
+          }
+        ).error;
+        message = err?.message ?? err?.data?.message ?? err?.code ?? message;
       }
     } catch {
       message = body.slice(0, 200);