@hoox-sh/hoox-tui 0.2.0

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

@@ -0,0 +1,185 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Hoox Path Service — TUI-specific path resolution for state and config.
+ *
+ * Provides utilities for:
+ *   - Resolving the Hoox home directory ($HOME/.hoox)
+ *   - Creating/accessing the .tui-state directory for persistent state
+ *   - Falling back to current working directory if home location is not available
+ *
+ * Uses getHooxHome() from the shared package for cross-OS path resolution.
+ *
+ * Security: all resolved state paths are constrained under the TUI state dir
+ * (path traversal via `..` is rejected).
+ *
+ * @example
+ * ```typescript
+ * import { getTuiStateDir, ensureTuiStateDir } from "./services/hoox-path-service";
+ *
+ * const dir = await ensureTuiStateDir();
+ * // Returns: "/Users/alice/.hoox/.tui-state" (macOS/Linux)
+ * // Returns: "/home/alice/.hoox/.tui-state" (Linux)
+ * // Falls back to: "/current/working/dir/.tui-state" if HOME is unavailable
+ * ```
+ */
+import { getHooxHome, type HooxPath } from "@hoox-sh/hoox-shared";
+import { join, resolve, sep } from "path";
+import { mkdir } from "fs/promises";
+import { existsSync } from "fs";
+
+/**
+ * Subdirectory name for TUI persistent state within the Hoox home directory.
+ */
+const TUI_STATE_DIR = ".tui-state";
+
+/**
+ * Cached absolute path for {@link getTuiStateDir}.
+ * Keyed by HOOX_HOME/HOME so env overrides in tests invalidate the cache.
+ */
+let tuiStateDirCache: string | null = null;
+let tuiStateDirCacheKey: string | null = null;
+
+/** Reset path caches (tests only). */
+export function resetHooxPathCacheForTests(): void {
+  tuiStateDirCache = null;
+  tuiStateDirCacheKey = null;
+}
+
+function pathEnvCacheKey(): string {
+  return `${process.env.HOOX_HOME ?? ""}\0${process.env.HOME ?? ""}\0${process.cwd()}`;
+}
+
+/**
+ * Gets the TUI state directory path: $HOME/.hoox/.tui-state
+ *
+ * Falls back to <cwd>/.tui-state if the home directory is not available.
+ * This fallback ensures the TUI remains functional even in environments
+ * where $HOME is not set (e.g., some CI runners, containers).
+ *
+ * Result is cached while HOOX_HOME/HOME/cwd are unchanged.
+ *
+ * @returns Absolute path to the TUI state directory
+ */
+export function getTuiStateDir(): string {
+  const key = pathEnvCacheKey();
+  if (tuiStateDirCache && tuiStateDirCacheKey === key) return tuiStateDirCache;
+  try {
+    const hooxHome = getHooxHome();
+    tuiStateDirCache = join(hooxHome, TUI_STATE_DIR);
+  } catch {
+    // Fallback: use current working directory
+    tuiStateDirCache = resolve(process.cwd(), TUI_STATE_DIR);
+  }
+  tuiStateDirCacheKey = key;
+  return tuiStateDirCache;
+}
+
+/**
+ * Ensures the TUI state directory exists, creating it if necessary.
+ *
+ * This should be called during TUI initialization to make sure
+ * persistent state can be written. Uses mkdir with recursive option.
+ * Falls back to <cwd>/.tui-state if the primary path cannot be created.
+ *
+ * @returns The path to the TUI state directory that was ensured
+ * @throws If the directory cannot be created (even after fallback)
+ */
+export async function ensureTuiStateDir(): Promise<string> {
+  const dir = getTuiStateDir();
+  try {
+    await mkdir(dir, { recursive: true });
+    return dir;
+  } catch {
+    // mkdir on primary path failed — fall back to current working directory
+    const fallback = resolve(process.cwd(), TUI_STATE_DIR);
+    await mkdir(fallback, { recursive: true });
+    tuiStateDirCache = fallback;
+    tuiStateDirCacheKey = pathEnvCacheKey();
+    return fallback;
+  }
+}
+
+/**
+ * Checks whether the TUI state directory already exists on disk.
+ *
+ * @returns true if .tui-state directory exists, false otherwise
+ */
+export function tuiStateDirExists(): boolean {
+  try {
+    return existsSync(getTuiStateDir());
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when `resolved` is exactly `base` or a path under `base`.
+ * Uses resolved absolute paths so symlinks / `..` cannot escape.
+ */
+function isPathInsideBase(base: string, resolved: string): boolean {
+  const baseResolved = resolve(base);
+  const target = resolve(resolved);
+  if (target === baseResolved) return true;
+  const prefix = baseResolved.endsWith(sep) ? baseResolved : baseResolved + sep;
+  return target.startsWith(prefix);
+}
+
+/**
+ * Resolves a path within the TUI state directory.
+ *
+ * Rejects path traversal (`..` segments or absolute escape). Callers that
+ * must never throw (storage) should catch — throw is intentional fail-closed.
+ *
+ * @param subpath - Relative path within .tui-state (e.g., "session.json", "crash.log")
+ * @returns Absolute path to the file within the TUI state directory
+ *
+ * @example
+ * ```typescript
+ * const sessionPath = resolveTuiStatePath("session.json");
+ * // Returns: "/Users/alice/.hoox/.tui-state/session.json"
+ * ```
+ */
+export function resolveTuiStatePath(subpath: string): string {
+  // Strip leading slash to ensure subpath is treated as relative.
+  // On POSIX, path.join treats absolute paths as root-relative, but Bun may
+  // handle this differently. Normalizing to relative prevents ambiguity.
+  let normalized =
+    subpath.startsWith("/") || subpath.startsWith("\\")
+      ? subpath.slice(1)
+      : subpath;
+
+  // Normalize Windows-style separators and strip empty / `.` segments early.
+  const segments = normalized.split(/[/\\]+/).filter((s) => s && s !== ".");
+  if (segments.some((s) => s === "..")) {
+    throw new Error(
+      `Path escapes TUI state directory: refused "${subpath}" (contains "..")`
+    );
+  }
+  normalized = segments.join(sep);
+
+  const base = getTuiStateDir();
+  const resolved = resolve(base, normalized);
+  if (!isPathInsideBase(base, resolved)) {
+    throw new Error(
+      `Path escapes TUI state directory: refused "${subpath}" → ${resolved}`
+    );
+  }
+  return resolved;
+}
+
+/**
+ * Resolves a path within the Hoox home directory.
+ *
+ * Delegates to the shared resolveHooxPath but exposed here for TUI convenience.
+ *
+ * @param relativePath - Path relative to $HOME/.hoox
+ * @returns Absolute branded HooxPath
+ */
+export function resolveHooxHomePath(relativePath: string): HooxPath {
+  const hooxHome = getHooxHome();
+  return join(hooxHome, relativePath) as HooxPath;
+}

package/src/services/tui-connection.test.ts

@@ -0,0 +1,212 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from "bun:test";
+import {
+  classifyConnectionError,
+  formatAuthBanner,
+  getApiBase,
+  getApiHost,
+  getSettingsConnectionSnapshot,
+  getTuiMode,
+  hasAccessCredentials,
+  hasApiToken,
+  isRemoteAuthReady,
+  resolveTuiConnectionEnv,
+  shouldUseCliFallback,
+} from "./tui-connection";
+
+describe("tui-connection", () => {
+  describe("getTuiMode", () => {
+    it("defaults to local", () => {
+      expect(getTuiMode({})).toBe("local");
+    });
+    it("reads remote", () => {
+      expect(getTuiMode({ HOOX_TUI_MODE: "remote" })).toBe("remote");
+    });
+  });
+
+  describe("getApiBase / getApiHost", () => {
+    it("defaults to localhost:8787", () => {
+      expect(getApiBase({})).toBe("http://localhost:8787");
+      expect(getApiHost(getApiBase({}))).toBe("localhost:8787");
+    });
+    it("strips trailing slashes", () => {
+      expect(getApiBase({ HOOX_API_URL: "https://gw.example.com///" })).toBe(
+        "https://gw.example.com"
+      );
+    });
+  });
+
+  describe("hasApiToken", () => {
+    it("is false when empty", () => {
+      expect(hasApiToken({})).toBe(false);
+      expect(hasApiToken({ HOOX_API_TOKEN: "  " })).toBe(false);
+    });
+    it("is true when set", () => {
+      expect(hasApiToken({ HOOX_API_TOKEN: "secret" })).toBe(true);
+    });
+  });
+
+  describe("hasAccessCredentials / isRemoteAuthReady", () => {
+    it("requires both Access id and secret", () => {
+      expect(hasAccessCredentials({})).toBe(false);
+      expect(hasAccessCredentials({ CF_ACCESS_CLIENT_ID: "cid" })).toBe(false);
+      expect(
+        hasAccessCredentials({
+          CF_ACCESS_CLIENT_ID: "cid",
+          CF_ACCESS_CLIENT_SECRET: "sec",
+        })
+      ).toBe(true);
+    });
+
+    it("local mode is always auth-ready", () => {
+      expect(isRemoteAuthReady({})).toBe(true);
+    });
+
+    it("remote fail-closed without credentials", () => {
+      expect(isRemoteAuthReady({ HOOX_TUI_MODE: "remote" })).toBe(false);
+    });
+
+    it("remote ready with Bearer only", () => {
+      expect(
+        isRemoteAuthReady({
+          HOOX_TUI_MODE: "remote",
+          HOOX_API_TOKEN: "tok",
+        })
+      ).toBe(true);
+    });
+
+    it("remote ready with Access only (no Bearer)", () => {
+      expect(
+        isRemoteAuthReady({
+          HOOX_TUI_MODE: "remote",
+          CF_ACCESS_CLIENT_ID: "cid",
+          CF_ACCESS_CLIENT_SECRET: "sec",
+        })
+      ).toBe(true);
+    });
+  });
+
+  describe("shouldUseCliFallback", () => {
+    it("allows CLI only in local mode", () => {
+      expect(shouldUseCliFallback("local")).toBe(true);
+      expect(shouldUseCliFallback("remote")).toBe(false);
+    });
+  });
+
+  describe("resolveTuiConnectionEnv", () => {
+    it("builds a remote snapshot", () => {
+      const env = resolveTuiConnectionEnv({
+        HOOX_TUI_MODE: "remote",
+        HOOX_API_URL: "https://hoox.example.workers.dev",
+        HOOX_API_TOKEN: "tok",
+      });
+      expect(env.mode).toBe("remote");
+      expect(env.apiHost).toBe("hoox.example.workers.dev");
+      expect(env.hasToken).toBe(true);
+      expect(env.hasAuth).toBe(true);
+      expect(env.allowCliFallback).toBe(false);
+    });
+
+    it("remote without credentials is fail-closed (hasAuth false)", () => {
+      const env = resolveTuiConnectionEnv({
+        HOOX_TUI_MODE: "remote",
+        HOOX_API_URL: "https://mgmt.example.com",
+      });
+      expect(env.hasToken).toBe(false);
+      expect(env.hasAccessCredentials).toBe(false);
+      expect(env.hasAuth).toBe(false);
+      expect(env.allowCliFallback).toBe(false);
+    });
+
+    it("remote Access-only reports hasAuth without hasToken", () => {
+      const env = resolveTuiConnectionEnv({
+        HOOX_TUI_MODE: "remote",
+        CF_ACCESS_CLIENT_ID: "cid",
+        CF_ACCESS_CLIENT_SECRET: "sec",
+      });
+      expect(env.hasToken).toBe(false);
+      expect(env.hasAccessCredentials).toBe(true);
+      expect(env.hasAuth).toBe(true);
+    });
+  });
+
+  describe("classifyConnectionError", () => {
+    it("detects auth failures", () => {
+      expect(classifyConnectionError("Authentication failed (HTTP 401)")).toBe(
+        "auth"
+      );
+      expect(classifyConnectionError("HTTP 403: Forbidden")).toBe("auth");
+      expect(classifyConnectionError("CF-Access denied")).toBe("auth");
+    });
+    it("detects rate limits", () => {
+      expect(classifyConnectionError("API rate limited — backing off")).toBe(
+        "rate-limit"
+      );
+    });
+    it("detects network errors", () => {
+      expect(
+        classifyConnectionError("Network request failed: ECONNREFUSED")
+      ).toBe("network");
+      expect(classifyConnectionError("socket hang up")).toBe("network");
+    });
+    it("unknown for empty", () => {
+      expect(classifyConnectionError(null)).toBe("unknown");
+    });
+  });
+
+  describe("formatAuthBanner", () => {
+    it("describes missing remote token", () => {
+      expect(formatAuthBanner(false, "remote")).toContain("missing");
+      expect(formatAuthBanner(true, "remote")).toContain("set");
+    });
+    it("mentions Access when only Access is set", () => {
+      expect(formatAuthBanner(false, "remote", true)).toContain("Access");
+    });
+  });
+
+  describe("getSettingsConnectionSnapshot", () => {
+    it("defaults to local/public with no auth", () => {
+      const snap = getSettingsConnectionSnapshot({});
+      expect(snap.mode).toBe("local");
+      expect(snap.transport).toBe("public");
+      expect(snap.authSummary).toBe("none");
+      expect(snap.apiHost).toBe("localhost:8787");
+      expect(snap.hint).toContain("hx config transport");
+    });
+
+    it("reports remote + Bearer without leaking token", () => {
+      const snap = getSettingsConnectionSnapshot({
+        HOOX_TUI_MODE: "remote",
+        HOOX_API_URL: "https://mgmt.example.com",
+        HOOX_API_TOKEN: "super-secret",
+      });
+      expect(snap.mode).toBe("remote");
+      expect(snap.apiHost).toBe("mgmt.example.com");
+      expect(snap.authSummary).toBe("Bearer");
+      expect(JSON.stringify(snap)).not.toContain("super-secret");
+    });
+
+    it("uses config transport fallback when env unset", () => {
+      const snap = getSettingsConnectionSnapshot(
+        {},
+        { transport: "access", apiUrl: "https://cfg.example.com" }
+      );
+      expect(snap.transport).toBe("access");
+      expect(snap.apiHost).toBe("cfg.example.com");
+    });
+
+    it("combines Bearer + Access in auth summary", () => {
+      const snap = getSettingsConnectionSnapshot({
+        HOOX_API_TOKEN: "tok",
+        CF_ACCESS_CLIENT_ID: "cid",
+        CF_ACCESS_CLIENT_SECRET: "sec",
+      });
+      expect(snap.authSummary).toBe("Bearer + Access");
+      expect(snap.transport).toBe("access");
+    });
+  });
+});

package/src/services/tui-connection.ts

@@ -0,0 +1,236 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * TUI connection helpers — LOCAL/REMOTE mode, auth presence, and error
+ * classification used by the status bar, connection toasts, and startup.
+ *
+ * Pure functions (env-read wrappers included) so unit tests don't need a
+ * renderer. Never log raw tokens.
+ *
+ * Remote auth is **fail-closed**: REMOTE mode requires Bearer (`HOOX_API_TOKEN`)
+ * and/or Cloudflare Access service-token credentials. CLI fallback is never
+ * used in REMOTE mode.
+ */
+
+import {
+  resolveOperatorTransportProfile,
+  type OperatorTransport,
+  type OperatorTransportEnv,
+} from "@hoox-sh/hoox-shared";
+
+export type TuiMode = "local" | "remote";
+
+export type ConnectionErrorKind = "auth" | "rate-limit" | "network" | "unknown";
+
+export interface TuiConnectionEnv {
+  mode: TuiMode;
+  apiUrl: string;
+  apiHost: string;
+  /** True when `HOOX_API_TOKEN` is non-empty. */
+  hasToken: boolean;
+  /** True when CF Access client id + secret are both set. */
+  hasAccessCredentials: boolean;
+  /**
+   * Fail-closed readiness for REMOTE: Bearer and/or Access credentials.
+   * LOCAL always reports true (token optional for wrangler dev).
+   */
+  hasAuth: boolean;
+  /** True when CLI fallback is appropriate (local only). */
+  allowCliFallback: boolean;
+}
+
+const DEFAULT_API_URL = "http://localhost:8787";
+
+/** Read `HOOX_TUI_MODE` (defaults to local). */
+export function getTuiMode(env: NodeJS.ProcessEnv = process.env): TuiMode {
+  return env.HOOX_TUI_MODE === "remote" ? "remote" : "local";
+}
+
+/** Resolved API base URL (no trailing slash). */
+export function getApiBase(env: NodeJS.ProcessEnv = process.env): string {
+  const raw = env.HOOX_API_URL?.trim() || DEFAULT_API_URL;
+  return raw.replace(/\/+$/, "");
+}
+
+/** Host label for status bar / toasts. */
+export function getApiHost(apiUrl: string = getApiBase()): string {
+  try {
+    return new URL(apiUrl).host || apiUrl;
+  } catch {
+    return apiUrl.replace(/^https?:\/\//, "").replace(/\/+$/, "") || apiUrl;
+  }
+}
+
+/** Whether a non-empty API bearer token is configured. */
+export function hasApiToken(env: NodeJS.ProcessEnv = process.env): boolean {
+  return Boolean(env.HOOX_API_TOKEN?.trim());
+}
+
+/** Whether Cloudflare Access service-token env vars are both present. */
+export function hasAccessCredentials(
+  env: NodeJS.ProcessEnv = process.env
+): boolean {
+  return Boolean(
+    env.CF_ACCESS_CLIENT_ID?.trim() && env.CF_ACCESS_CLIENT_SECRET?.trim()
+  );
+}
+
+/**
+ * Auth presence for fail-closed remote gateways: Bearer and/or Access pair.
+ * LOCAL mode always returns true (auth optional).
+ */
+export function isRemoteAuthReady(
+  env: NodeJS.ProcessEnv = process.env
+): boolean {
+  if (getTuiMode(env) !== "remote") return true;
+  return hasApiToken(env) || hasAccessCredentials(env);
+}
+
+/**
+ * Remote HTTP is the source of truth — local CLI `check health` must not
+ * mark a remote session as connected when the gateway is down.
+ */
+export function shouldUseCliFallback(mode: TuiMode): boolean {
+  return mode === "local";
+}
+
+/** Snapshot of mode/auth/url for startup and toasts. */
+export function resolveTuiConnectionEnv(
+  env: NodeJS.ProcessEnv = process.env
+): TuiConnectionEnv {
+  const mode = getTuiMode(env);
+  const apiUrl = getApiBase(env);
+  const hasToken = hasApiToken(env);
+  const hasAccess = hasAccessCredentials(env);
+  return {
+    mode,
+    apiUrl,
+    apiHost: getApiHost(apiUrl),
+    hasToken,
+    hasAccessCredentials: hasAccess,
+    hasAuth: mode === "local" ? true : hasToken || hasAccess,
+    allowCliFallback: shouldUseCliFallback(mode),
+  };
+}
+
+/**
+ * Classify a connection error message (from WorkerAPIError / fetch).
+ * Used for auth-specific UX and toast routing.
+ */
+export function classifyConnectionError(
+  message: string | null | undefined
+): ConnectionErrorKind {
+  if (!message) return "unknown";
+  const m = message.toLowerCase();
+  if (
+    m.includes("authentication failed") ||
+    m.includes("http 401") ||
+    m.includes("http 403") ||
+    m.includes("unauthorized") ||
+    m.includes("forbidden") ||
+    m.includes("invalid token") ||
+    m.includes("missing authorization") ||
+    m.includes("access denied") ||
+    m.includes("cf-access")
+  ) {
+    return "auth";
+  }
+  if (
+    m.includes("rate limited") ||
+    m.includes("http 429") ||
+    m.includes("429")
+  ) {
+    return "rate-limit";
+  }
+  if (
+    m.includes("econnrefused") ||
+    m.includes("enotfound") ||
+    m.includes("network") ||
+    m.includes("timeout") ||
+    m.includes("abort") ||
+    m.includes("fetch failed") ||
+    m.includes("connection") ||
+    m.includes("econnreset") ||
+    m.includes("socket hang up")
+  ) {
+    return "network";
+  }
+  return "unknown";
+}
+
+/**
+ * Human-readable auth status for CLI launch banner (never includes the token).
+ */
+export function formatAuthBanner(
+  hasToken: boolean,
+  mode: TuiMode,
+  hasAccess = false
+): string {
+  if (hasToken && hasAccess) {
+    return "set (Bearer + Access)";
+  }
+  if (hasToken) return "set (Bearer HOOX_API_TOKEN)";
+  if (hasAccess) return "set (Cloudflare Access service token)";
+  if (mode === "remote") {
+    return "missing — remote gateway may reject requests (set HOOX_API_TOKEN or Access credentials)";
+  }
+  return "not set (optional for local wrangler dev)";
+}
+
+/** Safe one-line hint when remote auth is missing. */
+export function remoteAuthMissingHint(): string {
+  return "Set HOOX_API_TOKEN (or pass --token), or CF_ACCESS_CLIENT_ID + CF_ACCESS_CLIENT_SECRET for authenticated remote API access.";
+}
+
+/** Read-only connection snapshot for Settings (never includes secrets). */
+export interface SettingsConnectionSnapshot {
+  mode: TuiMode;
+  apiHost: string;
+  transport: OperatorTransport;
+  /** Human auth presence: none | Bearer | Access | Bearer + Access */
+  authSummary: string;
+  /** CLI hint for changing transport / probing security */
+  hint: string;
+}
+
+export interface SettingsConnectionConfigFallback {
+  transport?: string;
+  apiUrl?: string;
+  apiToken?: string;
+}
+
+/**
+ * Build a Settings-friendly connection line from env (+ optional config.json).
+ * Env always wins over config for URL/token/transport (mirrors operator profile).
+ */
+export function getSettingsConnectionSnapshot(
+  env: NodeJS.ProcessEnv = process.env,
+  config: SettingsConnectionConfigFallback = {}
+): SettingsConnectionSnapshot {
+  const conn = resolveTuiConnectionEnv(env);
+  const profile = resolveOperatorTransportProfile(env as OperatorTransportEnv, {
+    configTransport: config.transport,
+    configApiUrl: config.apiUrl,
+    configApiToken: config.apiToken,
+  });
+
+  const hasBearer = Boolean(profile.bearerToken);
+  const hasAccess = Boolean(
+    profile.accessClientId && profile.accessClientSecret
+  );
+  let authSummary = "none";
+  if (hasBearer && hasAccess) authSummary = "Bearer + Access";
+  else if (hasBearer) authSummary = "Bearer";
+  else if (hasAccess) authSummary = "Access";
+
+  return {
+    mode: conn.mode,
+    apiHost: getApiHost(profile.apiBase),
+    transport: profile.transport,
+    authSummary,
+    hint: "hx config transport · hx doctor --security",
+  };
+}