@hoox-sh/hoox-tui 0.2.0

package/src/services/dev-log.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  devLog,
+  getDevLogPath,
+  isDevLogEnabled,
+  resetDevLogForTests,
+  tuiDevLog,
+  redactSecretsInText,
+  redactDevLogContext,
+} from "./dev-log";
+
+describe("dev-log", () => {
+  const ORIGINAL_DEBUG = process.env.HOOX_DEBUG;
+  const ORIGINAL_TUI_DEBUG = process.env.TUI_DEBUG;
+  const ORIGINAL_HOOX_HOME = process.env.HOOX_HOME;
+  let tempHooxHome: string;
+
+  beforeEach(async () => {
+    resetDevLogForTests();
+    // Prefer HOOX_HOME override (highest priority in getHooxHome) for isolation
+    tempHooxHome = await mkdtemp(join(tmpdir(), "hoox-dev-log-"));
+    process.env.HOOX_HOME = tempHooxHome;
+    delete process.env.HOOX_DEBUG;
+    delete process.env.TUI_DEBUG;
+  });
+
+  afterEach(async () => {
+    resetDevLogForTests();
+    if (ORIGINAL_DEBUG === undefined) delete process.env.HOOX_DEBUG;
+    else process.env.HOOX_DEBUG = ORIGINAL_DEBUG;
+    if (ORIGINAL_TUI_DEBUG === undefined) delete process.env.TUI_DEBUG;
+    else process.env.TUI_DEBUG = ORIGINAL_TUI_DEBUG;
+    if (ORIGINAL_HOOX_HOME === undefined) delete process.env.HOOX_HOME;
+    else process.env.HOOX_HOME = ORIGINAL_HOOX_HOME;
+    await rm(tempHooxHome, { recursive: true, force: true });
+  });
+
+  it("is disabled by default", () => {
+    expect(isDevLogEnabled()).toBe(false);
+  });
+
+  it("enables when HOOX_DEBUG=1", () => {
+    process.env.HOOX_DEBUG = "1";
+    resetDevLogForTests();
+    expect(isDevLogEnabled()).toBe(true);
+  });
+
+  it("enables when TUI_DEBUG=true", () => {
+    process.env.TUI_DEBUG = "true";
+    resetDevLogForTests();
+    expect(isDevLogEnabled()).toBe(true);
+  });
+
+  it("no-ops when disabled (does not create log file)", async () => {
+    await devLog("info", "test", "should not write");
+    const path = getDevLogPath();
+    expect(path.startsWith(tempHooxHome)).toBe(true);
+    let exists = true;
+    try {
+      await readFile(path, "utf8");
+    } catch {
+      exists = false;
+    }
+    expect(exists).toBe(false);
+  });
+
+  it("appends JSON lines when enabled", async () => {
+    process.env.HOOX_DEBUG = "1";
+    resetDevLogForTests();
+
+    await tuiDevLog.info("startup", "TUI booting", {
+      mode: "local",
+      apiUrl: "http://localhost:8787",
+    });
+    await tuiDevLog.debug("api", "fetchWorkers", { path: "/workers" });
+
+    const path = getDevLogPath();
+    expect(path.startsWith(tempHooxHome)).toBe(true);
+    const raw = await readFile(path, "utf8");
+    const lines = raw.trim().split("\n");
+    expect(lines.length).toBe(2);
+
+    const first = JSON.parse(lines[0]!) as {
+      level: string;
+      scope: string;
+      message: string;
+      context: { mode: string; apiUrl: string };
+    };
+    expect(first.level).toBe("info");
+    expect(first.scope).toBe("startup");
+    expect(first.message).toBe("TUI booting");
+    expect(first.context.mode).toBe("local");
+    expect(first.context.apiUrl).toBe("http://localhost:8787");
+  });
+
+  it("redacts secret-looking context keys", async () => {
+    process.env.HOOX_DEBUG = "1";
+    resetDevLogForTests();
+
+    await devLog("info", "auth", "token present", {
+      apiToken: "super-secret-value",
+      path: "/health",
+    });
+
+    const raw = await readFile(getDevLogPath(), "utf8");
+    const lines = raw
+      .trim()
+      .split("\n")
+      .filter((l) => l.length > 0);
+    expect(lines.length).toBe(1);
+    const entry = JSON.parse(lines[0]!) as {
+      context: { apiToken: string; path: string };
+    };
+    expect(entry.context.apiToken).toBe("[redacted]");
+    expect(entry.context.path).toBe("/health");
+    expect(raw).not.toContain("super-secret-value");
+  });
+
+  it("redacts nested secret keys and message Bearer tokens", async () => {
+    process.env.HOOX_DEBUG = "1";
+    resetDevLogForTests();
+
+    await devLog(
+      "warn",
+      "http",
+      "Authorization: Bearer super-secret-value failed",
+      {
+        headers: { authorization: "Bearer super-secret-value" },
+        nested: { client_secret: "access-secret-xyz" },
+        path: "/workers",
+      }
+    );
+
+    const raw = await readFile(getDevLogPath(), "utf8");
+    expect(raw).not.toContain("super-secret-value");
+    expect(raw).not.toContain("access-secret-xyz");
+    expect(raw).toContain("[redacted]");
+  });
+
+  it("redactSecretsInText scrubs env-style assignments", () => {
+    const scrubbed = redactSecretsInText(
+      "HOOX_API_TOKEN=abc123 CF_ACCESS_CLIENT_SECRET=xyz Authorization: Bearer tok12345678"
+    );
+    expect(scrubbed).not.toContain("abc123");
+    expect(scrubbed).not.toContain("xyz");
+    expect(scrubbed).not.toContain("tok12345678");
+    expect(scrubbed).toContain("HOOX_API_TOKEN=[redacted]");
+  });
+
+  it("redactDevLogContext redacts nested client_secret", () => {
+    const out = redactDevLogContext({
+      ok: true,
+      auth: { client_secret: "s3cret", mode: "access" },
+    });
+    expect(out).toEqual({
+      ok: true,
+      auth: { client_secret: "[redacted]", mode: "access" },
+    });
+  });
+});

