@hoox-sh/hoox-tui 0.2.0

package/src/services/cli-bridge.test.ts

@@ -0,0 +1,406 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Tests for validateReadOnlySql — the client-side read-only SQL validator.
+ *
+ * Validates the security guarantees of the db-query view:
+ *   - SELECT / WITH / EXPLAIN are allowed
+ *   - INSERT / UPDATE / DELETE / DROP / CREATE / ALTER / TRUNCATE / PRAGMA
+ *     / ATTACH / DETACH / VACUUM / REINDEX are rejected
+ *   - Multi-statement payloads (semicolons with content after) are rejected
+ *   - Empty/whitespace-only input is rejected
+ *   - Comment-only input is rejected
+ *   - Mixed-case variants are handled case-insensitively
+ *   - String literals and comments are stripped before keyword check
+ */
+import { describe, it, expect } from "bun:test";
+import {
+  validateReadOnlySql,
+  tryParseJsonLoose,
+  sanitizeCliArgsForLog,
+  type SqlValidationResult,
+} from "./cli-bridge";
+
+// ─── Helper ───────────────────────────────────────────────────────────────────
+
+function isValid(sql: string): boolean {
+  return validateReadOnlySql(sql).readonly;
+}
+
+function rejectReason(sql: string): string {
+  const result = validateReadOnlySql(sql);
+  return result.readonly ? "" : (result as { reason: string }).reason;
+}
+
+// ─── Allowed entry points ─────────────────────────────────────────────────────
+
+describe("validateReadOnlySql — allowed entry points", () => {
+  it("accepts simple SELECT", () => {
+    expect(isValid("SELECT * FROM users")).toBe(true);
+  });
+
+  it("accepts SELECT with WHERE clause", () => {
+    expect(isValid("SELECT id, name FROM users WHERE active = 1")).toBe(true);
+  });
+
+  it("accepts SELECT with JOIN", () => {
+    expect(
+      isValid(
+        "SELECT u.name, o.total FROM users u JOIN orders o ON u.id = o.user_id"
+      )
+    ).toBe(true);
+  });
+
+  it("accepts SELECT with subquery", () => {
+    expect(
+      isValid(
+        "SELECT * FROM (SELECT id, name FROM users WHERE active = 1) AS active_users"
+      )
+    ).toBe(true);
+  });
+
+  it("accepts WITH ... SELECT (CTE)", () => {
+    expect(
+      isValid(
+        "WITH active_users AS (SELECT * FROM users WHERE active = 1) SELECT * FROM active_users"
+      )
+    ).toBe(true);
+  });
+
+  it("accepts EXPLAIN SELECT", () => {
+    expect(isValid("EXPLAIN SELECT * FROM users")).toBe(true);
+  });
+
+  it("accepts EXPLAIN QUERY PLAN", () => {
+    expect(isValid("EXPLAIN QUERY PLAN SELECT * FROM users")).toBe(true);
+  });
+
+  it("accepts SELECT with LIMIT", () => {
+    expect(isValid("SELECT * FROM migrations ORDER BY id DESC LIMIT 5")).toBe(
+      true
+    );
+  });
+
+  it("accepts SELECT from sqlite_master", () => {
+    expect(
+      isValid(
+        "SELECT name, sql FROM sqlite_master WHERE type = 'table' ORDER BY name"
+      )
+    ).toBe(true);
+  });
+});
+
+// ─── Forbidden keywords ────────────────────────────────────────────────────────
+
+describe("validateReadOnlySql — forbidden keywords", () => {
+  // INSERT
+  it("rejects INSERT", () => {
+    expect(isValid("INSERT INTO users (name) VALUES ('test')")).toBe(false);
+  });
+  it("rejects INSERT as first token (uppercase)", () => {
+    expect(isValid("INSERT INTO users VALUES (1)")).toBe(false);
+  });
+  it("rejects insert (lowercase)", () => {
+    expect(isValid("insert into users values (1)")).toBe(false);
+  });
+
+  // UPDATE
+  it("rejects UPDATE", () => {
+    expect(isValid("UPDATE users SET name = 'test' WHERE id = 1")).toBe(false);
+  });
+  it("rejects update (lowercase)", () => {
+    expect(isValid("update users set name = 'test' where id = 1")).toBe(false);
+  });
+
+  // DELETE
+  it("rejects DELETE", () => {
+    expect(isValid("DELETE FROM users WHERE id = 1")).toBe(false);
+  });
+  it("rejects delete (lowercase)", () => {
+    expect(isValid("delete from users where id = 1")).toBe(false);
+  });
+
+  // REPLACE
+  it("rejects REPLACE", () => {
+    expect(isValid("REPLACE INTO users (id, name) VALUES (1, 'test')")).toBe(
+      false
+    );
+  });
+
+  // DROP
+  it("rejects DROP TABLE", () => {
+    expect(isValid("DROP TABLE users")).toBe(false);
+  });
+  it("rejects DROP INDEX", () => {
+    expect(isValid("DROP INDEX idx_users")).toBe(false);
+  });
+
+  // CREATE
+  it("rejects CREATE TABLE", () => {
+    expect(isValid("CREATE TABLE test (id INTEGER PRIMARY KEY)")).toBe(false);
+  });
+  it("rejects CREATE INDEX", () => {
+    expect(isValid("CREATE INDEX idx ON users(name)")).toBe(false);
+  });
+  it("rejects CREATE VIEW", () => {
+    expect(isValid("CREATE VIEW v AS SELECT * FROM users")).toBe(false);
+  });
+
+  // ALTER
+  it("rejects ALTER TABLE", () => {
+    expect(isValid("ALTER TABLE users ADD COLUMN email TEXT")).toBe(false);
+  });
+
+  // TRUNCATE
+  it("rejects TRUNCATE", () => {
+    expect(isValid("TRUNCATE TABLE users")).toBe(false);
+  });
+
+  // PRAGMA
+  it("rejects PRAGMA", () => {
+    expect(isValid("PRAGMA journal_mode=WAL")).toBe(false);
+  });
+  it("rejects pragma (lowercase)", () => {
+    expect(isValid("pragma journal_mode")).toBe(false);
+  });
+
+  // ATTACH
+  it("rejects ATTACH", () => {
+    expect(isValid("ATTACH DATABASE '/tmp/test.db' AS test")).toBe(false);
+  });
+
+  // DETACH
+  it("rejects DETACH", () => {
+    expect(isValid("DETACH DATABASE test")).toBe(false);
+  });
+
+  // VACUUM
+  it("rejects VACUUM", () => {
+    expect(isValid("VACUUM")).toBe(false);
+  });
+
+  // REINDEX
+  it("rejects REINDEX", () => {
+    expect(isValid("REINDEX")).toBe(false);
+  });
+
+  // Forbidden keyword mixed into a valid-looking SELECT (injection attempt)
+  it("rejects SELECT with DROP in string literal", () => {
+    // The validator strips string literals before checking, so embedded
+    // keywords in string literals should not trigger rejection.
+    // However, the whole-statement check should still reject if the
+    // keyword appears outside strings/comments.
+    expect(isValid("SELECT 'DROP TABLE users'")).toBe(true); // keyword is inside string
+  });
+
+  it("rejects SELECT with forbidden keyword after string literal", () => {
+    // Keyword outside string → must be rejected
+    expect(isValid("SELECT 'hello' FROM users; DROP TABLE users")).toBe(false);
+  });
+});
+
+// ─── Comment stripping ────────────────────────────────────────────────────────
+
+describe("validateReadOnlySql — comment stripping", () => {
+  it("accepts SELECT with trailing line comment", () => {
+    expect(isValid("SELECT * FROM users -- this is a comment")).toBe(true);
+  });
+
+  it("accepts SELECT with inline line comment", () => {
+    expect(isValid("SELECT * FROM users -- comment\nWHERE id = 1")).toBe(true);
+  });
+
+  it("accepts SELECT with block comment", () => {
+    expect(isValid("SELECT /* comment */ * FROM users")).toBe(true);
+  });
+
+  it("rejects INSERT hidden in block comment prefix", () => {
+    // The first significant token is read from the stripped+string-stripped
+    // input. Block comments are stripped first, so "INSERT /* ... */ INTO"
+    // should still be caught.
+    // Actual behaviour: "INSERT" is the first token after block comment
+    // stripping → rejected. This tests the defence-in-depth property.
+    expect(isValid("INSERT /* comment */ INTO users VALUES (1)")).toBe(false);
+  });
+
+  it("rejects comment-only input", () => {
+    expect(isValid("-- just a comment")).toBe(false);
+    expect(isValid("/* block comment */")).toBe(false);
+  });
+});
+
+// ─── String literal stripping ──────────────────────────────────────────────────
+
+describe("validateReadOnlySql — string literal stripping", () => {
+  it("accepts SELECT with string literal containing keyword", () => {
+    // Keywords inside single-quoted strings should be stripped and not
+    // cause false positives.
+    expect(isValid("SELECT 'INSERT' FROM users")).toBe(true);
+  });
+
+  it("accepts SELECT with double-quoted identifier containing keyword", () => {
+    expect(isValid('SELECT "DROP" FROM users')).toBe(true);
+  });
+
+  it("rejects keyword that appears after string literal end", () => {
+    expect(isValid("SELECT 'x' FROM users; DROP TABLE users")).toBe(false);
+  });
+});
+
+// ─── Multi-statement rejection ─────────────────────────────────────────────────
+
+describe("validateReadOnlySql — multi-statement rejection", () => {
+  it("rejects two SELECTs with semicolon", () => {
+    expect(isValid("SELECT 1; SELECT 2")).toBe(false);
+  });
+
+  it("rejects SELECT then DROP with semicolon", () => {
+    expect(isValid("SELECT * FROM users; DROP TABLE users")).toBe(false);
+  });
+
+  it("rejects SELECT with trailing semicolon (allowed)", () => {
+    expect(isValid("SELECT * FROM users;")).toBe(true);
+  });
+
+  it("rejects SELECT with semicolon and trailing whitespace (allowed)", () => {
+    expect(isValid("SELECT * FROM users;   ")).toBe(true);
+  });
+
+  it("rejects SELECT with semicolon and extra statement after", () => {
+    expect(isValid("SELECT * FROM users; SELECT 2")).toBe(false);
+  });
+
+  it("rejects multiple semicolons", () => {
+    expect(isValid("SELECT 1;; SELECT 2")).toBe(false);
+  });
+});
+
+// ─── Empty / whitespace input ─────────────────────────────────────────────────
+
+describe("validateReadOnlySql — empty and whitespace input", () => {
+  it("rejects empty string", () => {
+    expect(isValid("")).toBe(false);
+  });
+
+  it("rejects whitespace-only string", () => {
+    expect(isValid("   ")).toBe(false);
+    expect(isValid("\t\n")).toBe(false);
+  });
+
+  it("rejects newlines only", () => {
+    expect(isValid("\n\n")).toBe(false);
+  });
+});
+
+// ─── Result shape ─────────────────────────────────────────────────────────────
+
+describe("validateReadOnlySql — result shape", () => {
+  it("returns {readonly: true} for valid SQL", () => {
+    const result = validateReadOnlySql("SELECT * FROM users");
+    expect(result.readonly).toBe(true);
+  });
+
+  it("returns {readonly: false, reason: string} for invalid SQL", () => {
+    const result = validateReadOnlySql("DROP TABLE users");
+    expect(result.readonly).toBe(false);
+    expect(typeof (result as { reason: string }).reason).toBe("string");
+    expect((result as { reason: string }).reason.length).toBeGreaterThan(0);
+  });
+
+  it("returns a non-empty reason for forbidden keyword", () => {
+    const result = validateReadOnlySql("INSERT INTO users VALUES (1)");
+    expect(result.readonly).toBe(false);
+    expect((result as { reason: string }).reason).toContain("INSERT");
+  });
+});
+
+// ─── Edge cases ───────────────────────────────────────────────────────────────
+
+describe("validateReadOnlySql — edge cases", () => {
+  it("handles SQL with leading whitespace", () => {
+    expect(isValid("   SELECT * FROM users")).toBe(true);
+  });
+
+  it("handles SQL with leading parenthesis", () => {
+    expect(isValid("(SELECT * FROM users)")).toBe(true);
+  });
+
+  it("handles long valid SQL without issues", () => {
+    const longSql =
+      "SELECT u.id, u.name, o.total, o.created_at " +
+      "FROM users u " +
+      "JOIN orders o ON u.id = o.user_id " +
+      "WHERE u.active = 1 AND o.total > 100 " +
+      "ORDER BY o.created_at DESC LIMIT 50";
+    expect(isValid(longSql)).toBe(true);
+  });
+
+  it("handles unicode in SQL (emoji in string)", () => {
+    expect(isValid("SELECT '🚀' FROM users")).toBe(true);
+  });
+
+  it("handles backslash in string literal", () => {
+    expect(isValid("SELECT 'C:\\Users\\test' FROM users")).toBe(true);
+  });
+
+  it("handles escaped single quote in string", () => {
+    expect(isValid("SELECT name FROM users WHERE name = 'O''Brien'")).toBe(
+      true
+    );
+  });
+
+  it("handles doubled single quotes (SQL standard escape)", () => {
+    expect(isValid("SELECT 'it''s fine' FROM users")).toBe(true);
+  });
+});
+
+// ─── Robust JSON + secret redaction helpers ───────────────────────────────────
+
+describe("tryParseJsonLoose", () => {
+  it("parses clean JSON", () => {
+    expect(tryParseJsonLoose('{"ok":true}')).toEqual({ ok: true });
+    expect(tryParseJsonLoose("[1,2]")).toEqual([1, 2]);
+  });
+
+  it("parses JSON after leading noise lines", () => {
+    const noisy = 'Fetching queues…\n{\n  "queues": []\n}\n';
+    expect(tryParseJsonLoose(noisy)).toEqual({ queues: [] });
+  });
+
+  it("returns null on empty or garbage", () => {
+    expect(tryParseJsonLoose("")).toBeNull();
+    expect(tryParseJsonLoose("not json at all")).toBeNull();
+  });
+});
+
+describe("sanitizeCliArgsForLog", () => {
+  it("redacts values after set", () => {
+    const sanitized = sanitizeCliArgsForLog([
+      "config",
+      "kv",
+      "set",
+      "OPENAI_API_KEY",
+      "sk-live-super-secret",
+    ]);
+    expect(sanitized).toEqual([
+      "config",
+      "kv",
+      "set",
+      "OPENAI_API_KEY",
+      "[redacted]",
+    ]);
+    expect(sanitized.join(" ")).not.toContain("sk-live");
+  });
+
+  it("redacts Bearer tokens in free-form args", () => {
+    const sanitized = sanitizeCliArgsForLog([
+      "deploy",
+      "Authorization: Bearer abcdefghijklmnop",
+    ]);
+    expect(sanitized[1]).toContain("[redacted]");
+    expect(sanitized.join(" ")).not.toContain("abcdefghijklmnop");
+  });
+});

