okengine 0.20.0 → 0.21.1

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/dev.test.ts

@@ -6,7 +6,7 @@
  * context and exercises `oke.manifest.get` over HTTP on :6535.
  */
 
-import { afterEach, describe, expect, test } from "bun:test";
+import { afterEach, describe, expect, mock, test } from "bun:test";
 import { mkdir, mkdtemp, readdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
@@ -17,9 +17,19 @@ import {
 } from "../compiler/generate-adopt.ts";
 import type { Manifest } from "../manifest/types.ts";
 import type { WideEvent } from "../runs/types.ts";
+import type { ConsoleAppHandle } from "../console/server/app.ts";
+import { createConsoleState } from "../console/server/state.ts";
 import { isDataEnvelope, MCP_DATA_KIND } from "../mcp/data.ts";
 import { mintMcpSession } from "../mcp/session.ts";
-import { isFlowsTreeWatchPath, runDev, type DevOptions, type DevSession } from "./dev.ts";
+import {
+  CLIENT_REGEN_DEBOUNCE_MS,
+  isClientRegenWatchPath,
+  isFlowsTreeWatchPath,
+  runDev,
+  type DevOptions,
+  type DevSession,
+  type DevWatchFn,
+} from "./dev.ts";
 import { mcpContextFromConsole } from "./mcp-from-console.ts";
 
 /** Repo public entry — absolute import so temp apps need no install. */
@@ -803,6 +813,99 @@ describe("isFlowsTreeWatchPath", () => {
   });
 });
 
