okengine 0.2.3 → 0.2.5

package/src/cli/hero-meta.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Hero snapshot — profile, elements, encode/decode.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { OkeConfig } from "../config/index.ts";
+import {
+  buildDevHeroSnapshot,
+  decodeHeroSnapshot,
+  encodeHeroSnapshot,
+  resolveDevProfile,
+  resolveHeroElements,
+} from "./hero-meta.ts";
+
+const SAMPLE: OkeConfig = {
+  drivers: {
+    store: {
+      sql: { dev: "sqlite", stack: "postgres", prod: "postgres" },
+      kv: { dev: "memory", stack: "redis", prod: "redis" },
+    },
+    signal: { dev: "memory", stack: "postgres", prod: "postgres" },
+    clock: { dev: "memory", stack: "postgres", prod: "postgres" },
+    vault: { dev: "dotenv", stack: "dotenv", prod: "sops" },
+    channel: {
+      email: { dev: "console", stack: "smtp", prod: "smtp" },
+    },
+    ai: { dev: "mock", stack: "mock" },
+  },
+};
+
+describe("hero-meta", () => {
+  test("resolveDevProfile maps stack and NODE_ENV", () => {
+    expect(resolveDevProfile({ stack: false })).toBe("local");
+    expect(resolveDevProfile({ stack: true })).toBe("local-server");
+    expect(resolveDevProfile({ stack: false, nodeEnv: "test" })).toBe("test");
+    expect(resolveDevProfile({ stack: false, nodeEnv: "production" })).toBe(
+      "production",
+    );
+  });
+
+  test("resolveHeroElements lists eight elements with drivers", () => {
+    const rows = resolveHeroElements(SAMPLE, { stack: false });
+    expect(rows.map((r) => r.element)).toEqual([
+      "flow",
+      "signal",
+      "store",
+      "clock",
+      "gate",
+      "vault",
+      "channel",
+      "ai",
+    ]);
+    expect(rows.find((r) => r.element === "store")?.detail).toContain("sqlite");
+    expect(rows.find((r) => r.element === "flow")?.detail).toBe("●");
+  });
+
+  test("stack profile applies to every element", () => {
+    const rows = resolveHeroElements(SAMPLE, {
+      stack: true,
+      sqlDriver: "postgres",
+      kvDriver: "redis",
+    });
+    const store = rows.find((r) => r.element === "store")?.detail ?? "";
+    expect(store).toContain("postgres");
+    expect(store).toContain("redis");
+    expect(store).not.toContain("sqlite");
+    expect(rows.find((r) => r.element === "signal")?.detail).toBe("postgres");
+    expect(rows.find((r) => r.element === "clock")?.detail).toBe("postgres");
+    expect(rows.find((r) => r.element === "channel")?.detail).toContain("smtp");
+  });
+
+  test("encode/decode round-trips", () => {
+    const snap = buildDevHeroSnapshot({
+      config: SAMPLE,
+      stack: true,
+      sqlDriver: "postgres",
+      kvDriver: "redis",
+      version: "0.2.4",
+      nodeEnv: "development",
+    });
+    expect(snap.profile).toBe("local-server");
+    expect(snap.runtimeEnv).toBe("local");
+    expect(decodeHeroSnapshot(encodeHeroSnapshot(snap))).toEqual(snap);
+  });
+});

package/src/cli/hero-meta.ts

