okengine 0.10.2 → 0.11.0

package/src/cli/tui/components/Wordmark.tsx

@@ -0,0 +1,43 @@
+/**
+ * OKE ASCII wordmark — same art as `oke dev` / {@link formatOkeWordmark}.
+ */
+
+import { Box, Text } from "ink";
+import type { ReactElement } from "react";
+import { TUI_BRAND, TUI_MUTED } from "../theme.ts";
+
+/** Plain wordmark lines (no ANSI) — matches `formatOkeWordmark`. */
+export const OKE_WORDMARK_LINES: readonly string[] = [
+  "   ██████╗ ██╗  ██╗███████╗",
+  "  ██╔═══██╗██║ ██╔╝██╔════╝",
+  "  ██║   ██║█████╔╝ █████╗  ",
+  "  ██║   ██║██╔═██╗ ██╔══╝  ",
+  "  ╚██████╔╝██║  ██╗███████╗",
+  "   ╚═════╝ ╚═╝  ╚═╝╚══════╝",
+];
+
+/** Props for {@link Wordmark}. */
+export type WordmarkProps = {
+  readonly version?: string;
+};
+
+/**
+ * Green block-letter OKE + version.
+ *
+ * @param props - Optional pinned version
+ */
+export function Wordmark(props: WordmarkProps): ReactElement {
+  const version = props.version ?? "0.10.3";
+  return (
+    <Box flexDirection="column">
+      {OKE_WORDMARK_LINES.map((line) => (
+        <Text key={line} bold color={TUI_BRAND}>
+          {line}
+        </Text>
+      ))}
+      <Text color={TUI_MUTED}>
+        {"  "}v{version}
+      </Text>
+    </Box>
+  );
+}

package/src/cli/tui/format.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared TUI format helpers.
+ */
+
+/**
+ * Format ms as compact uptime (`4m 21s`).
+ *
+ * @param ms - Elapsed milliseconds
+ */
+export function formatUptime(ms: number): string {
+  const s = Math.max(0, Math.floor(ms / 1000));
+  const m = Math.floor(s / 60);
+  const h = Math.floor(m / 60);
+  if (h > 0) return `${h}h ${m % 60}m`;
+  if (m > 0) return `${m}m ${s % 60}s`;
+  return `${s}s`;
+}
+
+/**
+ * Open a URL in the default browser (best-effort).
+ *
+ * @param url - http(s) URL
+ */
+export async function openUrl(url: string): Promise<void> {
+  const platform = process.platform;
+  const cmd =
+    platform === "darwin"
+      ? ["open", url]
+      : platform === "win32"
+        ? ["cmd", "/c", "start", "", url]
+        : ["xdg-open", url];
+  try {
+    const proc = Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore" });
+    await proc.exited;
+  } catch {
+    // ignore — TUI still shows the link
+  }
+}

package/src/cli/tui/keys.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test";
+import { mapDevControlInput } from "./keys.ts";
+
+describe("mapDevControlInput", () => {
+  test("maps ? r q u x and aliases", () => {
+    expect(mapDevControlInput("?", {})).toBe("?");
+    expect(mapDevControlInput("h", {})).toBe("?");
+    expect(mapDevControlInput("r", {})).toBe("r");
+    expect(mapDevControlInput("q", {})).toBe("q");
+    expect(mapDevControlInput("u", {})).toBe("u");
+    expect(mapDevControlInput("x", {})).toBe("x");
+    expect(mapDevControlInput("c", {})).toBeNull();
+  });
+
+  test("maps Ctrl+C to quit", () => {
+    expect(mapDevControlInput("c", { ctrl: true })).toBe("q");
+  });
+});

package/src/cli/tui/keys.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared keyboard mapping for Ink `useInput` and pure tests.
+ * Parity with legacy `parseDevControlKey` (`? r q u x`).
+ */
+
+/** Dev control action from a keypress. */
+export type DevControlKey = "?" | "r" | "q" | "u" | "x";
+
+/**
+ * Map Ink input (+ ctrl) to a control key.
+ *
+ * @param input - Character from useInput
+ * @param key - Ink key modifiers
+ */
+export function mapDevControlInput(
+  input: string,
+  key: { readonly ctrl?: boolean },
+): DevControlKey | null {
+  if (key.ctrl && input === "c") return "q";
+  if (input === "?" || input === "h" || input === "H") return "?";
+  if (input === "q" || input === "Q") return "q";
+  if (input === "r" || input === "R") return "r";
+  if (input === "u" || input === "U") return "u";
+  if (input === "x" || input === "X") return "x";
+  return null;
+}

