okengine 0.10.2 → 0.11.0

package/src/cli/dev-controller.ts

@@ -0,0 +1,298 @@
+/**
+ * Headless `oke dev` controller — UI-agnostic lifecycle + events.
+ *
+ * Ink TUI and plain CLI both consume this; never kill a foreign pid.
+ */
+
+import { resolve } from "node:path";
+import { APP_PORT, CONSOLE_PORT, DOCS_MCP_PORT, MCP_PORT } from "../runtime/types.ts";
+import type { DevStatus } from "../term.ts";
+import { type DevOptions, type DevSession, runDev } from "./dev.ts";
+import {
+  clearDevSessionLock,
+  type DevOwnership,
+  type DevSessionLock,
+  type DevSessionPorts,
+  probeDevPortsBusy,
+  resolveDevOwnership,
+  writeDevSessionLock,
+} from "./dev-session-lock.ts";
+
+/** Controller event kinds. */
+export type DevControllerEvent =
+  | { readonly type: "boot"; readonly phase: string; readonly detail?: string }
+  | {
+      readonly type: "ready";
+      readonly ports: DevSessionPorts;
+      readonly ownership: DevOwnership;
+    }
+  | {
+      readonly type: "status";
+      readonly service: string;
+      readonly status: DevStatus;
+      readonly detail?: string;
+    }
+  | { readonly type: "log"; readonly text: string }
+  | { readonly type: "error"; readonly message: string; readonly fatal?: boolean }
+  | {
+      readonly type: "exit";
+      readonly code: number;
+      readonly signal?: string;
+    }
+  | { readonly type: "ownership"; readonly ownership: DevOwnership };
+
+/** Listener for {@link DevController} events. */
+export type DevControllerListener = (event: DevControllerEvent) => void;
+
+/** Options for {@link DevController.start}. */
+export type DevControllerStartOptions = Omit<DevOptions, "keepAlive" | "write" | "onReady"> & {
+  readonly cwd?: string;
+  /** Forward formatted chrome to stdout as well as events (default false). */
+  readonly echoLogs?: boolean;
+};
+
+/**
+ * Headless orchestration for a project’s dev stack.
+ */
+export class DevController {
+  private readonly listeners = new Set<DevControllerListener>();
+  private session: DevSession | null = null;
+  private ownership: DevOwnership = "stopped";
+  private lock: DevSessionLock | null = null;
+  private starting = false;
+  private readonly preferredPorts: DevSessionPorts;
+
+  /**
+   * @param preferredPorts - Default ports when probing without a lock
+   */
+  constructor(
+    preferredPorts: DevSessionPorts = {
+      app: APP_PORT,
+      console: CONSOLE_PORT,
+      mcp: MCP_PORT,
+      docsMcp: DOCS_MCP_PORT,
+    },
+  ) {
+    this.preferredPorts = preferredPorts;
+  }
+
+  /** Current ownership classification. */
+  getOwnership(): DevOwnership {
+    return this.ownership;
+  }
+
+  /** Live session when managed and started. */
+  getSession(): DevSession | null {
+    return this.session;
+  }
+
+  /** Last lock we wrote (managed only). */
+  getLock(): DevSessionLock | null {
+    return this.lock;
+  }
+
+  /**
+   * Subscribe to controller events.
+   *
+   * @param listener - Callback
+   */
+  on(listener: DevControllerListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * Emit an event to all listeners.
+   *
+   * @param event - Payload
+   */
+  emit(event: DevControllerEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+        // listeners must not break the controller
+      }
+    }
+  }
+
+  /**
+   * Discover an existing stack without starting one.
+   *
+   * @param cwd - Project root
+   */
+  async attach(cwd: string = process.cwd()): Promise<{
+    readonly ownership: DevOwnership;
+    readonly lock: DevSessionLock | null;
+    readonly busy: Awaited<ReturnType<typeof probeDevPortsBusy>>;
+  }> {
+    const root = resolve(cwd);
+    const resolved = await resolveDevOwnership(root, this.preferredPorts);
+    this.ownership = resolved.ownership;
+    this.lock = resolved.lock;
+    this.emit({ type: "ownership", ownership: this.ownership });
+    if (this.ownership === "managed" || this.ownership === "external") {
+      const ports = resolved.lock?.ports ?? this.preferredPorts;
+      this.emit({
+        type: "ready",
+        ports,
+        ownership: this.ownership,
+      });
+      this.emit({
+        type: "log",
+        text:
+          this.ownership === "managed"
+            ? "Attached to managed oke dev session\n"
+            : "Connected to external oke dev (read-only)\n",
+      });
+    }
+    return resolved;
+  }
+
+  /**
+   * Start a managed session. Refuses if ports are already taken by another stack.
+   *
+   * @param options - Dev options (keepAlive forced false)
+   */
+  async start(options: DevControllerStartOptions = {}): Promise<number> {
+    if (this.starting) {
+      this.emit({ type: "error", message: "dev start already in progress" });
+      return 1;
+    }
+    if (this.session) {
+      this.emit({ type: "error", message: "dev session already running (managed)" });
+      return 1;
+    }
+
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const attached = await this.attach(cwd);
+    if (attached.ownership === "external") {
+      this.emit({
+        type: "error",
+        message: "oke dev already running externally — attach only (will not start a second stack)",
+        fatal: false,
+      });
+      return 1;
+    }
+    if (attached.ownership === "managed" && attached.lock && attached.lock.pid !== process.pid) {
+      // Another managed process still alive — do not steal.
+      this.emit({
+        type: "error",
+        message: `oke dev already managed by pid ${attached.lock.pid}`,
+        fatal: false,
+      });
+      return 1;
+    }
+
+    this.starting = true;
+    this.emit({ type: "boot", phase: "starting" });
+
+    const echo = options.echoLogs === true;
+    const write = (text: string): void => {
+      this.emit({ type: "log", text });
+      if (echo) process.stdout.write(text);
+    };
+
+    try {
+      const result = await runDev({
+        ...options,
+        cwd,
+        keepAlive: false,
+        write,
+        onReady: async (session) => {
+          const ports: DevSessionPorts = {
+            app: session.appPort,
+            console: session.consolePort,
+            mcp: session.mcpPort,
+            docsMcp: session.docsMcpPort,
+          };
+          const lock: DevSessionLock = {
+            pid: process.pid,
+            ports,
+            startedAt: new Date().toISOString(),
+            cwd,
+          };
+          await writeDevSessionLock(cwd, lock);
+          this.lock = lock;
+          this.session = session;
+          this.ownership = "managed";
+          this.emit({ type: "ownership", ownership: "managed" });
+          this.emit({ type: "ready", ports, ownership: "managed" });
+          this.emit({ type: "boot", phase: "ready" });
+        },
+      });
+
+      if (result.code !== 0 || !result.session) {
+        this.ownership = "stopped";
+        this.session = null;
+        this.emit({ type: "error", message: "oke dev failed to start", fatal: true });
+        this.emit({ type: "exit", code: result.code });
+        return result.code;
+      }
+
+      // onReady may have already set session; ensure we hold it.
+      this.session = result.session;
+      return 0;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.emit({ type: "error", message, fatal: true });
+      this.emit({ type: "exit", code: 1 });
+      return 1;
+    } finally {
+      this.starting = false;
+    }
+  }
+
+  /**
+   * Stop only a session this controller owns. Never kills an external pid.
+   */
+  async stop(): Promise<void> {
+    if (this.ownership === "external") {
+      this.emit({
+        type: "error",
+        message: "refusing to stop external oke dev session",
+        fatal: false,
+      });
+      return;
+    }
+    if (this.ownership !== "managed" || !this.session) {
+      this.ownership = "stopped";
+      this.emit({ type: "ownership", ownership: "stopped" });
+      return;
+    }
+
+    const cwd = this.lock?.cwd ?? process.cwd();
+    try {
+      this.session.stop();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.emit({ type: "error", message });
+    }
+    this.session = null;
+    this.lock = null;
+    this.ownership = "stopped";
+    await clearDevSessionLock(cwd);
+    this.emit({ type: "ownership", ownership: "stopped" });
+    this.emit({ type: "exit", code: 0 });
+  }
+
+  /**
+   * Stop then start (managed only).
+   *
+   * @param options - Start options
+   */
+  async restart(options: DevControllerStartOptions = {}): Promise<number> {
+    if (this.ownership === "external") {
+      this.emit({
+        type: "error",
+        message: "cannot restart an external oke dev session",
+        fatal: false,
+      });
+      return 1;
+    }
+    await this.stop();
+    return this.start(options);
+  }
+}