@@ -0,0 +1,252 @@
+/**
+ * Resolve `oke dev` hero facts — eight elements, profile, env, system.
+ */
+
+import { release } from "node:os";
+import {
+  resolveDriverId,
+  type ConfigEnv,
+  type DriversConfig,
+  type OkeConfig,
+} from "../config/index.ts";
+
+/** How the process is running (local laptop → production). */
+export type DevRuntimeProfile =
+  | "local"
+  | "local-server"
+  | "test"
+  | "production";
+
+/** Data plane: still on a laptop vs real production. */
+export type DevRuntimeEnv = "local" | "production";
+
+/** One of the eight elements with its active driver summary. */
+export type HeroElementRow = {
+  readonly element: string;
+  /** Driver summary, or `—` when unbound. */
+  readonly detail: string;
+};
+
+/** Serializable hero payload (TTY + soft-reload env). */
+export type DevHeroSnapshot = {
+  readonly profile: DevRuntimeProfile;
+  readonly runtimeEnv: DevRuntimeEnv;
+  readonly system: string;
+  readonly elements: readonly HeroElementRow[];
+  readonly version?: string;
+};
+
+const EIGHT_ELEMENTS = [
+  "flow",
+  "signal",
+  "store",
+  "clock",
+  "gate",
+  "vault",
+  "channel",
+  "ai",
+] as const;
+
+/**
+ * Host / runtime line for the hero (`darwin 25.4.0 · bun 1.3.14`).
+ */
+export function formatHeroSystemLine(
+  bunVersion: string = Bun.version,
+  platform: string = process.platform,
+  osRelease: string = release(),
+): string {
+  return `${platform} ${osRelease} · bun ${bunVersion}`;
+}
+
+/**
+ * Profile for an `oke dev` session.
+ *
+ * @param options - Stack / NODE_ENV hints
+ */
+export function resolveDevProfile(options: {
+  readonly stack: boolean;
+  /** Explicit role — do not infer from ambient `NODE_ENV` (tests set `test`). */
+  readonly nodeEnv?: string;
+}): DevRuntimeProfile {
+  if (options.nodeEnv === "test") return "test";
+  if (options.nodeEnv === "production") return "production";
+  return options.stack ? "local-server" : "local";
+}
+
+/**
+ * Data-plane environment (local machine vs production deploy).
+ *
+ * @param profile - Runtime profile
+ */
+export function resolveDevRuntimeEnv(
+  profile: DevRuntimeProfile,
+): DevRuntimeEnv {
+  return profile === "production" ? "production" : "local";
+}
+
+/**
+ * Active driver id for an env map, preferring {@link prefer} when set.
+ *
+ * @param map - Env driver map
+ * @param env - Config env key
+ * @param prefer - Override (stack sql/kv)
+ */
+function driverOr(
+  map: Parameters<typeof resolveDriverId>[0],
+  env: ConfigEnv,
+  prefer?: string,
+): string | undefined {
+  if (prefer !== undefined && prefer.length > 0) return prefer;
+  return resolveDriverId(map, env);
+}
+
+/**
+ * Summarize channel mediums for the active config env.
+ *
+ * @param channel - Channel driver maps
+ * @param env - Config env
+ */
+function channelDetail(
+  channel: DriversConfig["channel"],
+  env: ConfigEnv,
+): string {
+  if (!channel) return "—";
+  const parts: string[] = [];
+  for (const medium of ["email", "sms", "whatsapp", "push"] as const) {
+    const id = resolveDriverId(channel[medium], env);
+    if (id) parts.push(`${medium} ${id}`);
+  }
+  return parts.length > 0 ? parts.join(" · ") : "—";
+}
+
+/**
+ * Summarize store facets for the active (or stack-overridden) drivers.
+ *
+ * @param store - Store driver maps
+ * @param env - Config env for non-overridden facets
+ * @param overrides - Stack sql/kv ids
+ */
+function storeDetail(
+  store: DriversConfig["store"],
+  env: ConfigEnv,
+  overrides: { readonly sql?: string; readonly kv?: string },
+): string {
+  if (!store && !overrides.sql && !overrides.kv) return "—";
+  const parts: string[] = [];
+  const sql = driverOr(store?.sql, env, overrides.sql);
+  const kv = driverOr(store?.kv, env, overrides.kv);
+  const files = resolveDriverId(store?.files, env);
+  const index = resolveDriverId(store?.index, env);
+  if (sql) parts.push(`sql ${sql}`);
+  if (kv) parts.push(`kv ${kv}`);
+  if (files) parts.push(`files ${files}`);
+  if (index) parts.push(`index ${index}`);
+  return parts.length > 0 ? parts.join(" · ") : "—";
+}
+
+/**
+ * Resolve eight-element rows from `oke.config` + stack overrides.
+ *
+ * @param config - Loaded config (or null)
+ * @param options - Stack driver overrides; config env for maps
+ */
+export function resolveHeroElements(
+  config: OkeConfig | null | undefined,
+  options: {
+    /** Use prod store ids from stack (`oke dev -s`). */
+    readonly stack: boolean;
+    readonly sqlDriver?: string;
+    readonly kvDriver?: string;
+    /** Which driver map column to read (default `dev`). */
+    readonly configEnv?: ConfigEnv;
+  },
+): readonly HeroElementRow[] {
+  const drivers = config?.drivers;
+  // `-s` reads the `stack` profile for every element (not a store-only override).
+  const configEnv: ConfigEnv =
+    options.configEnv ?? (options.stack ? "stack" : "dev");
+
+  const byName: Record<string, string> = {
+    flow: "●",
+    signal: resolveDriverId(drivers?.signal, configEnv) ?? "—",
+    store: storeDetail(drivers?.store, configEnv, {
+      sql: options.sqlDriver,
+      kv: options.kvDriver,
+    }),
+    clock: resolveDriverId(drivers?.clock, configEnv) ?? "—",
+    gate: "—",
+    vault: resolveDriverId(drivers?.vault, configEnv) ?? "—",
+    channel: channelDetail(drivers?.channel, configEnv),
+    ai: resolveDriverId(drivers?.ai, configEnv) ?? "—",
+  };
+
+  return EIGHT_ELEMENTS.map((element) => ({
+    element,
+    detail: byName[element] ?? "—",
+  }));
+}
+
+/**
+ * Build the full hero snapshot for banner / soft reload.
+ *
+ * @param options - Config, stack, versions
+ */
+export function buildDevHeroSnapshot(options: {
+  readonly config?: OkeConfig | null;
+  readonly stack: boolean;
+  readonly sqlDriver?: string;
+  readonly kvDriver?: string;
+  readonly version?: string;
+  readonly nodeEnv?: string;
+}): DevHeroSnapshot {
+  const profile = resolveDevProfile({
+    stack: options.stack,
+    nodeEnv: options.nodeEnv,
+  });
+  return {
+    profile,
+    runtimeEnv: resolveDevRuntimeEnv(profile),
+    system: formatHeroSystemLine(),
+    elements: resolveHeroElements(options.config, {
+      stack: options.stack,
+      sqlDriver: options.sqlDriver,
+      kvDriver: options.kvDriver,
+    }),
+    ...(options.version !== undefined ? { version: options.version } : {}),
+  };
+}
+
+/**
+ * Encode snapshot for the app child soft-reload env.
+ *
+ * @param snapshot - Hero facts
+ */
+export function encodeHeroSnapshot(snapshot: DevHeroSnapshot): string {
+  return JSON.stringify(snapshot);
+}
+
+/**
+ * Decode soft-reload hero env (invalid → null).
+ *
+ * @param raw - JSON from `OKE_DEV_HERO_META`
+ */
+export function decodeHeroSnapshot(raw: string | undefined): DevHeroSnapshot | null {
+  if (raw === undefined || raw.length === 0) return null;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      !("profile" in parsed) ||
+      !("runtimeEnv" in parsed) ||
+      !("system" in parsed) ||
+      !("elements" in parsed) ||
+      !Array.isArray((parsed as DevHeroSnapshot).elements)
+    ) {
+      return null;
+    }
+    return parsed as DevHeroSnapshot;
+  } catch {
+    return null;
+  }
+}