package/src/cli/tui/launch.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test";
+import { clearTerminalScreen } from "../../term.ts";
+import { canRenderTui, clearTerminalViewport } from "./launch.ts";
+
+describe("canRenderTui", () => {
+  test("requires stdout.isTTY", () => {
+    expect(canRenderTui({ isTTY: true })).toBe(true);
+    expect(canRenderTui({ isTTY: false })).toBe(false);
+    expect(canRenderTui({})).toBe(false);
+  });
+});
+
+describe("clearTerminalViewport", () => {
+  test("writes the same clear sequence as oke dev", () => {
+    expect(clearTerminalScreen()).toContain("\u001b[2J");
+    expect(typeof clearTerminalViewport).toBe("function");
+  });
+});

package/src/cli/tui/launch.ts

@@ -0,0 +1,57 @@
+/**
+ * Launch the interactive Ink TUI (dynamic-imported from the bin).
+ */
+
+import { clearTerminalScreen } from "../../term.ts";
+import { EXIT_OK, EXIT_RUNTIME, EXIT_USAGE } from "../exit.ts";
+import { formatOkeHelp } from "../registry.ts";
+
+/**
+ * True when stdout can host an interactive Ink app.
+ *
+ * @param stream - stdout-like
+ */
+export function canRenderTui(stream: { readonly isTTY?: boolean } = process.stdout): boolean {
+  return stream.isTTY === true;
+}
+
+/**
+ * Wipe the viewport so boot logs never sit above the Ink frame.
+ */
+export function clearTerminalViewport(): void {
+  process.stdout.write(clearTerminalScreen());
+}
+
+/**
+ * Start the TUI. Call only after {@link canRenderTui} is true.
+ *
+ * @param cwd - Project root
+ */
+export async function launchTui(cwd: string = process.cwd()): Promise<number> {
+  try {
+    clearTerminalViewport();
+    const React = await import("react");
+    const { render } = await import("ink");
+    const { OkeTuiApp } = await import("./App.tsx");
+    const instance = render(React.createElement(OkeTuiApp, { cwd }), {
+      exitOnCtrlC: false,
+    });
+    await instance.waitUntilExit();
+    return EXIT_OK;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const missing =
+      /Cannot find (module|package)|ERR_MODULE_NOT_FOUND|Cannot find package/i.test(msg) ||
+      msg.includes("'ink'") ||
+      msg.includes('"ink"');
+    if (missing) {
+      console.error("oke: interactive TUI requires optional deps `ink` and `react`.");
+      console.error("      bun add ink react");
+      console.error("      Or run `oke --help` / `oke <command>` without the TUI.");
+      console.log(formatOkeHelp());
+      return EXIT_USAGE;
+    }
+    console.error(`oke: TUI failed — ${msg}`);
+    return EXIT_RUNTIME;
+  }
+}

package/src/cli/tui/panels/Dashboard.tsx

