okengine 0.2.2 → 0.2.4

package/src/docker/stack-id.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Per-project stack identity.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  hostPortForInstance,
+  parseStackCredentials,
+  stackAppSlug,
+  stackInstanceId,
+} from "./stack-id.ts";
+import { deriveInfrastructure } from "./derive.ts";
+
+describe("stackInstanceId", () => {
+  test("is stable for the same cwd and differs across paths", () => {
+    const a = stackInstanceId("/tmp/oke-project-a");
+    const b = stackInstanceId("/tmp/oke-project-a");
+    const c = stackInstanceId("/tmp/oke-project-b");
+    expect(a).toBe(b);
+    expect(a).toHaveLength(6);
+    expect(a).not.toBe(c);
+  });
+
+  test("stackAppSlug is dev-<id>", () => {
+    const id = stackInstanceId("/tmp/oke-x");
+    expect(stackAppSlug("/tmp/oke-x")).toBe(`dev-${id}`);
+  });
+});
+
+describe("hostPortForInstance", () => {
+  test("offsets sql and kv into separate ranges", () => {
+    const id = "abcd12";
+    const sql = hostPortForInstance("store.sql", 5432, id);
+    const kv = hostPortForInstance("store.kv", 6379, id);
+    expect(sql).toBeGreaterThanOrEqual(15_000);
+    expect(sql).toBeLessThan(16_000);
+    expect(kv).toBeGreaterThanOrEqual(16_000);
+    expect(kv).toBeLessThan(17_000);
+  });
+});
+
+describe("parseStackCredentials", () => {
+  test("reads OKE_* credential keys", () => {
+    const text = `
+OKE_STORE_SQL_USER=oke
+OKE_STORE_SQL_PASSWORD=s3cret
+OKE_STORE_SQL_DB=oke
+OKE_STORE_KV_USER=oke
+OKE_STORE_KV_PASSWORD=kvpass
+OKE_STORE_KV_DB=oke
+`;
+    const creds = parseStackCredentials(text, ["store.sql", "store.kv"]);
+    expect(creds["store.sql"]?.password).toBe("s3cret");
+    expect(creds["store.kv"]?.password).toBe("kvpass");
+  });
+});
+
+describe("deriveInfrastructure instanceId", () => {
+  test("unique app name and host ports land in stackEnv URLs", () => {
+    const result = deriveInfrastructure({
+      images: {
+        "store.sql": "postgres:18-alpine",
+        "store.kv": "redis:8-alpine",
+      },
+      app: "dev-abcdef",
+      instanceId: "abcdef",
+      includeApp: false,
+      credentials: {
+        "store.sql": {
+          user: "oke",
+          password: "stack-id-test-sql-password",
+          database: "oke",
+        },
+        "store.kv": {
+          user: "oke",
+          password: "stack-id-test-kv-password",
+          database: "oke",
+        },
+      },
+    });
+    const base = result.files.find((f) => f.path === "compose.yml")!.content;
+    expect(base).toContain("oke-dev-abcdef");
+    expect(result.stackEnv.DATABASE_URL).toMatch(/:15\d{3}\//);
+    expect(result.stackEnv.REDIS_URL).toMatch(/:16\d{3}/);
+  });
+});

package/src/docker/stack-id.ts

@@ -0,0 +1,108 @@
+/**
+ * Per-project local stack identity — unique compose project + host ports.
+ *
+ * `oke dev --stack` must not share one `oke-dev` Postgres across every app on
+ * the machine. Identity is a stable short hash of the project cwd.
+ */
+
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import type { ServiceCredentials } from "./types.ts";
+import { defaultHostPort, envPrefix } from "./helpers.ts";
+
+/**
+ * Stable 6-hex id for a project directory (local stacks only).
+ *
+ * @param cwd - Project root
+ */
+export function stackInstanceId(cwd: string): string {
+  return createHash("sha256")
+    .update(resolve(cwd))
+    .digest("hex")
+    .slice(0, 6);
+}
+
+/**
+ * Compose project / app slug: `dev-<id>` → Docker name `oke-dev-<id>`.
+ *
+ * @param cwd - Project root
+ */
+export function stackAppSlug(cwd: string): string {
+  return `dev-${stackInstanceId(cwd)}`;
+}
+
+/**
+ * Host port for a role, offset by instance id so two stacks can run at once.
+ *
+ * @param role - Role key
+ * @param containerPort - Container listen port
+ * @param instanceId - 6-hex stack id
+ */
+export function hostPortForInstance(
+  role: string,
+  containerPort: number,
+  instanceId: string,
+): number {
+  const n = Number.parseInt(instanceId.slice(0, 4), 16) % 1000;
+  if (role === "store.sql") return 15_000 + n;
+  if (role === "store.kv") return 16_000 + n;
+  if (role === "signal") return 17_000 + n;
+  return defaultHostPort(role, containerPort) + n;
+}
+
+/**
+ * Parse role credentials from an existing `.env.stack` body (reuse on restart).
+ *
+ * @param text - Dotenv contents
+ * @param roles - Roles to look up
+ */
+export function parseStackCredentials(
+  text: string,
+  roles: readonly string[],
+): Record<string, ServiceCredentials> {
+  const map = new Map<string, string>();
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq);
+    let value = trimmed.slice(eq + 1);
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    map.set(key, value);
+  }
+
+  const out: Record<string, ServiceCredentials> = {};
+  for (const role of roles) {
+    const prefix = envPrefix(role);
+    const user = map.get(`${prefix}_USER`);
+    const password = map.get(`${prefix}_PASSWORD`);
+    const database = map.get(`${prefix}_DB`);
+    if (user && password && database) {
+      out[role] = { user, password, database };
+    }
+  }
+  return out;
+}
+
+/**
+ * Load credentials from project `.env.stack` when present.
+ *
+ * @param cwd - Project root
+ * @param roles - Image roles
+ */
+export async function loadExistingStackCredentials(
+  cwd: string,
+  roles: readonly string[],
+): Promise<Readonly<Record<string, ServiceCredentials>> | undefined> {
+  const path = resolve(cwd, ".env.stack");
+  const file = Bun.file(path);
+  if (!(await file.exists())) return undefined;
+  const parsed = parseStackCredentials(await file.text(), roles);
+  return Object.keys(parsed).length > 0 ? parsed : undefined;
+}

