okengine 0.9.1 → 0.10.1

package/src/term.test.ts

@@ -5,7 +5,9 @@
 import { describe, expect, test } from "bun:test";
 import {
   formatAppReadyLine,
+  formatBootWarn,
   formatClaimNote,
+  formatCliChrome,
   formatDevBanner,
   formatDevHero,
   formatDevLogSeparator,
@@ -13,6 +15,11 @@ import {
   formatServiceLine,
   formatRequestLine,
   formatStackSummary,
+  countTermLines,
+  createAnchoredBoard,
+  createBootProgress,
+  createRewritableBlock,
+  formatStatusDot,
   formatStatusLine,
   termStyle,
 } from "./term.ts";
@@ -38,9 +45,10 @@ describe("term", () => {
       runtimeEnv: "local",
       system: "darwin 25.4.0 · bun 1.3.14",
       elements: [
-        { element: "flow", detail: "●" },
-        { element: "store", detail: "sql postgres · kv redis" },
-        { element: "signal", detail: "memory" },
+        { element: "flow", detail: "", status: "ready" },
+        { element: "store", detail: "sql postgres · kv redis", status: "ready" },
+        { element: "signal", detail: "memory", status: "ready" },
+        { element: "ai", detail: "openai-compatible · smollm2", status: "pending" },
       ],
     });
     expect(out).toContain("oke dev  v0.2.4");
@@ -53,11 +61,65 @@ describe("term", () => {
     expect(out).toContain("elements");
     expect(out).toContain("store");
     expect(out).toContain("postgres");
+    expect(out).toContain("● flow");
+    expect(out).toContain("● ai");
     expect(out).not.toContain("on(Trigger)");
     expect(out).not.toContain("O·K·E");
     expect(out).not.toMatch(/\u001b\[/);
   });
 
+  test("formatStatusDot colors by status", () => {
+    const s = termStyle(true);
+    expect(formatStatusDot("ready", true)).toBe(`${s.green}●${s.reset}`);
+    expect(formatStatusDot("pending", true)).toBe(`${s.yellow}●${s.reset}`);
+    expect(formatStatusDot("error", true)).toBe(`${s.red}●${s.reset}`);
+    expect(formatStatusDot("idle", true)).toBe(`${s.dim}●${s.reset}`);
+    expect(formatStatusDot("ready", false)).toBe("●");
+  });
+
+  test("createRewritableBlock appends when disabled", () => {
+    let out = "";
+    const block = createRewritableBlock((t) => {
+      out += t;
+    }, false);
+    block.paint("a\nb\n");
+    block.paint("c\n");
+    expect(out).toBe("a\nb\nc\n");
+    expect(countTermLines("a\nb\n")).toBe(2);
+  });
+
+  test("createBootProgress replaces keyed rows then clears", () => {
+    let out = "";
+    const progress = createBootProgress((t) => {
+      out += t;
+    }, false);
+    progress.set("compose", "compose…\n");
+    progress.set("compose", "compose ok\n");
+    progress.set("vault", "vault ok\n");
+    // Non-TTY appends each set (including replacements).
+    expect(out).toContain("compose ok\n");
+    expect(out).toContain("vault ok\n");
+    progress.clear();
+    // clear is a no-op on the stream when rewrite is disabled
+    expect(out).toContain("vault ok\n");
+  });
+
+  test("createAnchoredBoard wrapWrite tracks below output", () => {
+    let out = "";
+    const board = createAnchoredBoard((t) => {
+      out += t;
+    }, false);
+    board.paint("board\n");
+    const w = board.wrapWrite((t) => {
+      out += t;
+    });
+    w("below\n");
+    board.paint("board2\n"); // non-TTY: no rewrite append
+    expect(out).toContain("board\n");
+    expect(out).toContain("below\n");
+    board.stop();
+  });
+
   test("formatServiceLine / formatAppReadyLine include URL", () => {
     expect(formatServiceLine("Console", "http://127.0.0.1:6533", false)).toContain(
       "http://127.0.0.1:6533",
@@ -65,7 +127,7 @@ describe("term", () => {
     expect(formatAppReadyLine("http://127.0.0.1:6530", false)).toContain("http://127.0.0.1:6530");
   });
 
-  test("formatDevHero keeps App Console MCP URLs", () => {
+  test("formatDevHero keeps Backend Console MCP URLs", () => {
     const out = formatDevHero({
       appUrl: "http://127.0.0.1:6530",
       consoleUrl: "http://127.0.0.1:6533",
@@ -73,12 +135,12 @@ describe("term", () => {
       profile: "local",
       runtimeEnv: "local",
       system: "darwin 25.4.0 · bun 1.3.14",
-      elements: [{ element: "flow", detail: "●" }],
+      elements: [{ element: "flow", detail: "", status: "ready" }],
       color: false,
     });
     expect(out).toContain("oke dev");
     expect(out).toContain("██");
-    expect(out).toContain("App");
+    expect(out).toContain("Backend");
     expect(out).toContain("Console");
     expect(out).toContain("MCP");
     expect(out).toContain("http://127.0.0.1:6530");
@@ -106,10 +168,27 @@ describe("term", () => {
     expect(formatStatusLine("stack up (sql)", false)).toContain("stack up");
   });
 
+  test("formatBootWarn wraps under Notice chrome", () => {
+    const out = formatBootWarn(
+      "oke boot: Channel suppression defaults to process-local memory for multi-instance",
+      false,
+    );
+    expect(out).toContain("Notice");
+    expect(out).toContain("process-local");
+    expect(out).not.toContain("oke boot:");
+  });
+
+  test("formatCliChrome routes boot and status lines", () => {
+    const out = formatCliChrome("oke db seed: ok\noke boot: hello world\n", false);
+    expect(out).toContain("oke db seed: ok");
+    expect(out).toContain("Notice");
+    expect(out).toContain("hello world");
+  });
+
   test("formatRequestLine shows date, time, surface, flow, ms, status", () => {
     const at = new Date(2026, 6, 26, 3, 11, 42);
     const out = formatRequestLine({
-      surface: "App",
+      surface: "Backend",
       method: "GET",
       path: "/health",
       flow: "main.health",
@@ -120,7 +199,7 @@ describe("term", () => {
     });
     expect(out).toContain("2026-07-26");
     expect(out).toContain("03:11:42");
-    expect(out).toContain("App");
+    expect(out).toContain("Backend");
     expect(out).toContain("200");
     expect(out).not.toMatch(/\u001b\[/);
   });
@@ -144,14 +223,20 @@ describe("term", () => {
     const out = formatStackSummary({
       project: "oke-dev-a3f791",
       services: [
-        { label: "postgres", hostPort: 15975 },
-        { label: "redis", hostPort: 16975 },
+        { label: "postgres", hostPort: 15975, status: "ready" },
+        { label: "redis", hostPort: 16975, status: "ready" },
+        { label: "ai", hostPort: 23975, detail: "gemma4:e4b-q4_K_M", status: "pending" },
       ],
       appDrivers: ["postgres", "redis"],
       color: false,
     });
     expect(out).toContain("Docker");
     expect(out).toContain(":15975");
+    expect(out).toContain("gemma4:e4b-q4_K_M");
+    expect(out).toContain("● postgres");
+    expect(out).toContain("● ai");
+    // Blank │ row separates the Docker header from whatever sits above.
+    expect(out).toMatch(/│\n◇ {2}Docker/);
     expect(out).not.toMatch(/\u001b\[/);
   });
 });

package/src/term.ts

@@ -60,10 +60,56 @@ export function termStyle(color: boolean = termColorEnabled()): TermStyle {
   };
 }
 
+/**
+ * Readiness for hero / Docker status dots.
+ *
+ * - `ready` — green ●
+ * - `pending` — yellow ● (starting / loading)
+ * - `error` — red ●
+ * - `idle` — dim ● (unbound)
+ */
+export type DevStatus = "ready" | "pending" | "error" | "idle";
+
+/**
+ * Colored ● for {@link DevStatus}.
+ *
+ * @param status - Readiness
+ * @param color - Color on/off
+ */
+export function formatStatusDot(status: DevStatus, color: boolean = termColorEnabled()): string {
+  const s = termStyle(color);
+  switch (status) {
+    case "ready":
+      return `${s.green}●${s.reset}`;
+    case "pending":
+      return `${s.yellow}●${s.reset}`;
+    case "error":
+      return `${s.red}●${s.reset}`;
+    case "idle":
+      return `${s.dim}●${s.reset}`;
+  }
+}
+
+/**
+ * Map AI model phase → {@link DevStatus}.
+ *
+ * @param phase - Probe phase string
+ */
+export function devStatusFromAiPhase(
+  phase: "unreachable" | "starting" | "loading" | "ready" | "error" | string,
+): DevStatus {
+  if (phase === "ready") return "ready";
+  if (phase === "error") return "error";
+  if (phase === "unreachable" || phase === "starting" || phase === "loading") return "pending";
+  return "pending";
+}
+
 /** One eight-element row in the hero. */
 export type DevHeroElement = {
   readonly element: string;
   readonly detail: string;
+  /** Status dot (default: idle when detail is `—`, else ready). */
+  readonly status?: DevStatus;
 };
 
 /** Shared options for the `oke dev` hero / banner. */
@@ -124,10 +170,18 @@ export function formatDevHeroDetails(options: DevHeroMeta = {}): string {
   const elements = options.elements ?? [];
   if (elements.length > 0) {
     lines.push(`${bar}  ${s.dim}elements${s.reset}`);
+    const color = options.color ?? termColorEnabled();
     for (const row of elements) {
-      const idle = row.detail === "—";
-      const detail = idle ? `${s.dim}—${s.reset}` : `${s.cyan}${row.detail}${s.reset}`;
-      lines.push(`${bar}  ${s.dim}${row.element.padEnd(9)}${s.reset} ${detail}`);
+      const idle = row.detail === "—" || row.detail === "";
+      const status = row.status ?? (idle ? "idle" : "ready");
+      const dot = formatStatusDot(status, color);
+      const detail = idle
+        ? row.detail === ""
+          ? ""
+          : `${s.dim}—${s.reset}`
+        : `${s.cyan}${row.detail}${s.reset}`;
+      const detailPart = detail ? ` ${detail}` : "";
+      lines.push(`${bar}  ${dot} ${s.dim}${row.element.padEnd(9)}${s.reset}${detailPart}`);
     }
   }
   return lines.length > 0 ? `${lines.join("\n")}\n` : "";
@@ -152,11 +206,220 @@ export function formatDevBanner(options: DevHeroMeta = {}): string {
   if (options.watching !== false) {
     lines.push(`${bar}  ${s.dim}watching — client types regenerate on save${s.reset}`);
   }
-  lines.push(formatDevHeroDetails(options).trimEnd());
+  const details = formatDevHeroDetails(options).trimEnd();
+  if (details) lines.push(details);
   lines.push(bar);
   return `${lines.join("\n")}\n`;
 }
 
+/**
+ * Count visual lines in a terminal string (trailing newline optional).
+ *
+ * @param text - Block text
+ */
+export function countTermLines(text: string): number {
+  if (text.length === 0) return 0;
+  const normalized = text.endsWith("\n") ? text.slice(0, -1) : text;
+  if (normalized.length === 0) return 0;
+  return normalized.split("\n").length;
+}
+
+/** Handle for a bottom-of-TTY block that can be repainted until frozen. */
+export type RewritableBlock = {
+  /** Paint / repaint the block (must still be the last output). */
+  readonly paint: (text: string) => void;
+  /** Erase the block in place (no-op when frozen or non-TTY). */
+  readonly clear: () => void;
+  /** Stop rewriting — further {@link paint} calls append instead. */
+  readonly freeze: () => void;
+  readonly frozen: () => boolean;
+};
+
+/**
+ * Erase `lineCount` lines above the cursor (cursor ends on the first cleared row).
+ *
+ * @param write - stdout writer
+ * @param lineCount - Rows to clear
+ */
+function eraseTermLines(write: (text: string) => void, lineCount: number): void {
+  if (lineCount <= 0) return;
+  write(`\x1b[${lineCount}A`);
+  for (let i = 0; i < lineCount; i++) {
+    write("\x1b[2K");
+    if (i < lineCount - 1) write("\x1b[1B");
+  }
+  if (lineCount > 1) write(`\x1b[${lineCount - 1}A`);
+}
+
+/**
+ * Bottom-anchored live block for hero elements / Docker summary.
+ *
+ * Repaints in place with ANSI cursor moves while at the bottom of the TTY.
+ * Call {@link RewritableBlock.freeze} before printing anything below it.
+ *
+ * @param write - stdout writer
+ * @param enabled - When false (non-TTY / tests), every paint appends
+ */
+export function createRewritableBlock(
+  write: (text: string) => void,
+  enabled: boolean = termColorEnabled() && process.stdout.isTTY === true,
+): RewritableBlock {
+  let lineCount = 0;
+  let frozen = false;
+  return {
+    paint(text: string) {
+      if (text.length === 0) {
+        this.clear();
+        return;
+      }
+      const body = text.endsWith("\n") ? text : `${text}\n`;
+      const nextLines = countTermLines(body);
+      if (!frozen && enabled && lineCount > 0) {
+        eraseTermLines(write, lineCount);
+      }
+      write(body);
+      if (!frozen && enabled) lineCount = nextLines;
+      else lineCount = 0;
+    },
+    clear() {
+      if (frozen) return;
+      if (enabled && lineCount > 0) eraseTermLines(write, lineCount);
+      lineCount = 0;
+    },
+    freeze() {
+      frozen = true;
+      lineCount = 0;
+    },
+    frozen: () => frozen,
+  };
+}
+
+/** Keyed ephemeral boot-progress lines (compose / vault / health / AI). */
+export type BootProgress = {
+  /** Set or replace a progress row by key, then repaint. */
+  readonly set: (key: string, line: string) => void;
+  /** Erase all progress rows (TTY) before the final board. */
+  readonly clear: () => void;
+};
+
+/**
+ * Live boot-progress pane — keyed rows replace in place, then {@link BootProgress.clear}.
+ *
+ * @param write - stdout writer
+ * @param enabled - TTY rewrite on/off
+ */
+export function createBootProgress(
+  write: (text: string) => void,
+  enabled: boolean = termColorEnabled() && process.stdout.isTTY === true,
+): BootProgress {
+  const block = createRewritableBlock(write, enabled);
+  const order: string[] = [];
+  const lines = new Map<string, string>();
+  const repaint = (): void => {
+    if (order.length === 0) {
+      block.clear();
+      return;
+    }
+    block.paint(order.map((key) => lines.get(key) ?? "").join(""));
+  };
+  return {
+    set(key: string, line: string) {
+      const body = line.endsWith("\n") ? line : `${line}\n`;
+      if (!lines.has(key)) order.push(key);
+      lines.set(key, body);
+      if (!enabled) {
+        write(body);
+        return;
+      }
+      repaint();
+    },
+    clear() {
+      order.length = 0;
+      lines.clear();
+      block.clear();
+    },
+  };
+}
+
+/** Live elements/Docker board that can rewrite after content is printed below. */
+export type AnchoredBoard = {
+  /** Paint or rewrite the board (same height preferred). */
+  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;
+  /**
+   * Forget board geometry (after a full-screen clear) so the next
+   * {@link paint} writes fresh at the cursor.
+   */
+  readonly reset: () => void;
+  /** Disable further in-place rewrites (session end). */
+  readonly stop: () => void;
+};
+
+/**
+ * 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.
+ *
+ * @param write - stdout writer
+ * @param enabled - TTY rewrite on/off
+ */
+export function createAnchoredBoard(
+  write: (text: string) => void,
+  enabled: boolean = termColorEnabled() && process.stdout.isTTY === true,
+): AnchoredBoard {
+  let boardLines = 0;
+  let belowLines = 0;
+  let stopped = false;
+  let lastBody = "";
+
+  return {
+    paint(text: string) {
+      if (stopped) return;
+      const body = text.endsWith("\n") ? text : `${text}\n`;
+      const nextLines = countTermLines(body);
+      if (!enabled) {
+        if (boardLines === 0) write(body);
+        boardLines = nextLines;
+        lastBody = body;
+        return;
+      }
+      if (boardLines === 0) {
+        write(body);
+        boardLines = nextLines;
+        lastBody = body;
+        return;
+      }
+      if (body === lastBody) return;
+      // Move to board start, replace rows, restore cursor.
+      write("\x1b[s");
+      write(`\x1b[${belowLines + boardLines}A`);
+      eraseTermLines(write, boardLines);
+      write(body);
+      boardLines = nextLines;
+      lastBody = body;
+      write("\x1b[u");
+    },
+    wrapWrite(inner: (text: string) => void) {
+      return (text: string) => {
+        if (!stopped && enabled && boardLines > 0) {
+          belowLines += countTermLines(text);
+        }
+        inner(text);
+      };
+    },
+    reset() {
+      boardLines = 0;
+      belowLines = 0;
+      lastBody = "";
+    },
+    stop() {
+      stopped = true;
+    },
+  };
+}
+
 /**
  * One service URL line (Console / MCP after bind).
  *
@@ -175,14 +438,14 @@ export function formatServiceLine(
 }
 
 /**
- * App child ready line (`bun --hot` soft reload).
+ * Backend child ready line (`bun --hot` soft reload).
  *
- * @param url - App base URL
+ * @param url - Backend base URL
  * @param color - Color on/off
  */
 export function formatAppReadyLine(url: string, color: boolean = termColorEnabled()): string {
   const s = termStyle(color);
-  return `${s.green}●${s.reset}  ${s.dim}App${s.reset}      ${s.cyan}${url}${s.reset}\n`;
+  return `${s.green}●${s.reset}  ${s.dim}${"Backend".padEnd(7)}${s.reset}  ${s.cyan}${url}${s.reset}\n`;
 }
 
 /**
@@ -241,10 +504,87 @@ export function formatDevLogSeparator(color: boolean = termColorEnabled()): stri
  *
  * @param message - Status text
  * @param color - Color on/off
+ * @param status - Optional colored ● prefix
+ */
+export function formatStatusLine(
+  message: string,
+  color: boolean = termColorEnabled(),
+  status?: DevStatus,
+): string {
+  const s = termStyle(color);
+  const dot = status ? `${formatStatusDot(status, color)} ` : "";
+  return `${s.dim}│${s.reset}  ${dot}${s.dim}${message}${s.reset}\n`;
+}
+
+/**
+ * Wrap a long message to `width` columns (word-aware).
+ *
+ * @param text - Source text
+ * @param width - Max columns per line
+ */
+function wrapWords(text: string, width: number): string[] {
+  const words = text.split(/\s+/).filter((w) => w.length > 0);
+  if (words.length === 0) return [];
+  const lines: string[] = [];
+  let cur = "";
+  for (const word of words) {
+    if (cur.length === 0) {
+      cur = word;
+      continue;
+    }
+    if (`${cur} ${word}`.length <= width) {
+      cur = `${cur} ${word}`;
+      continue;
+    }
+    lines.push(cur);
+    cur = word;
+  }
+  if (cur.length > 0) lines.push(cur);
+  return lines;
+}
+
+/**
+ * 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 formatStatusLine(message: string, color: boolean = termColorEnabled()): string {
+export function formatBootWarn(message: string, color: boolean = termColorEnabled()): string {
   const s = termStyle(color);
-  return `${s.dim}│${s.reset}  ${s.dim}${message}${s.reset}\n`;
+  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}`];
+  for (const line of wrapped) {
+    lines.push(`${bar}  ${s.dim}${line}${s.reset}`);
+  }
+  lines.push(bar);
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Route raw CLI / boot lines into hero chrome (`│  …` or Notice boxes).
+ *
+ * @param text - Chunk that may contain newlines
+ * @param color - Color on/off
+ */
+export function formatCliChrome(text: string, color: boolean = termColorEnabled()): string {
+  const parts = text.split("\n");
+  const out: string[] = [];
+  for (let i = 0; i < parts.length; i++) {
+    const line = parts[i]!;
+    const isLastEmpty = i === parts.length - 1 && line.length === 0;
+    if (isLastEmpty) continue;
+    const trimmed = line.trimEnd();
+    if (trimmed.length === 0) continue;
+    if (/^oke boot:/i.test(trimmed)) {
+      out.push(formatBootWarn(trimmed, color));
+      continue;
+    }
+    out.push(formatStatusLine(trimmed, color));
+  }
+  return out.join("");
 }
 
 /** One infra service row for {@link formatStackSummary}. */
@@ -253,10 +593,16 @@ export type StackSummaryService = {
   readonly label: string;
   /** Published host port. */
   readonly hostPort: number;
+  /** Optional trailing detail (e.g. AI model id). */
+  readonly detail?: string;
+  /** Status dot (default `pending` until probed). */
+  readonly status?: DevStatus;
+  /** Compose service name for health lookup (`ai`, `store-sql`). */
+  readonly serviceName?: string;
 };
 
 /** Surfaces that emit request lines during `oke dev`. */
-export type DevLogSurface = "App" | "Console" | "MCP";
+export type DevLogSurface = "Backend" | "Console" | "MCP";
 
 /**
  * Local calendar date `YYYY-MM-DD` (no time).
@@ -286,7 +632,7 @@ export function formatDevLogTime(at: Date = new Date()): string {
  * One HTTP/RPC request line for the `oke dev` TTY.
  *
  * @example
- * `●  App      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`
  *
  * @param options - Surface, method, path, flow, timing, status
  */
@@ -308,7 +654,7 @@ export function formatRequestLine(options: {
   const date = formatDevLogDate(at);
   const time = formatDevLogTime(at);
   const surfaceColor =
-    options.surface === "App" ? s.green : options.surface === "Console" ? s.magenta : s.cyan;
+    options.surface === "Backend" ? s.green : options.surface === "Console" ? s.magenta : s.cyan;
   const statusColor = options.status >= 500 ? s.red : options.status >= 400 ? s.yellow : s.green;
   const methodRaw = options.method.toUpperCase();
   const methodColor =
@@ -356,15 +702,24 @@ export function formatStackSummary(options: {
   const s = termStyle(options.color ?? termColorEnabled());
   const bar = `${s.dim}│${s.reset}`;
   const pad = (label: string) => label.padEnd(8);
+  const color = options.color ?? termColorEnabled();
   const lines: string[] = [
+    `${s.dim}│${s.reset}`,
     `${s.green}◇${s.reset}  ${s.bold}Docker${s.reset}     ${s.cyan}${options.project}${s.reset}`,
   ];
   for (const svc of options.services) {
-    lines.push(`${bar}  ${s.dim}${pad(svc.label)}${s.reset}  ${s.cyan}:${svc.hostPort}${s.reset}`);
+    const detail = svc.detail?.trim();
+    const status = svc.status ?? "pending";
+    const dot = formatStatusDot(status, color);
+    lines.push(
+      `${bar}  ${dot} ${s.dim}${pad(svc.label)}${s.reset}  ${s.cyan}:${svc.hostPort}${s.reset}` +
+        (detail ? `  ${s.dim}${detail}${s.reset}` : ""),
+    );
   }
   const drivers = options.appDrivers ?? [];
   const appDetail = drivers.length > 0 ? `host Bun · ${drivers.join(" + ")}` : "host Bun";
-  lines.push(`${bar}  ${s.dim}${pad("app")}${s.reset}  ${s.dim}${appDetail}${s.reset}`);
+  const appDot = formatStatusDot("ready", color);
+  lines.push(`${bar}  ${appDot} ${s.dim}${pad("app")}${s.reset}  ${s.dim}${appDetail}${s.reset}`);
   lines.push(bar);
   return `${lines.join("\n")}\n`;
 }