okengine 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "type": "module",

package/src/cli/dev.ts

@@ -31,6 +31,7 @@ import {
 import { clientAdd } from "./client-add.ts";
 import { loadManifest, loadOkeConfig, resolveImages } from "./load-config.ts";
 import { mcpContextFromConsole } from "./mcp-from-console.ts";
+import { resolveDevPorts } from "./ports.ts";
 
 /** Max wait for the `bun --hot` app child to bind a port. */
 const APP_READY_TIMEOUT_MS = 30_000;
@@ -183,9 +184,27 @@ export interface DevResult {
 export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   const write = options.write ?? ((t) => process.stdout.write(t));
   const cwd = options.cwd ?? process.cwd();
-  const appPort = options.appPort ?? Number(Bun.env.PORT ?? APP_PORT);
-  const consolePort = options.consolePort ?? CONSOLE_PORT;
-  const mcpPort = options.mcpPort ?? MCP_PORT;
+  const preferredApp = options.appPort ?? Number(Bun.env.PORT ?? APP_PORT);
+  const preferredConsole = options.consolePort ?? CONSOLE_PORT;
+  const preferredMcp = options.mcpPort ?? MCP_PORT;
+  // Explicit overrides (incl. `0` ephemeral) skip probing; otherwise +1 until free.
+  const ports =
+    options.appPort !== undefined ||
+    options.consolePort !== undefined ||
+    options.mcpPort !== undefined
+      ? {
+          app: preferredApp,
+          console: preferredConsole,
+          mcp: preferredMcp,
+        }
+      : await resolveDevPorts({
+          app: preferredApp,
+          console: preferredConsole,
+          mcp: preferredMcp,
+        });
+  const appPort = ports.app;
+  const consolePort = ports.console;
+  const mcpPort = ports.mcp;
   const keepAlive = options.keepAlive ?? true;
 
   let entry = options.entry;
@@ -297,6 +316,20 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
       ? options.manifest
       : await tryLoadProjectManifest(cwd);
 
+  async function refreshManifestInto(
+    state: ConsoleState | null,
+  ): Promise<void> {
+    if (!state) return;
+    try {
+      const { extractManifest } = await import("../compiler/extract.ts");
+      const { feedManifest } = await import("../console/server/live.ts");
+      const next = await extractManifest({ rootDir: cwd });
+      feedManifest(state, next);
+    } catch {
+      // Source may be mid-edit — keep the last good Manifest.
+    }
+  }
+
   const serveConsole =
     options.serveConsole ??
     (async (port) => {
@@ -402,6 +435,10 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     { recursive: true },
     () => {
       void regen(appUrl);
+      // Only live-extract when the host did not pin a Manifest (tests).
+      if (options.manifest === undefined) {
+        void refreshManifestInto(consoleState);
+      }
     },
   );
 
@@ -453,20 +490,45 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
 }
 
 /**
- * Load `oke.manifest.json` / `manifest.oke.json` when present.
+ * True when a Manifest has no declared flows (scaffold / empty extract).
+ *
+ * @param manifest - Candidate
+ */
+function isSparseManifest(manifest: Manifest): boolean {
+  const flows = manifest.flows;
+  if (!flows || typeof flows !== "object") return true;
+  return Object.keys(flows).length === 0;
+}
+
+/**
+ * Load Manifest — prefer AoT extract from `src/` when it has flows;
+ * otherwise on-disk JSON snapshots; otherwise a sparse extract.
  *
  * @param cwd - Project root
  */
 async function tryLoadProjectManifest(
   cwd: string,
 ): Promise<Manifest | null | undefined> {
+  let extracted: Manifest | undefined;
+  try {
+    const { extractManifest } = await import("../compiler/extract.ts");
+    extracted = await extractManifest({ rootDir: cwd });
+  } catch {
+    // Fall through to JSON snapshots.
+  }
+
+  let fromDisk: Manifest | undefined;
   for (const name of ["oke.manifest.json", "manifest.oke.json"]) {
     const path = resolve(cwd, name);
     if (await Bun.file(path).exists()) {
-      return loadManifest(path);
+      fromDisk = await loadManifest(path);
+      break;
     }
   }
-  return undefined;
+
+  if (extracted && !isSparseManifest(extracted)) return extracted;
+  if (fromDisk) return fromDisk;
+  return extracted;
 }
 
 /**

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/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,75 @@
+/**
+ * Default image pins derived from prod drivers.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  defaultImagesFromConfig,
+  resolveImages,
+} 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");
+  });
+});

package/src/cli/load-config.ts

@@ -3,9 +3,68 @@
  */
 
 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;
+}
+
+/**
+ * Derive default image pins from 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 = 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 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 +119,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 +129,8 @@ 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 {};
 }

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/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);

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

package/src/console/server/operator-db.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Durable Console operators under `.oke/console.sqlite`.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createOperator } from "../../auth/operator.ts";
+import { createConsoleApp } from "./app.ts";
+import {
+  openConsolePersistence,
+  resolveConsoleSecret,
+} from "./operator-db.ts";
+
+describe("console operator persistence", () => {
+  const dirs: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(
+      dirs.splice(0).map((d) => rm(d, { recursive: true, force: true })),
+    );
+  });
+
+  test("secret is stable across resolveConsoleSecret calls", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "oke-console-secret-"));
+    dirs.push(cwd);
+    const a = await resolveConsoleSecret(cwd);
+    const b = await resolveConsoleSecret(cwd);
+    expect(a).toBe(b);
+    expect(a.length).toBeGreaterThan(16);
+  });
+
+  test("claim persists and second boot skips claim print", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "oke-console-ops-"));
+    dirs.push(cwd);
+
+    const first = await openConsolePersistence(cwd);
+    expect(first.operators.operators.size).toBe(0);
+    const op = await createOperator(first.operators, {
+      email: "ops@example.com",
+      name: "Ops",
+      password: "password123",
+    });
+    first.persistOperator(op.id);
+    first.close();
+
+    const second = await openConsolePersistence(cwd);
+    expect(second.operators.operators.size).toBe(1);
+    expect(second.operators.operators.get(op.id)?.email).toBe(
+      "ops@example.com",
+    );
+    expect(second.operators.credentials.has(op.id)).toBe(true);
+
+    const printed: string[] = [];
+    const origLog = console.log;
+    console.log = (line?: unknown) => {
+      printed.push(String(line ?? ""));
+    };
+    try {
+      const app = createConsoleApp({
+        cwd,
+        secret: second.secret,
+        operators: second.operators,
+        persistOperator: second.persistOperator,
+        silentClaim: false,
+      });
+      expect(app.state.setupClosed).toBe(true);
+      expect(printed.join("\n")).not.toContain("Claim code");
+    } finally {
+      console.log = origLog;
+      second.close();
+    }
+  });
+});