okengine 0.2.3 → 0.2.5

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

@@ -0,0 +1,130 @@
+/**
+ * Dev-only request lines for `oke dev` (App / Console / MCP).
+ *
+ * Gated by `OKE_DEV_REQUEST_LOG=1`. Surfaces share one TTY; label + color
+ * keep streams readable without a multiplexer.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { formatRequestLine, type DevLogSurface } from "../term.ts";
+
+const surfaceAls = new AsyncLocalStorage<DevLogSurface>();
+
+/**
+ * Whether colored request lines should print.
+ */
+export function shouldLogDevRequests(): boolean {
+  return process.env.OKE_DEV_REQUEST_LOG === "1";
+}
+
+/**
+ * Active surface for this async context, or `OKE_DEV_SURFACE`, or `App`.
+ */
+export function currentDevSurface(): DevLogSurface {
+  const fromAls = surfaceAls.getStore();
+  if (fromAls) return fromAls;
+  const fromEnv = process.env.OKE_DEV_SURFACE;
+  if (fromEnv === "App" || fromEnv === "Console" || fromEnv === "MCP") {
+    return fromEnv;
+  }
+  return "App";
+}
+
+/**
+ * Run a handler tagged with a surface (Console wrap around `app.fetch`).
+ *
+ * @param surface - App · Console · MCP
+ * @param fn - Async work
+ */
+export function runWithDevSurface<T>(
+  surface: DevLogSurface,
+  fn: () => T | Promise<T>,
+): T | Promise<T> {
+  return surfaceAls.run(surface, fn);
+}
+
+/** Fields for one request line. */
+export type DevRequestLogInput = {
+  readonly surface?: DevLogSurface;
+  readonly method: string;
+  readonly path: string;
+  /** Flow name, RPC method, or tool id. */
+  readonly flow?: string;
+  readonly status: number;
+  readonly ms: number;
+};
+
+/**
+ * Paths that would drown the TTY (live WS, health probes, static assets).
+ *
+ * @param method - HTTP method
+ * @param path - URL pathname
+ */
+export function isSilentDevRequest(method: string, path: string): boolean {
+  if (path === "/console/live") return true;
+  // Client-types regen — lands between hero and Logs and breaks the separator.
+  if (path === "/_oke/client.json") return true;
+  if (method === "GET" && (path === "/health" || path.endsWith("/health"))) {
+    return true;
+  }
+  return /\.(?:js|css|map|svg|png|ico|woff2?|ttf|webp)$/i.test(path);
+}
+
+/**
+ * Print one request line when {@link shouldLogDevRequests} is on.
+ *
+ * @param input - Request summary
+ */
+export function logDevRequest(input: DevRequestLogInput): void {
+  if (!shouldLogDevRequests()) return;
+  if (isSilentDevRequest(input.method.toUpperCase(), input.path)) return;
+  process.stdout.write(
+    formatRequestLine({
+      surface: input.surface ?? currentDevSurface(),
+      method: input.method,
+      path: input.path,
+      flow: input.flow,
+      status: input.status,
+      ms: input.ms,
+    }),
+  );
+}
+
+/**
+ * Time an async fetch handler and log the outcome.
+ *
+ * @param surface - Fixed surface (MCP) or omit to use ALS/env
+ * @param request - Incoming request
+ * @param handle - Inner fetch
+ * @param resolveFlow - Optional label after the response (e.g. RPC method)
+ */
+export async function timedDevFetch(
+  request: Request,
+  handle: (request: Request) => Response | Promise<Response>,
+  options: {
+    readonly surface?: DevLogSurface;
+    readonly resolveFlow?: (
+      request: Request,
+      response: Response,
+    ) => string | undefined;
+    /** Skip logging for this path/method. */
+    readonly silent?: (request: Request) => boolean;
+  } = {},
+): Promise<Response> {
+  if (!shouldLogDevRequests() || options.silent?.(request)) {
+    return handle(request);
+  }
+  const started = performance.now();
+  const url = new URL(request.url);
+  const method = request.method.toUpperCase();
+  const response = await handle(request);
+  logDevRequest({
+    surface: options.surface ?? currentDevSurface(),
+    method,
+    path: url.pathname,
+    flow: options.resolveFlow?.(request, response),
+    status: response.status,
+    ms: Math.round(performance.now() - started),
+  });
+  return response;
+}