package/src/cli/load-config.images.test.ts

@@ -6,6 +6,7 @@ import { describe, expect, test } from "bun:test";
 import {
   defaultImagesFromConfig,
   resolveImages,
+  stackDevDriverMismatches,
 } from "./load-config.ts";
 
 describe("defaultImagesFromConfig", () => {
@@ -73,3 +74,53 @@ describe("resolveImages", () => {
     expect(images["store.kv"]).toBe("redis:8-alpine");
   });
 });
+
+describe("stackDevDriverMismatches", () => {
+  test("flags stack/prod sqlite/memory when containers are up", () => {
+    const mismatches = stackDevDriverMismatches(
+      {
+        drivers: {
+          store: {
+            sql: { dev: "sqlite", stack: "sqlite", prod: "sqlite" },
+            kv: { dev: "memory", stack: "memory", prod: "memory" },
+          },
+        },
+      },
+      ["store.sql", "store.kv"],
+    );
+    expect(mismatches).toEqual([
+      { label: "sql", using: "sqlite", container: "postgres" },
+      { label: "kv", using: "memory", container: "redis" },
+    ]);
+  });
+
+  test("silent when stack profile matches containers", () => {
+    const mismatches = stackDevDriverMismatches(
+      {
+        drivers: {
+          store: {
+            sql: { dev: "sqlite", stack: "postgres", prod: "postgres" },
+            kv: { dev: "memory", stack: "redis", prod: "redis" },
+          },
+        },
+      },
+      ["store.sql", "store.kv"],
+    );
+    expect(mismatches).toEqual([]);
+  });
+
+  test("silent when only prod is set (stack falls back to prod)", () => {
+    const mismatches = stackDevDriverMismatches(
+      {
+        drivers: {
+          store: {
+            sql: { dev: "sqlite", prod: "postgres" },
+            kv: { dev: "memory", prod: "redis" },
+          },
+        },
+      },
+      ["store.sql", "store.kv"],
+    );
+    expect(mismatches).toEqual([]);
+  });
+});