package/src/services/clipboard.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from "bun:test";
+import { copyToClipboard, copyViaSystemClipboard } from "./clipboard";
+import { messageCopiedToClipboard } from "../components/ui/toast";
+
+describe("clipboard", () => {
+  it("treats empty text as success without throwing", async () => {
+    const result = await copyToClipboard("   ", null);
+    expect(result.ok).toBe(true);
+  });
+
+  it("copyViaSystemClipboard returns a tool name or null", async () => {
+    const tool = await copyViaSystemClipboard("hoox-clipboard-test");
+    // CI may lack clipboard tools; null is acceptable
+    expect(tool === null || typeof tool === "string").toBe(true);
+  });
+
+  it("copyToClipboard falls back when no renderer is available", async () => {
+    const result = await copyToClipboard("hello from hoox tui", null);
+    // Success if system tool exists; otherwise structured failure
+    if (result.ok) {
+      expect(result.method === "osc52" || result.method === "system").toBe(
+        true
+      );
+    } else {
+      expect(result.error).toMatch(/clipboard/i);
+    }
+  });
+
+  it("accepts notify option without throwing", async () => {
+    // Toast singleton may no-op without a Toaster in unit tests
+    const result = await copyToClipboard("notify me", null, { notify: true });
+    expect(typeof result.ok).toBe("boolean");
+  });
+});
+
+describe("messageCopiedToClipboard", () => {
+  it("previews short text", () => {
+    expect(messageCopiedToClipboard("hello")).toBe("Copied: “hello”");
+  });
+
+  it("truncates long text", () => {
+    const long = "x".repeat(80);
+    const msg = messageCopiedToClipboard(long);
+    expect(msg.startsWith("Copied: “")).toBe(true);
+    expect(msg.endsWith("…”")).toBe(true);
+    expect(msg.length).toBeLessThan(long.length + 20);
+  });
+
+  it("collapses whitespace", () => {
+    expect(messageCopiedToClipboard("a\n\nb")).toBe("Copied: “a b”");
+  });
+});

