okengine 0.10.3 → 0.11.0

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

@@ -0,0 +1,172 @@
+/**
+ * `/` command palette — autofill over the full `oke` CLI + panel jumps.
+ */
+
+import { Box, Text, useInput } from "ink";
+import { useMemo, useState, type ReactElement } from "react";
+import {
+  commonPrefix,
+  filterSlashActions,
+  parseSlashArgv,
+  type SlashAction,
+} from "../slash-catalog.ts";
+import { TUI_BRAND, TUI_HINT, TUI_MUTED, TUI_OK, TUI_WARN } from "../theme.ts";
+
+/** Props for {@link SlashPalette}. */
+export type SlashPaletteProps = {
+  readonly cwd: string;
+  readonly onClose: () => void;
+  readonly onJumpPanel: (panelId: string) => void;
+  readonly onRunCli: (argv: readonly string[]) => void | Promise<void>;
+  readonly busy?: boolean;
+};
+
+/**
+ * Slash palette overlay — type to filter, Tab autofills, Enter runs.
+ *
+ * @param props - Callbacks
+ */
+export function SlashPalette(props: SlashPaletteProps): ReactElement {
+  const [query, setQuery] = useState("");
+  const [selected, setSelected] = useState(0);
+  const [status, setStatus] = useState("");
+
+  const matches = useMemo(() => filterSlashActions(query, 14), [query]);
+  const sel = Math.min(selected, Math.max(0, matches.length - 1));
+  const active = matches[sel] ?? null;
+
+  useInput(
+    (input, key) => {
+      if (props.busy) return;
+
+      if (key.escape) {
+        props.onClose();
+        return;
+      }
+
+      if (key.upArrow) {
+        setSelected((i) => Math.max(0, i - 1));
+        return;
+      }
+      if (key.downArrow) {
+        setSelected((i) => Math.min(Math.max(0, matches.length - 1), i + 1));
+        return;
+      }
+
+      if (key.tab) {
+        if (active) {
+          const ids = matches.map((m) => m.id);
+          const prefix = commonPrefix(ids);
+          const next =
+            prefix.length > query.length && ids.every((id) => id.startsWith(prefix))
+              ? prefix
+              : active.id;
+          setQuery(next);
+          setSelected(0);
+          setStatus(`autofill → /${next}`);
+        }
+        return;
+      }
+
+      if (key.return) {
+        void submit(active, query);
+        return;
+      }
+
+      if (key.backspace || key.delete) {
+        setQuery((q) => q.slice(0, -1));
+        setSelected(0);
+        setStatus("");
+        return;
+      }
+
+      if (!input || key.ctrl || key.meta) return;
+      // Ignore a second leading `/`; otherwise append printable chars.
+      if (input === "/" && query.length === 0) return;
+      setQuery((q) => q + input);
+      setSelected(0);
+      setStatus("");
+    },
+    { isActive: true },
+  );
+
+  const submit = async (action: SlashAction | null, raw: string): Promise<void> => {
+    if (action?.kind === "panel" && action.panel) {
+      props.onJumpPanel(action.panel);
+      props.onClose();
+      return;
+    }
+
+    if (action?.kind === "cli" && action.argv) {
+      const typed = parseSlashArgv(raw);
+      const base = action.argv;
+      // Append trailing free tokens the user typed beyond the suggestion.
+      let argv: readonly string[] = base;
+      if (typed.length > base.length && typed.slice(0, base.length).join(" ") === base.join(" ")) {
+        argv = typed;
+      }
+      setStatus(`running oke ${argv.join(" ")}…`);
+      await props.onRunCli(argv);
+      props.onClose();
+      return;
+    }
+
+    const argv = parseSlashArgv(raw);
+    if (argv.length === 0) {
+      setStatus("type a command · Tab to autofill");
+      return;
+    }
+    setStatus(`running oke ${argv.join(" ")}…`);
+    await props.onRunCli(argv);
+    props.onClose();
+  };
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={TUI_BRAND}
+      paddingX={1}
+      width="100%"
+      flexGrow={1}
+    >
+      <Box>
+        <Text bold color={TUI_BRAND}>
+          /
+        </Text>
+        <Text bold>{query}</Text>
+        <Text color={TUI_BRAND}>█</Text>
+        <Text color={TUI_MUTED}> Tab autofill · ↑↓ · Enter run · Esc</Text>
+      </Box>
+
+      <Box flexDirection="column" marginTop={1} flexGrow={1}>
+        {matches.length === 0 ? (
+          <Text color={TUI_WARN}>No matches — Enter runs free-form `oke …`</Text>
+        ) : (
+          matches.map((m, i) => {
+            const on = i === sel;
+            return (
+              <Box key={m.id} gap={1}>
+                <Text bold={on} color={on ? TUI_BRAND : TUI_MUTED}>
+                  {on ? "›" : " "}
+                </Text>
+                <Text bold={on} color={on ? TUI_BRAND : undefined}>
+                  /{m.label}
+                </Text>
+                <Text color={m.kind === "panel" ? TUI_OK : TUI_MUTED}>
+                  {m.kind === "panel" ? "panel" : "cli"}
+                </Text>
+                <Text color={TUI_MUTED} wrap="truncate">
+                  {m.summary}
+                </Text>
+              </Box>
+            );
+          })
+        )}
+      </Box>
+
+      {status ? <Text color={TUI_HINT}>{status}</Text> : null}
+      {props.busy ? <Text color={TUI_WARN}>Running…</Text> : null}
+    </Box>
+  );
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Lightweight terminal spinner (no extra deps).
+ */
+
+import { Text } from "ink";
+import { useEffect, useState, type ReactElement } from "react";
+import { TUI_WARN } from "../theme.ts";
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+
+/** Props for {@link Spinner}. */
+export type SpinnerProps = {
+  readonly label?: string;
+};
+
+/**
+ * Animated spinner + optional label.
+ *
+ * @param props - Label
+ */
+export function Spinner(props: SpinnerProps): ReactElement {
+  const [i, setI] = useState(0);
+  useEffect(() => {
+    const id = setInterval(() => setI((n) => (n + 1) % FRAMES.length), 80);
+    return () => clearInterval(id);
+  }, []);
+  return (
+    <Text color={TUI_WARN}>
+      {FRAMES[i]} {props.label ?? "Working…"}
+    </Text>
+  );
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Single global footer — shortcuts + transient action status (no own border;
+ * the app chrome already frames the shell).
+ */
+
+import { Box, Text } from "ink";
+import type { ReactElement } from "react";
+import { Spinner } from "./Spinner.tsx";
+import { TUI_HINT, TUI_MUTED, TUI_OK } from "../theme.ts";
+
+/** Footer mode. */
+export type FooterStatus =
+  | { readonly kind: "idle" }
+  | { readonly kind: "running"; readonly label: string }
+  | { readonly kind: "done"; readonly label?: string };
+
+/** Props for {@link StatusBar}. */
+export type StatusBarProps = {
+  readonly status?: FooterStatus;
+  readonly hints?: string;
+};
+
+/**
+ * Shortcut strip + optional running/done feedback.
+ *
+ * @param props - Status + hints
+ */
+export function StatusBar(props: StatusBarProps): ReactElement {
+  const hints =
+    props.hints ?? "/ command · Tab panels · ↑↓ navigate · Enter action · 1-5 jump · Esc";
+  const status = props.status ?? { kind: "idle" as const };
+
+  return (
+    <Box paddingX={1} paddingY={0} marginTop={0} justifyContent="space-between">
+      <Box>
+        {status.kind === "running" ? (
+          <Spinner label={status.label} />
+        ) : status.kind === "done" ? (
+          <Text color={TUI_OK}>✓ {status.label ?? "Done"}</Text>
+        ) : (
+          <Text color={TUI_HINT}>{hints}</Text>
+        )}
+      </Box>
+      {status.kind !== "idle" ? (
+        <Text color={TUI_MUTED} dimColor>
+          {hints}
+        </Text>
+      ) : null}
+    </Box>
+  );
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Ink readiness glyph for {@link DevStatus}.
+ */
+
+import { Text } from "ink";
+import type { ReactElement } from "react";
+import type { DevStatus } from "../../../term.ts";
+import { TUI_ERR, TUI_OK, TUI_WARN } from "../theme.ts";
+
+/** Props for {@link StatusDot}. */
+export type StatusDotProps = {
+  readonly status: DevStatus;
+};
+
+/**
+ * ● online/pending/error · ○ offline (yellow/red, not gray).
+ *
+ * @param props - Status
+ */
+export function StatusDot(props: StatusDotProps): ReactElement {
+  if (props.status === "idle") {
+    return <Text color={TUI_WARN}>○</Text>;
+  }
+  const color = props.status === "ready" ? TUI_OK : props.status === "pending" ? TUI_WARN : TUI_ERR;
+  return <Text color={color}>●</Text>;
+}
+
+/** Fixed-width status word. */
+export function statusWord(status: DevStatus): {
+  readonly word: string;
+  readonly color: typeof TUI_OK | typeof TUI_WARN | typeof TUI_ERR;
+} {
+  if (status === "ready") return { word: "online ", color: TUI_OK };
+  if (status === "pending") return { word: "start  ", color: TUI_WARN };
+  if (status === "error") return { word: "error  ", color: TUI_ERR };
+  return { word: "offline", color: TUI_WARN };
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Top-level panel tabs — green active chip, no enclosing border.
+ */
+
+import { Box, Text } from "ink";
+import type { ReactElement } from "react";
+import { TUI_BRAND, TUI_MUTED } from "../theme.ts";
+
+/** One tab descriptor. */
+export type TabItem = {
+  readonly id: string;
+  readonly label: string;
+};
+
+/** Props for {@link TabBar}. */
+export type TabBarProps = {
+  readonly tabs: readonly TabItem[];
+  readonly activeIndex: number;
+  /** When true, tab strip owns focus (reserved for future emphasis). */
+  readonly focused?: boolean;
+};
+
+/**
+ * Horizontal tab bar.
+ *
+ * @param props - Tabs + selection
+ */
+export function TabBar(props: TabBarProps): ReactElement {
+  return (
+    <Box paddingX={1} gap={0}>
+      {props.tabs.map((tab, i) => {
+        const active = i === props.activeIndex;
+        const label = `  ${i + 1} ${tab.label}  `;
+        if (active) {
+          return (
+            <Text key={tab.id} backgroundColor={TUI_BRAND} color="black" bold>
+              {label}
+            </Text>
+          );
+        }
+        return (
+          <Text key={tab.id} color={TUI_MUTED}>
+            {label}
+          </Text>
+        );
+      })}
+    </Box>
+  );
+}

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;
+  }
+}