+describe("isClientRegenWatchPath", () => {
+  test("flow files and schema declares regenerate the client; unrelated files do not", () => {
+    expect(isClientRegenWatchPath("flows/notes/get.ts")).toBe(true);
+    expect(isClientRegenWatchPath("schema.ts")).toBe(true);
+    expect(isClientRegenWatchPath("db/schema/links.ts")).toBe(true);
+    expect(isClientRegenWatchPath("lib/util.ts")).toBe(false);
+    expect(isClientRegenWatchPath("flows/index.ts")).toBe(false);
+    expect(isClientRegenWatchPath("flows/notes/get.ts.tmp")).toBe(false);
+    expect(isClientRegenWatchPath("db/drizzle/schema.ts")).toBe(false);
+  });
+});
+
+describe("oke dev client regen watch", () => {
+  let session: DevSession | undefined;
+
+  afterEach(() => {
+    session?.stop();
+    session = undefined;
+    mock.restore();
+  });
+
+  test("three flow saves within 50ms regenerate the client once", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-dev-regen-"));
+    await mkdir(join(dir, "src"), { recursive: true });
+    await Bun.write(join(dir, "src/app.ts"), "export {};\n");
+
+    const extractMod = await import("../compiler/extract.ts");
+    const originalExtract = extractMod.extractManifest;
+    let extracts = 0;
+    mock.module(resolve(import.meta.dir, "../compiler/extract.ts"), () => ({
+      ...extractMod,
+      extractManifest: (opts: Parameters<typeof originalExtract>[0]) => {
+        extracts++;
+        return originalExtract(opts);
+      },
+    }));
+
+    let regens = 0;
+    let listener: Parameters<DevWatchFn>[2] | undefined;
+    const result = await runDev({
+      cwd: dir,
+      stdinIsTTY: false,
+      appPort: 0,
+      consolePort: 0,
+      mcpPort: 0,
+      ...stubSurfaces(),
+      serveConsole: async () => ({
+        port: 0,
+        stop() {},
+        console: {
+          state: createConsoleState({ cwd: dir, secret: SECRET }),
+        } as ConsoleAppHandle,
+      }),
+      startApp: async () => ({
+        port: 0,
+        url: new URL("http://127.0.0.1:9"),
+        stop() {},
+      }),
+      syncAdoptBarrel: async () => [],
+      regenClient: async () => {
+        regens++;
+      },
+      watchFs: (_path, _options, next) => {
+        listener = next;
+        return { close() {} };
+      },
+    });
+
+    expect(result.code).toBe(0);
+    session = result.session;
+    const boot = regens;
+    expect(boot).toBe(1);
+    const extractsAfterBoot = extracts;
+    expect(extractsAfterBoot).toBeGreaterThan(0);
+    if (!listener) throw new Error("watcher not started");
+
+    listener("change", "flows/notes/get.ts");
+    listener("change", "flows/notes/list.ts");
+    listener("change", "flows/notes/[id]/delete.ts");
+    await Bun.sleep(50);
+    expect(regens).toBe(boot);
+    expect(extracts).toBe(extractsAfterBoot);
+
+    await Bun.sleep(CLIENT_REGEN_DEBOUNCE_MS + 80);
+    expect(regens).toBe(boot + 1);
+    expect(extracts).toBe(extractsAfterBoot + 1);
+
+    listener("change", "lib/util.ts");
+    await Bun.sleep(CLIENT_REGEN_DEBOUNCE_MS + 80);
+    expect(regens).toBe(boot + 1);
+  });
+});
+
 describe("oke dev Docker-first", () => {
   test("dryRun always plans compose (no mode ask)", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-dev-always-compose-"));

package/src/cli/dev.ts

@@ -1417,15 +1417,26 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
 
   const watchFs: DevWatchFn =
     options.watchFs ?? ((path, watchOptions, listener) => watch(path, watchOptions, listener));
+  // Trailing timer, always re-armed. A burst resets the window and still
+  // fires once after it goes quiet — a timestamp check that only `return`s
+  // drops the save and never regenerates.
+  const clientRegen = createDebouncedRunner(() => {
+    void regen(appUrl);
+  }, CLIENT_REGEN_DEBOUNCE_MS);
+  const manifestRefresh = createDebouncedRunner(() => {
+    void refreshManifestInto(consoleState);
+  }, CLIENT_REGEN_DEBOUNCE_MS);
   const watcher = watchFs(resolve(cwd, "src"), { recursive: true }, (_event, filename) => {
     const rel = (filename?.toString() ?? "").replace(/\\/g, "/");
     if (isFlowsTreeWatchPath(rel)) {
       void syncAdoptBarrel(cwd);
     }
-    void regen(appUrl);
+    if (isClientRegenWatchPath(rel)) {
+      clientRegen.trigger();
+    }
     // Only live-extract when the host did not pin a Manifest (tests).
     if (options.manifest === undefined) {
-      void refreshManifestInto(consoleState);
+      manifestRefresh.trigger();
     }
     if (autoPushEnabled && isDomainSchemaWatchPath(filename?.toString())) {
       lastSchemaFilename = filename?.toString() ?? "schema.ts";
@@ -1444,6 +1455,8 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     stopComposeHealthWatch = null;
     bootBoard.stop();
     autoPushRunner.cancel();
+    clientRegen.cancel();
+    manifestRefresh.cancel();
     watcher.close();
     const host = attachedHost;
     attachedHost = null;
@@ -1613,6 +1626,28 @@ export function isFlowsTreeWatchPath(rel: string): boolean {
   return true;
 }
 
+/** Quiet window before one `oke-client.d.ts` regen after a burst of saves. */
+export const CLIENT_REGEN_DEBOUNCE_MS = 200;
+
+/**
+ * True when a `src/` watcher event can change the typed client
+ * (flow files, or a schema declare module those flows import).
+ *
+ * Editor temp files and the adopt barrel are excluded so a regen cannot
+ * retrigger itself.
+ *
+ * @param rel - Watcher filename (POSIX or Windows)
+ */
+export function isClientRegenWatchPath(rel: string): boolean {
+  const posix = rel.replace(/\\/g, "/");
+  if (posix.endsWith(".tmp")) return false;
+  if (isFlowsTreeWatchPath(posix)) return true;
+  if (/(^|\/)drizzle\//.test(posix)) return false;
+  if (/(^|\/)schema(\.decl)?\.tsx?$/.test(posix)) return true;
+  if (/(^|\/)schema\/.+\.tsx?$/.test(posix)) return true;
+  return false;
+}
+
 /**
  * Frame a schema-sync failure for the `oke dev` loop: warn loud for developer
  * bugs, soft-skip only known environmental gaps. Never crashes the session.

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

@@ -12,7 +12,7 @@
  * Untriggered flows fall back to `POST /_oke/{unit}/{flow}` RPC.
  */
 
-import { createTransport, type Transport } from "./transport.ts";
+import { createTransport, transportEnvelope, type Transport } from "./transport.ts";
 import { asThenableIterable, attachPager } from "./pager.ts";
 import {
   flattenLiveRoutes,
@@ -33,6 +33,7 @@ import type {
   LiveHandlers,
   ResolveApp,
 } from "./types.ts";
+import { methodAndPath, walkContracts } from "./wire.ts";
 
 /** App-shaped value that carries a runtime `$routes` table from typed adopt. */
 export interface AppWithRoutes {
@@ -169,19 +170,11 @@ function mergeHeaders(base: ClientHeaders | undefined, over: ClientHeaders): Cli
 export function flattenRoutes(
   $routes: ClientRouteMap | undefined,
 ): ClientOptions["routes"] | undefined {
-  if (!$routes) return undefined;
   const out: Record<string, { readonly method: string; readonly path: string }> = {};
-  for (const [unit, flows] of Object.entries($routes)) {
-    if (!flows || typeof flows !== "object") continue;
-    for (const [flow, contract] of Object.entries(flows)) {
-      if (!contract || typeof contract !== "object") continue;
-      const method = "method" in contract ? contract.method : undefined;
-      const path = "path" in contract ? contract.path : undefined;
-      if (typeof method === "string" && typeof path === "string") {
-        out[`${unit}.${flow}`] = { method, path };
-      }
-    }
-  }
+  walkContracts($routes, (unit, flow, contract) => {
+    const route = methodAndPath(contract);
+    if (route) out[`${unit}.${flow}`] = route;
+  });
   return Object.keys(out).length > 0 ? out : undefined;
 }
 
@@ -194,27 +187,21 @@ 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(".") || "?"}(…)`,
-            },
-          },
-        },
+        transportEnvelope(message),
         (nextInput) => invoke(nextInput, callOpts),
         input,
       );
     }
     const unit = path[0]!;
     const flow = path.slice(1).join(".");
-    const result = await transport.call(`${unit}/${flow}`, input, {
-      headers: ctx.perCallHeaders.read(),
-      ...(callOpts?.response !== undefined ? { response: callOpts.response } : {}),
-      ...(callOpts?.signal !== undefined ? { signal: callOpts.signal } : {}),
-    });
+    const headers = ctx.perCallHeaders.read();
+    const result = await transport.call(
+      `${unit}/${flow}`,
+      input,
+      callOpts ? { headers, ...callOpts } : headers,
+    );
     return attachPager(result, (nextInput) => invoke(nextInput, callOpts), input);
   };
   const call = (a?: unknown, b?: unknown): unknown => {

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]);
+  });
+});