okengine 0.2.2 → 0.2.4

package/src/cli/docker-cli.test.ts

@@ -27,25 +27,25 @@ const credentials = {
 } as const;
 
 describe("oke docker CLI", () => {
-  test("writes Dockerfile and compose without credentials in YAML", async () => {
+  test("writes Dockerfile and compose under docker/ by default", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-cli-docker-"));
     const logs: string[] = [];
     const { code, result } = await runDockerDerive({
       cwd: dir,
-      outDir: dir,
       images,
       credentials,
       write: (t) => logs.push(t),
     });
     expect(code).toBe(0);
     expect(result).toBeDefined();
-    expect(await Bun.file(join(dir, "Dockerfile")).exists()).toBe(true);
-    expect(await Bun.file(join(dir, "compose.store.sql.yml")).exists()).toBe(
-      true,
-    );
-    const yml = await Bun.file(join(dir, "compose.store.sql.yml")).text();
+    expect(await Bun.file(join(dir, "docker/Dockerfile")).exists()).toBe(true);
+    expect(
+      await Bun.file(join(dir, "docker/compose.store.sql.yml")).exists(),
+    ).toBe(true);
+    const yml = await Bun.file(join(dir, "docker/compose.store.sql.yml")).text();
     expect(yml).not.toContain("test-password-not-in-yaml");
-    expect(logs.join("")).toContain("compose.override.yml");
+    expect(yml).toContain("../.env.stack");
+    expect(logs.join("")).toContain("docker/compose.override.yml");
   });
 });
 
@@ -164,8 +164,10 @@ describe("oke dev --stack", () => {
     expect(code).toBe(0);
     expect(plan?.stackRoles).toEqual(["store.sql"]);
     expect(plan?.composeFiles?.some((f) => f.includes("store.sql"))).toBe(true);
+    expect(plan?.composeFiles).toContain("compose.yml");
     expect(plan?.stackEnv?.DATABASE_URL).toContain("postgres://");
     expect(await Bun.file(join(dir, "compose.yml")).exists()).toBe(false);
+    expect(await Bun.file(join(dir, "docker/compose.yml")).exists()).toBe(false);
   });
 });
 

package/src/cli/docker.ts