package/src/cli/dev-controls.ts

@@ -1,19 +1,17 @@
 /**
- * Keyboard controls for a live `oke dev` session (TTY raw mode).
+ * Dev control key mapping + pure dispatcher (tests).
  *
- * Keys: `?` help · `q` quit · `r` refresh · `u` up all · `x` stop all.
- *
- * Compose health / model phase update the status board above Logs — it
- * already lists every service with a live ● status, so refresh alone is
- * enough to see the stack; there is no separate services panel.
+ * Interactive raw-mode stdin was removed — Ink `useInput` owns TTY input
+ * via {@link ./tui/keys.ts}.
  */
 
 import { formatStatusLine, termColorEnabled, termStyle } from "../term.ts";
+import { mapDevControlInput } from "./tui/keys.ts";
 
 /** Compose action against the whole stack. */
 export type DevComposeControlAction = "up" | "stop";
 
-/** Options for {@link startDevControls}. */
+/** Options for {@link createDevControlDispatcher}. */
 export type StartDevControlsOptions = {
   readonly write: (text: string) => void;
   /** Called on `q` / Ctrl+C. */
@@ -23,14 +21,13 @@ export type StartDevControlsOptions = {
    */
   readonly onRefresh?: () => void | Promise<void>;
   /**
-   * Show help in a clean pane (refreshes chrome first so the panel is not
-   * interleaved with request logs).
+   * Show help in a clean pane.
    *
    * @param body - Formatted panel text
    */
   readonly onShowPanel?: (body: string) => void | Promise<void>;
   /**
-   * After a compose up/stop — sync health into the board (no log lines).
+   * After a compose up/stop — sync health into the board.
    */
   readonly onComposeSettled?: () => void | Promise<void>;
   /**
@@ -39,16 +36,9 @@ export type StartDevControlsOptions = {
    * @param action - up / stop
    */
   readonly composeAction: (action: DevComposeControlAction) => Promise<void>;
-  readonly stdin?: NodeJS.ReadStream;
-  readonly isTTY?: boolean;
   readonly color?: boolean;
 };
 
-/** Handle returned by {@link startDevControls}. */
-export type DevControlsHandle = {
-  readonly stop: () => void;
-};
-
 /**
  * One-line keys hint under Logs.
  *
@@ -97,24 +87,18 @@ export function formatDevControlsHelp(color: boolean = termColorEnabled()): stri
  */
 export function parseDevControlKey(chunk: string): string | null {
   if (chunk.length === 0) return null;
-  if (chunk === "\u0003") return "q"; // Ctrl+C
-  const ch = chunk[0]!;
-  if (ch === "?" || ch === "h" || ch === "H") return "?";
-  if (ch === "q" || ch === "Q") return "q";
-  if (ch === "r" || ch === "R") return "r";
-  if (ch === "u" || ch === "U") return "u";
-  if (ch === "x" || ch === "X") return "x";
-  return null;
+  if (chunk === "\u0003") return mapDevControlInput("c", { ctrl: true });
+  return mapDevControlInput(chunk[0] ?? "", {});
 }
 
-/** Key dispatcher for tests and {@link startDevControls}. */
+/** Key dispatcher for tests. */
 export type DevControlDispatcher = {
   readonly handleKey: (key: string) => void;
   readonly stop: () => void;
 };
 
 /**
- * Pure key dispatcher (no stdin) — used by tests and the TTY listener.
+ * Pure key dispatcher (no stdin) — used by tests.
  *
  * @param opts - Quit / compose actions
  */
@@ -165,41 +149,3 @@ export function createDevControlDispatcher(opts: StartDevControlsOptions): DevCo
     },
   };
 }
