okengine 0.2.3 → 0.2.5

package/src/kernel/app.ts

@@ -45,6 +45,11 @@ import {
   type FxOperator,
   type NamedRef,
 } from "./fx.ts";
+import {
+  currentDevSurface,
+  logDevRequest,
+  shouldLogDevRequests,
+} from "../runtime/dev-request-log.ts";
 import {
   mergeHooks,
   runPipeline,
@@ -126,6 +131,11 @@ export interface OkeOptions {
   readonly archiveInputFields?: readonly string[];
   /** Active environment for {@link OkeApp.boot} (defaults to `dev`). */
   readonly env?: BootOptions["env"];
+  /**
+   * Local-server mode (`oke dev -s` / `OKE_STACK=1`) — force the `stack`
+   * driver profile at boot.
+   */
+  readonly stack?: BootOptions["stack"];
   /** Optional `oke.config.ts` document consumed at boot. */
   readonly config?: BootOptions["config"];
   /** Pre-built element runtimes (skip construction at boot when present). */
@@ -483,6 +493,7 @@ export function oke(options: OkeOptions): OkeApp {
     bootEnv = overrides?.env ?? options.env ?? "dev";
     const merged: BootOptions = {
       env: bootEnv,
+      stack: overrides?.stack ?? options.stack,
       config: overrides?.config ?? options.config,
       elements: overrides?.elements ?? options.elements,
       secrets: overrides?.secrets ?? options.secrets,
@@ -892,13 +903,31 @@ export function oke(options: OkeOptions): OkeApp {
     },
     execute,
     async fetch(request) {
+      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: currentDevSurface(),
+            method,
+            path: url.pathname,
+            flow: flowLabel,
+            status: response.status,
+            ms: Math.round(performance.now() - started),
+          });
+        }
+        return response;
+      };
+
       if (method === "GET" && url.pathname === "/_oke/client.json") {
-        return new Response(JSON.stringify(routes), {
-          headers: { "content-type": "application/json" },
-        });
+        return respond(
+          new Response(JSON.stringify(routes), {
+            headers: { "content-type": "application/json" },
+          }),
+        );
       }
 
       if (method === "POST" && url.pathname.startsWith("/_oke/")) {
@@ -910,8 +939,9 @@ export function oke(options: OkeOptions): OkeApp {
           const target =
             flowsByName.get(`${unit}.${flowName}`) ?? flowsByName.get(flowName);
           if (!target) {
-            return new Response("Not Found", { status: 404 });
+            return respond(new Response("Not Found", { status: 404 }));
           }
+          flowLabel = target.name;
           let internalInput: unknown;
           try {
             internalInput = await request.json();
@@ -924,15 +954,16 @@ export function oke(options: OkeOptions): OkeApp {
             { kind: "internal" } satisfies InternalTrigger,
             { request },
           );
-          return encodeExecuteResult(internalResult);
+          return respond(encodeExecuteResult(internalResult));
         }
       }
 
       const matched = router.match(method, url.pathname);
       if (!matched) {
-        return new Response("Not Found", { status: 404 });
+        return respond(new Response("Not Found", { status: 404 }));
       }
       const { value: binding, params } = matched;
+      flowLabel = binding.flow.name;
 
       let route = compiled.get(binding);
       if (!route && binding.trigger.kind === "http") {
@@ -946,7 +977,7 @@ export function oke(options: OkeOptions): OkeApp {
       if (route) {
         const parsed = await route.parseValidate(request, params);
         if (!parsed.ok) {
-          return encodeFailure(parsed.failure);
+          return respond(encodeFailure(parsed.failure));
         }
         input = parsed.input;
         validated = true;
@@ -962,7 +993,7 @@ export function oke(options: OkeOptions): OkeApp {
         { request, params, validated },
       );
 
-      return encodeExecuteResult(result);
+      return respond(encodeExecuteResult(result));
     },
     async dispatchSignal(signal, payload) {
       const name = resolveName(signal);

package/src/kernel/boot-bind/store.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Store binder — stack profile (+ env overrides).
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { resolveKvDriverId, resolveSqlDriverId } from "./store.ts";
+
+describe("bindStore driver resolution", () => {
+  const prev = {
+    stack: process.env.OKE_STACK,
+    sql: process.env.OKE_SQL_DRIVER,
+    kv: process.env.OKE_KV_DRIVER,
+  };
+
+  afterEach(() => {
+    if (prev.stack === undefined) delete process.env.OKE_STACK;
+    else process.env.OKE_STACK = prev.stack;
+    if (prev.sql === undefined) delete process.env.OKE_SQL_DRIVER;
+    else process.env.OKE_SQL_DRIVER = prev.sql;
+    if (prev.kv === undefined) delete process.env.OKE_KV_DRIVER;
+    else process.env.OKE_KV_DRIVER = prev.kv;
+  });
+
+  test("dev env keeps sqlite / memory from config", () => {
+    const options = {
+      config: {
+        drivers: {
+          store: {
+            sql: { dev: "sqlite", stack: "postgres", prod: "postgres" },
+            kv: { dev: "memory", stack: "redis", prod: "redis" },
+          },
+        },
+      },
+    };
+    expect(resolveSqlDriverId(options, "dev", false)).toBe("sqlite");
+    expect(resolveKvDriverId(options, "dev", false)).toBe("memory");
+  });
+
+  test("stack env uses stack profile (falls back to prod)", () => {
+    const options = {
+      config: {
+        drivers: {
+          store: {
+            sql: { dev: "sqlite", stack: "postgres", prod: "postgres" },
+            kv: { dev: "memory", prod: "redis" },
+          },
+        },
+      },
+    };
+    expect(resolveSqlDriverId(options, "stack", true)).toBe("postgres");
+    expect(resolveKvDriverId(options, "stack", true)).toBe("redis");
+  });
+
+  test("stack mode honours OKE_*_DRIVER overrides", () => {
+    process.env.OKE_SQL_DRIVER = "postgres";
+    process.env.OKE_KV_DRIVER = "redis";
+    expect(resolveSqlDriverId({}, "stack", true)).toBe("postgres");
+    expect(resolveKvDriverId({}, "stack", true)).toBe("redis");
+  });
+});

package/src/kernel/boot-bind/store.ts

@@ -2,42 +2,70 @@
  * Lazy store binder — loaded only when Store is declared.
  */
 
+import {
+  resolveDriverId,
+  type ConfigEnv,
+} from "../../config/index.ts";
 import { memoryDrivers } from "../../drivers/memory.ts";
+import { postgresDriver } from "../../drivers/postgres.ts";
+import { redisDriver } from "../../drivers/redis.ts";
+import { sqliteDriver } from "../../drivers/sqlite.ts";
+import type { KvDriver, SqlDriver } from "../../drivers/types.ts";
 import {
   createStoreRuntime,
   type StoreRuntime,
 } from "../../elements/store.ts";
-import {
-  resolveDriverId,
-  type ConfigEnv,
-} from "../../config/index.ts";
+import type { StoreDecl } from "../../elements/store/declare.ts";
 import type { BootOptions } from "../boot.ts"; // type-only — no cycle at runtime
 
 /**
  * Construct a Store runtime and register facet declarations.
  *
+ * In stack mode (`env === "stack"` / `OKE_STACK=1`), SQL/KV resolve from the
+ * `stack` driver map (falling back to `prod`) and URLs from `.env.stack`.
+ *
  * @param options - Boot options
  * @param env - Active environment
  * @param now - Clock
+ * @param stack - Prefer compose URLs when opening postgres/redis
  */
 export function bindStore(
   options: BootOptions,
   env: ConfigEnv,
   now: () => number,
+  stack = false,
 ): StoreRuntime {
-  const sqlId =
-    resolveDriverId(options.config?.drivers?.store?.sql, env) ?? "memory";
-  const kvId =
-    resolveDriverId(options.config?.drivers?.store?.kv, env) ?? "memory";
-  void sqlId;
-  void kvId;
+  const sqlId = resolveSqlDriverId(options, env, stack);
+  const kvId = resolveKvDriverId(options, env, stack);
+  const sqlUrl = sqlUrlFor(sqlId, stack);
+  const kvUrl = kvUrlFor(kvId, stack);
+
+  const sqlBindings: Record<
+    string,
+    { name: string; primary: { url: string } }
+  > = {};
+  const kvBindings: Record<string, { url?: string }> = {};
+
+  for (const decl of options.stores ?? []) {
+    if (isSqlDecl(decl)) {
+      sqlBindings[decl.name] = {
+        name: decl.name,
+        primary: { url: sqlUrl },
+      };
+    } else if (isKvDecl(decl)) {
+      kvBindings[decl.name] = kvUrl !== undefined ? { url: kvUrl } : {};
+    }
+  }
+
   const store = createStoreRuntime({
     drivers: {
-      sql: memoryDrivers.sql,
-      kv: memoryDrivers.kv,
+      sql: sqlDriverFor(sqlId),
+      kv: kvDriverFor(kvId),
       files: memoryDrivers.files,
       index: memoryDrivers.index,
     },
+    sql: sqlBindings,
+    kv: kvBindings,
     now,
   });
   for (const decl of options.stores ?? []) {
@@ -45,3 +73,105 @@ export function bindStore(
   }
   return store;
 }
+
+/**
+ * @param options - Boot options
+ * @param env - Active env
+ * @param stack - Stack mode
+ */
+export function resolveSqlDriverId(
+  options: BootOptions,
+  env: ConfigEnv,
+  stack: boolean,
+): string {
+  const fromEnv = process.env.OKE_SQL_DRIVER?.trim();
+  if (stack && fromEnv) return fromEnv;
+  const resolved = resolveDriverId(options.config?.drivers?.store?.sql, env);
+  if (resolved) return resolved;
+  return stack ? "postgres" : "memory";
+}
+
+/**
+ * @param options - Boot options
+ * @param env - Active env
+ * @param stack - Stack mode
+ */
+export function resolveKvDriverId(
+  options: BootOptions,
+  env: ConfigEnv,
+  stack: boolean,
+): string {
+  const fromEnv = process.env.OKE_KV_DRIVER?.trim();
+  if (stack && fromEnv) return fromEnv;
+  const resolved = resolveDriverId(options.config?.drivers?.store?.kv, env);
+  if (resolved) return resolved;
+  return stack ? "redis" : "memory";
+}
+
+function sqlDriverFor(id: string): SqlDriver {
+  switch (id) {
+    case "postgres":
+      return postgresDriver;
+    case "sqlite":
+      return sqliteDriver;
+    case "memory":
+      return memoryDrivers.sql;
+    default:
+      throw new Error(`oke boot: unknown sql driver "${id}"`);
+  }
+}
+
+function kvDriverFor(id: string): KvDriver {
+  switch (id) {
+    case "redis":
+      return redisDriver;
+    case "memory":
+      return memoryDrivers.kv;
+    default:
+      throw new Error(`oke boot: unknown kv driver "${id}"`);
+  }
+}
+
+function sqlUrlFor(sqlId: string, stack: boolean): string {
+  if (sqlId === "postgres") {
+    const url =
+      process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL ?? undefined;
+    if (!url) {
+      throw new Error(
+        stack
+          ? "oke boot: postgres driver needs DATABASE_URL (did `oke dev -s` write .env.stack?)"
+          : "oke boot: postgres driver needs DATABASE_URL",
+      );
+    }
+    return url;
+  }
+  if (sqlId === "sqlite") {
+    return process.env.OKE_SQLITE_URL ?? ".oke/app.sqlite";
+  }
+  return ":memory:";
+}
+
+function kvUrlFor(kvId: string, stack: boolean): string | undefined {
+  if (kvId !== "redis") return undefined;
+  const url = process.env.REDIS_URL ?? process.env.OKE_STORE_KV_URL ?? undefined;
+  if (!url) {
+    throw new Error(
+      stack
+        ? "oke boot: redis driver needs REDIS_URL (did `oke dev -s` write .env.stack?)"
+        : "oke boot: redis driver needs REDIS_URL",
+    );
+  }
+  return url;
+}
+
+function isSqlDecl(
+  decl: StoreDecl,
+): decl is Extract<StoreDecl, { facet: "sql" }> {
+  return decl.facet === "sql";
+}
+
+function isKvDecl(
+  decl: StoreDecl,
+): decl is Extract<StoreDecl, { facet: "kv" }> {
+  return decl.facet === "kv";
+}

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