package/src/docker/stack.integration.test.ts

@@ -32,10 +32,11 @@ describe("oke dev --stack postgres integration", () => {
     }
 
     const dir = await mkdtemp(join(tmpdir(), "oke-stack-pg-"));
+    const dockerDir = join(dir, "docker");
     const project = `oke-pg-${Date.now()}`;
     try {
       const derived = deriveInfrastructure({
-        images: { "store.sql": "postgres:16-alpine" },
+        images: { "store.sql": "postgres:18-alpine" },
         credentials: {
           "store.sql": {
             user: "oke",
@@ -45,11 +46,16 @@ describe("oke dev --stack postgres integration", () => {
         },
         app: "stacktest",
         host: "127.0.0.1",
+        includeApp: false,
+        composeDir: "docker",
+      });
+      await writeDerivedFiles(derived, dockerDir, {
+        writeStackEnv: true,
+        stackEnvDir: dir,
       });
-      await writeDerivedFiles(derived, dir, { writeStackEnv: true });
 
-      // Stack-only: no app service — just the role compose file.
-      const composeFiles = ["compose.store.sql.yml"];
+      // Infra-only: network + role compose (no app build).
+      const composeFiles = ["compose.yml", "compose.store.sql.yml"];
       const up = Bun.spawn(
         [
           "docker",
@@ -61,7 +67,7 @@ describe("oke dev --stack postgres integration", () => {
           "-d",
         ],
         {
-          cwd: dir,
+          cwd: dockerDir,
           stdout: "pipe",
           stderr: "pipe",
           env: {
@@ -92,7 +98,7 @@ describe("oke dev --stack postgres integration", () => {
             "--format",
             "json",
           ],
-          { cwd: dir, stdout: "pipe", stderr: "pipe" },
+          { cwd: dockerDir, stdout: "pipe", stderr: "pipe" },
         );
         const text = await new Response(ps.stdout).text();
         await ps.exited;
@@ -115,11 +121,12 @@ describe("oke dev --stack postgres integration", () => {
       }
 
       // Prove credentials live in .env.stack, not YAML.
-      const yml = await Bun.file(join(dir, "compose.store.sql.yml")).text();
+      const yml = await Bun.file(join(dockerDir, "compose.store.sql.yml")).text();
       expect(yml).not.toContain("stack-integration-pass");
       expect(formatStackEnv(derived.stackEnv)).toContain(
         "stack-integration-pass",
       );
+      expect(await Bun.file(join(dir, ".env.stack")).exists()).toBe(true);
     } finally {
       await Bun.spawn(
         [
@@ -128,11 +135,13 @@ describe("oke dev --stack postgres integration", () => {
           "-p",
           project,
           "-f",
+          "compose.yml",
+          "-f",
           "compose.store.sql.yml",
           "down",
           "-v",
         ],
-        { cwd: dir, stdout: "pipe", stderr: "pipe" },
+        { cwd: dockerDir, stdout: "pipe", stderr: "pipe" },
       ).exited.catch(() => {});
       await rm(dir, { recursive: true, force: true }).catch(() => {});
     }

package/src/docker/types.ts

@@ -100,7 +100,18 @@ export interface DeriveOptions {
   readonly appPort?: number;
   /** When true, emit prod overlays (limits, secret refs, deploy.replicas). */
   readonly prod?: boolean;
-  /** Output directory (default `.`). */
+  /**
+   * Include the `app` service in `compose.yml` (default true).
+   * `oke dev --stack` sets false — host Bun runs the app; Docker is infra only.
+   */
+  readonly includeApp?: boolean;
+  /**
+   * Compose artefact directory relative to the project root (default `docker`).
+   * Controls generated `env_file` / `build.context` paths (e.g. `../.env.stack`).
+   * Pass `"."` for legacy root-level layout.
+   */
+  readonly composeDir?: string;
+  /** Output directory (default `docker`). */
   readonly outDir?: string;
   /** Inject credentials (tests). Defaults to generated randoms. */
   readonly credentials?: Readonly<Record<string, ServiceCredentials>>;
@@ -108,8 +119,16 @@ export interface DeriveOptions {
   readonly host?: string;
   /** Extra image recipes (plugins). */
   readonly recipes?: readonly ImageRecipe[];
+  /**
+   * Local stack instance id (6-hex). When set, host ports are offset so two
+   * `oke dev -s` projects do not share one Postgres on `:5432`.
+   */
+  readonly instanceId?: string;
 }
 
+/** Default relative directory for generated Docker / compose artefacts. */
+export const DEFAULT_DOCKER_DIR = "docker";
+
 /** One generated file. */
 export interface GeneratedFile {
   /** Relative path under `outDir`. */

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