package/src/services/dev-log.ts

@@ -0,0 +1,194 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * TUI dev logger — file-backed diagnostics that never touch stdout/stderr
+ * (those would corrupt the OpenTUI alternate screen).
+ *
+ * Enable with any of:
+ *   - `hoox tui --debug`
+ *   - `HOOX_DEBUG=1` / `TUI_DEBUG=1` / `true` / `yes`
+ *
+ * Writes append-only JSON lines to `$HOME/.hoox/.tui-state/debug.log`.
+ */
+import { appendFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  getTuiStateDir,
+  resetHooxPathCacheForTests,
+} from "./hoox-path-service";
+
+export type DevLogLevel = "debug" | "info" | "warn" | "error";
+
+export interface DevLogEntry {
+  ts: string;
+  level: DevLogLevel;
+  scope: string;
+  message: string;
+  context?: Record<string, unknown>;
+}
+
+const DEBUG_LOG_FILE = "debug.log";
+
+let enabledCache: boolean | null = null;
+let logPathCache: string | null = null;
+let logPathCacheKey: string | null = null;
+let ensureDirPromise: Promise<string> | null = null;
+
+/** Reset caches (tests only). */
+export function resetDevLogForTests(): void {
+  enabledCache = null;
+  logPathCache = null;
+  logPathCacheKey = null;
+  ensureDirPromise = null;
+  // Dev log path is under getTuiStateDir(); clear path cache when HOOX_HOME changes in tests.
+  resetHooxPathCacheForTests();
+}
+
+/**
+ * Whether dev logging is active for this process.
+ * Cached after first read so hot paths stay cheap.
+ */
+export function isDevLogEnabled(): boolean {
+  if (enabledCache !== null) return enabledCache;
+  const v = process.env.HOOX_DEBUG ?? process.env.TUI_DEBUG ?? "";
+  enabledCache = v === "1" || v === "true" || v === "yes";
+  return enabledCache;
+}
+
+/** Absolute path to the debug log file (even if logging is disabled). */
+export function getDevLogPath(): string {
+  const dir = getTuiStateDir();
+  if (logPathCache && logPathCacheKey === dir) return logPathCache;
+  logPathCache = join(dir, DEBUG_LOG_FILE);
+  logPathCacheKey = dir;
+  return logPathCache;
+}
+
+async function ensureLogDir(): Promise<string> {
+  const dir = getTuiStateDir();
+  // Re-bind ensure promise if the state dir moved (HOOX_HOME override in tests).
+  if (!ensureDirPromise || logPathCacheKey !== dir) {
+    ensureDirPromise = mkdir(dir, { recursive: true }).then(() => dir);
+  }
+  return ensureDirPromise;
+}
+
+/** Keys that almost always carry credentials or private material. */
+const SECRET_KEY_RE =
+  /token|secret|password|passwd|authorization|api[_-]?key|private[_-]?key|client[_-]?secret|access[_-]?client|credential|cookie|session/i;
+
+/**
+ * Redact secret-looking keys in structured context (nested objects included).
+ * Exported for unit tests.
+ */
+export function redactDevLogContext(
+  context?: Record<string, unknown>
+): Record<string, unknown> | undefined {
+  if (!context) return undefined;
+  return redactValue(context) as Record<string, unknown>;
+}
+
+function redactValue(value: unknown): unknown {
+  if (value === undefined) return undefined;
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: redactSecretsInText(value.message),
+    };
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactValue(item));
+  }
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(
+      value as Record<string, unknown>
+    )) {
+      if (child === undefined) continue;
+      if (SECRET_KEY_RE.test(key)) {
+        out[key] =
+          typeof child === "string" && child.length > 0
+            ? "[redacted]"
+            : child === null
+              ? null
+              : typeof child === "object"
+                ? "[redacted]"
+                : child;
+        continue;
+      }
+      out[key] = redactValue(child);
+    }
+    return out;
+  }
+  if (typeof value === "string") {
+    return redactSecretsInText(value);
+  }
+  return value;
+}
+
+/**
+ * Scrub common secret patterns that leak into free-form log messages.
+ * Exported for unit tests.
+ */
+export function redactSecretsInText(text: string): string {
+  let out = text;
+  // Bearer tokens in Authorization headers or prose
+  out = out.replace(/(Bearer\s+)[A-Za-z0-9._\-+/=]{8,}/gi, "$1[redacted]");
+  // Common env-style assignments
+  out = out.replace(
+    /\b(HOOX_API_TOKEN|CLOUDFLARE_API_TOKEN|CF_ACCESS_CLIENT_SECRET|CF_ACCESS_CLIENT_ID|OPERATOR_API_KEY|INTERNAL_API_KEY|INTERNAL_KEY_BINDING)\s*[=:]\s*\S+/gi,
+    "$1=[redacted]"
+  );
+  // Authorization: <scheme> <value>
+  out = out.replace(/(Authorization\s*:\s*)\S+/gi, "$1[redacted]");
+  return out;
+}
+
+function serializeContext(
+  context?: Record<string, unknown>
+): Record<string, unknown> | undefined {
+  return redactDevLogContext(context);
+}
+
+/**
+ * Append one structured log line. No-op when debug is disabled.
+ * Failures are swallowed — logging must never crash the TUI.
+ */
+export async function devLog(
+  level: DevLogLevel,
+  scope: string,
+  message: string,
+  context?: Record<string, unknown>
+): Promise<void> {
+  if (!isDevLogEnabled()) return;
+
+  const entry: DevLogEntry = {
+    ts: new Date().toISOString(),
+    level,
+    scope,
+    message: redactSecretsInText(message),
+    ...(context ? { context: serializeContext(context) } : {}),
+  };
+
+  try {
+    await ensureLogDir();
+    await appendFile(getDevLogPath(), `${JSON.stringify(entry)}\n`, "utf8");
+  } catch {
+    // Swallow — alternate-screen UI must stay intact
+  }
+}
+
+/** Convenience helpers. */
+export const tuiDevLog = {
+  debug: (scope: string, message: string, context?: Record<string, unknown>) =>
+    devLog("debug", scope, message, context),
+  info: (scope: string, message: string, context?: Record<string, unknown>) =>
+    devLog("info", scope, message, context),
+  warn: (scope: string, message: string, context?: Record<string, unknown>) =>
+    devLog("warn", scope, message, context),
+  error: (scope: string, message: string, context?: Record<string, unknown>) =>
+    devLog("error", scope, message, context),
+};

