okengine 0.20.0 → 0.21.0

package/src/kernel/fx.ts

@@ -58,7 +58,7 @@ import {
   recordWouldHaveFired,
   touchDryRunStore,
 } from "./dry-run.ts";
-import { fail, type FailOptions, type FlowFailure } from "./errors.ts";
+import type { FailFn } from "./errors.ts";
 import { currentAbortSignal, linkAbort } from "./abort-scope.ts";
 import {
   fxAll,
@@ -82,6 +82,13 @@ import { okid } from "../okid.ts";
 import { lazyRequire } from "./lazy-require.ts";
 import type { AppMessageKey, MessageValues } from "../i18n/types.ts";
 
+function loadFail(): FailFn {
+  return lazyRequire<typeof import("./fail-helpers.ts")>(
+    import.meta.dir,
+    ["fail", "helpers"].join("-"),
+  ).fail;
+}
+
 /** Lazy runs/window helpers — kept off the cold `oke` static graph. */
 async function loadRunsWindow(): Promise<typeof import("../runs/window.ts")> {
   return import("../runs/window.ts");
@@ -884,11 +891,10 @@ export interface Fx {
   /**
    * Flow-boundary failure value (does not throw).
    *
-   * @param code - Declared error code (narrowed by clients via `error.code`)
-   * @param data - Error payload
-   * @param opts - Optional message
+   * Built-in helpers (`fx.fail.notFound`, `fx.fail.forbidden`, …) need no
+   * `errors:` declaration. Domain codes still use `fx.fail("OutOfStock", data)`.
    */
-  fail<E>(code: string, data: E, opts?: FailOptions): FlowFailure<E>;
+  readonly fail: FailFn;
   /** JSON response helpers (status + Stripe-style envelope). */
   readonly json: FxJson;
   /**
@@ -2246,7 +2252,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     operator,
     principal,
     tenant,
-    fail,
+    fail: loadFail(),
     json: {
       ok<T>(value: T, opts?: { readonly meta?: Record<string, unknown> }): JsonResult<T> {
         return {

package/src/kernel/index.ts

@@ -106,14 +106,15 @@ export {
   type RunTelemetry,
 } from "./run-telemetry.ts";
 
+export { fail } from "./fail-helpers.ts";
 export {
-  fail,
   formatOkeMessage,
   lookupOkeError,
   OKE_ERROR_RANGES,
   OKE_ERRORS,
   OkeError,
   throwOke,
+  type FailFn,
   type FailOptions,
   type FlowErrorValue,
   type FlowFailure,
@@ -122,6 +123,16 @@ export {
   type OkeErrorDomain,
   type OkeErrorParams,
 } from "./errors.ts";
+export {
+  BUILTIN_ERROR_STATUS,
+  httpStatusForFailure,
+  statusForBuiltinError,
+  type BuiltinErrorBag,
+  type BuiltinErrorCode,
+  type BuiltinErrorMap,
+  type BuiltinValidationIssue,
+  type DatabaseErrorReason,
+} from "./builtin-errors.ts";
 
 export {
   flow,

package/src/runtime/dev-request-log.ts

@@ -56,6 +56,8 @@ export type DevRequestLogInput = {
   readonly ms: number;
   /** Human failure detail (error.message / code) for 4xx/5xx. */
   readonly detail?: string;
+  /** Failure `error.code` for the title chip. */
+  readonly errorCode?: string;
 };
 
 /**
@@ -85,16 +87,19 @@ export function isSilentDevRequest(method: string, path: string, surface?: DevLo
  *
  * @param response - HTTP response (cloned; original body stays readable)
  */
-export async function failureDetailFromResponse(response: Response): Promise<string | undefined> {
-  if (response.status < 400) return undefined;
+export async function failureEnvelopeFromResponse(
+  response: Response,
+): Promise<{ readonly detail?: string; readonly code?: string }> {
+  if (response.status < 400) return {};
   try {
     const body: unknown = await response.clone().json();
-    if (body === null || typeof body !== "object" || !("error" in body)) return undefined;
+    if (body === null || typeof body !== "object" || !("error" in body)) return {};
     const error = (body as { error: unknown }).error;
-    if (error === null || typeof error !== "object") return undefined;
+    if (error === null || typeof error !== "object") return {};
     const rec = error as { message?: unknown; code?: unknown; data?: unknown };
+    const code = typeof rec.code === "string" ? rec.code : undefined;
     if (typeof rec.message === "string" && rec.message.trim().length > 0) {
-      return rec.message.trim();
+      return { detail: rec.message.trim(), ...(code ? { code } : {}) };
     }
     if (
       rec.data !== null &&
@@ -103,14 +108,25 @@ export async function failureDetailFromResponse(response: Response): Promise<str
       typeof (rec.data as { reason: unknown }).reason === "string"
     ) {
       const reason = (rec.data as { reason: string }).reason;
-      const code = typeof rec.code === "string" ? rec.code : "Error";
-      return `${code}: ${reason}`;
+      return {
+        detail: `${code ?? "Error"}: ${reason}`,
+        ...(code ? { code } : {}),
+      };
     }
-    if (typeof rec.code === "string") return rec.code;
+    if (code) return { detail: code, code };
   } catch {
     // non-JSON error bodies stay status-only
   }
-  return undefined;
+  return {};
+}
+
+/**
+ * Extract a short failure detail from an OKE JSON envelope body.
+ *
+ * @param response - HTTP response (cloned; original body stays readable)
+ */
+export async function failureDetailFromResponse(response: Response): Promise<string | undefined> {
+  return (await failureEnvelopeFromResponse(response)).detail;
 }
 
 /**
@@ -135,6 +151,7 @@ export function logDevRequest(input: DevRequestLogInput): void {
       status: input.status,
       ms: input.ms,
       detail: input.detail,
+      errorCode: input.errorCode,
     }),
   );
 }
@@ -167,7 +184,7 @@ export async function timedDevFetch(
   const url = new URL(request.url);
   const method = request.method.toUpperCase();
   const response = await handle(request);
-  const detail = await failureDetailFromResponse(response);
+  const envelope = await failureEnvelopeFromResponse(response);
   logDevRequest({
     surface: options.surface ?? currentDevSurface(),
     method,
@@ -176,7 +193,8 @@ export async function timedDevFetch(
     runId: options.resolveRunId?.(request, response),
     status: response.status,
     ms: Math.round(performance.now() - started),
-    detail,
+    detail: envelope.detail,
+    errorCode: envelope.code,
   });
   return response;
 }

package/src/term.test.ts

@@ -16,6 +16,7 @@ import {
   formatOkeWordmark,
   formatServiceLine,
   formatSurfaceBox,
+  formatFatalError,
   formatRequestLine,
   formatStackSummary,
   countTermLines,
@@ -296,6 +297,81 @@ describe("term", () => {
     expect(out).not.toContain("↳");
   });
 
+  test("formatRequestLine title chip includes error.code", () => {
+    const out = formatRequestLine({
+      surface: "Backend",
+      method: "POST",
+      path: "/links",
+      flow: "links.create",
+      status: 409,
+      ms: 3,
+      detail: "That value is already in use.",
+      errorCode: "Conflict",
+      color: false,
+    });
+    expect(out).toMatch(/◇ {2}409 Conflict\n/);
+  });
+
+  test("formatFatalError prints VaultBootError as OKE1510 with cause and fix", () => {
+    const err = Object.assign(new Error("vault boot failed"), {
+      name: "VaultBootError",
+      gaps: [{ name: "STRIPE_SECRET_KEY" }, { name: "DATABASE_URL" }],
+    });
+    const out = formatFatalError(err, false);
+    expect(out).toContain("OKE1510");
+    expect(out).toContain("2 secrets have no value in any resolution layer.");
+    expect(out).toContain("- STRIPE_SECRET_KEY");
+    expect(out).toContain("oke vault set");
+    expect(out).toContain("https://oke.omqkhafi.dev/e/1510");
+    expect(out).not.toContain("Error:");
+    expect(out).not.toContain("    at ");
+  });
+
+  test("formatFatalError prints GateBootError with posture gaps", () => {
+    const err = Object.assign(new Error("gate boot failed"), {
+      name: "GateBootError",
+      gaps: [{ flowId: "notes.get", method: "GET", path: "/notes/:id" }],
+    });
+    const out = formatFatalError(err, false);
+    expect(out).toContain("Gate");
+    expect(out).toContain("1 trigger(s) missing auth posture.");
+    expect(out).toContain("- notes.get GET /notes/:id");
+    expect(out).toContain("Attach a gate or `.public()`.");
+    expect(out).not.toContain("    at ");
+  });
+
+  test("formatFatalError prints PluginNeedsError with unmet needs", () => {
+    const err = Object.assign(new Error("plugin needs failed"), {
+      name: "PluginNeedsError",
+      gaps: [{ plugin: "auth", need: "store.sql" }],
+    });
+    const out = formatFatalError(err, false);
+    expect(out).toContain("Plugin");
+    expect(out).toContain("1 unmet .needs() dependency.");
+    expect(out).toContain('- auth needs "store.sql"');
+    expect(out).toContain("Install the missing plugin");
+    expect(out).not.toContain("    at ");
+  });
+
+  test("formatFatalError hides stack unless OKE_DEBUG=1", () => {
+    const prev = process.env["OKE_DEBUG"];
+    const boom = new Error("plain boom");
+    try {
+      delete process.env["OKE_DEBUG"];
+      const hidden = formatFatalError(boom, false);
+      expect(hidden).toContain("Error");
+      expect(hidden).toContain("plain boom");
+      expect(hidden).not.toContain("    at ");
+
+      process.env["OKE_DEBUG"] = "1";
+      const shown = formatFatalError(boom, false);
+      expect(shown).toContain("Error");
+    } finally {
+      if (prev === undefined) delete process.env["OKE_DEBUG"];
+      else process.env["OKE_DEBUG"] = prev;
+    }
+  });
+
   test("formatStackSummary is scannable", () => {
     const out = formatStackSummary({
       project: "oke-dev-a3f791",

package/src/term.ts

@@ -5,6 +5,9 @@
  * Flip to monochrome with `NO_COLOR=1` or non-TTY stdout.
  */
 
+import { docsUrl } from "./docs-origin.ts";
+import { lookupOkeError } from "./kernel/errors.ts";
+
 /** Whether ANSI color should be applied. */
 export function termColorEnabled(stream: { readonly isTTY?: boolean } = process.stdout): boolean {
   if (process.env["NO_COLOR"] !== undefined) return false;
@@ -701,15 +704,171 @@ export function formatDevNote(options: {
   const ink = options.tone === "error" ? s.red : s.yellow;
   const bar = `${s.dim}│${s.reset}`;
   const width = Math.max(40, Math.min(72, (process.stdout.columns ?? 80) - 6));
-  const wrapped = wrapWords(options.body.trim(), width);
+  const wrapped = wrapBodyLines(options.body.trimEnd(), width);
   const lines = [`${ink}◇${s.reset}  ${s.bold}${ink}${options.title}${s.reset}`, bar];
   for (const line of wrapped) {
-    lines.push(`${bar}  ${ink}${line}${s.reset}`);
+    lines.push(line.length === 0 ? bar : `${bar}  ${ink}${line}${s.reset}`);
   }
   lines.push(bar);
   return `${lines.join("\n")}\n`;
 }
 
+function wrapBodyLines(body: string, width: number): string[] {
+  const out: string[] = [];
+  for (const raw of body.split("\n")) {
+    const line = raw.trimEnd();
+    if (line.length === 0) {
+      out.push("");
+      continue;
+    }
+    out.push(...wrapWords(line, width));
+  }
+  return out;
+}
+
+/**
+ * Boot / start fatal — cause, optional list, fix, docs URL. No stack unless
+ * `OKE_DEBUG=1`.
+ *
+ * @param err - Thrown boot value
+ * @param color - Color on/off
+ */
+export function formatFatalError(err: unknown, color: boolean = termColorEnabled()): string {
+  const debug = process.env["OKE_DEBUG"] === "1";
+  const formatted = describeFatalError(err, debug);
+  return formatDevNote({
+    title: formatted.title,
+    body: formatted.body,
+    tone: "error",
+    color,
+  });
+}
+
+function describeFatalError(
+  err: unknown,
+  debug: boolean,
+): { readonly title: string; readonly body: string } {
+  const vault = vaultBootGaps(err);
+  if (vault) {
+    const def = lookupOkeError(1510);
+    const count = String(vault.length);
+    const cause = def
+      ? interpolateTemplate(def.cause, { count })
+      : `${count} secrets have no value in any resolution layer.`;
+    const fix = def
+      ? interpolateTemplate(def.fix, { count })
+      : "Set each name (`oke vault set <name>`, or `.env.local`).";
+    const url = def ? docsUrl(`/e/${def.code}`) : docsUrl("/e/1510");
+    const names = vault.map((g) =>
+      g.description ? `- ${g.name}: ${g.description}` : `- ${g.name}`,
+    );
+    return {
+      title: "OKE1510",
+      body: [cause, ...names, `→ ${fix}`, url].join("\n"),
+    };
+  }
+
+  const gate = namedGaps(err, "GateBootError");
+  if (gate) {
+    const lines = gate.map((g) => {
+      const rec = g as Record<string, unknown>;
+      const flow = typeof rec.flowId === "string" ? rec.flowId : "flow";
+      const method = typeof rec.method === "string" ? rec.method : "";
+      const path = typeof rec.path === "string" ? rec.path : "";
+      return `- ${flow} ${method} ${path}`.trim();
+    });
+    return {
+      title: "Gate",
+      body: [
+        `${gate.length} trigger(s) missing auth posture.`,
+        ...lines,
+        "→ Attach a gate or `.public()`.",
+      ].join("\n"),
+    };
+  }
+
+  const plugin = namedGaps(err, "PluginNeedsError");
+  if (plugin) {
+    const lines = plugin.map((g) => {
+      const rec = g as Record<string, unknown>;
+      const name = typeof rec.plugin === "string" ? rec.plugin : "plugin";
+      const need = typeof rec.need === "string" ? rec.need : "";
+      return `- ${name} needs "${need}"`;
+    });
+    return {
+      title: "Plugin",
+      body: [
+        `${plugin.length} unmet .needs() dependenc${plugin.length === 1 ? "y" : "ies"}.`,
+        ...lines,
+        "→ Install the missing plugin or bind the element / driver.",
+      ].join("\n"),
+    };
+  }
+
+  if (isOkeErrorShape(err)) {
+    return {
+      title: `OKE${err.code}`,
+      body: [err.causeText, `→ ${err.fix}`, err.docsUrl].join("\n"),
+    };
+  }
+
+  const message = err instanceof Error ? err.message : String(err);
+  const stack = debug && err instanceof Error && err.stack ? `\n${err.stack}` : "";
+  return { title: "Error", body: `${message}${stack}` };
+}
+
+function interpolateTemplate(template: string, params: Readonly<Record<string, string>>): string {
+  return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (_, key: string) => params[key] ?? `{${key}}`);
+}
+
+function vaultBootGaps(
+  err: unknown,
+): readonly { readonly name: string; readonly description?: string }[] | undefined {
+  if (!err || typeof err !== "object") return undefined;
+  if ((err as { name?: unknown }).name !== "VaultBootError") return undefined;
+  const gaps = (err as { gaps?: unknown }).gaps;
+  if (!Array.isArray(gaps)) return undefined;
+  const out: { name: string; description?: string }[] = [];
+  for (const g of gaps) {
+    if (!g || typeof g !== "object") continue;
+    const name = (g as { name?: unknown }).name;
+    if (typeof name !== "string") continue;
+    const description = (g as { description?: unknown }).description;
+    out.push({
+      name,
+      ...(typeof description === "string" ? { description } : {}),
+    });
+  }
+  return out;
+}
+
+function namedGaps(err: unknown, name: string): readonly unknown[] | undefined {
+  if (!err || typeof err !== "object") return undefined;
+  if ((err as { name?: unknown }).name !== name) return undefined;
+  const gaps = (err as { gaps?: unknown }).gaps;
+  return Array.isArray(gaps) ? gaps : undefined;
+}
+
+function isOkeErrorShape(
+  err: unknown,
+): err is { code: number; causeText: string; fix: string; docsUrl: string } {
+  if (!err || typeof err !== "object") return false;
+  const rec = err as {
+    name?: unknown;
+    code?: unknown;
+    causeText?: unknown;
+    fix?: unknown;
+    docsUrl?: unknown;
+  };
+  return (
+    rec.name === "OkeError" &&
+    typeof rec.code === "number" &&
+    typeof rec.causeText === "string" &&
+    typeof rec.fix === "string" &&
+    typeof rec.docsUrl === "string"
+  );
+}
+
 /**
  * Boot honesty notice — Clack-like column under the `oke dev` hero.
  *
@@ -808,6 +967,8 @@ export function formatRequestLine(options: {
   readonly color?: boolean;
   /** Failure detail printed on a follow-up line (4xx/5xx). */
   readonly detail?: string;
+  /** Failure `error.code` for the title chip (`409 Conflict`). */
+  readonly errorCode?: string;
   /** WideEvent / run id when the request executed a flow. */
   readonly runId?: string;
 }): string {
@@ -849,8 +1010,10 @@ export function formatRequestLine(options: {
   const detail = options.detail?.trim();
   if (!detail || options.status < 400) return main;
   const tone: DevNoteTone = options.status >= 500 ? "error" : "warn";
+  const code = options.errorCode?.trim();
+  const title = code && code.length > 0 ? `${options.status} ${code}` : String(options.status);
   const note = formatDevNote({
-    title: String(options.status),
+    title,
     body: detail,
     tone,
     color: options.color ?? termColorEnabled(),