okengine 0.2.2 → 0.2.4

package/src/kernel/boot.ts

@@ -76,8 +76,17 @@ export interface ElementRuntimes {
 
 /** Declarations + options consumed by {@link bootApplication}. */
 export interface BootOptions {
-  /** Active environment (defaults to `dev`). */
+  /**
+   * Active environment (defaults to `dev`, or `stack` when
+   * {@link stack} / `OKE_STACK=1`).
+   */
   readonly env?: ConfigEnv;
+  /**
+   * Local-server mode (`oke dev -s` / `OKE_STACK=1`): force driver maps to the
+   * `stack` profile and prefer compose URLs (`.env.stack`).
+   * When unset, derived from `process.env.OKE_STACK`.
+   */
+  readonly stack?: boolean;
   /** Optional `oke.config.ts` document. */
   readonly config?: OkeConfig;
   /** Pre-built runtimes (skip construction when present). */
@@ -243,9 +252,24 @@ async function loadBind<T>(name: string): Promise<T> {
  * @param options - Declarations, config, pre-built runtimes
  */
 export async function bootApplication(
-  options: BootOptions = {},
+  input: BootOptions = {},
 ): Promise<BootResult> {
-  const env: ConfigEnv = options.env ?? "dev";
+  const stack =
+    input.stack === true ||
+    (input.stack !== false && process.env.OKE_STACK === "1");
+  // `-s` always selects the `stack` driver profile — not a mix of test/dev +
+  // prod store overrides (templates often pin `env: "test"` for harnesses).
+  const env: ConfigEnv = stack ? "stack" : (input.env ?? "dev");
+  let config = input.config;
+  if (config === undefined) {
+    try {
+      const { loadOkeConfig } = await import("../cli/load-config.ts");
+      config = (await loadOkeConfig(process.cwd())).config;
+    } catch {
+      config = undefined;
+    }
+  }
+  const options: BootOptions = { ...input, config, env, stack };
   const pre = options.elements ?? {};
   const now = options.now ?? (() => Date.now());
   const needs = resolveElementNeeds(options);
@@ -340,7 +364,7 @@ export async function bootApplication(
   let store = pre.store;
   if (needs.store) {
     if (!store) {
-      store = storeBind!.bindStore(options, env, now);
+      store = storeBind!.bindStore(options, env, now, stack);
     } else {
       for (const decl of options.stores ?? []) {
         store.register?.(decl);

package/src/mcp/server.ts

@@ -8,6 +8,10 @@
  * adapters receive structured operator ids.
  */
 
+import {
+  logDevRequest,
+  shouldLogDevRequests,
+} from "../runtime/dev-request-log.ts";
 import {
   checkRequestSecurity,
   forbiddenResponse,
@@ -67,28 +71,48 @@ export function createMcpServer(options: CreateMcpServerOptions): McpServer {
   const transportSessions = new Set<string>();
 
   const fetch = async (request: Request): Promise<Response> => {
+    const started = performance.now();
+    let flowLabel: string | undefined;
+    const url = new URL(request.url);
+    const method = request.method.toUpperCase();
+
+    const respond = (response: Response): Response => {
+      if (shouldLogDevRequests()) {
+        logDevRequest({
+          surface: "MCP",
+          method,
+          path: url.pathname,
+          flow: flowLabel,
+          status: response.status,
+          ms: Math.round(performance.now() - started),
+        });
+      }
+      return response;
+    };
+
     const security = checkRequestSecurity(request, allowed);
-    if (!security.ok) return forbiddenResponse(security.reason);
+    if (!security.ok) return respond(forbiddenResponse(security.reason));
 
-    const url = new URL(request.url);
-    if (request.method === "GET" && url.pathname === "/health") {
-      return Response.json({ ok: true, surface: "mcp" });
+    if (method === "GET" && url.pathname === "/health") {
+      return respond(Response.json({ ok: true, surface: "mcp" }));
     }
 
-    if (request.method !== "POST" || url.pathname !== "/mcp") {
-      return new Response("Not Found", { status: 404 });
+    if (method !== "POST" || url.pathname !== "/mcp") {
+      return respond(new Response("Not Found", { status: 404 }));
     }
 
     const bearer = extractBearer(request.headers.get("authorization"));
     if (bearer === null) {
-      return jsonRpcHttp(
-        rpcError(
-          null,
-          RpcErrorCode.unauthorized,
-          "Bearer token required",
-          asData({ reason: "missing-token" }, "error"),
+      return respond(
+        jsonRpcHttp(
+          rpcError(
+            null,
+            RpcErrorCode.unauthorized,
+            "Bearer token required",
+            asData({ reason: "missing-token" }, "error"),
+          ),
+          401,
         ),
-        401,
       );
     }
 
@@ -103,14 +127,16 @@ export function createMcpServer(options: CreateMcpServerOptions): McpServer {
     } catch (err) {
       const message =
         err instanceof SessionError ? err.message : "authentication failed";
-      return jsonRpcHttp(
-        rpcError(
-          null,
-          RpcErrorCode.unauthorized,
-          message,
-          asData({ reason: "auth-failed", message }, "error"),
+      return respond(
+        jsonRpcHttp(
+          rpcError(
+            null,
+            RpcErrorCode.unauthorized,
+            message,
+            asData({ reason: "auth-failed", message }, "error"),
+          ),
+          401,
         ),
-        401,
       );
     }
 
@@ -122,22 +148,27 @@ export function createMcpServer(options: CreateMcpServerOptions): McpServer {
     try {
       body = await request.json();
     } catch {
-      return jsonRpcHttp(
-        rpcError(null, RpcErrorCode.parse, "invalid JSON body"),
-        400,
+      return respond(
+        jsonRpcHttp(
+          rpcError(null, RpcErrorCode.parse, "invalid JSON body"),
+          400,
+        ),
       );
     }
 
     const parsed = parseJsonRpcRequest(body);
     if (!parsed.ok) {
-      return jsonRpcHttp(
-        rpcError(null, RpcErrorCode.invalidRequest, parsed.message),
-        400,
+      return respond(
+        jsonRpcHttp(
+          rpcError(null, RpcErrorCode.invalidRequest, parsed.message),
+          400,
+        ),
       );
     }
 
     const { request: rpc } = parsed;
     const id: JsonRpcId = rpc.id;
+    flowLabel = rpc.method;
 
     switch (rpc.method) {
       case "initialize": {
@@ -149,10 +180,10 @@ export function createMcpServer(options: CreateMcpServerOptions): McpServer {
           serverInfo: { name: "okengine-mcp", version },
           sessionId,
         };
-        return jsonRpcHttp(rpcSuccess(id, result));
+        return respond(jsonRpcHttp(rpcSuccess(id, result)));
       }
       case "ping":
-        return jsonRpcHttp(rpcSuccess(id, { ok: true }));
+        return respond(jsonRpcHttp(rpcSuccess(id, { ok: true })));
       case "tools/list": {
         const listed = tools.listTools().map((t) => ({
           name: t.name,
@@ -163,22 +194,27 @@ export function createMcpServer(options: CreateMcpServerOptions): McpServer {
             destructiveHint: t.mutability === "write",
           },
         }));
-        return jsonRpcHttp(
-          rpcSuccess(id, {
-            tools: listed,
-            // Catalogue itself is data.
-            _oke: asData({ count: listed.length }, "catalog"),
-          }),
+        return respond(
+          jsonRpcHttp(
+            rpcSuccess(id, {
+              tools: listed,
+              // Catalogue itself is data.
+              _oke: asData({ count: listed.length }, "catalog"),
+            }),
+          ),
         );
       }
       case "tools/call": {
         const call = parseToolsCallParams(rpc.params);
         if (!call.ok) {
-          return jsonRpcHttp(
-            rpcError(id, RpcErrorCode.invalidParams, call.message),
-            400,
+          return respond(
+            jsonRpcHttp(
+              rpcError(id, RpcErrorCode.invalidParams, call.message),
+              400,
+            ),
           );
         }
+        flowLabel = call.name;
         const result = await tools.callTool(
           requester,
           call.name,
@@ -193,34 +229,40 @@ export function createMcpServer(options: CreateMcpServerOptions): McpServer {
                 : result.code === "not-found"
                   ? RpcErrorCode.methodNotFound
                   : RpcErrorCode.invalidParams;
-          return jsonRpcHttp(
-            rpcError(id, code, result.message, result.data),
-            result.code === "unauthorized" ? 401 : 403,
+          return respond(
+            jsonRpcHttp(
+              rpcError(id, code, result.message, result.data),
+              result.code === "unauthorized" ? 401 : 403,
+            ),
           );
         }
         // MCP content blocks: text carries JSON of the inert envelope.
         // Agents must treat it as data (envelope.kind === "data").
-        return jsonRpcHttp(
-          rpcSuccess(id, {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify(result.data),
-              },
-            ],
-            structuredContent: result.data,
-            isError: false,
-          }),
+        return respond(
+          jsonRpcHttp(
+            rpcSuccess(id, {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(result.data),
+                },
+              ],
+              structuredContent: result.data,
+              isError: false,
+            }),
+          ),
         );
       }
       default:
-        return jsonRpcHttp(
-          rpcError(
-            id,
-            RpcErrorCode.methodNotFound,
-            `method not found: ${rpc.method}`,
+        return respond(
+          jsonRpcHttp(
+            rpcError(
+              id,
+              RpcErrorCode.methodNotFound,
+              `method not found: ${rpc.method}`,
+            ),
+            404,
           ),
-          404,
         );
     }
   };

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

@@ -0,0 +1,33 @@
+/**
+ * Dev request log gating and silence rules.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  isSilentDevRequest,
+  shouldLogDevRequests,
+} from "./dev-request-log.ts";
+
+describe("dev-request-log", () => {
+  const prev = process.env.OKE_DEV_REQUEST_LOG;
+
+  afterEach(() => {
+    if (prev === undefined) delete process.env.OKE_DEV_REQUEST_LOG;
+    else process.env.OKE_DEV_REQUEST_LOG = prev;
+  });
+
+  test("shouldLogDevRequests follows OKE_DEV_REQUEST_LOG", () => {
+    process.env.OKE_DEV_REQUEST_LOG = "1";
+    expect(shouldLogDevRequests()).toBe(true);
+    process.env.OKE_DEV_REQUEST_LOG = "0";
+    expect(shouldLogDevRequests()).toBe(false);
+  });
+
+  test("isSilentDevRequest skips live, health, assets, client.json", () => {
+    expect(isSilentDevRequest("GET", "/console/live")).toBe(true);
+    expect(isSilentDevRequest("GET", "/health")).toBe(true);
+    expect(isSilentDevRequest("GET", "/assets/index.js")).toBe(true);
+    expect(isSilentDevRequest("GET", "/_oke/client.json")).toBe(true);
+    expect(isSilentDevRequest("POST", "/console/flows")).toBe(false);
+  });
+});

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\[/);
+  });
 });