okengine 0.2.2 → 0.2.4

package/src/cli/load-config.ts

@@ -3,9 +3,79 @@
  */
 
 import { resolve } from "node:path";
-import type { OkeConfig } from "../config/index.ts";
+import type { DriverRef, OkeConfig } from "../config/index.ts";
 import type { Manifest } from "../manifest/types.ts";
 
+/** Default image pins when `images` is omitted but prod drivers need containers. */
+const DEFAULT_SQL_IMAGE = "postgres:18-alpine";
+const DEFAULT_PGVECTOR_IMAGE = "pgvector/pgvector:pg17";
+const DEFAULT_KV_IMAGE = "redis:8-alpine";
+
+/**
+ * Extract protocol id from a driver ref.
+ *
+ * @param ref - String or `{ driver }` object
+ */
+function driverId(ref: DriverRef | undefined): string | undefined {
+  if (ref === undefined) return undefined;
+  return typeof ref === "string" ? ref : ref.driver;
+}
+
+/**
+ * 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.
+ *
+ * @param config - Loaded config
+ */
+export function defaultImagesFromConfig(
+  config: OkeConfig,
+): Readonly<Record<string, string>> {
+  const out: Record<string, string> = {};
+  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" ||
+    sql === "pgvector" ||
+    index === "pgvector" ||
+    signal === "postgres" ||
+    clock === "postgres" ||
+    (config.drivers?.prod ?? []).some(
+      (p) => p === "postgres" || p === "pgvector",
+    );
+
+  if (needsSql) {
+    out["store.sql"] =
+      sql === "pgvector" || index === "pgvector"
+        ? DEFAULT_PGVECTOR_IMAGE
+        : DEFAULT_SQL_IMAGE;
+  }
+
+  const needsKv =
+    kv === "redis" || (config.drivers?.prod ?? []).includes("redis");
+  if (needsKv) {
+    out["store.kv"] = DEFAULT_KV_IMAGE;
+  }
+
+  return out;
+}
+
 /** Result of loading project config. */
 export interface LoadedConfig {
   readonly config: OkeConfig;
@@ -60,6 +130,9 @@ export async function loadManifest(path: string): Promise<Manifest> {
 /**
  * Resolve images map from config or Manifest.
  *
+ * When neither declares `images`, derive defaults from prod driver protocols
+ * so `oke dev -s` works on scaffolded templates without an explicit pin map.
+ *
  * @param config - Optional config
  * @param manifest - Optional manifest
  */
@@ -67,5 +140,75 @@ export function resolveImages(
   config?: OkeConfig,
   manifest?: Manifest,
 ): Readonly<Record<string, string>> {
-  return config?.images ?? manifest?.images ?? {};
+  const explicit = config?.images ?? manifest?.images;
+  if (explicit && Object.keys(explicit).length > 0) return explicit;
+  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/cli/ports.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Dev port probing — prefer then +1 until free.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { findFreePort, resolveDevPorts } from "./ports.ts";
+
+describe("findFreePort", () => {
+  test("returns preferred when free", async () => {
+    const port = await findFreePort(6530, new Set(), async () => false);
+    expect(port).toBe(6530);
+  });
+
+  test("increments until free", async () => {
+    const busy = new Set([6530, 6531]);
+    const port = await findFreePort(
+      6530,
+      new Set(),
+      async (p) => busy.has(p),
+    );
+    expect(port).toBe(6532);
+  });
+
+  test("skips occupied set even when probe says free", async () => {
+    const port = await findFreePort(
+      6530,
+      new Set([6530, 6531]),
+      async () => false,
+    );
+    expect(port).toBe(6532);
+  });
+
+  test("passes through ephemeral 0", async () => {
+    expect(await findFreePort(0)).toBe(0);
+  });
+});
+
+describe("resolveDevPorts", () => {
+  test("keeps app · console · mcp distinct when preferred collide", async () => {
+    // Everything busy except 6531, 6534, 6536 — force increments.
+    const busy = new Set([6530, 6533, 6535]);
+    const ports = await resolveDevPorts(
+      { app: 6530, console: 6533, mcp: 6535 },
+      async (p) => busy.has(p),
+    );
+    expect(ports.app).toBe(6531);
+    expect(ports.console).toBe(6534);
+    expect(ports.mcp).toBe(6536);
+    expect(new Set([ports.app, ports.console, ports.mcp]).size).toBe(3);
+  });
+});

package/src/cli/ports.ts

@@ -0,0 +1,81 @@
+/**
+ * Dev-time port probing — Next.js-style prefer-then-increment.
+ */
+
+import { createServer } from "node:net";
+
+/** Max upward probes from a preferred port before failing. */
+const MAX_PORT_ATTEMPTS = 100;
+
+/**
+ * True when something is already listening on `port` at 127.0.0.1.
+ *
+ * @param port - TCP port
+ */
+export function isPortInUse(port: number): Promise<boolean> {
+  return new Promise((resolvePromise) => {
+    const server = createServer();
+    server.once("error", (err: NodeJS.ErrnoException) => {
+      resolvePromise(err.code === "EADDRINUSE");
+    });
+    server.once("listening", () => {
+      server.close(() => resolvePromise(false));
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+/**
+ * Find the first free port at or above `preferred`, skipping occupied set.
+ *
+ * @param preferred - Starting port (e.g. 6530)
+ * @param occupied - Ports already claimed in this session
+ * @param probe - Injectable busy check (tests)
+ */
+export async function findFreePort(
+  preferred: number,
+  occupied: ReadonlySet<number> = new Set(),
+  probe: (port: number) => Promise<boolean> = isPortInUse,
+): Promise<number> {
+  if (!Number.isFinite(preferred) || preferred < 0) {
+    throw new Error(`oke: invalid preferred port ${preferred}`);
+  }
+  // Ephemeral (0) — leave to the OS; no probing.
+  if (preferred === 0) return 0;
+
+  for (let i = 0; i < MAX_PORT_ATTEMPTS; i++) {
+    const port = preferred + i;
+    if (occupied.has(port)) continue;
+    if (!(await probe(port))) return port;
+  }
+  throw new Error(
+    `oke: no free port near ${preferred} after ${MAX_PORT_ATTEMPTS} attempts`,
+  );
+}
+
+/**
+ * Resolve distinct free ports for app · Console · MCP (dev only).
+ *
+ * @param preferred - Preferred ports
+ * @param probe - Injectable busy check (tests)
+ */
+export async function resolveDevPorts(
+  preferred: {
+    readonly app: number;
+    readonly console: number;
+    readonly mcp: number;
+  },
+  probe: (port: number) => Promise<boolean> = isPortInUse,
+): Promise<{
+  readonly app: number;
+  readonly console: number;
+  readonly mcp: number;
+}> {
+  const occupied = new Set<number>();
+  const app = await findFreePort(preferred.app, occupied, probe);
+  if (app !== 0) occupied.add(app);
+  const consolePort = await findFreePort(preferred.console, occupied, probe);
+  if (consolePort !== 0) occupied.add(consolePort);
+  const mcp = await findFreePort(preferred.mcp, occupied, probe);
+  return { app, console: consolePort, mcp };
+}

package/src/cli/registry.help.test.ts

@@ -0,0 +1,18 @@
+/**
+ * Top-level help — no Flags/JSON comment footers.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { formatOkeHelp } from "./registry.ts";
+
+describe("formatOkeHelp", () => {
+  test("lists commands without Flags/JSON commentary", () => {
+    const help = formatOkeHelp();
+    expect(help).toContain("oke — okengine CLI");
+    expect(help).toContain("Commands:");
+    expect(help).toContain("dev");
+    expect(help).not.toContain("Flags:");
+    expect(help).not.toContain("JSON:");
+    expect(help).not.toContain("Exit codes:");
+  });
+});

package/src/cli/registry.ts

@@ -373,10 +373,6 @@ export function formatOkeHelp(): string {
     }
   }
   lines.push("");
-  lines.push("Flags: long form is canonical; short form is convenience only.");
-  lines.push("JSON:  doctor · stack · images list · gates list accept --json|-j");
-  lines.push("       (stdout = JSON only; hints/progress on stderr).");
-  lines.push("");
   return `${lines.join("\n")}\n`;
 }
 

package/src/cli/safe-defaults.test.ts

@@ -16,7 +16,7 @@ describe("oke safe-default overrides", () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-safe-docker-"));
     await Bun.write(
       join(dir, "oke.config.ts"),
-      `export default { images: { "store.sql": "postgres:16-alpine" } }\n`,
+      `export default { images: { "store.sql": "postgres:18-alpine" } }\n`,
     );
     // Without --prod, derive still runs but prod overlays are not requested.
     // We assert the parser default by calling runDockerDerive via dockerCli
@@ -25,7 +25,7 @@ describe("oke safe-default overrides", () => {
     const off = await runDockerDerive({
       cwd: dir,
       outDir: dir,
-      images: { "store.sql": "postgres:16-alpine" },
+      images: { "store.sql": "postgres:18-alpine" },
       dryRun: true,
       write: () => {},
     });
@@ -35,7 +35,7 @@ describe("oke safe-default overrides", () => {
     const on = await runDockerDerive({
       cwd: dir,
       outDir: dir,
-      images: { "store.sql": "postgres:16-alpine" },
+      images: { "store.sql": "postgres:18-alpine" },
       prod: true,
       dryRun: true,
       write: () => {},

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

package/src/config/resolve-driver.test.ts

@@ -0,0 +1,30 @@
+/**
+ * Driver map resolution — including `stack` → prod fallback.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { resolveDriverId } from "./index.ts";
+
+describe("resolveDriverId", () => {
+  test("reads the named env key", () => {
+    expect(
+      resolveDriverId({ dev: "sqlite", prod: "postgres" }, "dev"),
+    ).toBe("sqlite");
+    expect(
+      resolveDriverId({ dev: "sqlite", prod: "postgres" }, "prod"),
+    ).toBe("postgres");
+  });
+
+  test("stack prefers stack, then prod, then dev", () => {
+    expect(
+      resolveDriverId(
+        { dev: "sqlite", stack: "postgres", prod: "postgres" },
+        "stack",
+      ),
+    ).toBe("postgres");
+    expect(
+      resolveDriverId({ dev: "sqlite", prod: "postgres" }, "stack"),
+    ).toBe("postgres");
+    expect(resolveDriverId({ dev: "sqlite" }, "stack")).toBe("sqlite");
+  });
+});

package/src/console/server/app.ts

@@ -49,7 +49,8 @@ export function createConsoleApp(
   options: CreateConsoleAppOptions = {},
 ): ConsoleAppHandle {
   const state = createConsoleState(options);
-  if (!options.silentClaim) {
+  // Spec §2.5 — claim prints only while setup is open (no operators yet).
+  if (!options.silentClaim && !state.setupClosed) {
     printClaimCodeOnce(state.claim);
   }
 

package/src/console/server/flows.ts

@@ -1771,6 +1771,7 @@ function createSetupClaim(state: ConsoleState) {
         name: input.name,
         password: input.password,
       });
+      state.persistOperator(op.id);
       const issued = await issueOperatorSession(state, op.id);
       fx.log.info("console.setup.claim", { operatorId: op.id });
       return sessionPayload(op.id, op.email, op.name, issued);
@@ -2365,7 +2366,7 @@ async function issueOperatorSession(
 ): Promise<IssuedSession> {
   const op = state.operators.operators.get(operatorId);
   if (op) op.lastSeenAt = state.now();
-  return issueSession(
+  const issued = await issueSession(
     state.sessions,
     {
       secret: state.secret,
@@ -2378,6 +2379,8 @@ async function issueOperatorSession(
       scopes: ["console:*"],
     },
   );
+  state.persistSessions();
+  return issued;
 }
 
 function sessionPayload(

package/src/console/server/index.ts

@@ -71,6 +71,11 @@ export {
   type ClaimCodeState,
   type ClaimVerifyResult,
 } from "./claim.ts";
+export {
+  openConsolePersistence,
+  resolveConsoleSecret,
+  type ConsolePersistence,
+} from "./operator-db.ts";
 export {
   createConsoleBindings,
 } from "./flows.ts";