package/src/cli/load-config.ts

@@ -22,7 +22,18 @@ function driverId(ref: DriverRef | undefined): string | undefined {
 }
 
 /**
- * Derive default image pins from prod driver protocols.
+ * Prefer `stack` then `prod` for a driver map (local server ≈ production).
+ *
+ * @param map - Env driver map
+ */
+function stackOrProdId(
+  map: { readonly stack?: DriverRef; readonly prod?: DriverRef } | undefined,
+): string | undefined {
+  return driverId(map?.stack) ?? driverId(map?.prod);
+}
+
+/**
+ * Derive default image pins from stack/prod driver protocols.
  *
  * Used when `oke.config.ts` omits `images` but declares postgres/redis (etc.)
  * so `oke dev -s` / `oke stack` / `oke docker` have something to run.
@@ -33,11 +44,11 @@ export function defaultImagesFromConfig(
   config: OkeConfig,
 ): Readonly<Record<string, string>> {
   const out: Record<string, string> = {};
-  const sql = driverId(config.drivers?.store?.sql?.prod);
-  const index = driverId(config.drivers?.store?.index?.prod);
-  const kv = driverId(config.drivers?.store?.kv?.prod);
-  const signal = driverId(config.drivers?.signal?.prod);
-  const clock = driverId(config.drivers?.clock?.prod);
+  const sql = stackOrProdId(config.drivers?.store?.sql);
+  const index = stackOrProdId(config.drivers?.store?.index);
+  const kv = stackOrProdId(config.drivers?.store?.kv);
+  const signal = stackOrProdId(config.drivers?.signal);
+  const clock = stackOrProdId(config.drivers?.clock);
 
   const needsSql =
     sql === "postgres" ||
@@ -134,3 +145,70 @@ export function resolveImages(
   if (config) return defaultImagesFromConfig(config);
   return {};
 }
+
+/** Compact driver mismatch for {@link formatStackSummary}. */
+export type StackDriverMismatch = {
+  /** Short label (`sql`, `kv`). */
+  readonly label: string;
+  /** Active `drivers.*.stack` (→ prod) id. */
+  readonly using: string;
+  /** Driver that would use the container. */
+  readonly container: string;
+};
+
+/**
+ * Detect when `oke dev -s` containers will not back the app because the
+ * `stack` driver profile still points at local/memory backends.
+ *
+ * @param config - Loaded config
+ * @param stackRoles - Roles being composed
+ */
+export function stackDevDriverMismatches(
+  config: OkeConfig,
+  stackRoles: readonly string[],
+): readonly StackDriverMismatch[] {
+  const roles = new Set(stackRoles);
+  const out: StackDriverMismatch[] = [];
+  const sqlStack =
+    driverId(config.drivers?.store?.sql?.stack) ??
+    driverId(config.drivers?.store?.sql?.prod);
+  const kvStack =
+    driverId(config.drivers?.store?.kv?.stack) ??
+    driverId(config.drivers?.store?.kv?.prod);
+
+  if (
+    roles.has("store.sql") &&
+    (sqlStack === "sqlite" || sqlStack === "memory" || sqlStack === undefined)
+  ) {
+    out.push({
+      label: "sql",
+      using: sqlStack ?? "unset",
+      container: "postgres",
+    });
+  }
+  if (
+    roles.has("store.kv") &&
+    (kvStack === "memory" || kvStack === undefined)
+  ) {
+    out.push({
+      label: "kv",
+      using: kvStack ?? "memory",
+      container: "redis",
+    });
+  }
+  return out;
+}
+
+/**
+ * @deprecated Use {@link stackDevDriverMismatches} — kept for older call sites.
+ * @param config - Loaded config
+ * @param stackRoles - Roles being composed
+ */
+export function stackDevDriverWarnings(
+  config: OkeConfig,
+  stackRoles: readonly string[],
+): readonly string[] {
+  return stackDevDriverMismatches(config, stackRoles).map(
+    (m) => `${m.label}: ${m.using}`,
+  );
+}

