okengine 0.2.1 → 0.2.3

package/README.md

@@ -8,7 +8,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Bun >=1.3](https://img.shields.io/badge/Bun-%3E%3D1.3-black.svg)](https://bun.sh)
 
-**Framework:** [`okengine`](https://www.npmjs.com/package/okengine) · **CLI:** `oke` · **Scaffold:** [`create-oke`](https://www.npmjs.com/package/create-oke) · **Docs:** [oke.dev](https://oke.dev) · **License:** MIT
+**Framework:** [`okengine`](https://www.npmjs.com/package/okengine) · **CLI:** `oke` · **Scaffold:** [`create-oke`](https://www.npmjs.com/package/create-oke) · **Docs:** [okengine.vercel.app](https://okengine.vercel.app) · **License:** MIT
 
 ### Install
 
@@ -35,7 +35,7 @@ Eight elements cover what a backend needs. Ten exports are the whole public voca
 import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
 ```
 
-Batteries included for the Bun era: contract-first APIs, typed client, infrastructure primitives, Console, auth — pure TypeScript, MIT, self-hostable, no cloud lock-in. Handbook: [oke.dev/docs](https://oke.dev/docs). Spec depth: [`docs/spec/unified-theory.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/unified-theory.md).
+Batteries included for the Bun era: contract-first APIs, typed client, infrastructure primitives, Console, auth — pure TypeScript, MIT, self-hostable, no cloud lock-in. Handbook: [handbook](https://okengine.vercel.app/docs). Spec depth: [`docs/spec/unified-theory.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/unified-theory.md).
 
 ---
 
@@ -131,7 +131,7 @@ The rest of the scaffold is small and ordinary: `oke.config.ts` (drivers by prot
 
 ## How to learn (read in order)
 
-Start on the site if you want the handbook path: [Introduction](https://oke.dev/docs/get-started/introduction) → [Installation](https://oke.dev/docs/get-started/installation) → [Basic usage](https://oke.dev/docs/get-started/basic-usage).
+Start on the site if you want the handbook path: [Introduction](https://okengine.vercel.app/docs/get-started/introduction) → [Installation](https://okengine.vercel.app/docs/get-started/installation) → [Basic usage](https://okengine.vercel.app/docs/get-started/basic-usage).
 
 Each teaching app adds the smallest next set of ideas. Do not skip ahead.
 
@@ -153,8 +153,8 @@ Same path in the spec: [`docs/spec/four-applications.md`](docs/spec/four-applica
 
 ## Documentation
 
-- **Site** — [oke.dev](https://oke.dev) (landing) · [oke.dev/docs](https://oke.dev/docs) (handbook) · [changelog](https://oke.dev/changelog)
-- **Agents on the site** — [`/llms.txt`](https://oke.dev/llms.txt) index · [`/llms-full.txt`](https://oke.dev/llms-full.txt) full text · `/llms.mdx/docs/...` per-page markdown
+- **Site** — [okengine.vercel.app](https://okengine.vercel.app) (landing) · [handbook](https://okengine.vercel.app/docs) (handbook) · [changelog](https://okengine.vercel.app/changelog)
+- **Agents on the site** — [`/llms.txt`](https://okengine.vercel.app/llms.txt) index · [`/llms-full.txt`](https://okengine.vercel.app/llms-full.txt) full text · `/llms.mdx/docs/...` per-page markdown
 - **Docs MCP** — `:6536` · tools `oke.docs.search` / `oke.docs.get` (read-only; Host/Origin validated like the other surfaces)
 - **App MCP** — `:6535` · live Manifest, schemas, effects, traces, Console-safe actions (Bearer + confirmation for writes)
 - **Canonical specs in-repo** — [`docs/spec/`](docs/spec) (unified theory, four applications, Console)
@@ -204,7 +204,7 @@ flowchart TD
 
 Seventeen panels on `:6533` (app `:6530`, MCP `:6535`): Overview, Flows, Signals, Store, Clock, Gates, Vault, Channels, AI, Architecture, Traces, Runs, Manifest Diff, Access, Plugins — plus Privacy and Tenancy when those plugins are plugged.
 
-Operator and user planes stay separate. Every Console action is a real flow through `fx`, so the audit log is the trace. Spec: [`docs/spec/console.md`](docs/spec/console.md) · handbook: [oke.dev/docs/console](https://oke.dev/docs/console/overview).
+Operator and user planes stay separate. Every Console action is a real flow through `fx`, so the audit log is the trace. Spec: [`docs/spec/console.md`](docs/spec/console.md) · handbook: [console handbook](https://okengine.vercel.app/docs/console/overview).
 
 ---
 
@@ -348,11 +348,11 @@ Measured size and latency caps — see [`BUDGETS.md`](BUDGETS.md). Refresh with
 
 ## Status
 
-Pre-1.0. Published on [npm](https://www.npmjs.com/package/okengine) and [JSR](https://jsr.io/@omqkhafi/okengine) (`okengine` + `create-oke`, lockstep). Docs at [oke.dev](https://oke.dev). MIT. No `CONTRIBUTING` yet — issues and PRs welcome.
+Pre-1.0. Published on [npm](https://www.npmjs.com/package/okengine) and [JSR](https://jsr.io/@omqkhafi/okengine) (`okengine` + `create-oke`, lockstep). Docs at [okengine.vercel.app](https://okengine.vercel.app). MIT. No `CONTRIBUTING` yet — issues and PRs welcome.
 
 | Resource | Path |
 |---|---|
-| Docs site | [oke.dev](https://oke.dev) · [handbook](https://oke.dev/docs) · [changelog](https://oke.dev/changelog) |
+| Docs site | [okengine.vercel.app](https://okengine.vercel.app) · [handbook](https://okengine.vercel.app/docs) · [changelog](https://okengine.vercel.app/changelog) |
 | Unified theory | [`docs/spec/unified-theory.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/unified-theory.md) |
 | Four applications | [`docs/spec/four-applications.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/four-applications.md) |
 | Console | [`docs/spec/console.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/console.md) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.2.1",
+  "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",
@@ -35,6 +35,7 @@
     "test:mcp": "bun test src/mcp",
     "test:console:smoke": "bunx playwright test tests/console/smoke.spec.ts",
     "build:console": "bunx vite build --config src/console/ui/vite.config.ts",
+    "prepack": "bun run build:console",
     "bench:cold-start": "bun test ./src/runtime/cold-start.bench.ts",
     "bench:client": "bun test src/client/budget.test.ts",
     "bench:console": "bun test src/console/budget.test.ts",

package/src/cli/dev-app-runner.ts

@@ -17,6 +17,7 @@ import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createBunRuntime } from "../runtime/bun.ts";
 import { APP_PORT, type FetchApp } from "../runtime/types.ts";
+import { formatAppReadyLine } from "../term.ts";
 
 /** Stable Bun.serve id so `--hot` reuses the socket across soft reloads. */
 export const DEV_APP_SERVE_ID = "oke-dev-app";
@@ -59,8 +60,11 @@ const handle = createBunRuntime().serve(mod.app, {
   id: DEV_APP_SERVE_ID,
 });
 
-const line = `oke app http://${formatHostForUrl(hostname)}:${handle.port}\n`;
-process.stdout.write(line);
+process.stdout.write(
+  formatAppReadyLine(
+    `http://${formatHostForUrl(hostname)}:${handle.port}`,
+  ),
+);
 
 if (readyPath !== undefined && readyPath.length > 0) {
   await Bun.write(readyPath, `${handle.port}\n`);

package/src/cli/dev.ts

@@ -23,9 +23,15 @@ import {
   CONSOLE_PORT,
   MCP_PORT,
 } from "../runtime/types.ts";
+import {
+  formatDevBanner,
+  formatServiceLine,
+  formatStatusLine,
+} from "../term.ts";
 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;
@@ -178,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;
@@ -258,7 +282,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
           }
         });
       await up(composeFiles, cwd);
-      write(`oke dev: stack up (${stackRoles.join(", ")})\n`);
+      write(formatStatusLine(`stack up (${stackRoles.join(", ")})`));
     }
   }
 
@@ -272,10 +296,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     stackEnv,
   };
 
-  write(
-    `oke dev: app :${appPort} · Console :${consolePort} · MCP :${mcpPort}\n`,
-  );
-  write("oke dev: watching — client types regenerate on save\n");
+  write(formatDevBanner());
 
   if (options.dryRun) return { code: 0, plan };
 
@@ -295,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) => {
@@ -312,7 +347,12 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
           ? { manifest: seedManifest }
           : {}),
       });
-      write(`oke Console http://127.0.0.1:${server.port}\n`);
+      write(
+        formatServiceLine(
+          "Console",
+          `http://127.0.0.1:${server.port}`,
+        ),
+      );
       return {
         console: server.console,
         port: server.port,
@@ -334,7 +374,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
         context: mcpOptions.context,
         now: mcpOptions.now,
       });
-      write(`oke MCP http://127.0.0.1:${server.port}\n`);
+      write(formatServiceLine("MCP", `http://127.0.0.1:${server.port}`));
       return {
         port: server.port,
         url: server.url,
@@ -352,7 +392,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
           url: appUrl,
           out: resolve(cwd, "oke-client.d.ts"),
         });
-        write("oke dev: regenerated oke-client.d.ts\n");
+        write(formatStatusLine("regenerated oke-client.d.ts"));
       } catch {
         // App may not be ready yet — ignore until next save.
       }
@@ -395,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);
+      }
     },
   );
 
@@ -446,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;
 }
 
 /**
@@ -515,7 +584,7 @@ async function startAppHot(
       proc,
       APP_READY_TIMEOUT_MS,
     );
-    // Child prints `oke app http://…` (again on each soft reload).
+    // Child prints the App ready line (again on each soft reload).
     const url = new URL(`http://${hostname}:${boundPort}/`);
     return { stop, port: boundPort, url };
   } catch (err) {

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