package/src/services/clipboard.ts

@@ -0,0 +1,180 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Clipboard helpers for the Hoox TUI.
+ *
+ * Strategy (first success wins):
+ *   1. OpenTUI OSC 52 via CliRenderer.copyToClipboardOSC52 (works over SSH
+ *      when the terminal allows it)
+ *   2. Platform tools: wl-copy / xclip / xsel (Linux), pbcopy (macOS),
+ *      clip (Windows)
+ *
+ * Used for auto-copy on mouse text selection.
+ */
+import { getRendererRef } from "../hooks";
+import {
+  toastCopiedToClipboard,
+  toastCopyFailed,
+} from "../components/ui/toast";
+
+/** Minimal surface we need from OpenTUI's CliRenderer (typed loosely for packages). */
+export type ClipboardRenderer = {
+  copyToClipboardOSC52: (text: string) => boolean;
+  on: (event: string, listener: (...args: unknown[]) => void) => unknown;
+  off: (event: string, listener: (...args: unknown[]) => void) => unknown;
+};
+
+export type ClipboardResult =
+  | { ok: true; method: "osc52" | "system"; tool?: string }
+  | { ok: false; error: string };
+
+const SYSTEM_CLIPBOARD_CANDIDATES: { bin: string; args: string[] }[] = [
+  { bin: "wl-copy", args: [] },
+  { bin: "xclip", args: ["-selection", "clipboard"] },
+  { bin: "xsel", args: ["--clipboard", "--input"] },
+  { bin: "pbcopy", args: [] },
+  { bin: "clip.exe", args: [] },
+  { bin: "clip", args: [] },
+];
+
+/** Hang-guard for clipboard utilities (X11/Wayland can block forever). */
+const CLIPBOARD_SPAWN_TIMEOUT_MS = 2_000;
+
+/**
+ * Write text to the system clipboard via a known clipboard utility.
+ * Returns the tool name on success, or null if none worked.
+ * Each candidate is hard-killed after {@link CLIPBOARD_SPAWN_TIMEOUT_MS}.
+ */
+export async function copyViaSystemClipboard(
+  text: string
+): Promise<string | null> {
+  for (const { bin, args } of SYSTEM_CLIPBOARD_CANDIDATES) {
+    if (!Bun.which(bin)) continue;
+    try {
+      const proc = Bun.spawn([bin, ...args], {
+        stdin: "pipe",
+        stdout: "ignore",
+        stderr: "ignore",
+      });
+      proc.stdin.write(text);
+      proc.stdin.end();
+
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        try {
+          if (!proc.killed) proc.kill();
+        } catch {
+          /* already dead */
+        }
+      }, CLIPBOARD_SPAWN_TIMEOUT_MS);
+
+      const code = await proc.exited;
+      clearTimeout(timer);
+      if (!timedOut && code === 0) return bin;
+    } catch {
+      // try next tool
+    }
+  }
+  return null;
+}
+
+export interface CopyToClipboardOptions {
+  /**
+   * Show a success/error toast. Default false so generic callers stay quiet;
+   * auto-copy on selection opts in.
+   */
+  notify?: boolean;
+}
+
+/**
+ * Copy text using the best available method for the current environment.
+ *
+ * @param text - Content to copy (empty / whitespace-only is a no-op success)
+ * @param renderer - Optional renderer for OSC 52; falls back to getRendererRef()
+ * @param options - Optional `{ notify: true }` for toast feedback
+ */
+export async function copyToClipboard(
+  text: string,
+  renderer?: ClipboardRenderer | null,
+  options?: CopyToClipboardOptions
+): Promise<ClipboardResult> {
+  if (!text || !text.trim()) {
+    return { ok: true, method: "osc52" };
+  }
+
+  const notify = options?.notify === true;
+
+  const r = (renderer ??
+    (getRendererRef() as ClipboardRenderer | null)) as ClipboardRenderer | null;
+  if (r && typeof r.copyToClipboardOSC52 === "function") {
+    try {
+      const ok = Boolean(r.copyToClipboardOSC52(text));
+      if (ok) {
+        // Still try system clipboard so local paste works even when OSC 52
+        // only reaches the remote terminal emulator.
+        void copyViaSystemClipboard(text);
+        if (notify) toastCopiedToClipboard(text);
+        return { ok: true, method: "osc52" };
+      }
+    } catch {
+      // fall through to system tools
+    }
+  }
+
+  const tool = await copyViaSystemClipboard(text);
+  if (tool) {
+    if (notify) toastCopiedToClipboard(text);
+    return { ok: true, method: "system", tool };
+  }
+
+  const error =
+    "No clipboard backend available (OSC 52 failed; install wl-copy/xclip/pbcopy)";
+  if (notify) toastCopyFailed(error);
+  return {
+    ok: false,
+    error,
+  };
+}
+
+/**
+ * Wire auto-copy when the user finishes a mouse text selection.
+ * Call once after createCliRenderer + setRendererRef.
+ *
+ * OpenTUI emits `"selection"` from finishSelection() with isDragging=false.
+ * We only copy non-empty selections and ignore pure clicks (empty text).
+ */
+export function enableAutoCopyOnSelection(
+  renderer: ClipboardRenderer
+): () => void {
+  let lastCopied = "";
+  let lastAt = 0;
+
+  const onSelection = (...args: unknown[]) => {
+    const selection = args[0] as
+      | {
+          isDragging?: boolean;
+          getSelectedText?: () => string;
+        }
+      | undefined;
+    if (selection?.isDragging) return;
+    const text = selection?.getSelectedText?.() ?? "";
+    if (!text.trim()) return;
+
+    // Debounce identical rapid emissions
+    const now = Date.now();
+    if (text === lastCopied && now - lastAt < 400) return;
+    lastCopied = text;
+    lastAt = now;
+
+    void copyToClipboard(text, renderer, { notify: true });
+  };
+
+  renderer.on("selection", onSelection);
+  return () => {
+    renderer.off("selection", onSelection);
+  };
+}

package/src/services/dashboard-settings-loader.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Load worker dashboard.jsonc manifests for the TUI worker-settings view.
+ * Thin wrapper around shared filesystem discovery.
+ */
+import {
+  loadDashboardManifestsFromRoot,
+  resolveHooxRuntimeRoot,
+  type WorkerDashboardManifest,
+} from "@hoox-sh/hoox-shared";
+import { join } from "node:path";
+
+/**
+ * Discover and parse all dashboard settings manifests available in the
+ * current runtime monorepo (or empty list when not found).
+ */
+export function loadDashboardSettingsManifests(
+  runtimeRoot?: string | null
+): WorkerDashboardManifest[] {
+  const root =
+    runtimeRoot ??
+    resolveHooxRuntimeRoot().root ??
+    // packages/tui/src/services → monorepo root
+    join(import.meta.dir, "..", "..", "..", "..");
+
+  return loadDashboardManifestsFromRoot(root);
+}