@@ -0,0 +1,201 @@
+/**
+ * Landing panel — OKE wordmark, session, aligned services, quick actions.
+ */
+
+import { Box, Text, useInput } from "ink";
+import { useEffect, useState, type ReactElement } from "react";
+import type { FooterStatus } from "../components/StatusBar.tsx";
+import { StatusDot, statusWord } from "../components/StatusDot.tsx";
+import { Wordmark } from "../components/Wordmark.tsx";
+import { formatUptime, openUrl } from "../format.ts";
+import { pollPortSnapshot, type PortSnapshot } from "../state/ports.ts";
+import { TUI_ACCENT, TUI_MUTED, TUI_OK, TUI_WARN } from "../theme.ts";
+
+/** Props for {@link DashboardPanel}. */
+export type DashboardPanelProps = {
+  readonly cwd: string;
+  readonly active: boolean;
+  readonly onJumpPanel: (panelId: string) => void;
+  readonly onStatus: (status: FooterStatus) => void;
+};
+
+const ACTIONS = [
+  { id: "open", label: "[O]pen Console", key: "o" },
+  { id: "mcp", label: "[M]CP Docs", key: "m" },
+  { id: "dev", label: "[D]ev Panel", key: "d" },
+] as const;
+
+/**
+ * Dashboard panel — polls ports every 1.5s.
+ *
+ * @param props - cwd + focus/actions
+ */
+export function DashboardPanel(props: DashboardPanelProps): ReactElement {
+  const [snap, setSnap] = useState<PortSnapshot | null>(null);
+  const [startedAt, setStartedAt] = useState<number | null>(null);
+  const [now, setNow] = useState(Date.now());
+  const [selected, setSelected] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    const tick = async (): Promise<void> => {
+      const next = await pollPortSnapshot(props.cwd);
+      if (cancelled) return;
+      setSnap(next);
+      if (next.ownership === "managed") {
+        setStartedAt((prev) => prev ?? Date.now());
+      } else {
+        setStartedAt(null);
+      }
+      setNow(Date.now());
+    };
+    void tick();
+    const id = setInterval(() => void tick(), 1500);
+    return () => {
+      cancelled = true;
+      clearInterval(id);
+    };
+  }, [props.cwd]);
+
+  // Prefer lock startedAt when available via re-read
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      const { readDevSessionLock } = await import("../../dev-session-lock.ts");
+      const lock = await readDevSessionLock(props.cwd);
+      if (!cancelled && lock) {
+        const t = Date.parse(lock.startedAt);
+        if (Number.isFinite(t)) setStartedAt(t);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [props.cwd, snap?.ownership]);
+
+  useInput(
+    (input, key) => {
+      if (!props.active) return;
+      if (key.upArrow) setSelected((i) => Math.max(0, i - 1));
+      if (key.downArrow) setSelected((i) => Math.min(ACTIONS.length - 1, i + 1));
+      const lower = input.toLowerCase();
+      if (lower === "o") void runAction("open");
+      else if (lower === "m") void runAction("mcp");
+      else if (lower === "d") void runAction("dev");
+      else if (key.return) {
+        const a = ACTIONS[selected];
+        if (a) void runAction(a.id);
+      }
+    },
+    { isActive: props.active },
+  );
+
+  const runAction = async (id: (typeof ACTIONS)[number]["id"]): Promise<void> => {
+    if (id === "dev") {
+      props.onJumpPanel("dev");
+      return;
+    }
+    const consoleSurf = snap?.surfaces.find((s) => s.id === "console");
+    const docsSurf = snap?.surfaces.find((s) => s.id === "docsMcp");
+    if (id === "open") {
+      const url = consoleSurf?.url ?? "http://127.0.0.1:6533";
+      props.onStatus({ kind: "running", label: `Opening ${url}…` });
+      await openUrl(url);
+      props.onStatus({ kind: "done", label: "Opened Console" });
+      return;
+    }
+    const url = docsSurf?.url ?? "http://127.0.0.1:6536";
+    props.onStatus({ kind: "running", label: `Opening ${url}…` });
+    await openUrl(url);
+    props.onStatus({ kind: "done", label: "Opened MCP Docs" });
+  };
+
+  const ownership = snap?.ownership ?? "stopped";
+  const ownershipLabel =
+    ownership === "managed"
+      ? "Managed"
+      : ownership === "external"
+        ? "Connected (external)"
+        : "Stopped";
+  const ownershipColor = ownership === "managed" || ownership === "external" ? TUI_OK : TUI_WARN;
+  const uptime = startedAt && ownership === "managed" ? formatUptime(now - startedAt) : null;
+
+  return (
+    <Box flexDirection="column" gap={1} flexGrow={1}>
+      <Box justifyContent="space-between" alignItems="flex-start">
+        <Wordmark version="0.10.3" />
+      </Box>
+
+      <Box flexDirection="column">
+        <Text bold color={TUI_ACCENT}>
+          Session
+        </Text>
+        <Box gap={1}>
+          <StatusDot
+            status={ownership === "managed" || ownership === "external" ? "ready" : "idle"}
+          />
+          <Text bold color={ownershipColor}>
+            {ownershipLabel}
+          </Text>
+          {uptime ? <Text color={TUI_MUTED}>· uptime {uptime}</Text> : null}
+        </Box>
+        {ownership === "external" ? (
+          <Text color={TUI_WARN}>Read-only — will not start a second stack</Text>
+        ) : null}
+        {ownership === "stopped" ? (
+          <Text color={TUI_MUTED}>No live oke dev — press [D] or open Dev panel</Text>
+        ) : null}
+      </Box>
+
+      <Box flexDirection="column" flexGrow={1}>
+        <Box>
+          <Box width={14}>
+            <Text bold color={TUI_ACCENT}>
+              Services
+            </Text>
+          </Box>
+          <Box width={8}>
+            <Text color={TUI_MUTED}>Port</Text>
+          </Box>
+          <Box width={10}>
+            <Text color={TUI_MUTED}>Status</Text>
+          </Box>
+          <Text color={TUI_MUTED}>URL</Text>
+        </Box>
+        <Text color={TUI_MUTED}>{"─".repeat(56)}</Text>
+        {(snap?.surfaces ?? []).map((s) => {
+          const sw = statusWord(s.status);
+          return (
+            <Box key={s.id}>
+              <Box width={14} gap={1}>
+                <StatusDot status={s.status} />
+                <Text>{s.label.padEnd(9)}</Text>
+              </Box>
+              <Box width={8}>
+                <Text color={TUI_ACCENT}>{`:${String(s.port).padEnd(5)}`}</Text>
+              </Box>
+              <Box width={10}>
+                <Text color={sw.color}>{sw.word}</Text>
+              </Box>
+              <Text color={TUI_MUTED}>{s.url}</Text>
+            </Box>
+          );
+        })}
+        {!snap ? <Text color={TUI_MUTED}>Probing ports…</Text> : null}
+      </Box>
+
+      <Box gap={2}>
+        {ACTIONS.map((a, i) => (
+          <Text
+            key={a.id}
+            bold={props.active && i === selected}
+            color={props.active && i === selected ? TUI_ACCENT : TUI_MUTED}
+          >
+            {props.active && i === selected ? "› " : "  "}
+            {a.label}
+          </Text>
+        ))}
+      </Box>
+    </Box>
+  );
+}

