okengine 0.11.2 → 0.13.0

package/src/runtime/serve.test.ts

@@ -1,10 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { gate } from "../elements/gate.ts";
 import { oke } from "../kernel/app.ts";
 import { flow, resetFlowSeq } from "../kernel/flow.ts";
 import { on, resetBindings } from "../kernel/on.ts";
 import { http } from "../kernel/triggers.ts";
-import { createBunRuntime } from "./bun.ts";
+import { buildBunRoutes, createBunRuntime, serveBunHttp } from "./bun.ts";
 import { createWebStandardRuntime } from "./web-standard.ts";
 import type { ServerHandle } from "./types.ts";
 
@@ -56,13 +55,13 @@ function rawHttp(port: number, payload: string): Promise<string> {
 
 function buildApp() {
   on(
-    http.get("/ping").gate(gate.public),
+    http.get("/ping").gate.public,
     flow("ping", {
       do: () => ({ ok: true as const, n: 1 }),
     }),
   );
   on(
-    http.get("/notes/:id").gate(gate.public),
+    http.get("/notes/:id").gate.public,
     flow("notes.get", {
       do: ({ id }: { id: string }) => ({ id }),
     }),
@@ -138,6 +137,52 @@ describe("Bun.serve — real HTTP", () => {
     expect(bad.status).toBe(403);
   });
 
+  test("invalid native routes fall back to fetch — no Bun HTML example thrown", () => {
+    const server = serveBunHttp({
+      port: 0,
+      hostname: "127.0.0.1",
+      routes: {
+        "/search": {
+          QUERY: async () => new Response("native"),
+        },
+      },
+      fetch: async () => new Response("fetch"),
+    });
+    try {
+      expect(server.port).toBeGreaterThan(0);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("QUERY is omitted from native routes so Bun.serve still boots", async () => {
+    on(
+      http.query("/search").gate.public,
+      flow("search.query", {
+        do: () => ({ hits: 1 }),
+      }),
+    );
+    on(
+      http.get("/search/suggest").gate.public,
+      flow("search.suggest", {
+        do: () => ({ hits: 0 }),
+      }),
+    );
+    const app = oke({ name: "runtime-query" });
+    const routes = buildBunRoutes(app, async () => new Response("ok"));
+    expect(routes["/search"]).toBeUndefined();
+    expect(routes["/search/suggest"]?.GET).toBeTypeOf("function");
+
+    handle = createBunRuntime().serve(app, { port: 0, hostname: "127.0.0.1" });
+    const res = await fetch(new URL("/search", handle.url), {
+      method: "QUERY",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ data: { hits: 1 }, error: null });
+  });
+
   test("param route serves through Bun native routes + app pipeline", async () => {
     const app = buildApp();
     const rt = createBunRuntime();

package/src/term.test.ts

@@ -7,6 +7,7 @@ import {
   formatAppReadyLine,
   formatBootWarn,
   formatClaimNote,
+  formatDevNote,
   formatCliChrome,
   formatDevBanner,
   formatDevHero,
@@ -16,8 +17,10 @@ import {
   formatRequestLine,
   formatStackSummary,
   countTermLines,
+  createAnchoredBoard,
   formatStatusDot,
   formatStatusLine,
+  grownBoardTail,
   termStyle,
 } from "./term.ts";
 
@@ -60,11 +63,19 @@ describe("term", () => {
     expect(out).toContain("postgres");
     expect(out).toContain("● flow");
     expect(out).toContain("● ai");
+    expect(out).toContain("Starting");
+    expect(out).not.toContain("Ready");
     expect(out).not.toContain("on(Trigger)");
     expect(out).not.toContain("O·K·E");
     expect(out).not.toMatch(/\u001b\[/);
   });
 
+  test("formatDevBanner phase ready says Ready", () => {
+    const out = formatDevBanner({ color: false, phase: "ready", version: "0.2.4" });
+    expect(out).toContain("Ready");
+    expect(out).not.toContain("Starting");
+  });
+
   test("formatStatusDot colors by status", () => {
     const s = termStyle(true);
     expect(formatStatusDot("ready", true)).toBe(`${s.green}●${s.reset}`);
@@ -79,6 +90,38 @@ describe("term", () => {
     expect(countTermLines("")).toBe(0);
   });
 
+  test("grownBoardTail returns only the new rows", () => {
+    expect(grownBoardTail("a\nb\n", "a\nb\nCLAIM\n")).toBe("CLAIM\n");
+    expect(grownBoardTail("a\nb\n", "a\nb\n")).toBe("");
+  });
+
+  test("createAnchoredBoard appends growth when rewrite is off", () => {
+    const chunks: string[] = [];
+    const board = createAnchoredBoard((t) => {
+      chunks.push(t);
+    }, false);
+    board.paint("one\ntwo\n");
+    board.paint("one\ntwo\nCLAIM\n");
+    expect(chunks.join("")).toBe("one\ntwo\nCLAIM\n");
+  });
+
+  test("createAnchoredBoard inserts rows when the board grows under output", () => {
+    const chunks: string[] = [];
+    const board = createAnchoredBoard((t) => {
+      chunks.push(t);
+    }, true);
+    board.paint("A\nB\n");
+    const wrapped = board.wrapWrite((t) => {
+      chunks.push(t);
+    });
+    wrapped("url\n");
+    board.paint("A\nB\nCLAIM\n");
+    const out = chunks.join("");
+    expect(out).toContain("\x1b[1L");
+    expect(out).toContain("CLAIM");
+    expect(out).toContain("url\n");
+  });
+
   test("formatServiceLine / formatAppReadyLine include URL", () => {
     expect(formatServiceLine("Console", "http://127.0.0.1:6533", false)).toContain(
       "http://127.0.0.1:6533",
@@ -119,10 +162,18 @@ describe("term", () => {
     const out = formatClaimNote(code, false);
     expect(out).toContain(code);
     expect(out).toContain("Claim code");
+    expect(out).toContain("oke console claim-code");
     expect(out).toContain("owns the server");
     expect(out).not.toMatch(/\u001b\[/);
   });
 
+  test("formatClaimNote can point at the Console URL", () => {
+    const out = formatClaimNote("aabbccddeeff00112233445566778899", false, {
+      consoleUrl: "http://127.0.0.1:6533",
+    });
+    expect(out).toContain("Paste at http://127.0.0.1:6533");
+  });
+
   test("formatStatusLine keeps message", () => {
     expect(formatStatusLine("stack up (sql)", false)).toContain("stack up");
   });
@@ -135,6 +186,25 @@ describe("term", () => {
     expect(out).toContain("Notice");
     expect(out).toContain("process-local");
     expect(out).not.toContain("oke boot:");
+    expect(out).toMatch(/◇ {2}Notice\n│\n│ {2}Channel/);
+  });
+
+  test("formatDevNote colors the title chip and body", () => {
+    const warn = formatDevNote({
+      title: "Notice",
+      body: "open capability",
+      tone: "warn",
+      color: true,
+    });
+    const err = formatDevNote({
+      title: "500",
+      body: "boom",
+      tone: "error",
+      color: true,
+    });
+    expect(warn).toContain("\u001b[33m");
+    expect(err).toContain("\u001b[31m");
+    expect(warn).toContain("\u001b[1m");
   });
 
   test("formatCliChrome routes boot and status lines", () => {
@@ -163,6 +233,22 @@ describe("term", () => {
     expect(out).not.toMatch(/\u001b\[/);
   });
 
+  test("formatRequestLine appends run id after time", () => {
+    const at = new Date(2026, 6, 26, 3, 11, 42);
+    const out = formatRequestLine({
+      surface: "Console",
+      method: "GET",
+      path: "/console/vault",
+      flow: "console.vault.list",
+      status: 200,
+      ms: 5,
+      runId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      at,
+      color: false,
+    });
+    expect(out).toContain("03:11:42  a1b2c3d4-e5f6-7890-abcd-ef1234567890");
+  });
+
   test("formatRequestLine prints failure detail under 4xx/5xx", () => {
     const out = formatRequestLine({
       surface: "Console",
@@ -175,7 +261,9 @@ describe("term", () => {
       color: false,
     });
     expect(out).toContain("400");
-    expect(out).toContain("↳ Password needs at least 12 characters");
+    expect(out).toContain("Password needs at least 12 characters");
+    expect(out).toMatch(/◇ {2}400\n│\n│ {2}Password/);
+    expect(out).not.toContain("↳");
   });
 
   test("formatStackSummary is scannable", () => {

package/src/term.ts

@@ -125,6 +125,8 @@ export type DevHeroMeta = {
   readonly version?: string;
   readonly color?: boolean;
   readonly watching?: boolean;
+  /** Banner verb — `Starting` during boot, `Ready` after surfaces bind. */
+  readonly phase?: "starting" | "ready";
 };
 
 /**
@@ -201,7 +203,7 @@ export function formatDevBanner(options: DevHeroMeta = {}): string {
     `${s.cyan}${s.bold}┌${s.reset}  ${s.bold}oke dev${s.reset}` +
       (options.version ? `  ${s.dim}v${options.version}${s.reset}` : ""),
     bar,
-    `${s.green}◇${s.reset}  Starting`,
+    `${s.green}◇${s.reset}  ${options.phase === "ready" ? "Ready" : "Starting"}`,
   ];
   if (options.watching !== false) {
     lines.push(`${bar}  ${s.dim}watching — client types regenerate on save${s.reset}`);
@@ -343,7 +345,10 @@ export function createBootProgress(
 
 /** Live elements/Docker board that can rewrite after content is printed below. */
 export type AnchoredBoard = {
-  /** Paint or rewrite the board (same height preferred). */
+  /**
+   * Paint or rewrite the board. A taller body (claim code, extra Docker
+   * rows) inserts lines so Backend / Logs below are pushed down, not overwritten.
+   */
   readonly paint: (text: string) => void;
   /** Wrap a writer so post-board output is tracked for cursor math. */
   readonly wrapWrite: (inner: (text: string) => void) => (text: string) => void;
@@ -356,11 +361,27 @@ export type AnchoredBoard = {
   readonly stop: () => void;
 };
 
+/**
+ * Rows added when an anchored board grows (claim pane, extra Docker rows).
+ *
+ * @param previous - Last painted body
+ * @param next - Next painted body
+ */
+export function grownBoardTail(previous: string, next: string): string {
+  const prevBody = previous.endsWith("\n") ? previous.slice(0, -1) : previous;
+  const nextBody = next.endsWith("\n") ? next.slice(0, -1) : next;
+  const prevLines = prevBody.length === 0 ? 0 : prevBody.split("\n").length;
+  const nextRows = nextBody.length === 0 ? [] : nextBody.split("\n");
+  if (nextRows.length <= prevLines) return "";
+  return `${nextRows.slice(prevLines).join("\n")}\n`;
+}
+
 /**
  * Anchored status board — rewrites in place even after Backend / Logs lines.
  *
- * Uses saved cursor + line offsets. Soft-reload full-screen clears can desync;
- * later paints then append instead.
+ * Growing inserts rows (`CSI n L`) so content below shifts down. Shrinking
+ * deletes the leftover rows. Soft-reload full-screen clears can desync;
+ * {@link AnchoredBoard.reset} then paints fresh at the cursor.
  *
  * @param write - stdout writer
  * @param enabled - TTY rewrite on/off
@@ -380,7 +401,12 @@ export function createAnchoredBoard(
       const body = text.endsWith("\n") ? text : `${text}\n`;
       const nextLines = countTermLines(body);
       if (!enabled) {
-        if (boardLines === 0) write(body);
+        if (boardLines === 0) {
+          write(body);
+        } else if (body !== lastBody) {
+          const tail = grownBoardTail(lastBody, body);
+          if (tail.length > 0) write(tail);
+        }
         boardLines = nextLines;
         lastBody = body;
         return;
@@ -392,14 +418,21 @@ export function createAnchoredBoard(
         return;
       }
       if (body === lastBody) return;
-      // Move to board start, replace rows, restore cursor.
-      write("\x1b[s");
-      write(`\x1b[${belowLines + boardLines}A`);
+      const grew = nextLines - boardLines;
+      // Cursor sits after the below-board output. Move onto the first
+      // below line (or stay after the board when nothing is below).
+      if (belowLines > 0) write(`\x1b[${belowLines}A`);
+      if (grew > 0 && belowLines > 0) {
+        write(`\x1b[${grew}L`);
+      }
       eraseTermLines(write, boardLines);
       write(body);
+      if (grew < 0 && belowLines > 0) {
+        write(`\x1b[${-grew}M`);
+      }
+      if (belowLines > 0) write(`\x1b[${belowLines}B`);
       boardLines = nextLines;
       lastBody = body;
-      write("\x1b[u");
     },
     wrapWrite(inner: (text: string) => void) {
       return (text: string) => {
@@ -456,7 +489,8 @@ export function clearTerminalScreen(): string {
 }
 
 /**
- * Compact hero reprinted on soft reload — URLs stay, request logs do not.
+ * Compact hero (banner + URLs + Logs). Tests use this; the `bun --hot`
+ * child must not print it — a full reprint would wipe the claim pane.
  *
  * @param options - Surface base URLs + meta
  */
@@ -543,26 +577,45 @@ function wrapWords(text: string, width: number): string[] {
   return lines;
 }
 
+/** Tone for {@link formatDevNote} — warning (4xx / boot) or error (5xx). */
+export type DevNoteTone = "warn" | "error";
+
 /**
- * Boot honesty notice — Clack-like column under the `oke dev` hero.
+ * House note block — title chip on its own row, body underneath.
+ * Same column as Claim / Docker: `◇  Title` then `│` then `│  body`.
  *
- * @param message - Body (with or without `oke boot:` prefix)
- * @param color - Color on/off
+ * @param options - Title, body, tone
  */
-export function formatBootWarn(message: string, color: boolean = termColorEnabled()): string {
-  const s = termStyle(color);
+export function formatDevNote(options: {
+  readonly title: string;
+  readonly body: string;
+  readonly tone?: DevNoteTone;
+  readonly color?: boolean;
+}): string {
+  const s = termStyle(options.color ?? termColorEnabled());
+  const ink = options.tone === "error" ? s.red : s.yellow;
   const bar = `${s.dim}│${s.reset}`;
-  const body = message.replace(/^oke boot:\s*/i, "").trim();
   const width = Math.max(40, Math.min(72, (process.stdout.columns ?? 80) - 6));
-  const wrapped = wrapWords(body, width);
-  const lines = [`${s.yellow}◇${s.reset}  ${s.dim}Notice${s.reset}`];
+  const wrapped = wrapWords(options.body.trim(), width);
+  const lines = [`${ink}◇${s.reset}  ${s.bold}${ink}${options.title}${s.reset}`, bar];
   for (const line of wrapped) {
-    lines.push(`${bar}  ${s.dim}${line}${s.reset}`);
+    lines.push(`${bar}  ${ink}${line}${s.reset}`);
   }
   lines.push(bar);
   return `${lines.join("\n")}\n`;
 }
 
+/**
+ * Boot honesty notice — Clack-like column under the `oke dev` hero.
+ *
+ * @param message - Body (with or without `oke boot:` prefix)
+ * @param color - Color on/off
+ */
+export function formatBootWarn(message: string, color: boolean = termColorEnabled()): string {
+  const body = message.replace(/^oke boot:\s*/i, "").trim();
+  return formatDevNote({ title: "Notice", body, tone: "warn", color });
+}
+
 /**
  * Route raw CLI / boot lines into hero chrome (`│  …` or Notice boxes).
  *
@@ -632,9 +685,11 @@ export function formatDevLogTime(at: Date = new Date()): string {
  * One HTTP/RPC request line for the `oke dev` TTY.
  *
  * @example
- * `●  Backend GET  /health                 main.health            12ms  200  2026-07-26  03:11:42`
+ * `●  Backend GET  /health                 main.health            12ms  200  2026-07-26  03:11:42  a1b2c3d4-…`
+ *
+ * 4xx/5xx append a house note (`◇  401` then the message), not a dim `↳`.
  *
- * @param options - Surface, method, path, flow, timing, status
+ * @param options - Surface, method, path, flow, timing, status, run id
  */
 export function formatRequestLine(options: {
   readonly surface: DevLogSurface;
@@ -648,6 +703,8 @@ export function formatRequestLine(options: {
   readonly color?: boolean;
   /** Failure detail printed on a follow-up line (4xx/5xx). */
   readonly detail?: string;
+  /** WideEvent / run id when the request executed a flow. */
+  readonly runId?: string;
 }): string {
   const s = termStyle(options.color ?? termColorEnabled());
   const at = options.at ?? new Date();
@@ -658,7 +715,7 @@ export function formatRequestLine(options: {
   const statusColor = options.status >= 500 ? s.red : options.status >= 400 ? s.yellow : s.green;
   const methodRaw = options.method.toUpperCase();
   const methodColor =
-    methodRaw === "GET"
+    methodRaw === "GET" || methodRaw === "QUERY"
       ? s.green
       : methodRaw === "POST"
         ? s.yellow
@@ -667,10 +724,12 @@ export function formatRequestLine(options: {
           : methodRaw === "DELETE"
             ? s.red
             : s.cyan;
-  const method = methodRaw.padEnd(4);
+  const method = methodRaw.padEnd(6);
   const path = options.path.length > 28 ? `${options.path.slice(0, 27)}…` : options.path.padEnd(28);
   const flow = (options.flow ?? "—").padEnd(22);
   const ms = `${options.ms}ms`.padStart(6);
+  const runId = options.runId?.trim();
+  const run = runId && runId.length > 0 ? `  ${s.dim}${runId}${s.reset}` : "";
   const main =
     `${surfaceColor}●${s.reset}  ` +
     `${surfaceColor}${options.surface.padEnd(7)}${s.reset}  ` +
@@ -680,11 +739,18 @@ export function formatRequestLine(options: {
     `${s.dim}${ms}${s.reset}  ` +
     `${statusColor}${options.status}${s.reset}  ` +
     `${s.dim}${date}${s.reset}  ` +
-    `${s.dim}${time}${s.reset}\n`;
+    `${s.dim}${time}${s.reset}` +
+    `${run}\n`;
   const detail = options.detail?.trim();
   if (!detail || options.status < 400) return main;
-  const clipped = detail.length > 120 ? `${detail.slice(0, 119)}…` : detail;
-  return `${main}${s.dim}   ↳ ${clipped}${s.reset}\n`;
+  const tone: DevNoteTone = options.status >= 500 ? "error" : "warn";
+  const note = formatDevNote({
+    title: String(options.status),
+    body: detail,
+    tone,
+    color: options.color ?? termColorEnabled(),
+  });
+  return `${main}${s.dim}│${s.reset}\n${note}`;
 }
 
 /**
@@ -726,25 +792,33 @@ export function formatStackSummary(options: {
 
 /**
  * First-admin claim code note (clack `note`-style box).
+ * Stays on the `oke dev` board — never sent to the Console HTTP API.
  *
  * @param code - Hex claim code
  * @param color - Color on/off
+ * @param options - Optional Console URL for the paste hint
  */
-export function formatClaimNote(code: string, color: boolean = termColorEnabled()): string {
+export function formatClaimNote(
+  code: string,
+  color: boolean = termColorEnabled(),
+  options: { readonly consoleUrl?: string } = {},
+): string {
   const s = termStyle(color);
   const bar = `${s.dim}│${s.reset}`;
   const title = "Claim code";
   const hint = "expires in 30 min";
+  const paste = options.consoleUrl
+    ? `Paste at ${options.consoleUrl}  ·  oke console claim-code`
+    : "oke console claim-code";
   const ownership = "Whoever can read this log already owns the server.";
   const lines = [
-    "",
     `${s.magenta}◆${s.reset}  ${s.bold}${title}${s.reset}  ${s.dim}${hint}${s.reset}`,
     bar,
     `${bar}  ${s.bold}${code}${s.reset}`,
     bar,
+    `${bar}  ${s.dim}${paste}${s.reset}`,
     `${bar}  ${s.dim}${ownership}${s.reset}`,
     `${s.dim}└${s.reset}`,
-    "",
   ];
   return `${lines.join("\n")}\n`;
 }

package/src/test/create-test-app.ts

@@ -26,6 +26,7 @@ import { createAiRuntime, type AiPromptDecl, type AiRuntime } from "../elements/
 import { createChannelRuntime, type DeliveryReceipt } from "../elements/channel.ts";
 import { createTestClockRuntime } from "../elements/clock.ts";
 import type { GateDecl } from "../elements/gate.ts";
+import { flattenGatePolicies } from "../elements/gate/config.ts";
 import type { SignalDecl } from "../elements/signal.ts";
 import type { VaultSecretDecl } from "../elements/vault.ts";
 import type { OkeApp } from "../kernel/app.ts";
@@ -227,6 +228,7 @@ export async function createTestApp<App extends OkeApp>(
       },
     },
   };
+  const rawGates = options.gates ?? options.boot?.gates ?? appOpts.gate?.policies;
 
   await app.boot({
     ...(options.boot ?? {}),
@@ -236,7 +238,7 @@ export async function createTestApp<App extends OkeApp>(
     // boots never skip posture via this flag.
     unguardedHttp: options.boot?.unguardedHttp ?? appOpts.gate?.unguardedHttp ?? "allow",
     startScheduler: options.startScheduler ?? options.boot?.startScheduler ?? false,
-    gates: options.gates ?? options.boot?.gates ?? appOpts.gate?.policies,
+    gates: rawGates === undefined ? undefined : flattenGatePolicies(rawGates),
     secrets: options.secrets ?? options.boot?.secrets ?? appOpts.secrets,
     signals: options.signals ?? options.boot?.signals ?? appOpts.signals,
     stores: options.boot?.stores ?? appOpts.stores,