package/src/term.test.ts

@@ -7,7 +7,12 @@ import {
   formatAppReadyLine,
   formatClaimNote,
   formatDevBanner,
+  formatDevHero,
+  formatDevLogSeparator,
+  formatOkeWordmark,
   formatServiceLine,
+  formatRequestLine,
+  formatStackSummary,
   formatStatusLine,
   termStyle,
 } from "./term.ts";
@@ -19,11 +24,37 @@ describe("term", () => {
     expect(s.bold).toBe("");
   });
 
-  test("formatDevBanner is readable without color", () => {
-    const out = formatDevBanner({ color: false });
-    expect(out).toContain("oke dev");
-    expect(out).toContain("Starting");
-    expect(out).toContain("watching");
+  test("formatOkeWordmark is block letters", () => {
+    const out = formatOkeWordmark(false);
+    expect(out).toContain("██");
+    expect(out).toContain("╗");
+  });
+
+  test("formatDevBanner shows profile env system elements", () => {
+    const out = formatDevBanner({
+      color: false,
+      version: "0.2.4",
+      profile: "local-server",
+      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" },
+      ],
+    });
+    expect(out).toContain("oke dev  v0.2.4");
+    expect(out).toContain("profile");
+    expect(out).toContain("local-server");
+    expect(out).toContain("env");
+    expect(out).toContain("local");
+    expect(out).toContain("system");
+    expect(out).toContain("bun 1.3.14");
+    expect(out).toContain("elements");
+    expect(out).toContain("store");
+    expect(out).toContain("postgres");
+    expect(out).not.toContain("on(Trigger)");
+    expect(out).not.toContain("O·K·E");
     expect(out).not.toMatch(/\u001b\[/);
   });
 
@@ -36,6 +67,34 @@ describe("term", () => {
     );
   });
 
+  test("formatDevHero keeps App Console MCP URLs", () => {
+    const out = formatDevHero({
+      appUrl: "http://127.0.0.1:6530",
+      consoleUrl: "http://127.0.0.1:6533",
+      mcpUrl: "http://127.0.0.1:6535",
+      profile: "local",
+      runtimeEnv: "local",
+      system: "darwin 25.4.0 · bun 1.3.14",
+      elements: [{ element: "flow", detail: "●" }],
+      color: false,
+    });
+    expect(out).toContain("oke dev");
+    expect(out).toContain("██");
+    expect(out).toContain("App");
+    expect(out).toContain("Console");
+    expect(out).toContain("MCP");
+    expect(out).toContain("http://127.0.0.1:6530");
+    expect(out).toContain("└");
+    expect(out).toContain("Logs");
+  });
+
+  test("formatDevLogSeparator closes hero and titles Logs", () => {
+    const out = formatDevLogSeparator(false);
+    expect(out).toContain("│");
+    expect(out).toContain("└");
+    expect(out).toContain("Logs");
+  });
+
   test("formatClaimNote embeds code and ownership line", () => {
     const code = "aabbccddeeff00112233445566778899";
     const out = formatClaimNote(code, false);
@@ -48,4 +107,38 @@ describe("term", () => {
   test("formatStatusLine keeps message", () => {
     expect(formatStatusLine("stack up (sql)", false)).toContain("stack up");
   });
+
+  test("formatRequestLine shows date, time, surface, flow, ms, status", () => {
+    const at = new Date(2026, 6, 26, 3, 11, 42);
+    const out = formatRequestLine({
+      surface: "App",
+      method: "GET",
+      path: "/health",
+      flow: "main.health",
+      status: 200,
+      ms: 12,
+      at,
+      color: false,
+    });
+    expect(out).toContain("2026-07-26");
+    expect(out).toContain("03:11:42");
+    expect(out).toContain("App");
+    expect(out).toContain("200");
+    expect(out).not.toMatch(/\u001b\[/);
+  });
+
+  test("formatStackSummary is scannable", () => {
+    const out = formatStackSummary({
+      project: "oke-dev-a3f791",
+      services: [
+        { label: "postgres", hostPort: 15975 },
+        { label: "redis", hostPort: 16975 },
+      ],
+      appDrivers: ["postgres", "redis"],
+      color: false,
+    });
+    expect(out).toContain("Stack");
+    expect(out).toContain(":15975");
+    expect(out).not.toMatch(/\u001b\[/);
+  });
 });

package/src/term.ts

@@ -27,6 +27,7 @@ export type TermStyle = {
   readonly magenta: string;
   readonly yellow: string;
   readonly white: string;
+  readonly red: string;
 };
 
 /**
@@ -45,6 +46,7 @@ export function termStyle(color: boolean = termColorEnabled()): TermStyle {
       magenta: "",
       yellow: "",
       white: "",
+      red: "",
     };
   }
   return {
@@ -56,22 +58,108 @@ export function termStyle(color: boolean = termColorEnabled()): TermStyle {
     magenta: `${ESC}35m`,
     yellow: `${ESC}33m`,
     white: `${ESC}37m`,
+    red: `${ESC}31m`,
   };
 }
 
+/** One eight-element row in the hero. */
+export type DevHeroElement = {
+  readonly element: string;
+  readonly detail: string;
+};
+
+/** Shared options for the `oke dev` hero / banner. */
+export type DevHeroMeta = {
+  /** `local` · `local-server` · `test` · `production` */
+  readonly profile?: string;
+  /** Data plane: `local` · `production` */
+  readonly runtimeEnv?: string;
+  /** Host OS + Bun, e.g. `darwin 25.4.0 · bun 1.3.14`. */
+  readonly system?: string;
+  /** Active drivers for the eight elements. */
+  readonly elements?: readonly DevHeroElement[];
+  readonly version?: string;
+  readonly color?: boolean;
+  readonly watching?: boolean;
+};
+
+/**
+ * Compact OKE wordmark — CRT / hacker block letters.
+ *
+ * @param color - Color on/off
+ */
+export function formatOkeWordmark(
+  color: boolean = termColorEnabled(),
+): string {
+  const s = termStyle(color);
+  const ink = `${s.green}${s.bold}`;
+  const r = s.reset;
+  return [
+    `${ink}   ██████╗ ██╗  ██╗███████╗${r}`,
+    `${ink}  ██╔═══██╗██║ ██╔╝██╔════╝${r}`,
+    `${ink}  ██║   ██║█████╔╝ █████╗  ${r}`,
+    `${ink}  ██║   ██║██╔═██╗ ██╔══╝  ${r}`,
+    `${ink}  ╚██████╔╝██║  ██╗███████╗${r}`,
+    `${ink}   ╚═════╝ ╚═╝  ╚═╝╚══════╝${r}`,
+  ].join("\n") + "\n";
+}
+
 /**
- * `oke dev` intro — clack chrome; service URLs print as each surface binds.
+ * Detail rows — profile, env, system, eight elements + drivers.
  *
- * @param options - Color / watch hint
+ * @param options - Snapshot fields from {@link import("./cli/hero-meta.ts").buildDevHeroSnapshot}
  */
-export function formatDevBanner(
-  options: { readonly color?: boolean; readonly watching?: boolean } = {},
+export function formatDevHeroDetails(
+  options: DevHeroMeta = {},
 ): string {
+  const s = termStyle(options.color ?? termColorEnabled());
+  const bar = `${s.dim}│${s.reset}`;
+  const label = (name: string) => `${s.dim}${name.padEnd(9)}${s.reset}`;
+  const lines: string[] = [];
+  if (options.profile) {
+    lines.push(
+      `${bar}  ${label("profile")} ${s.cyan}${options.profile}${s.reset}`,
+    );
+  }
+  if (options.runtimeEnv) {
+    lines.push(
+      `${bar}  ${label("env")} ${s.cyan}${options.runtimeEnv}${s.reset}`,
+    );
+  }
+  if (options.system) {
+    lines.push(
+      `${bar}  ${label("system")} ${s.dim}${options.system}${s.reset}`,
+    );
+  }
+  const elements = options.elements ?? [];
+  if (elements.length > 0) {
+    lines.push(`${bar}  ${s.dim}elements${s.reset}`);
+    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}`,
+      );
+    }
+  }
+  return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+
+/**
+ * `oke dev` intro — wordmark + details; service URLs print as each surface binds.
+ *
+ * @param options - Color / watch / ports / entry
+ */
+export function formatDevBanner(options: DevHeroMeta = {}): string {
   const s = termStyle(options.color ?? termColorEnabled());
   const bar = `${s.dim}│${s.reset}`;
   const lines = [
     "",
-    `${s.cyan}${s.bold}┌${s.reset}  ${s.bold}oke dev${s.reset}`,
+    formatOkeWordmark(options.color ?? termColorEnabled()).trimEnd(),
+    `${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`,
   ];
@@ -80,6 +168,7 @@ export function formatDevBanner(
       `${bar}  ${s.dim}watching — client types regenerate on save${s.reset}`,
     );
   }
+  lines.push(formatDevHeroDetails(options).trimEnd());
   lines.push(bar);
   return `${lines.join("\n")}\n`;
 }
@@ -116,7 +205,60 @@ export function formatAppReadyLine(
 }
 
 /**
- * Quiet status line (regen, stack up, …).
+ * ANSI clear screen + home (drops request logs; hero is reprinted after).
+ */
+export function clearTerminalScreen(): string {
+  return "\u001b[2J\u001b[3J\u001b[H";
+}
+
+/**
+ * Compact hero reprinted on soft reload — URLs stay, request logs do not.
+ *
+ * @param options - Surface base URLs + meta
+ */
+export function formatDevHero(
+  options: DevHeroMeta & {
+    readonly appUrl: string;
+    readonly consoleUrl: string;
+    readonly mcpUrl: string;
+  },
+): string {
+  const color = options.color ?? termColorEnabled();
+  const s = termStyle(color);
+  const bar = `${s.dim}│${s.reset}`;
+  return (
+    `\n${formatOkeWordmark(color)}` +
+    `${s.cyan}${s.bold}┌${s.reset}  ${s.bold}oke dev${s.reset}` +
+    (options.version ? `  ${s.dim}v${options.version}${s.reset}` : "") +
+    `\n${bar}\n` +
+    formatDevHeroDetails({ ...options, color }) +
+    `${bar}\n` +
+    formatAppReadyLine(options.appUrl, color) +
+    formatServiceLine("Console", options.consoleUrl, color) +
+    formatServiceLine("MCP", options.mcpUrl, color) +
+    formatDevLogSeparator(color)
+  );
+}
+
+/**
+ * Closes the hero block and opens the Logs section.
+ *
+ * @param color - Color on/off
+ */
+export function formatDevLogSeparator(
+  color: boolean = termColorEnabled(),
+): string {
+  const s = termStyle(color);
+  return (
+    `${s.dim}│${s.reset}\n` +
+    `${s.dim}└${s.reset}\n` +
+    `\n${s.green}◇${s.reset}  ${s.bold}Logs${s.reset}\n` +
+    `${s.dim}│${s.reset}\n\n`
+  );
+}
+
+/**
+ * Quiet status line (regen, …).
  *
  * @param message - Status text
  * @param color - Color on/off
@@ -129,6 +271,145 @@ export function formatStatusLine(
   return `${s.dim}│${s.reset}  ${s.dim}${message}${s.reset}\n`;
 }
 
+/** One infra service row for {@link formatStackSummary}. */
+export type StackSummaryService = {
+  /** Human label (`postgres`, `redis`). */
+  readonly label: string;
+  /** Published host port. */
+  readonly hostPort: number;
+};
+
+/** Surfaces that emit request lines during `oke dev`. */
+export type DevLogSurface = "App" | "Console" | "MCP";
+
+/**
+ * Local calendar date `YYYY-MM-DD` (no time).
+ *
+ * @param at - Instant (default now)
+ */
+export function formatDevLogDate(at: Date = new Date()): string {
+  const y = at.getFullYear();
+  const m = String(at.getMonth() + 1).padStart(2, "0");
+  const d = String(at.getDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+
+/**
+ * Local clock time `HH:MM:SS` (no date).
+ *
+ * @param at - Instant (default now)
+ */
+export function formatDevLogTime(at: Date = new Date()): string {
+  const h = String(at.getHours()).padStart(2, "0");
+  const min = String(at.getMinutes()).padStart(2, "0");
+  const sec = String(at.getSeconds()).padStart(2, "0");
+  return `${h}:${min}:${sec}`;
+}
+
+/**
+ * One HTTP/RPC request line for the `oke dev` TTY.
+ *
+ * @example
+ * `●  App      GET  /health                 main.health            12ms  200  2026-07-26  03:11:42`
+ *
+ * @param options - Surface, method, path, flow, timing, status
+ */
+export function formatRequestLine(
+  options: {
+    readonly surface: DevLogSurface;
+    readonly method: string;
+    readonly path: string;
+    readonly flow?: string;
+    readonly status: number;
+    readonly ms: number;
+    /** Instant for date/time columns (default now). */
+    readonly at?: Date;
+    readonly color?: boolean;
+  },
+): string {
+  const s = termStyle(options.color ?? termColorEnabled());
+  const at = options.at ?? new Date();
+  const date = formatDevLogDate(at);
+  const time = formatDevLogTime(at);
+  const surfaceColor =
+    options.surface === "App"
+      ? 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 =
+    methodRaw === "GET"
+      ? s.green
+      : methodRaw === "POST"
+        ? s.yellow
+        : methodRaw === "PUT" || methodRaw === "PATCH"
+          ? s.magenta
+          : methodRaw === "DELETE"
+            ? s.red
+            : s.cyan;
+  const method = methodRaw.padEnd(4);
+  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);
+  return (
+    `${surfaceColor}●${s.reset}  ` +
+    `${surfaceColor}${options.surface.padEnd(7)}${s.reset}  ` +
+    `${methodColor}${method}${s.reset} ` +
+    `${s.cyan}${path}${s.reset}  ` +
+    `${s.dim}${flow}${s.reset}  ` +
+    `${s.dim}${ms}${s.reset}  ` +
+    `${statusColor}${options.status}${s.reset}  ` +
+    `${s.dim}${date}${s.reset}  ` +
+    `${s.dim}${time}${s.reset}\n`
+  );
+}
+
+/**
+ * Compact `oke dev -s` summary — project, ports, app driver mode.
+ *
+ * @param options - Project name, services, driver labels
+ */
+export function formatStackSummary(
+  options: {
+    readonly project: string;
+    readonly services: readonly StackSummaryService[];
+    /** Drivers the host app will use (e.g. `postgres`, `redis`). */
+    readonly appDrivers?: readonly string[];
+    readonly color?: boolean;
+  },
+): string {
+  const s = termStyle(options.color ?? termColorEnabled());
+  const bar = `${s.dim}│${s.reset}`;
+  const pad = (label: string) => label.padEnd(8);
+  const lines: string[] = [
+    `${s.green}◇${s.reset}  ${s.bold}Stack${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 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}`,
+  );
+  lines.push(bar);
+  return `${lines.join("\n")}\n`;
+}
+
 /**
  * First-admin claim code note (clack `note`-style box).
  *