okengine 0.2.8 → 0.3.2

package/src/cli/mode.ts

@@ -1,8 +1,11 @@
 /**
  * `oke mode [local|docker]` — read or set the saved `oke dev` preference.
+ * Setting a mode also syncs domain schema for that env (emit + push).
  */
 
 import { parseDevMode, readDevMode, writeDevMode, type DevMode } from "./dev-mode.ts";
+import { sqlDialectForEnv, syncDevSchema } from "./dev-schema-sync.ts";
+import { loadOkeConfig } from "./load-config.ts";
 
 /**
  * CLI entry for `oke mode`.
@@ -16,8 +19,11 @@ export async function modeCli(args: readonly string[]): Promise<number> {
       console.log(`oke mode [local|docker]
 
 Get or set the default infrastructure mode for \`oke dev\`
-(saved in .oke/mode). Session flags \`oke dev --local\` /
-\`oke dev --docker\` never change this preference.
+(saved in .oke/mode). Setting a mode syncs domain schema for that env:
+emits schema.generated.ts for the active dialect, then runs \`oke db push\`.
+Data planes stay isolated — switching modes never copies rows.
+Session flags \`oke dev --local\` / \`oke dev --docker\` never change this
+preference.
 `);
       return 0;
     }
@@ -40,6 +46,20 @@ Get or set the default infrastructure mode for \`oke dev\`
     return 1;
   }
   await writeDevMode(cwd, next satisfies DevMode);
-  console.log(`oke mode: saved ${next}`);
-  return 0;
+
+  try {
+    const result = await syncDevSchema(cwd, next);
+    console.log(`oke mode: saved ${next} · dialect ${result.dialect}`);
+    return result.code;
+  } catch (err) {
+    const loaded = await loadOkeConfig(cwd).catch(() => null);
+    const dialect = loaded?.config
+      ? sqlDialectForEnv(loaded.config, next).dialect
+      : next === "docker"
+        ? "postgresql"
+        : "sqlite";
+    console.error(`oke mode: saved ${next} · dialect ${dialect}`);
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
 }

package/src/cli/openbao-bootstrap.test.ts

@@ -0,0 +1,147 @@
+/**
+ * OpenBao bootstrap — material durability gates (`.oke/` ignore + real
+ * `0600`, init-then-write-fail must not report success, initialized-without-
+ * key fails loud).
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  assertMode,
+  ensureOpenBao,
+  OpenBaoBootstrapError,
+  OPENBAO_STATE_DIR_REL,
+} from "./openbao-bootstrap.ts";
+
+let dirs: string[] = [];
+
+async function tempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "oke-openbao-boot-"));
+  dirs.push(dir);
+  return dir;
+}
+
+afterEach(async () => {
+  for (const dir of dirs) await rm(dir, { recursive: true, force: true });
+  dirs = [];
+});
+
+/** Scripted fake OpenBao (seal-status → init → unseal → policy → token). */
+function fakeOpenBao(calls: { url: string; method: string; body?: string }[]) {
+  const routes: Record<string, () => Response> = {
+    "GET /v1/sys/seal-status": () =>
+      Response.json({ sealed: false, initialized: false, t: 1, n: 1, progress: 0 }),
+    "POST /v1/sys/init": () =>
+      Response.json({ keys: ["unseal-key-1"], keys_base64: ["dW5zZWFs"], root_token: "root-tok" }),
+    "POST /v1/sys/unseal": () => Response.json({ sealed: false, t: 1, n: 1, progress: 0 }),
+    "POST /v1/sys/mounts/secret": () => Response.json({}),
+    "POST /v1/sys/policy/oke-app": () => new Response(null, { status: 204 }),
+    "POST /v1/auth/token/create": () =>
+      Response.json({ auth: { client_token: "app-tok", policies: ["oke-app"] } }),
+  };
+  const fetchFn = (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = String(input);
+    const method = init?.method ?? "GET";
+    calls.push({ url, method, body: typeof init?.body === "string" ? init.body : undefined });
+    const path = new URL(url).pathname;
+    const handler = routes[`${method} ${path}`];
+    if (!handler) return new Response("not found", { status: 404 });
+    return handler();
+  }) as typeof globalThis.fetch;
+  return fetchFn;
+}
+
+describe("openbao bootstrap material gates", () => {
+  test("`.oke/` is gitignored (check-ignore, not inference)", () => {
+    const root = join(import.meta.dir, "../..");
+    for (const p of [
+      `${OPENBAO_STATE_DIR_REL}/unseal.key`,
+      `${OPENBAO_STATE_DIR_REL}/root.token`,
+    ]) {
+      const proc = Bun.spawnSync(["git", "check-ignore", "-v", p], {
+        cwd: root,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      expect(proc.exitCode).toBe(0);
+      expect(proc.stdout.toString()).toContain(".gitignore");
+    }
+  });
+
+  test("init writes 0600 files + 0700 dir (real mode) before success", async () => {
+    const cwd = await tempDir();
+    const calls: { url: string; method: string; body?: string }[] = [];
+    const result = await ensureOpenBao({
+      cwd,
+      url: "http://127.0.0.1:8200",
+      names: ["STRIPE_KEY", "DATABASE_URL"],
+      fetch: fakeOpenBao(calls),
+    });
+    expect(result.initializedNow).toBe(true);
+    expect(result.appToken).toBe("app-tok");
+
+    const stateDir = join(cwd, OPENBAO_STATE_DIR_REL);
+    expect(statSync(stateDir).mode & 0o777).toBe(0o700);
+    expect(statSync(join(stateDir, "unseal.key")).mode & 0o777).toBe(0o600);
+    expect(statSync(join(stateDir, "root.token")).mode & 0o777).toBe(0o600);
+    expect(statSync(join(stateDir, "app.token")).mode & 0o777).toBe(0o600);
+    assertMode(join(stateDir, "unseal.key"), 0o600);
+
+    // Policy is scoped to the two declared paths only.
+    const policyCall = calls.find((c) => c.url.endsWith("/v1/sys/policy/oke-app"));
+    expect(policyCall?.body).toContain("secret/data/STRIPE_KEY");
+    expect(policyCall?.body).toContain("secret/data/DATABASE_URL");
+    expect(policyCall?.body).not.toContain("secret/data/*");
+  });
+
+  test("post-init material write failure does NOT report success", async () => {
+    const cwd = await tempDir();
+    // Block the state dir with a *file* so mkdir/write fails after init.
+    const blocker = join(cwd, ".oke");
+    await Bun.write(blocker, "not-a-dir");
+
+    const calls: { url: string; method: string; body?: string }[] = [];
+    let failed: unknown;
+    try {
+      await ensureOpenBao({
+        cwd,
+        url: "http://127.0.0.1:8200",
+        names: ["STRIPE_KEY"],
+        fetch: fakeOpenBao(calls),
+      });
+    } catch (err) {
+      failed = err;
+    }
+    expect(failed).toBeDefined();
+    // init happened (vault now initialized server-side) but we never returned
+    // success without durable material.
+    expect(calls.some((c) => c.url.endsWith("/v1/sys/init"))).toBe(true);
+    expect(calls.some((c) => c.url.endsWith("/v1/auth/token/create"))).toBe(false);
+  });
+
+  test("initialized but host unseal.key missing → loud permanent-loss error", async () => {
+    const cwd = await tempDir();
+    const calls: { url: string; method: string; body?: string }[] = [];
+    const fetchFn = fakeOpenBao(calls);
+    // Seal-status says initialized (data exists) but the host has no material.
+    const initialized = (async (input: string | URL | Request, init?: RequestInit) => {
+      const url = String(input);
+      if (url.endsWith("/v1/sys/seal-status")) {
+        return Response.json({ sealed: true, initialized: true });
+      }
+      return fetchFn(input as string, init);
+    }) as typeof globalThis.fetch;
+
+    let failed: unknown;
+    try {
+      await ensureOpenBao({ cwd, url: "http://127.0.0.1:8200", fetch: initialized });
+    } catch (err) {
+      failed = err;
+    }
+    expect(failed).toBeInstanceOf(OpenBaoBootstrapError);
+    expect(String(failed)).toContain("unrecoverable");
+  });
+});

package/src/cli/openbao-bootstrap.ts

@@ -0,0 +1,280 @@
+/**
+ * OpenBao first-boot bootstrap — real init/unseal for the docker / prod vault.
+ *
+ * Durability contract (see the plan's three verification gates):
+ *
+ * 1. Host material lives under `.oke/openbao/` — `.gitignore` covers it,
+ *    directory mode `0700`, files `0600`, asserted after every write.
+ * 2. `POST /v1/sys/init` is NOT transactional with the host filesystem. We
+ *    write material atomically (temp → fsync → rename → chmod → verify) and
+ *    only then treat init as successful. When OpenBao is initialized but host
+ *    material is missing/corrupt, boot fails loud (permanent-loss message) —
+ *    never re-init, never soft-empty.
+ * 3. The root token never lands in `docker/.env.docker`; only the minted
+ *    least-privilege app token (`OKE_VAULT_TOKEN`) does.
+ */
+
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { openSync, fsyncSync, closeSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/** Material directory relative to the project root. */
+export const OPENBAO_STATE_DIR_REL = join(".oke", "openbao");
+/** OpenBao KV mount used by OKE apps. */
+export const OPENBAO_MOUNT = "secret";
+
+/** Fetch contract (injectable for tests). */
+export type OpenBaoFetch = typeof globalThis.fetch;
+
+/** Options for {@link ensureOpenBao}. */
+export interface OpenBaoBootstrapOptions {
+  readonly cwd?: string;
+  /** Base URL, e.g. `http://127.0.0.1:22042`. */
+  readonly url: string;
+  /** Declared vault contract names (least-privilege policy scope). */
+  readonly names?: readonly string[];
+  readonly fetch?: OpenBaoFetch;
+  /** Override state dir (tests). */
+  readonly stateDir?: string;
+}
+
+/** Result of a successful bootstrap. */
+export interface OpenBaoBootstrapResult {
+  readonly url: string;
+  /** App token bound to the `oke-app` policy (never root). */
+  readonly appToken: string;
+  /** Absolute path to the state dir that holds root token + unseal key. */
+  readonly stateDir: string;
+  /** Whether this run performed first-time init. */
+  readonly initializedNow: boolean;
+}
+
+/** Fail-loud bootstrap error (sealed with no key / unreachable / permanent loss). */
+export class OpenBaoBootstrapError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "OpenBaoBootstrapError";
+  }
+}
+
+interface SysSealStatus {
+  readonly sealed: boolean;
+  readonly initialized?: boolean;
+}
+
+/**
+ * Assert real filesystem modes (`0600` file / `0700` dir) — not a comment.
+ *
+ * @param path - File or directory
+ * @param expected - Expected `mode & 0o777`
+ */
+export function assertMode(path: string, expected: number): void {
+  const mode = statSync(path).mode & 0o777;
+  if (mode !== expected) {
+    throw new OpenBaoBootstrapError(
+      `openbao bootstrap: ${path} mode ${mode.toString(8)} — expected ${expected.toString(8)}`,
+    );
+  }
+}
+
+/**
+ * Atomically write `0600` material: temp → fsync → rename → chmod → re-read.
+ *
+ * @param path - Destination
+ * @param value - Contents
+ */
+function writeMaterial(path: string, value: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  chmodSync(dirname(path), 0o700);
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${value}\n`, { mode: 0o600 });
+  const fd = openSync(tmp, "r");
+  try {
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, path);
+  chmodSync(path, 0o600);
+  assertMode(path, 0o600);
+  const back = readFileSync(path, "utf8").trim();
+  if (back !== value) {
+    throw new OpenBaoBootstrapError(`openbao bootstrap: verify failed reading ${path}`);
+  }
+}
+
+async function api<T>(fetchFn: OpenBaoFetch, url: string, init?: RequestInit): Promise<T> {
+  const res = await fetchFn(url, init);
+  if (!res.ok) {
+    throw new OpenBaoBootstrapError(
+      `openbao bootstrap: ${init?.method ?? "GET"} ${url} → ${res.status}`,
+    );
+  }
+  const text = await res.text();
+  return (text ? JSON.parse(text) : {}) as T;
+}
+
+/**
+ * Ensure OpenBao is initialized + unsealed, mint/reuse the app token.
+ *
+ * Fails loud when: server unreachable · initialized but host unseal key
+ * missing/corrupt · still sealed after unseal. Never re-inits an existing
+ * backend; never writes root material into the compose env.
+ *
+ * @param options - URL / cwd / declared names
+ */
+export async function ensureOpenBao(
+  options: OpenBaoBootstrapOptions,
+): Promise<OpenBaoBootstrapResult> {
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const url = options.url.replace(/\/$/, "");
+  const stateDir = resolve(options.cwd ?? process.cwd(), options.stateDir ?? OPENBAO_STATE_DIR_REL);
+  const unsealPath = join(stateDir, "unseal.key");
+  const rootPath = join(stateDir, "root.token");
+  const appPath = join(stateDir, "app.token");
+
+  const initHeaders = { "content-type": "application/json" };
+
+  let status: SysSealStatus | undefined;
+  const deadline = Date.now() + 30_000;
+  let lastErr: unknown;
+  while (Date.now() < deadline) {
+    try {
+      status = await api<SysSealStatus>(fetchFn, `${url}/v1/sys/seal-status`);
+      break;
+    } catch (err) {
+      if (err instanceof OpenBaoBootstrapError) throw err;
+      lastErr = err;
+      await Bun.sleep(250);
+    }
+  }
+  if (!status) {
+    throw new OpenBaoBootstrapError(
+      `openbao bootstrap: unreachable at ${url} — ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`,
+    );
+  }
+
+  let initializedNow = false;
+  let rootToken: string;
+  let unsealKey: string;
+
+  if (!status.initialized) {
+    // First boot — init 1-of-1, then make material durable BEFORE success.
+    const init = await api<{ keys: string[]; root_token: string }>(fetchFn, `${url}/v1/sys/init`, {
+      method: "POST",
+      headers: initHeaders,
+      body: JSON.stringify({ secret_shares: 1, secret_threshold: 1 }),
+    });
+    unsealKey = init.keys[0] ?? "";
+    rootToken = init.root_token;
+    if (!unsealKey || !rootToken) {
+      throw new OpenBaoBootstrapError(
+        "openbao bootstrap: init returned no unseal key / root token",
+      );
+    }
+    // If this write throws, we fail loud while keys are still in memory.
+    mkdirSync(stateDir, { recursive: true });
+    chmodSync(stateDir, 0o700);
+    writeMaterial(unsealPath, unsealKey);
+    writeMaterial(rootPath, rootToken);
+    initializedNow = true;
+  } else {
+    // Initialized — material MUST exist on the host (no re-init, no silent).
+    if (!existsSync(unsealPath) || !existsSync(rootPath)) {
+      throw new OpenBaoBootstrapError(
+        `openbao bootstrap: OpenBao is initialized but ${stateDir} is missing ` +
+          `unseal.key/root.token. Without the unseal key the data is unrecoverable. ` +
+          `Restore your backup of .oke/openbao/ — permanent loss otherwise.`,
+      );
+    }
+    unsealKey = readFileSync(unsealPath, "utf8").trim();
+    rootToken = readFileSync(rootPath, "utf8").trim();
+    if (!unsealKey || !rootToken) {
+      throw new OpenBaoBootstrapError(
+        `openbao bootstrap: ${stateDir} material is empty/corrupt — restore your backup.`,
+      );
+    }
+  }
+
+  // Unseal whenever sealed (every restart).
+  let seal = await api<SysSealStatus>(fetchFn, `${url}/v1/sys/seal-status`);
+  if (seal.sealed) {
+    await api(fetchFn, `${url}/v1/sys/unseal`, {
+      method: "POST",
+      headers: initHeaders,
+      body: JSON.stringify({ key: unsealKey }),
+    });
+    seal = await api<SysSealStatus>(fetchFn, `${url}/v1/sys/seal-status`);
+    if (seal.sealed) {
+      throw new OpenBaoBootstrapError("openbao bootstrap: still sealed after unseal");
+    }
+  }
+
+  const rootHeaders = { "X-Vault-Token": rootToken, "content-type": "application/json" };
+
+  // Enable KV v2 at `secret/` once (mount exists after our first init).
+  if (initializedNow) {
+    try {
+      await api(fetchFn, `${url}/v1/sys/mounts/${OPENBAO_MOUNT}`, {
+        method: "POST",
+        headers: rootHeaders,
+        body: JSON.stringify({ type: "kv", options: { version: "2" } }),
+      });
+    } catch {
+      // Mount may already exist (e.g. re-race); policy sync below still runs.
+    }
+  }
+
+  // Least-privilege policy scoped to the app's declared secret paths.
+  const names = [...new Set(options.names ?? [])].filter((n) => /^[\w.-]+$/.test(n));
+  const policy = names
+    .flatMap((n) => [
+      `path "${OPENBAO_MOUNT}/data/${n}" {\n  capabilities = ["create", "update", "read", "delete"]\n}`,
+      `path "${OPENBAO_MOUNT}/metadata/${n}" {\n  capabilities = ["read", "list", "delete"]\n}`,
+    ])
+    .join("\n\n");
+  await api(fetchFn, `${url}/v1/sys/policy/oke-app`, {
+    method: "POST",
+    headers: rootHeaders,
+    body: JSON.stringify({ policy: `${policy}\n` }),
+  });
+
+  // Reuse the persisted app token when present; mint once otherwise.
+  let appToken = existsSync(appPath) ? readFileSync(appPath, "utf8").trim() : "";
+  if (!appToken) {
+    const minted = await api<{ auth: { client_token: string } }>(
+      fetchFn,
+      `${url}/v1/auth/token/create`,
+      {
+        method: "POST",
+        headers: rootHeaders,
+        body: JSON.stringify({ policies: ["oke-app"], ttl: "0" }),
+      },
+    );
+    appToken = minted.auth.client_token;
+    writeMaterial(appPath, appToken);
+  }
+
+  return { url, appToken, stateDir, initializedNow };
+}
+
+/**
+ * Build an `OKE_VAULT_*` env overlay for the app / Console from a bootstrap.
+ *
+ * @param result - Bootstrap result
+ */
+export function openbaoStackEnv(result: OpenBaoBootstrapResult): Record<string, string> {
+  return {
+    OKE_VAULT_URL: result.url,
+    OKE_VAULT_TOKEN: result.appToken,
+    OKE_VAULT_MOUNT: OPENBAO_MOUNT,
+  };
+}

package/src/cli/openbao-restart.integration.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Integration: real OpenBao survives a container restart with secrets intact.
+ *
+ * Proves the acceptance criterion — set a secret, kill/restart the container
+ * on the same Raft volume, re-run the bootstrap unseal, and read the secret
+ * back. Skips when no Docker daemon is available.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { deriveInfrastructure, writeDerivedFiles } from "../docker/index.ts";
+import { ensureOpenBao } from "./openbao-bootstrap.ts";
+
+async function dockerAvailable(): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(["docker", "info"], { stdout: "pipe", stderr: "pipe" });
+    return (await proc.exited) === 0;
+  } catch {
+    return false;
+  }
+}
+
+async function compose(project: string, dir: string, args: readonly string[]): Promise<number> {
+  const proc = Bun.spawn(["docker", "compose", "-p", project, ...args], {
+    cwd: dir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return proc.exited;
+}
+
+describe("openbao restart persistence (real container)", () => {
+  test("secret set before restart is readable after restart + unseal", async () => {
+    if (!(await dockerAvailable())) {
+      console.warn("skipping: docker daemon not available");
+      return;
+    }
+
+    const dir = await mkdtemp(join(tmpdir(), "oke-openbao-it-"));
+    const dockerDir = join(dir, "docker");
+    const project = `oke-bao-${Date.now()}`;
+    const composeFiles = ["compose.yml", "compose.vault.yml"];
+    try {
+      const derived = deriveInfrastructure({
+        images: { vault: "openbao/openbao:2.6.1" },
+        app: "baotest",
+        includeApp: false,
+        composeDir: "docker",
+      });
+      await writeDerivedFiles(derived, dockerDir, { writeStackEnv: true });
+      const spec = derived.specs.find((s) => s.role === "vault")!;
+      const url = `http://127.0.0.1:${spec.hostPort}`;
+
+      const up = await compose(project, dockerDir, [
+        ...composeFiles.flatMap((f) => ["-f", f]),
+        "up",
+        "-d",
+      ]);
+      expect(up).toBe(0);
+
+      const names = ["STRIPE_KEY"];
+      let first;
+      try {
+        first = await ensureOpenBao({ cwd: dir, url, names });
+      } catch (err) {
+        const logs = Bun.spawn(
+          [
+            "docker",
+            "compose",
+            "-p",
+            project,
+            ...composeFiles.flatMap((f) => ["-f", f]),
+            "logs",
+            "vault",
+          ],
+          { cwd: dockerDir, stdout: "pipe", stderr: "pipe" },
+        );
+        console.error(await new Response(logs.stdout).text());
+        console.error(await new Response(logs.stderr).text());
+        await logs.exited;
+        throw err;
+      }
+      expect(first.appToken.length).toBeGreaterThan(0);
+
+      const write = await fetch(`${url}/v1/secret/data/STRIPE_KEY`, {
+        method: "POST",
+        headers: { "X-Vault-Token": first.appToken, "content-type": "application/json" },
+        body: JSON.stringify({ data: { value: "sk_restart_persistent" } }),
+      });
+      if (!write.ok) console.error("write failed", write.status, await write.text());
+      expect(write.ok).toBe(true);
+
+      // Kill + start the same volume (a real restart, not a fresh stack).
+      const restart = await compose(project, dockerDir, [
+        ...composeFiles.flatMap((f) => ["-f", f]),
+        "restart",
+      ]);
+      expect(restart).toBe(0);
+      // Poll the API until the server is back (sealed or unsealed).
+      let apiUp = false;
+      for (let i = 0; i < 60; i++) {
+        try {
+          const probe = await fetch(`${url}/v1/sys/seal-status`);
+          if (probe.ok) {
+            apiUp = true;
+            break;
+          }
+        } catch {
+          // not up yet
+        }
+        await Bun.sleep(500);
+      }
+      expect(apiUp).toBe(true);
+
+      const second = await ensureOpenBao({ cwd: dir, url, names });
+      expect(second.initializedNow).toBe(false);
+      expect(second.appToken).toBe(first.appToken);
+
+      const read = await fetch(`${url}/v1/secret/data/STRIPE_KEY`, {
+        headers: { "X-Vault-Token": second.appToken },
+      });
+      expect(read.ok).toBe(true);
+      const body = (await read.json()) as { data?: { data?: { value?: string } } };
+      expect(body.data?.data?.value).toBe("sk_restart_persistent");
+    } finally {
+      await compose(project, dockerDir, [
+        ...composeFiles.flatMap((f) => ["-f", f]),
+        "down",
+        "-v",
+      ]).catch(() => 0);
+      await rm(dir, { recursive: true, force: true }).catch(() => {});
+    }
+  }, 180_000);
+});