package/src/cli/tui/panels/Database.tsx

@@ -0,0 +1,198 @@
+/**
+ * Database panel — 3-column action cards, no nested footer.
+ */
+
+import { Box, Text, useInput } from "ink";
+import { useState, type ReactElement } from "react";
+import { ConfirmDialog } from "../components/ConfirmDialog.tsx";
+import type { FooterStatus } from "../components/StatusBar.tsx";
+import { TUI_ACCENT, TUI_MUTED, TUI_WARN } from "../theme.ts";
+
+/** Props for {@link DatabasePanel}. */
+export type DatabasePanelProps = {
+  readonly cwd: string;
+  readonly active: boolean;
+  readonly onLog: (line: string) => void;
+  readonly onStatus: (status: FooterStatus) => void;
+};
+
+type DbAction = "push" | "generate" | "migrate" | "seed" | "studio";
+
+type Card = {
+  readonly id: DbAction;
+  readonly key: string;
+  readonly title: string;
+  readonly blurb: string;
+  readonly confirm: boolean;
+};
+
+const CARDS: readonly Card[] = [
+  {
+    id: "push",
+    key: "P",
+    title: "Push",
+    blurb: "sync schema → live DB",
+    confirm: true,
+  },
+  {
+    id: "generate",
+    key: "G",
+    title: "Generate",
+    blurb: "write SQL under drizzle/",
+    confirm: false,
+  },
+  {
+    id: "migrate",
+    key: "M",
+    title: "Migrate",
+    blurb: "apply pending migrations",
+    confirm: true,
+  },
+  {
+    id: "seed",
+    key: "E",
+    title: "Seed",
+    blurb: "run defineSeed",
+    confirm: true,
+  },
+  {
+    id: "studio",
+    key: "T",
+    title: "Studio",
+    blurb: "drizzle-kit (browser)",
+    confirm: false,
+  },
+];
+
+/**
+ * Database actions as a selectable card grid.
+ *
+ * @param props - cwd + log sink
+ */
+export function DatabasePanel(props: DatabasePanelProps): ReactElement {
+  const [selected, setSelected] = useState(0);
+  const [pending, setPending] = useState<DbAction | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  useInput(
+    (input, key) => {
+      if (!props.active || pending || busy) return;
+      if (key.leftArrow) setSelected((i) => Math.max(0, i - 1));
+      if (key.rightArrow) setSelected((i) => Math.min(CARDS.length - 1, i + 1));
+      if (key.upArrow) setSelected((i) => Math.max(0, i - 3));
+      if (key.downArrow) setSelected((i) => Math.min(CARDS.length - 1, i + 3));
+      const upper = input.toUpperCase();
+      const byKey = CARDS.findIndex((c) => c.key === upper);
+      if (byKey >= 0) {
+        setSelected(byKey);
+        const card = CARDS[byKey]!;
+        if (card.confirm) setPending(card.id);
+        else void run(card.id);
+        return;
+      }
+      if (key.return) {
+        const action = CARDS[selected];
+        if (!action) return;
+        if (action.confirm) setPending(action.id);
+        else void run(action.id);
+      }
+    },
+    { isActive: props.active && !pending && !busy },
+  );
+
+  const run = async (id: DbAction): Promise<void> => {
+    setBusy(true);
+    setPending(null);
+    props.onStatus({ kind: "running", label: `Running oke db ${id}…` });
+    props.onLog(`oke db ${id}\n`);
+    const prevCwd = process.cwd();
+    try {
+      process.chdir(props.cwd);
+      const { dbCli } = await import("../../db.ts");
+      const writes: string[] = [];
+      const origLog = console.log;
+      const origErr = console.error;
+      console.log = (...args: unknown[]) => {
+        writes.push(args.map(String).join(" ") + "\n");
+      };
+      console.error = (...args: unknown[]) => {
+        writes.push(args.map(String).join(" ") + "\n");
+      };
+      let code = 1;
+      try {
+        code = await dbCli([id, "--force"]);
+      } finally {
+        console.log = origLog;
+        console.error = origErr;
+      }
+      for (const w of writes) props.onLog(w);
+      props.onStatus({
+        kind: "done",
+        label: code === 0 ? `db ${id} ok` : `db ${id} exited ${code}`,
+      });
+    } catch (err) {
+      const m = err instanceof Error ? err.message : String(err);
+      props.onLog(`${m}\n`);
+      props.onStatus({ kind: "done", label: m });
+    } finally {
+      process.chdir(prevCwd);
+      setBusy(false);
+    }
+  };
+
+  if (pending) {
+    return (
+      <ConfirmDialog
+        message={`Run oke db ${pending}? This may change the live database.`}
+        onConfirm={() => void run(pending)}
+        onCancel={() => setPending(null)}
+      />
+    );
+  }
+
+  const row1 = CARDS.slice(0, 3);
+  const row2 = CARDS.slice(3);
+
+  return (
+    <Box flexDirection="column" gap={1} flexGrow={1}>
+      <Text bold color={TUI_ACCENT}>
+        Database
+      </Text>
+      <Text color={TUI_MUTED} dimColor>
+        Domain schema via drizzle-kit
+      </Text>
+      <Box gap={1}>
+        {row1.map((card, i) => (
+          <ActionCard key={card.id} card={card} selected={props.active && selected === i} />
+        ))}
+      </Box>
+      <Box gap={1}>
+        {row2.map((card, i) => (
+          <ActionCard key={card.id} card={card} selected={props.active && selected === i + 3} />
+        ))}
+      </Box>
+      <Text color={TUI_WARN}>! Push & Migrate modify the database — confirmation required</Text>
+    </Box>
+  );
+}
+
+/**
+ * One database action card.
+ */
+function ActionCard(props: { readonly card: Card; readonly selected: boolean }): ReactElement {
+  const { card, selected } = props;
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="single"
+      borderColor={selected ? TUI_ACCENT : TUI_MUTED}
+      width="32%"
+      paddingX={1}
+    >
+      <Text bold color={selected ? TUI_ACCENT : undefined}>
+        {selected ? "› " : "  "}[{card.key}] {card.title}
+      </Text>
+      <Text color={TUI_MUTED}>{card.blurb}</Text>
+    </Box>
+  );
+}