@@ -4,6 +4,7 @@
 
 import { resolve } from "node:path";
 import {
+  DEFAULT_DOCKER_DIR,
   deriveInfrastructure,
   writeDerivedFiles,
   type DeriveOptions,
@@ -38,7 +39,15 @@ export async function runDockerDerive(
 ): Promise<{ readonly code: number; readonly result?: DeriveResult }> {
   const write = options.write ?? ((t) => process.stdout.write(t));
   const cwd = options.cwd ?? process.cwd();
-  const outDir = resolve(cwd, options.outDir ?? ".");
+  const composeDirOpt = options.outDir ?? DEFAULT_DOCKER_DIR;
+  const outDir = resolve(cwd, composeDirOpt);
+  // Relative dir for env_file / build.context rewriting (`.` when out === cwd).
+  const composeDir =
+    outDir === cwd
+      ? "."
+      : outDir.startsWith(`${cwd}/`) || outDir.startsWith(`${cwd}\\`)
+        ? outDir.slice(cwd.length + 1)
+        : ".";
 
   let images = options.images;
   let app = "app";
@@ -70,6 +79,8 @@ export async function runDockerDerive(
       app,
       prod: options.prod ?? false,
       outDir,
+      composeDir,
+      includeApp: true,
       ...(options.credentials ? { credentials: options.credentials } : {}),
     });
 
@@ -77,13 +88,13 @@ export async function runDockerDerive(
       await writeDerivedFiles(result, outDir, { writeStackEnv: false });
     }
 
-    write(`oke docker: wrote ${result.files.length} file(s)\n`);
-    for (const f of result.files) write(`  ${f.path}\n`);
+    write(`oke docker: wrote ${result.files.length} file(s) → ${composeDir}/\n`);
+    for (const f of result.files) write(`  ${composeDir}/${f.path}\n`);
     write(
-      `compose merge order:\n${result.composeFiles.map((f) => `  -f ${f}`).join("\n")}\n`,
+      `compose merge order (cwd ${composeDir}/):\n${result.composeFiles.map((f) => `  -f ${f}`).join("\n")}\n`,
     );
     write(
-      "(compose.override.yml is layer 4 — user-owned, never written by oke)\n",
+      `(${composeDir}/compose.override.yml is layer 4 — user-owned, never written by oke)\n`,
     );
     return { code: 0, result };
   } catch (err) {
@@ -109,9 +120,9 @@ export async function dockerCli(args: readonly string[]): Promise<number> {
     else if (a === "--config" || a === "-c") configPath = args[++i];
     else if (a === "--manifest" || a === "-m") manifestPath = args[++i];
     else if (a === "--help" || a === "-h") {
-      console.log(`oke docker [--prod|-p] [--out|-o .] [--config|-c oke.config.ts]
+      console.log(`oke docker [--prod|-p] [--out|-o docker] [--config|-c oke.config.ts]
 
-Derive Dockerfile + compose.<role>.yml files.
+Derive Dockerfile + compose.<role>.yml under docker/ (default).
 --prod is opt-in (never the default). Credentials are never written into YAML.
 `);
       return 0;

package/src/cli/doctor.ts

@@ -2,7 +2,6 @@
  * `oke doctor` — verify secrets, ports, drivers, tenancy, schema drift.
  */
 
-import { createServer } from "node:net";
 import { resolve } from "node:path";
 import type { Manifest } from "../manifest/types.ts";
 import { APP_PORT, CONSOLE_PORT, MCP_PORT } from "../runtime/types.ts";
@@ -10,8 +9,11 @@ import { hasFlag, wantsJson } from "./args.ts";
 import { checkManifestPiiAsks } from "./doctor-pii.ts";
 import { EXIT_OK, EXIT_RUNTIME } from "./exit.ts";
 import { loadManifest } from "./load-config.ts";
+import { isPortInUse } from "./ports.ts";
 import { schemaFingerprint, readSchemaFingerprint } from "./schema.ts";
 
+export { isPortInUse } from "./ports.ts";
+
 /** One doctor finding. */
 export interface DoctorFinding {
   readonly code:
@@ -204,20 +206,3 @@ Verify secrets, ports, schema drift, and PII→model egress before serving.
   return code;
 }
 
-/**
- * True when something is already listening on `port`.
- *
- * @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");
-  });
-}

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/index.ts

@@ -90,7 +90,10 @@ if (cmd === "completion") {
 }
 
 if (cmd === undefined || cmd === "--help" || cmd === "-h" || cmd === "help") {
-  console.log(`${formatOkeHelp()}${EXIT_CODE_HELP}`);
+  // Bare `oke` — commands only. Exit-code table only on explicit --help.
+  const help =
+    cmd === undefined ? formatOkeHelp() : `${formatOkeHelp()}${EXIT_CODE_HELP}`;
+  console.log(help);
   process.exit(cmd ? EXIT_OK : EXIT_USAGE);
 }
 

package/src/cli/json-out.test.ts

@@ -42,7 +42,7 @@ describe("oke --json stdout discipline", () => {
   test("stack --json is valid JSON only on stdout", async () => {
     let out = "";
     const code = await runStackPreview({
-      images: { "store.sql": "postgres:16-alpine" },
+      images: { "store.sql": "postgres:18-alpine" },
       json: true,
       write: (t) => {
         out += t;

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

@@ -0,0 +1,126 @@
+/**
+ * Default image pins derived from prod drivers.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  defaultImagesFromConfig,
+  resolveImages,
+  stackDevDriverMismatches,
+} from "./load-config.ts";
+
+describe("defaultImagesFromConfig", () => {
+  test("maps postgres + redis prod drivers", () => {
+    const images = defaultImagesFromConfig({
+      drivers: {
+        store: {
+          sql: { prod: "postgres" },
+          kv: { prod: "redis" },
+        },
+      },
+    });
+    expect(images).toEqual({
+      "store.sql": "postgres:18-alpine",
+      "store.kv": "redis:8-alpine",
+    });
+  });
+
+  test("prefers pgvector image when index uses pgvector", () => {
+    const images = defaultImagesFromConfig({
+      drivers: {
+        store: {
+          sql: { prod: "postgres" },
+          index: { prod: "pgvector" },
+        },
+      },
+    });
+    expect(images["store.sql"]).toBe("pgvector/pgvector:pg17");
+  });
+
+  test("returns empty when no container drivers", () => {
+    expect(defaultImagesFromConfig({})).toEqual({});
+    expect(
+      defaultImagesFromConfig({
+        drivers: { store: { sql: { prod: "sqlite" } } },
+      }),
+    ).toEqual({});
+  });
+});
+
+describe("resolveImages", () => {
+  test("explicit images win over defaults", () => {
+    const images = resolveImages({
+      drivers: {
+        store: {
+          sql: { prod: "postgres" },
+          kv: { prod: "redis" },
+        },
+      },
+      images: { "store.sql": "pgvector/pgvector:pg17" },
+    });
+    expect(images).toEqual({ "store.sql": "pgvector/pgvector:pg17" });
+  });
+
+  test("falls back to driver defaults when images omitted", () => {
+    const images = resolveImages({
+      drivers: {
+        store: {
+          sql: { prod: "postgres" },
+          kv: { prod: "redis" },
+        },
+      },
+    });
+    expect(images["store.sql"]).toBe("postgres:18-alpine");
+    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([]);
+  });
+});