-
-/**
- * Start raw-mode keyboard controls. No-op when stdin is not a TTY.
- *
- * @param opts - Quit / compose actions
- */
-export function startDevControls(opts: StartDevControlsOptions): DevControlsHandle {
-  const stdin = opts.stdin ?? process.stdin;
-  const isTTY = opts.isTTY ?? stdin.isTTY === true;
-  const dispatcher = createDevControlDispatcher(opts);
-
-  if (!isTTY || typeof stdin.setRawMode !== "function") {
-    return { stop: () => dispatcher.stop() };
-  }
-
-  const onData = (buf: string | Buffer): void => {
-    const chunk = typeof buf === "string" ? buf : buf.toString("utf8");
-    const key = parseDevControlKey(chunk);
-    if (key) dispatcher.handleKey(key);
-  };
-
-  stdin.setRawMode(true);
-  stdin.resume();
-  stdin.setEncoding("utf8");
-  stdin.on("data", onData);
-
-  return {
-    stop() {
-      dispatcher.stop();
-      stdin.off("data", onData);
-      try {
-        if (typeof stdin.setRawMode === "function") stdin.setRawMode(false);
-      } catch {
-        // already closed
-      }
-    },
-  };
-}

package/src/cli/dev-db-push.test.ts

@@ -6,10 +6,39 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { runDev, type DevSession, type DevWatchFn } from "./dev.ts";
+import { runDev, type DevOptions, type DevSession, type DevWatchFn } from "./dev.ts";
 
 const sessions: DevSession[] = [];
 