package/src/config/define-config.test.ts

@@ -0,0 +1,61 @@
+/**
+ * `defineConfig` fills missing `stack` pins from `prod`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { defineConfig, fillStackFromProd } from "./index.ts";
+
+describe("fillStackFromProd / defineConfig", () => {
+  test("copies prod onto stack when stack is omitted", () => {
+    const filled = fillStackFromProd({
+      dev: "sqlite",
+      prod: "postgres",
+    });
+    expect(filled?.stack).toBe("postgres");
+    expect(filled?.dev).toBe("sqlite");
+  });
+
+  test("does not overwrite an explicit stack pin", () => {
+    expect(
+      fillStackFromProd({
+        dev: "sqlite",
+        stack: "memory",
+        prod: "postgres",
+      })?.stack,
+    ).toBe("memory");
+  });
+
+  test("vault sops → stack dotenv", () => {
+    expect(
+      fillStackFromProd({ dev: "dotenv", prod: "sops" }, { vault: true })
+        ?.stack,
+    ).toBe("dotenv");
+  });
+
+  test("defineConfig fills every element from prod", () => {
+    const cfg = defineConfig({
+      drivers: {
+        store: {
+          sql: { dev: "sqlite", prod: "postgres" },
+          kv: { dev: "memory", prod: "redis" },
+          files: { dev: "fs", prod: "s3" },
+        },
+        signal: { dev: "memory", prod: "postgres" },
+        clock: { dev: "memory", prod: "postgres" },
+        vault: { dev: "dotenv", prod: "sops" },
+        channel: {
+          email: { dev: "console", prod: "smtp" },
+        },
+        ai: { dev: "mock", prod: "anthropic" },
+      },
+    });
+    expect(cfg.drivers?.store?.sql?.stack).toBe("postgres");
+    expect(cfg.drivers?.store?.kv?.stack).toBe("redis");
+    expect(cfg.drivers?.store?.files?.stack).toBe("s3");
+    expect(cfg.drivers?.signal?.stack).toBe("postgres");
+    expect(cfg.drivers?.clock?.stack).toBe("postgres");
+    expect(cfg.drivers?.vault?.stack).toBe("dotenv");
+    expect(cfg.drivers?.channel?.email?.stack).toBe("smtp");
+    expect(cfg.drivers?.ai?.stack).toBe("anthropic");
+  });
+});

package/src/config/index.ts

@@ -5,8 +5,15 @@
  * @module
  */
 
