okengine 0.9.1 → 0.10.0

package/src/cli/db-seed.ts

@@ -19,7 +19,7 @@ import {
 } from "../elements/store/load-plugin-tables.ts";
 import { createFx, type Fx } from "../kernel/fx.ts";
 import type { OkeApp } from "../kernel/app.ts";
-import { resolveDrizzleKitEnv } from "./drizzle-env.ts";
+import { applyComposeEnvToProcess, resolveDrizzleKitEnv } from "./drizzle-env.ts";
 import { EXIT_OK, EXIT_RUNTIME, EXIT_USAGE } from "./exit.ts";
 import { loadOkeConfig } from "./load-config.ts";
 import { resolveDevSqlEnv } from "./resolve-dev-sql-env.ts";
@@ -38,7 +38,7 @@ export interface SeedOptions {
   readonly env?: ConfigEnv;
   /** Skip interactive confirm (`--force`). */
   readonly force?: boolean;
-  /** Override seed module path (default `src/seed/index.ts`). */
+  /** Override seed module path (default `src/db/seed/index.ts`). */
   readonly seedPath?: string;
   /** Override app entry for boot. */
   readonly entry?: string;
@@ -77,13 +77,17 @@ export function isSeedDef(value: unknown): value is SeedDef {
 /**
  * Redact password from a connection URL for display.
  *
+ * Builds the string by hand — assigning unicode bullets to `URL.password`
+ * then calling `toString()` percent-encodes them (`%E2%80%A2`).
+ *
  * @param raw - Connection URL or file path
  */
 export function redactConnectionTarget(raw: string): string {
   try {
     const u = new URL(raw);
-    if (u.password) u.password = "••••";
-    return u.toString();
+    if (!u.password) return u.toString();
+    const auth = u.username ? `${u.username}:••••@` : "••••@";
+    return `${u.protocol}//${auth}${u.host}${u.pathname}${u.search}${u.hash}`;
   } catch {
     return raw;
   }
@@ -158,14 +162,35 @@ export async function executeSeedDef(
   }
 }
 
+/** Default seed module (create-oke `src/db` layout). */
+export const DEFAULT_SEED_REL = "src/db/seed/index.ts";
+
+/** Legacy seed module path. */
+export const LEGACY_SEED_REL = "src/seed/index.ts";
+
 /**
- * Load `src/seed/index.ts` (or override) and return its SeedDef.
+ * Resolve the seed module path (explicit → new default → legacy).
+ *
+ * @param cwd - Project root
+ * @param seedPath - Optional override
+ */
+export async function resolveSeedModulePath(cwd: string, seedPath?: string): Promise<string> {
+  if (seedPath) return resolve(cwd, seedPath);
+  for (const rel of [DEFAULT_SEED_REL, LEGACY_SEED_REL]) {
+    const abs = resolve(cwd, rel);
+    if (await Bun.file(abs).exists()) return abs;
+  }
+  return resolve(cwd, DEFAULT_SEED_REL);
+}
+
+/**
+ * Load `src/db/seed/index.ts` (or legacy / override) and return its SeedDef.
  *
  * @param cwd - Project root
  * @param seedPath - Relative or absolute path
  */
 export async function loadSeedDef(cwd: string, seedPath?: string): Promise<SeedDef> {
-  const abs = resolve(cwd, seedPath ?? "src/seed/index.ts");
+  const abs = await resolveSeedModulePath(cwd, seedPath);
   if (!(await Bun.file(abs).exists())) {
     throw new Error(`oke db seed: no seed module at ${abs}`);
   }
@@ -193,6 +218,10 @@ export async function bootSeedFx(
   entry?: string,
   config?: OkeConfig | null,
 ): Promise<{ readonly fx: Fx; readonly stop: () => Promise<void> }> {
+  if (env === "docker") {
+    await applyComposeEnvToProcess(cwd);
+    if (process.env.OKE_DOCKER === undefined) process.env.OKE_DOCKER = "1";
+  }
   const entryAbs = await resolveAppEntryForPluginTables(cwd, entry ?? config?.db?.entry);
   if (!entryAbs) {
     throw new Error(
@@ -208,7 +237,7 @@ export async function bootSeedFx(
   const storeRuntime = app.elements?.store ?? app.bootResult?.store;
   if (!storeRuntime) {
     throw new Error(
-      "oke db seed: app booted without a store runtime — ensure stores are registered on the app (e.g. Object.assign(app.$options, { stores: [db] }))",
+      "oke db seed: app booted without a store runtime — ensure stores are registered on the app (e.g. oke({ name, stores: [db] }))",
     );
   }
   const fx = createFx({

package/src/cli/db.test.ts

@@ -242,7 +242,7 @@ export const app = oke({ name: "plugin-only" }).plug(
     const emitted = await emitAbstractSchemaPrestep(dir, loaded.config, () => {}, "local");
     expect(emitted).toBe(true);
 
-    const generated = await readFile(join(dir, "src", "schema.generated.ts"), "utf8");
+    const generated = await readFile(join(dir, "src", "db", "schema.generated.ts"), "utf8");
     expect(generated).toContain('sqliteTable("metrics_daily"');
     expect(generated).toContain('integer("hits")');
   });

package/src/cli/db.ts

@@ -3,7 +3,7 @@
  * plus explicit seed runs.
  *
  * Distinct from `oke schema generate` (core/plugin stub tables).
- * When abstract decls exist (`src/schema.decl.ts`), emits Drizzle first —
+ * When abstract decls exist (`src/db/schema.decl.ts`), emits Drizzle first —
  * not a third schema CLI.
  */
 
@@ -448,7 +448,7 @@ export async function dbCli(args: readonly string[]): Promise<number> {
     console.log(`oke db push|generate|migrate|seed [--config|-c] [--env name] [--force]
 
 Domain schema sync via drizzle-kit, plus explicit seed.
-When src/schema.decl.ts and/or a plugged app entry exists, emits
+When src/db/schema.decl.ts and/or a plugged app entry exists, emits
 schema.generated.ts from store.schema.table + live plugin .table()
 contributions — then runs drizzle-kit.
 Hand-written src/schema.ts remains supported (emit skipped if nothing to emit).

package/src/cli/dev-controls.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+import {
+  controlServicesFromStack,
+  createDevControlDispatcher,
+  formatDevControlsHelp,
+  formatDevControlsHint,
+  formatDevControlsServiceList,
+  parseDevControlKey,
+} from "./dev-controls.ts";
+
+describe("dev-controls", () => {
+  test("parseDevControlKey maps raw keys", () => {
+    expect(parseDevControlKey("q")).toBe("q");
+    expect(parseDevControlKey("\u0003")).toBe("q");
+    expect(parseDevControlKey("?")).toBe("?");
+    expect(parseDevControlKey("h")).toBe("?");
+    expect(parseDevControlKey("c")).toBe("c");
+    expect(parseDevControlKey("l")).toBe("l");
+    expect(parseDevControlKey("u")).toBe("u");
+    expect(parseDevControlKey("x")).toBe("x");
+    expect(parseDevControlKey("r")).toBe("r");
+    expect(parseDevControlKey("3")).toBe("3");
+    expect(parseDevControlKey("\u001b")).toBe("esc");
+    expect(parseDevControlKey("z")).toBeNull();
+  });
+
+  test("format hint and help are scannable", () => {
+    expect(formatDevControlsHint(false)).toContain("keys");
+    expect(formatDevControlsHint(false)).toContain("refresh");
+    expect(formatDevControlsHint(false)).toContain("quit");
+    expect(formatDevControlsHelp(false)).toContain("select service");
+    expect(formatDevControlsHelp(false)).toContain("refresh");
+    expect(formatDevControlsHelp(false)).not.toMatch(/\u001b\[/);
+  });
+
+  test("controlServicesFromStack dedupes by serviceName", () => {
+    const list = controlServicesFromStack([
+      { label: "ai", serviceName: "ai" },
+      { label: "mail", serviceName: "channel-email" },
+      { label: "mail-ui", serviceName: "channel-email" },
+      { label: "postgres", serviceName: "store-sql" },
+    ]);
+    expect(list.map((s) => s.serviceName)).toEqual(["ai", "channel-email", "store-sql"]);
+  });
+
+  test("formatDevControlsServiceList numbers rows", () => {
+    const out = formatDevControlsServiceList(
+      [
+        { label: "ai", serviceName: "ai" },
+        { label: "postgres", serviceName: "store-sql" },
+      ],
+      (name) => (name === "ai" ? "error" : "ready"),
+      false,
+      1,
+    );
+    expect(out).toContain("1");
+    expect(out).toContain("ai");
+    expect(out).toContain("postgres");
+    expect(out).toContain(">");
+  });
+
+  test("dispatcher select → stop → up stack → quit", async () => {
+    const calls: string[] = [];
+    let quit = false;
+    let settled = 0;
+    let refreshed = 0;
+    let panels = 0;
+    const d = createDevControlDispatcher({
+      write: () => {},
+      onQuit: () => {
+        quit = true;
+      },
+      onRefresh: () => {
+        refreshed += 1;
+      },
+      onShowPanel: () => {
+        panels += 1;
+      },
+      onComposeSettled: () => {
+        settled += 1;
+      },
+      services: () => [
+        { label: "ai", serviceName: "ai" },
+        { label: "postgres", serviceName: "store-sql" },
+      ],
+      composeAction: async (action, names) => {
+        calls.push(`${action}:${names.join(",") || "*"}`);
+      },
+    });
+    d.handleKey("l");
+    await Bun.sleep(10);
+    d.handleKey("1");
+    d.handleKey("x");
+    await Bun.sleep(10);
+    d.handleKey("u");
+    await Bun.sleep(10);
+    d.handleKey("c");
+    await Bun.sleep(10);
+    d.handleKey("q");
+    expect(calls).toEqual(["stop:ai", "up:*"]);
+    expect(settled).toBe(2);
+    expect(refreshed).toBe(1);
+    expect(panels).toBe(1);
+    expect(quit).toBe(true);
+    d.stop();
+  });
+});

package/src/cli/dev-controls.ts

@@ -0,0 +1,354 @@
+/**
+ * Keyboard controls for a live `oke dev` session (TTY raw mode).
+ *
+ * Keys: `?` help · `q` quit · `c` refresh · `l` list · `u` up all ·
+ * `x` stop all · `1`–`9` select service then `u`/`x`/`r`.
+ *
+ * Compose health / model phase update the status board above Logs — not
+ * the log stream. `c` clears the TTY and reprints the latest board.
+ */
+
+import {
+  formatStatusDot,
+  formatStatusLine,
+  termColorEnabled,
+  termStyle,
+  type DevStatus,
+} from "../term.ts";
+
+/** One Docker service row addressable by a digit key. */
+export type DevControlService = {
+  /** Human label (`ai`, `postgres`). */
+  readonly label: string;
+  /** Compose service name (`ai`, `store-sql`). */
+  readonly serviceName: string;
+};
+
+/** Compose action against zero or more service names. */
+export type DevComposeControlAction = "up" | "stop" | "restart";
+
+/** Options for {@link startDevControls}. */
+export type StartDevControlsOptions = {
+  readonly write: (text: string) => void;
+  /** Called on `q` / Ctrl+C. */
+  readonly onQuit: () => void;
+  /**
+   * Clear the TTY and reprint chrome + latest status board (drops log noise).
+   */
+  readonly onRefresh?: () => void | Promise<void>;
+  /**
+   * Show help / services in a clean pane (typically refresh chrome first so
+   * the panel is not interleaved with request logs).
+   *
+   * @param body - Formatted panel text
+   */
+  readonly onShowPanel?: (body: string) => void | Promise<void>;
+  /**
+   * After a compose up/stop/restart — sync health into the board (no log lines).
+   */
+  readonly onComposeSettled?: () => void | Promise<void>;
+  /** Live service catalogue (unique compose services). */
+  readonly services: () => readonly DevControlService[];
+  /**
+   * Run a compose control action.
+   *
+   * @param action - up / stop / restart
+   * @param serviceNames - Empty → whole stack
+   */
+  readonly composeAction: (
+    action: DevComposeControlAction,
+    serviceNames: readonly string[],
+  ) => Promise<void>;
+  /** Optional live ● status for list view. */
+  readonly statusOf?: (serviceName: string) => DevStatus | undefined;
+  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.
+ *
+ * @param color - Color on/off
+ */
+export function formatDevControlsHint(color: boolean = termColorEnabled()): string {
+  const s = termStyle(color);
+  return (
+    `${s.dim}│${s.reset}  ${s.dim}keys${s.reset}  ` +
+    `${s.cyan}?${s.reset} help · ` +
+    `${s.cyan}c${s.reset} refresh · ` +
+    `${s.cyan}q${s.reset} quit · ` +
+    `${s.cyan}l${s.reset} services · ` +
+    `${s.cyan}u${s.reset} up · ` +
+    `${s.cyan}x${s.reset} stop` +
+    `\n`
+  );
+}
+
+/**
+ * Full help block for `?` / `h`.
+ *
+ * @param color - Color on/off
+ */
+export function formatDevControlsHelp(color: boolean = termColorEnabled()): string {
+  const s = termStyle(color);
+  const bar = `${s.dim}│${s.reset}`;
+  const k = (key: string, meaning: string) =>
+    `${bar}  ${s.cyan}${key.padEnd(6)}${s.reset}  ${s.dim}${meaning}${s.reset}`;
+  return [
+    "",
+    `${s.green}◇${s.reset}  ${s.bold}Keys${s.reset}`,
+    k("?", "help"),
+    k("c", "refresh — clear logs, show latest ●"),
+    k("q", "quit oke dev"),
+    k("l", "list docker services"),
+    k("u", "compose up -d (all)"),
+    k("x", "compose stop (all)"),
+    k("1-9", "select service"),
+    k("… u", "start selected"),
+    k("… x", "stop selected"),
+    k("… r", "restart selected"),
+    k("esc", "clear selection"),
+    bar,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Format a numbered service list for `l`.
+ *
+ * @param services - Catalogue
+ * @param statusOf - Optional ● lookup
+ * @param color - Color on/off
+ * @param selected - Highlighted 1-based index
+ */
+export function formatDevControlsServiceList(
+  services: readonly DevControlService[],
+  statusOf?: (serviceName: string) => DevStatus | undefined,
+  color: boolean = termColorEnabled(),
+  selected?: number,
+): string {
+  const s = termStyle(color);
+  const bar = `${s.dim}│${s.reset}`;
+  if (services.length === 0) {
+    return `${bar}  ${s.dim}no docker services${s.reset}\n`;
+  }
+  const lines = [
+    "",
+    `${s.green}◇${s.reset}  ${s.bold}Services${s.reset}  ${s.dim}1-9 then u/x/r${s.reset}`,
+  ];
+  const max = Math.min(9, services.length);
+  for (let i = 0; i < max; i++) {
+    const svc = services[i]!;
+    const st = statusOf?.(svc.serviceName) ?? "pending";
+    const dot = formatStatusDot(st, color);
+    const num = `${i + 1}`;
+    const mark = selected === i + 1 ? `${s.cyan}>${s.reset}` : " ";
+    lines.push(
+      `${bar}  ${mark}${s.cyan}${num}${s.reset}  ${dot}  ${svc.label.padEnd(12)}  ${s.dim}${svc.serviceName}${s.reset}`,
+    );
+  }
+  if (services.length > 9) {
+    lines.push(`${bar}  ${s.dim}… ${services.length - 9} more (first 9 only)${s.reset}`);
+  }
+  lines.push(bar);
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Parse one raw stdin chunk into a control key (tests / non-TTY inject).
+ *
+ * @param chunk - Raw bytes/string
+ */
+export function parseDevControlKey(chunk: string): string | null {
+  if (chunk.length === 0) return null;
+  if (chunk === "\u0003") return "q"; // Ctrl+C
+  if (chunk === "\u001b") return "esc";
+  const ch = chunk[0]!;
+  if (ch === "?" || ch === "h" || ch === "H") return "?";
+  if (ch === "c" || ch === "C") return "c";
+  if (ch === "q" || ch === "Q") return "q";
+  if (ch === "l" || ch === "L") return "l";
+  if (ch === "u" || ch === "U") return "u";
+  if (ch === "x" || ch === "X") return "x";
+  if (ch === "r" || ch === "R") return "r";
+  if (ch >= "1" && ch <= "9") return ch;
+  return null;
+}
+
+/** Key dispatcher for tests and {@link startDevControls}. */
+export type DevControlDispatcher = {
+  readonly handleKey: (key: string) => void;
+  readonly stop: () => void;
+};
+
+/**
+ * Pure key dispatcher (no stdin) — used by tests and the TTY listener.
+ *
+ * @param opts - Quit / compose / services
+ */
+export function createDevControlDispatcher(opts: StartDevControlsOptions): DevControlDispatcher {
+  const color = opts.color ?? termColorEnabled();
+  let selected: number | null = null;
+  let busy = false;
+  let stopped = false;
+
+  const runAction = async (
+    action: DevComposeControlAction,
+    serviceNames: readonly string[],
+    _label: string,
+  ): Promise<void> => {
+    if (busy) return;
+    busy = true;
+    try {
+      await opts.composeAction(action, serviceNames);
+      await opts.onComposeSettled?.();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      opts.write(formatStatusLine(`${action} failed — ${msg}`, color, "error"));
+    } finally {
+      busy = false;
+    }
+  };
+
+  return {
+    handleKey(key: string): void {
+      if (stopped) return;
+      if (key === "q") {
+        opts.onQuit();
+        return;
+      }
+      if (key === "c") {
+        void Promise.resolve(opts.onRefresh?.()).catch((err: unknown) => {
+          const msg = err instanceof Error ? err.message : String(err);
+          opts.write(formatStatusLine(`refresh failed — ${msg}`, color, "error"));
+        });
+        return;
+      }
+      if (key === "?") {
+        const body = formatDevControlsHelp(color);
+        void Promise.resolve(opts.onShowPanel?.(body) ?? opts.write(body));
+        return;
+      }
+      if (key === "esc") {
+        selected = null;
+        return;
+      }
+      if (key === "l") {
+        const body = formatDevControlsServiceList(
+          opts.services(),
+          opts.statusOf,
+          color,
+          selected ?? undefined,
+        );
+        void Promise.resolve(opts.onShowPanel?.(body) ?? opts.write(body));
+        return;
+      }
+      if (key >= "1" && key <= "9") {
+        const n = Number(key);
+        const list = opts.services();
+        if (n < 1 || n > list.length || n > 9) {
+          opts.write(formatStatusLine(`no service ${n} — press l to list`, color, "pending"));
+          return;
+        }
+        selected = n;
+        const svc = list[n - 1]!;
+        opts.write(
+          formatStatusLine(
+            `selected ${n} ${svc.label} — u start · x stop · r restart · esc`,
+            color,
+            opts.statusOf?.(svc.serviceName) ?? "pending",
+          ),
+        );
+        return;
+      }
+      if (key === "u" || key === "x" || key === "r") {
+        const action: DevComposeControlAction =
+          key === "u" ? "up" : key === "x" ? "stop" : "restart";
+        if (selected !== null) {
+          const list = opts.services();
+          const svc = list[selected - 1];
+          if (!svc) {
+            selected = null;
+            opts.write(formatStatusLine("selection expired — press l", color, "pending"));
+            return;
+          }
+          selected = null;
+          void runAction(action, [svc.serviceName], svc.label);
+          return;
+        }
+        if (key === "r") {
+          opts.write(formatStatusLine("select a service first (l then 1-9)", color, "pending"));
+          return;
+        }
+        void runAction(action, [], "stack");
+      }
+    },
+    stop() {
+      stopped = true;
+    },
+  };
+}
+
+/**
+ * Start raw-mode keyboard controls. No-op when stdin is not a TTY.
+ *
+ * @param opts - Quit / compose / services
+ */
+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
+      }
+    },
+  };
+}
+
+/**
+ * Dedupe stack summary rows into control services (first label wins).
+ *
+ * @param rows - Stack summary services with compose names
+ */
+export function controlServicesFromStack(
+  rows: readonly { readonly label: string; readonly serviceName?: string }[],
+): DevControlService[] {
+  const seen = new Set<string>();
+  const out: DevControlService[] = [];
+  for (const row of rows) {
+    const name = row.serviceName?.trim();
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+    out.push({ label: row.label, serviceName: name });
+  }
+  return out;
+}

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

@@ -30,6 +30,11 @@ export interface DevSchemaSyncOptions {
   readonly pushFn?: (cwd: string, env: ConfigEnv) => Promise<number>;
   /** Derive docker infra without running compose (tests). */
   readonly dryRun?: boolean;
+  /**
+   * Skip the “compose env ready” line — `oke dev -d` already brought the
+   * stack up and prints {@link import("../term.ts").formatStackSummary}.
+   */
+  readonly quietComposeReady?: boolean;
 }
 
 /** Outcome of {@link syncDevSchema}. */
@@ -71,6 +76,7 @@ async function ensureDockerStack(
   cwd: string,
   config: OkeConfig,
   write: (text: string) => void,
+  quietComposeReady = false,
 ): Promise<void> {
   const images = resolveImages(config);
   if (Object.keys(images).length === 0) {
@@ -95,9 +101,11 @@ async function ensureDockerStack(
     host: "127.0.0.1",
   });
   await writeDerivedFiles(derived, resolve(cwd, DEFAULT_DOCKER_DIR), { writeStackEnv: true });
-  write(
-    "oke: docker compose env ready under docker/.env.docker (start containers with `oke dev -d` or docker compose up)\n",
-  );
+  if (!quietComposeReady) {
+    write(
+      "oke: docker compose env ready under docker/.env.docker (start containers with `oke dev -d` or docker compose up)\n",
+    );
+  }
 }
 
 /**
@@ -126,7 +134,7 @@ export async function syncDevSchema(
     if (!config) {
       throw new Error("docker mode: oke.config.ts not found");
     }
-    await ensureDockerStack(cwd, config, write);
+    await ensureDockerStack(cwd, config, write, options.quietComposeReady === true);
   }
 
   const push =