+const STUB_IMAGES = {
+  "store.sql": "postgres:16-alpine",
+  "store.kv": "redis:7-alpine",
+} as const;
+const STUB_CREDENTIALS = {
+  "store.sql": {
+    user: "oke",
+    password: "test-password-not-in-yaml",
+    database: "oke",
+  },
+} as const;
+
+function stubCompose(): Pick<
+  DevOptions,
+  "images" | "credentials" | "composeUp" | "composeHealth" | "composeStop"
+> {
+  return {
+    images: STUB_IMAGES,
+    credentials: STUB_CREDENTIALS,
+    composeUp: async () => {},
+    composeHealth: async () =>
+      new Map([
+        ["store-sql", "ready"],
+        ["store-kv", "ready"],
+      ]),
+    composeStop: () => {},
+  };
+}
+
 afterEach(() => {
   for (const s of sessions.splice(0)) s.stop();
 });
@@ -46,25 +75,26 @@ async function scaffoldProject(): Promise<string> {
     join(dir, "oke.config.ts"),
     `import { defineConfig } from ${JSON.stringify(configMod)};
 export default defineConfig({
-  drivers: { store: { sql: { local: "sqlite", test: "memory", prod: "postgres" } } },
+  drivers: { store: { sql: { dev: "postgres", test: "pglite", prod: "postgres" } } },
 });
 `,
   );
   await writeFile(join(dir, "src", "app.ts"), `export {};\n`);
   await writeFile(
     join(dir, "src", "schema.ts"),
-    `import { sqliteTable, text } from "drizzle-orm/sqlite-core";
-export const entries = sqliteTable("entries", { id: text("id").primaryKey() });
+    `import { pgTable, text } from "drizzle-orm/pg-core";
+export const entries = pgTable("entries", { id: text("id").primaryKey() });
 `,
   );
   await writeFile(
     join(dir, "drizzle.config.ts"),
     `import { defineConfig } from "drizzle-kit";
 export default defineConfig({
-  dialect: "sqlite",
+  dialect: "postgresql",
+  driver: "pglite",
   schema: "./src/schema.ts",
   out: "./drizzle",
-  dbCredentials: { url: "file::memory:" },
+  dbCredentials: { url: "memory://" },
 });
 `,
   );
@@ -83,7 +113,7 @@ describe("oke dev db auto-push", () => {
 
     const result = await runDev({
       cwd,
-      local: true,
+      ...stubCompose(),
       keepAlive: false,
       dryRun: false,
       appPort: 0,
@@ -127,8 +157,8 @@ describe("oke dev db auto-push", () => {
     const before = pushes.length;
     await writeFile(
       join(cwd, "src", "schema.ts"),
-      `import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
-export const entries = sqliteTable("entries", {
+      `import { integer, pgTable, text } from "drizzle-orm/pg-core";
+export const entries = pgTable("entries", {
   id: text("id").primaryKey(),
   n: integer("n"),
 });
@@ -139,7 +169,7 @@ export const entries = sqliteTable("entries", {
     expect(pushes.length).toBeGreaterThan(before);
   });
 
-  test("schema.generated.ts change does not re-trigger dbPush", async () => {
+  test("schema.drizzle.ts change does not re-trigger dbPush", async () => {
     const cwd = await scaffoldProject();
     const pushes: string[] = [];
     const watcher = controlledWatcher();
@@ -150,7 +180,7 @@ export const entries = sqliteTable("entries", {
 
     const result = await runDev({
       cwd,
-      local: true,
+      ...stubCompose(),
       keepAlive: false,
       dryRun: false,
       appPort: 0,
@@ -191,7 +221,9 @@ export const entries = sqliteTable("entries", {
     const before = pushes.length;
     expect(before).toBeGreaterThanOrEqual(1);
 
-    // Simulate emit writing schema.generated.ts after push — must not loop.
+    // Simulate emit writing schema.drizzle.ts after push — must not loop.
+    watcher.change("schema.drizzle.ts");
+    watcher.change("src/db/schema.drizzle.ts");
     watcher.change("schema.generated.ts");
     watcher.change("src/schema.generated.ts");
     await Bun.sleep(500);
@@ -205,7 +237,7 @@ export const entries = sqliteTable("entries", {
 
     const result = await runDev({
       cwd,
-      local: true,
+      ...stubCompose(),
       noDbPush: true,
       keepAlive: false,
       appPort: 0,
@@ -241,8 +273,8 @@ export const entries = sqliteTable("entries", {
     expect(result.code).toBe(0);
     await writeFile(
       join(cwd, "src", "schema.ts"),
-      `import { sqliteTable, text } from "drizzle-orm/sqlite-core";
-export const entries = sqliteTable("entries", { id: text("id").primaryKey(), x: text("x") });
+      `import { pgTable, text } from "drizzle-orm/pg-core";
+export const entries = pgTable("entries", { id: text("id").primaryKey(), x: text("x") });
 `,
     );
     watcher.change("schema.ts");

package/src/cli/dev-schema-sync.test.ts

@@ -22,41 +22,41 @@ async function tempDir(): Promise<string> {
 }
 
 describe("sqlDialectForEnv", () => {
-  test("local → sqlite, docker → postgresql", async () => {
+  test("test → postgresql (pglite), dev → postgresql", async () => {
     const config = {
       drivers: {
-        store: { sql: { local: "sqlite", docker: "postgres", prod: "postgres", test: "memory" } },
+        store: { sql: { dev: "postgres", test: "pglite", prod: "postgres" } },
       },
     } as never;
-    expect(sqlDialectForEnv(config, "local").dialect).toBe("sqlite");
-    expect(sqlDialectForEnv(config, "docker").dialect).toBe("postgresql");
+    expect(sqlDialectForEnv(config, "test").dialect).toBe("postgresql");
+    expect(sqlDialectForEnv(config, "dev").dialect).toBe("postgresql");
   });
 
-  test("missing config → sqlite default", () => {
-    expect(sqlDialectForEnv(null, "local").dialect).toBe("sqlite");
+  test("missing config → postgresql default", () => {
+    expect(sqlDialectForEnv(null, "test").dialect).toBe("postgresql");
   });
 });
 
 describe("syncDevSchema", () => {
-  test("local: ensures drizzle config, emits, pushes with env", async () => {
+  test("test: ensures drizzle config, emits, pushes with env", async () => {
     const dir = await tempDir();
     const calls: { cwd: string; env: ConfigEnv }[] = [];
-    const result = await syncDevSchema(dir, "local", {
+    const result = await syncDevSchema(dir, "test", {
       write: () => {},
       pushFn: async (cwd, env) => {
         calls.push({ cwd, env });
         return 0;
       },
     });
-    expect(result.dialect).toBe("sqlite");
+    expect(result.dialect).toBe("postgresql");
     expect(result.pushed).toBe(true);
-    expect(calls).toEqual([{ cwd: dir, env: "local" }]);
+    expect(calls).toEqual([{ cwd: dir, env: "test" }]);
     expect(await Bun.file(join(dir, "drizzle.config.ts")).exists()).toBe(true);
   });
 
   test("push failure surfaces code without throwing", async () => {
     const dir = await tempDir();
-    const result = await syncDevSchema(dir, "local", {
+    const result = await syncDevSchema(dir, "test", {
       write: () => {},
       pushFn: async () => 1,
     });

package/src/cli/dev-schema-sync.ts

@@ -1,5 +1,5 @@
 /**
- * Shared local↔docker schema sync pipeline for `oke mode` and `oke dev`
+ * Shared schema sync pipeline for `oke dev` / `oke db`
  * one-shot start. Ensures artefacts, emits for the active dialect, then
  * pushes via drizzle-kit. Data planes stay isolated — no row copying.
  */
@@ -24,7 +24,7 @@ import { loadOkeConfig, resolveImages } from "./load-config.ts";
 export interface DevSchemaSyncOptions {
   /** Write output (default: stdout). */
   readonly write?: (text: string) => void;
-  /** Skip emitting `schema.generated.ts` (tests). */
+  /** Skip emitting `schema.drizzle.ts` (tests). */
   readonly skipEmit?: boolean;
   /** Injectable push (tests). Default: `runDb("push", ...)`. */
   readonly pushFn?: (cwd: string, env: ConfigEnv) => Promise<number>;
@@ -40,7 +40,7 @@ export interface DevSchemaSyncOptions {
 /** Outcome of {@link syncDevSchema}. */
 export interface DevSchemaSyncResult {
   readonly env: ConfigEnv;
-  readonly dialect: "sqlite" | "postgresql";
+  readonly dialect: "postgresql";
   readonly pushed: boolean;
   readonly code: number;
 }
@@ -54,11 +54,11 @@ export interface DevSchemaSyncResult {
 export function sqlDialectForEnv(
   config: OkeConfig | null | undefined,
   env: ConfigEnv,
-): { readonly driverId: string; readonly dialect: "sqlite" | "postgresql" } {
-  const driverId = resolveDriverId(config?.drivers?.store?.sql, env) ?? "sqlite";
-  if (driverId !== "sqlite" && driverId !== "postgres") {
+): { readonly driverId: string; readonly dialect: "postgresql" } {
+  const driverId = resolveDriverId(config?.drivers?.store?.sql, env) ?? "postgres";
+  if (driverId !== "postgres" && driverId !== "pglite") {
     throw new Error(
-      `store.sql driver "${driverId}" is not supported by drizzle-kit (sqlite | postgres)`,
+      `store.sql driver "${driverId}" is not supported by drizzle-kit (postgres | pglite)`,
     );
   }
   return { driverId, dialect: drizzleDialectFromSqlDriver(driverId) };
@@ -103,7 +103,7 @@ async function ensureDockerStack(
   await writeDerivedFiles(derived, resolve(cwd, DEFAULT_DOCKER_DIR), { writeStackEnv: true });
   if (!quietComposeReady) {
     write(
-      "oke: docker compose env ready under docker/.env.docker (start containers with `oke dev -d` or docker compose up)\n",
+      "oke: docker compose env ready under docker/.env.docker (start containers with `oke dev` or docker compose up)\n",
     );
   }
 }
@@ -114,7 +114,7 @@ async function ensureDockerStack(
  * exists (writes `docker/.env.docker`) before pushing to the live DB.
  *
  * @param cwd - Project root
- * @param env - Target env (`local` | `docker`)
+ * @param env - Target {@link ConfigEnv} (`dev` for compose, `test` for laptop)
  * @param options - Injectables
  */
 export async function syncDevSchema(
@@ -130,7 +130,7 @@ export async function syncDevSchema(
 
   const { dialect } = sqlDialectForEnv(config, env);
 
-  if (env === "docker") {
+  if (env === "dev") {
     if (!config) {
       throw new Error("docker mode: oke.config.ts not found");
     }