-/** Environment role keys used in driver maps. */
-export type ConfigEnv = "dev" | "test" | "prod";
+/**
+ * Environment role keys used in driver maps.
+ *
+ * - `dev` — local laptop (`oke dev`)
+ * - `stack` — local server (`oke dev -s` / compose infra + host Bun)
+ * - `test` — automated tests
+ * - `prod` — production deploy
+ */
+export type ConfigEnv = "dev" | "stack" | "test" | "prod";
 
 /** Pool options for SQL drivers. */
 export interface DriverPoolOptions {
@@ -143,17 +150,90 @@ export interface OkeConfig {
 }
 
 /**
- * Define an `oke.config.ts` document (identity function + type check).
+ * Fill missing `stack` pins from `prod` (local server ≈ production protocols).
+ *
+ * Vault is the exception: `prod: "sops"` becomes `stack: "dotenv"` so
+ * `oke dev -s` can read `.env.stack` without age keys.
+ *
+ * @param map - Env → driver map
+ * @param options - Element-specific defaults
+ */
+export function fillStackFromProd(
+  map: EnvDriverMap | undefined,
+  options: { readonly vault?: boolean } = {},
+): EnvDriverMap | undefined {
+  if (!map) return undefined;
+  if (map.stack !== undefined || map.prod === undefined) return map;
+  if (options.vault) {
+    const prodId = typeof map.prod === "string" ? map.prod : map.prod.driver;
+    if (prodId === "sops") {
+      return { ...map, stack: "dotenv" };
+    }
+  }
+  return { ...map, stack: map.prod };
+}
+
+/**
+ * Copy production driver pins onto `stack` wherever `stack` is omitted.
+ *
+ * @param drivers - Drivers block
+ */
+export function fillDriversStackFromProd(
+  drivers: DriversConfig | undefined,
+): DriversConfig | undefined {
+  if (!drivers) return undefined;
+  const store = drivers.store
+    ? {
+        ...drivers.store,
+        sql: fillStackFromProd(drivers.store.sql),
+        kv: fillStackFromProd(drivers.store.kv),
+        files: fillStackFromProd(drivers.store.files),
+        index: fillStackFromProd(drivers.store.index),
+      }
+    : undefined;
+  const channel = drivers.channel
+    ? {
+        ...drivers.channel,
+        email: fillStackFromProd(drivers.channel.email),
+        sms: fillStackFromProd(drivers.channel.sms),
+        whatsapp: fillStackFromProd(drivers.channel.whatsapp),
+        push: fillStackFromProd(drivers.channel.push),
+      }
+    : undefined;
+  return {
+    ...drivers,
+    ...(store !== undefined ? { store } : {}),
+    signal: fillStackFromProd(drivers.signal),
+    clock: fillStackFromProd(drivers.clock),
+    vault: fillStackFromProd(drivers.vault, { vault: true }),
+    ...(channel !== undefined ? { channel } : {}),
+    ai: fillStackFromProd(drivers.ai),
+    runs: fillStackFromProd(drivers.runs),
+  };
+}
+
+/**
+ * Define an `oke.config.ts` document.
+ *
+ * Missing `stack` driver pins are filled from `prod` so `oke dev -s` uses the
+ * same server protocols as production (vault → dotenv for `.env.stack`).
  *
  * @param config - Driver / tenancy / i18n / topology
  */
-export function defineConfig<C extends OkeConfig>(config: C): C {
-  return config;
+export function defineConfig(config: OkeConfig): OkeConfig {
+  if (!config.drivers) return config;
+  return {
+    ...config,
+    drivers: fillDriversStackFromProd(config.drivers),
+  };
 }
 
 /**
  * Resolve a driver id for an env from an {@link EnvDriverMap}.
  *
+ * `stack` falls back to `prod` then `dev` so existing configs keep working
+ * until an explicit `stack:` pin is added.
+ *
  * @param map - Env → driver map
  * @param env - Active environment
  */
@@ -162,7 +242,10 @@ export function resolveDriverId(
   env: ConfigEnv,
 ): string | undefined {
   if (!map) return undefined;
-  const ref = map[env] ?? map.dev ?? map.test;
+  const ref =
+    env === "stack"
+      ? (map.stack ?? map.prod ?? map.dev ?? map.test)
+      : (map[env] ?? map.dev ?? map.test);
   if (ref === undefined) return undefined;
   return typeof ref === "string" ? ref : ref.driver;
 }