package/src/cli/ports.test.ts

@@ -28,15 +28,17 @@ describe("findFreePort", () => {
 });
 
 describe("resolveDevPorts", () => {
-  test("keeps app · console · mcp distinct when preferred collide", async () => {
-    // Everything busy except 6531, 6534, 6536 — force increments.
+  test("keeps app · console · mcp · docsMcp distinct when preferred collide", async () => {
+    // Everything busy except 6531, 6534, 6536, 6537 — force increments.
     const busy = new Set([6530, 6533, 6535]);
-    const ports = await resolveDevPorts({ app: 6530, console: 6533, mcp: 6535 }, async (p) =>
-      busy.has(p),
+    const ports = await resolveDevPorts(
+      { app: 6530, console: 6533, mcp: 6535, docsMcp: 6536 },
+      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);
+    expect(ports.docsMcp).toBe(6537);
+    expect(new Set([ports.app, ports.console, ports.mcp, ports.docsMcp]).size).toBe(4);
   });
 });

package/src/cli/ports.ts

@@ -52,7 +52,7 @@ export async function findFreePort(
 }
 
 /**
- * Resolve distinct free ports for app · Console · MCP (dev only).
+ * Resolve distinct free ports for app · Console · MCP · docs MCP (dev only).
  *
  * @param preferred - Preferred ports
  * @param probe - Injectable busy check (tests)
@@ -62,12 +62,14 @@ export async function resolveDevPorts(
     readonly app: number;
     readonly console: number;
     readonly mcp: number;
+    readonly docsMcp: number;
   },
   probe: (port: number) => Promise<boolean> = isPortInUse,
 ): Promise<{
   readonly app: number;
   readonly console: number;
   readonly mcp: number;
+  readonly docsMcp: number;
 }> {
   const occupied = new Set<number>();
   const app = await findFreePort(preferred.app, occupied, probe);
@@ -75,5 +77,7 @@ export async function resolveDevPorts(
   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 };
+  if (mcp !== 0) occupied.add(mcp);
+  const docsMcp = await findFreePort(preferred.docsMcp, occupied, probe);
+  return { app, console: consolePort, mcp, docsMcp };
 }