package/src/services/hoox-path-service.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Tests for TUI Hoox Path Service
+ *
+ * Covers:
+ *   - getTuiStateDir: returns correct path, fallback to cwd
+ *   - ensureTuiStateDir: creates directory, returns path, fallback
+ *   - tuiStateDirExists: checks existence of .tui-state directory
+ *   - resolveTuiStatePath: resolves paths within .tui-state
+ *   - resolveHooxHomePath: resolves paths within $HOME/.hoox
+ *   - Edge cases: empty subpath, error fallback
+ */
+import { describe, it, expect } from "bun:test";
+import { unlinkSync, existsSync } from "fs";
+import { join, resolve } from "path";
+
+// ─── Import the module under test ─────────────────────────────────────────────
+
+import {
+  getTuiStateDir,
+  ensureTuiStateDir,
+  tuiStateDirExists,
+  resolveTuiStatePath,
+  resolveHooxHomePath,
+} from "./hoox-path-service";
+
+// ─── Test Suite ───────────────────────────────────────────────────────────────
+
+describe("hoox-path-service", () => {
+  // ── getTuiStateDir ────────────────────────────────────────────────────────
+
+  describe("getTuiStateDir", () => {
+    it("should return a path ending with .tui-state", () => {
+      const dir = getTuiStateDir();
+      expect(dir).toMatch(/\.tui-state$/);
+    });
+
+    it("should return an absolute path", () => {
+      const dir = getTuiStateDir();
+      expect(dir).toMatch(/^\/|^[A-Z]:\\/);
+    });
+
+    it("should be consistent across multiple calls", () => {
+      const dir1 = getTuiStateDir();
+      const dir2 = getTuiStateDir();
+      expect(dir1).toBe(dir2);
+    });
+
+    it("should contain .tui-state directory name", () => {
+      const dir = getTuiStateDir();
+      expect(dir).toContain(".tui-state");
+    });
+
+    it("should be under the hoox home directory", () => {
+      const dir = getTuiStateDir();
+      // Should contain .hoox/.tui-state
+      expect(dir).toContain(".hoox");
+      expect(dir).toContain(".tui-state");
+    });
+  });
+
+  // ── ensureTuiStateDir ─────────────────────────────────────────────────────
+
+  describe("ensureTuiStateDir", () => {
+    it("should return a path ending with .tui-state", async () => {
+      const dir = await ensureTuiStateDir();
+      expect(dir).toMatch(/\.tui-state$/);
+    });
+
+    it("should create the .tui-state directory if it does not exist", async () => {
+      // Use a known-good path (the real hoox home)
+      const dir = await ensureTuiStateDir();
+      expect(existsSync(dir)).toBe(true);
+    });
+
+    it("should not throw when directory already exists", async () => {
+      // First call creates it
+      await ensureTuiStateDir();
+      // Second call should not throw
+      await expect(ensureTuiStateDir()).resolves.toBeDefined();
+    });
+
+    it("should return a writable directory", async () => {
+      const dir = await ensureTuiStateDir();
+      // Try writing a test file
+      const testFile = join(dir, ".write-test");
+      await Bun.write(testFile, "test");
+      expect(existsSync(testFile)).toBe(true);
+      // Cleanup
+      unlinkSync(testFile);
+    });
+  });
+
+  // ── tuiStateDirExists ────────────────────────────────────────────────────
+
+  describe("tuiStateDirExists", () => {
+    it("should return true when the .tui-state directory exists", () => {
+      // ensureTuiStateDir should have created it in the previous test
+      expect(tuiStateDirExists()).toBe(true);
+    });
+  });
+
+  // ── resolveTuiStatePath ──────────────────────────────────────────────────
+
+  describe("resolveTuiStatePath", () => {
+    it("should resolve a simple filename within .tui-state", () => {
+      const path = resolveTuiStatePath("session.json");
+      expect(path).toMatch(/\.tui-state[/\\]session\.json$/);
+    });
+
+    it("should resolve nested paths within .tui-state", () => {
+      const path = resolveTuiStatePath("subdir/data.json");
+      expect(path).toMatch(/\.tui-state[/\\]subdir[/\\]data\.json$/);
+    });
+
+    it("should return an absolute path", () => {
+      const path = resolveTuiStatePath("session.json");
+      expect(path).toMatch(/^\/|^[A-Z]:\\/);
+    });
+
+    it("should be consistent with getTuiStateDir for the base path", () => {
+      const base = getTuiStateDir();
+      const sessionPath = resolveTuiStatePath("session.json");
+      expect(sessionPath).toBe(join(base, "session.json"));
+    });
+
+    it("should handle empty subpath", () => {
+      const path = resolveTuiStatePath("");
+      const base = getTuiStateDir();
+      expect(path).toBe(base);
+    });
+
+    it("should handle subpath with leading slash", () => {
+      const path = resolveTuiStatePath("/session.json");
+      const base = getTuiStateDir();
+      // Leading slash is stripped and treated as relative
+      expect(path).toBe(join(base, "session.json"));
+    });
+
+    it("rejects path traversal with .. segments", () => {
+      expect(() => resolveTuiStatePath("../escape.json")).toThrow(
+        /escapes TUI state directory/
+      );
+      expect(() => resolveTuiStatePath("foo/../../etc/passwd")).toThrow(
+        /escapes TUI state directory/
+      );
+    });
+
+    it("keeps nested relative paths under .tui-state", () => {
+      const path = resolveTuiStatePath("a/b/c.json");
+      expect(path.startsWith(getTuiStateDir())).toBe(true);
+      expect(path.endsWith(join("a", "b", "c.json"))).toBe(true);
+    });
+  });
+
+  // ── resolveHooxHomePath ──────────────────────────────────────────────────
+
+  describe("resolveHooxHomePath", () => {
+    it("should resolve a path within the hoox home directory", () => {
+      const path = resolveHooxHomePath("config");
+      expect(path).toMatch(/\.hoox[/\\]config$/);
+    });
+
+    it("should resolve nested paths", () => {
+      const path = resolveHooxHomePath("config/wrangler.jsonc");
+      expect(path).toMatch(/\.hoox[/\\]config[/\\]wrangler\.jsonc$/);
+    });
+
+    it("should return an absolute path", () => {
+      const path = resolveHooxHomePath("repo");
+      expect(path).toMatch(/^\/|^[A-Z]:\\/);
+    });
+
+    it("should be within hoox home", () => {
+      const path = resolveHooxHomePath("data");
+      expect(path).toContain(".hoox");
+    });
+  });
+});