failproofai 0.0.1-beta.1

package/lib/use-url-params.ts

@@ -0,0 +1,66 @@
+"use client";
+
+/**
+ * Low-level hook for reading and writing URL query parameters.
+ *
+ * Wraps Next.js `useSearchParams()` + `useRouter()`.
+ * - `get(key)` — read a single param
+ * - `getAll()` — snapshot of all params
+ * - `setAll(params)` — batch-write params; `undefined` values are removed from URL
+ *
+ * Uses `router.replace()` (not `push`) with `scroll: false` so the browser
+ * history stays clean and the page doesn't jump.  Writes are debounced at
+ * 150 ms to batch rapid state changes into a single URL update.
+ */
+
+import { useSearchParams, useRouter, usePathname } from "next/navigation";
+import { useCallback, useRef, useEffect } from "react";
+
+export function useUrlParams() {
+  const searchParams = useSearchParams();
+  const router = useRouter();
+  const pathname = usePathname();
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const get = useCallback(
+    (key: string): string | null => {
+      return searchParams.get(key);
+    },
+    [searchParams],
+  );
+
+  const getAll = useCallback((): URLSearchParams => {
+    return new URLSearchParams(searchParams.toString());
+  }, [searchParams]);
+
+  const setAll = useCallback(
+    (params: Record<string, string | undefined>) => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+
+      timerRef.current = setTimeout(() => {
+        const next = new URLSearchParams(searchParams.toString());
+
+        for (const [key, value] of Object.entries(params)) {
+          if (value === undefined || value === "") {
+            next.delete(key);
+          } else {
+            next.set(key, value);
+          }
+        }
+
+        const qs = next.toString();
+        const url = qs ? `${pathname}?${qs}` : pathname;
+        router.replace(url, { scroll: false });
+      }, 150);
+    },
+    [searchParams, pathname, router],
+  );
+
+  useEffect(() => {
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, []);
+
+  return { get, getAll, setAll };
+}

package/lib/utils/session-id.ts

@@ -0,0 +1,4 @@
+export function baseSessionId(sessionId: string): string {
+  const slashIdx = sessionId.indexOf("/");
+  return slashIdx === -1 ? sessionId : sessionId.slice(0, slashIdx);
+}

package/lib/utils.ts

@@ -0,0 +1,31 @@
+/**
+ * General-purpose utility helpers.
+ *
+ * - `cn()` — merges Tailwind CSS class names with conflict resolution.
+ * - `formatDate()` — human-readable absolute date/time string (no ms).
+ */
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+/**
+ * Formats a date to a readable string format (e.g., "Jan 15, 2024, 3:45 PM").
+ *
+ * Creates a new Intl.DateTimeFormat on each call intentionally — this runs
+ * server-side where there's no shared state concern. The client-side hot-path
+ * formatter in lib/log-format.ts caches its instance at module scope instead.
+ */
+export function formatDate(date: Date): string {
+  return new Intl.DateTimeFormat("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+    hour12: true,
+  }).format(date);
+}
+

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "failproofai",
+  "version": "0.0.1-beta.1",
+  "description": "Open-source hooks, policies, and project visualization for Claude Code & Agents SDK",
+  "bin": {
+    "failproofai": "./bin/failproofai.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/",
+    "lib/",
+    ".next/standalone/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.9.0",
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "predev": "bun link",
+    "dev": "FAILPROOFAI_TELEMETRY_DISABLED=1 bun scripts/dev.ts --port 8020",
+    "build": "bun --bun next build",
+    "prestart": "bun link",
+    "start": "FAILPROOFAI_TELEMETRY_DISABLED=1 bun scripts/start.ts",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "lint": "eslint . --config eslint.config.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
+    "preuninstall": "node scripts/preuninstall.mjs",
+    "prepublishOnly": "bun run build",
+    "test:e2e": "vitest run --config vitest.config.e2e.mts",
+    "test:e2e:watch": "vitest --config vitest.config.e2e.mts"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "claude-agents-sdk",
+    "anthropic",
+    "ai-agent",
+    "llm-observability",
+    "agent-observability",
+    "log-viewer",
+    "session-replay",
+    "developer-tools",
+    "devtools",
+    "cli",
+    "local-first",
+    "monitoring",
+    "debugging",
+    "tracing",
+    "hooks",
+    "policies"
+  ],
+  "author": "ExosphereHost Inc. <failproofai@exosphere.host>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://github.com/exospherehost/failproofai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/exospherehost/failproofai.git"
+  },
+  "bugs": {
+    "url": "https://github.com/exospherehost/failproofai/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.1.18",
+    "@tanstack/react-virtual": "^3.13.18",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^25.5.2",
+    "@types/react": "^19.2.13",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "clsx": "^2.1.1",
+    "eslint": "^10.2.0",
+    "eslint-config-next": "^16.2.2",
+    "happy-dom": "^20.7.0",
+    "lucide-react": "^1.0.1",
+    "next": "^16.2.2",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tailwind-merge": "^3.4.0",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^6.0.2",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "posthog-node": "^5.28.11"
+  }
+}

package/scripts/dev.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { launch } from "./launch";
+launch("dev");

package/scripts/install-telemetry.mjs

@@ -0,0 +1,108 @@
+/**
+ * Lightweight PostHog telemetry for npm install/uninstall lifecycle scripts.
+ *
+ * Uses fetch() directly — no external dependencies, Node.js built-ins only.
+ * Mirrors the pattern used in src/hooks/hook-telemetry.ts.
+ */
+import { createHmac, randomUUID } from "node:crypto";
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir, platform, arch, hostname, cpus } from "node:os";
+import { join } from "node:path";
+
+const NAMESPACE = "failproofai-telemetry-v1";
+const API_KEY = "phc_Ac1Ww1GqKc0z1SyrRWbmatEeQdlOQIsDEEdP8l8JRgX";
+const CAPTURE_URL = "https://us.i.posthog.com/capture/";
+
+function hashToId(raw) {
+  return createHmac("sha256", NAMESPACE).update(raw).digest("hex");
+}
+
+function getInstanceId() {
+  // Tier 1: existing ~/.failproofai/instance-id file (consistent with server-side ID)
+  const idDir = join(homedir(), ".failproofai");
+  const idFile = join(idDir, "instance-id");
+  try {
+    const existing = readFileSync(idFile, "utf-8").trim();
+    if (existing) return existing;
+  } catch {}
+
+  // Tier 2: OS-native machine ID (hashed, survives cache deletion)
+  try {
+    const p = platform();
+    if (p === "linux") {
+      for (const machineIdPath of ["/etc/machine-id", "/var/lib/dbus/machine-id"]) {
+        try {
+          const id = readFileSync(machineIdPath, "utf-8").trim();
+          if (id) return hashToId(id);
+        } catch {}
+      }
+    } else if (p === "darwin") {
+      const out = execSync("ioreg -rd1 -c IOPlatformExpertDevice", {
+        encoding: "utf-8",
+        timeout: 3000,
+      });
+      const m = out.match(/"IOPlatformUUID"\s*=\s*"([^"]+)"/);
+      if (m?.[1]) return hashToId(m[1]);
+    } else if (p === "win32") {
+      const out = execSync(
+        'reg query "HKLM\\SOFTWARE\\Microsoft\\Cryptography" /v MachineGuid',
+        { encoding: "utf-8", timeout: 3000 }
+      );
+      const m = out.match(/MachineGuid\s+REG_SZ\s+(\S+)/);
+      if (m?.[1]) return hashToId(m[1]);
+    }
+  } catch {}
+
+  // Tier 3: hashed system properties
+  try {
+    const sysProps = [
+      hostname(),
+      homedir(),
+      platform(),
+      arch(),
+      cpus()[0]?.model ?? "",
+    ].join(":");
+    return hashToId(sysProps);
+  } catch {}
+
+  // Tier 4: random UUID written to file for future consistency
+  const id = randomUUID();
+  try {
+    mkdirSync(idDir, { recursive: true });
+    writeFileSync(idFile, id, "utf-8");
+  } catch {}
+  return id;
+}
+
+/**
+ * Track a named event to PostHog. No-op when telemetry is disabled.
+ * Uses process.env.npm_package_version (set automatically by npm in lifecycle scripts).
+ */
+export async function trackInstallEvent(event, properties = {}) {
+  if (process.env.FAILPROOFAI_TELEMETRY_DISABLED === "1") return;
+
+  const version = process.env.npm_package_version ?? "unknown";
+  const body = JSON.stringify({
+    api_key: process.env.FAILPROOFAI_POSTHOG_KEY ?? API_KEY,
+    event,
+    distinct_id: getInstanceId(),
+    properties: {
+      ...properties,
+      $lib: "failproofai-install",
+      failproofai_version: version,
+    },
+  });
+
+  await fetch(
+    process.env.FAILPROOFAI_POSTHOG_HOST
+      ? `${process.env.FAILPROOFAI_POSTHOG_HOST}/capture/`
+      : CAPTURE_URL,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+      signal: AbortSignal.timeout(5000),
+    }
+  );
+}

package/scripts/launch.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared launch logic for dev.ts and start.ts.
+ */
+import { getDefaultClaudeProjectsPath } from "../lib/paths";
+import { spawn } from "child_process";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseScriptArgs } from "./parse-script-args";
+import { version } from "../package.json";
+
+export function launch(mode: "dev" | "start"): void {
+  const { claudeProjectsPath: parsedPath, loggingLevel, disableTelemetry, remainingArgs } = parseScriptArgs(process.argv.slice(2));
+
+  console.log(`
+    ______      _ __                       ____   ___    ____
+   / ____/___ _(_) /___  _________  ____  / __/  /   |  /  _/
+  / /_  / __ \`/ / / __ \\/ ___/ __ \\/ __ \\/ /_   / /| |  / /
+ / __/ / /_/ / / / /_/ / /  / /_/ / /_/ / __/  / ___ |_/ /
+/_/    \\__,_/_/_/ .___/_/   \\____/\\____/_/    /_/  |_/___/
+               /_/   v${version}
+`);
+
+  let claudeProjectsPath = parsedPath;
+
+  if (!claudeProjectsPath) {
+    claudeProjectsPath = getDefaultClaudeProjectsPath();
+    console.log(`Using default .claude projects path: ${claudeProjectsPath}`);
+  } else {
+    console.log(`Using custom .claude projects path: ${claudeProjectsPath}`);
+  }
+
+  process.env.CLAUDE_PROJECTS_PATH = claudeProjectsPath;
+
+  let cmd: string;
+  let cmdArgs: string[];
+  if (mode === "start") {
+    const portIdx = remainingArgs.indexOf("--port");
+    const port = portIdx >= 0 ? remainingArgs[portIdx + 1] : "8020";
+    process.env.PORT = port;
+    process.env.HOSTNAME = "0.0.0.0";
+    cmd = "node";
+    // Absolute path — required so the CLI works from any working directory after install
+    cmdArgs = [resolve(dirname(fileURLToPath(import.meta.url)), "../.next/standalone/server.js")];
+  } else {
+    cmd = "bunx";
+    cmdArgs = ["--bun", "next", "dev", ...remainingArgs];
+  }
+
+  const nextProcess = spawn(cmd, cmdArgs, {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      CLAUDE_PROJECTS_PATH: claudeProjectsPath,
+      ...(loggingLevel ? { FAILPROOFAI_LOG_LEVEL: loggingLevel } : {}),
+      ...(disableTelemetry ? { FAILPROOFAI_TELEMETRY_DISABLED: "1" } : {}),
+    },
+  });
+
+  nextProcess.on("error", (error) => {
+    console.error("Error starting Next.js:", error);
+    process.exit(1);
+  });
+
+  nextProcess.on("exit", (code) => {
+    process.exit(code || 0);
+  });
+}

package/scripts/parse-script-args.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared CLI argument parser for scripts/dev.ts and scripts/start.ts.
+ */
+import { resolve } from "path";
+
+export interface ParsedScriptArgs {
+  claudeProjectsPath: string | undefined;
+  loggingLevel: string | undefined;
+  disableTelemetry: boolean;
+  remainingArgs: string[];
+}
+
+function parseStringFlag(
+  flagName: string,
+  errorLabel: string,
+  inlineValue: string | null,
+  args: string[],
+  index: number,
+  options?: { resolve?: boolean },
+): { value: string; spliceCount: number } {
+  const raw = inlineValue ?? args[index + 1];
+  if (raw === undefined || (inlineValue === null && raw.startsWith("-"))) {
+    console.error(`Error: ${flagName} requires ${errorLabel}`);
+    process.exit(1);
+  }
+  const value = options?.resolve ? resolve(raw) : raw;
+  return { value, spliceCount: inlineValue !== null ? 1 : 2 };
+}
+
+export function parseScriptArgs(argv: string[]): ParsedScriptArgs {
+  const args = [...argv];
+  let claudeProjectsPath: string | undefined;
+  let loggingLevel: string | undefined;
+  let disableTelemetry = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    const eqIdx = arg.indexOf("=");
+    const flag = eqIdx >= 0 ? arg.slice(0, eqIdx) : arg;
+    const inlineValue = eqIdx >= 0 ? arg.slice(eqIdx + 1) : null;
+
+    if (flag === "--projects-path" || flag === "-p") {
+      const { value, spliceCount } = parseStringFlag(flag, "a path argument", inlineValue, args, i);
+      claudeProjectsPath = value;
+      args.splice(i, spliceCount);
+      i--;
+      continue;
+    }
+
+    if (flag === "--logging") {
+      const raw = inlineValue ?? args[i + 1];
+      if (raw === undefined || (inlineValue === null && raw.startsWith("-"))) {
+        console.error("Error: --logging requires a level (info, warn, error)");
+        process.exit(1);
+      }
+      const val = raw.toLowerCase();
+      if (val !== "info" && val !== "warn" && val !== "error") {
+        console.error("Error: --logging must be one of: info, warn, error");
+        process.exit(1);
+      }
+      loggingLevel = val;
+      args.splice(i, inlineValue !== null ? 1 : 2);
+      i--;
+      continue;
+    }
+
+    if (flag === "--disable-telemetry") {
+      disableTelemetry = true;
+      args.splice(i, 1);
+      i--;
+      continue;
+    }
+  }
+
+  return { claudeProjectsPath, loggingLevel, disableTelemetry, remainingArgs: args };
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * postinstall script for the failproofai package.
+ *
+ * 1. Warns if hooks config exists but hooks are missing from Claude Code settings.
+ * 2. Tracks a package_installed telemetry event.
+ *
+ * No external dependencies — Node.js built-ins only.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { platform, arch, release, homedir, hostname } from "node:os";
+import { createHmac } from "node:crypto";
+import { trackInstallEvent } from "./install-telemetry.mjs";
+
+// Skip when running in development context (e.g. `bun install` in the source repo).
+// INIT_CWD is set by npm/bun to the directory where install was invoked; it differs
+// from process.cwd() only when we are being installed as a dependency by someone else.
+if (!process.env.INIT_CWD || process.env.INIT_CWD === process.cwd()) process.exit(0);
+
+const FAILPROOFAI_HOOK_MARKER = "__failproofai_hook__";
+const NAMESPACE = "failproofai-telemetry-v1";
+
+function hashToId(raw) {
+  return createHmac("sha256", NAMESPACE).update(raw).digest("hex");
+}
+
+/**
+ * Returns the current hooks configuration state.
+ * @returns {{ configured: boolean, registered: boolean, policyCount: number }}
+ */
+function checkHooks() {
+  const hooksConfigPath = resolve(homedir(), ".failproofai", "hooks-config.json");
+  if (!existsSync(hooksConfigPath)) {
+    return { configured: false, registered: false, policyCount: 0 };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(readFileSync(hooksConfigPath, "utf8"));
+  } catch {
+    return { configured: false, registered: false, policyCount: 0 };
+  }
+
+  if (!Array.isArray(config.enabledPolicies) || config.enabledPolicies.length === 0) {
+    return { configured: false, registered: false, policyCount: 0 };
+  }
+
+  const policyCount = config.enabledPolicies.length;
+
+  // Check if Claude Code settings have failproofai hooks
+  const settingsPath = resolve(homedir(), ".claude", "settings.json");
+  if (!existsSync(settingsPath)) {
+    printHooksWarning();
+    return { configured: true, registered: false, policyCount };
+  }
+
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+  } catch {
+    printHooksWarning();
+    return { configured: true, registered: false, policyCount };
+  }
+
+  if (!settings.hooks) {
+    printHooksWarning();
+    return { configured: true, registered: false, policyCount };
+  }
+
+  // Walk settings.hooks looking for failproofai entries
+  for (const matchers of Object.values(settings.hooks)) {
+    if (!Array.isArray(matchers)) continue;
+    for (const matcher of matchers) {
+      if (!matcher.hooks) continue;
+      if (matcher.hooks.some((h) => h[FAILPROOFAI_HOOK_MARKER] === true)) {
+        return { configured: true, registered: true, policyCount };
+      }
+    }
+  }
+
+  printHooksWarning();
+  return { configured: true, registered: false, policyCount };
+}
+
+function printHooksWarning() {
+  console.log(
+    `\n[failproofai] Warning: hooks config exists with enabled policies, but hooks are not registered in Claude Code settings.\n` +
+    `  To re-register hooks, run:\n` +
+    `    failproofai --remove-policies && failproofai --install-policies\n`
+  );
+}
+
+let hooksResult = { configured: false, registered: false, policyCount: 0 };
+try {
+  hooksResult = checkHooks();
+} catch {
+  // Non-critical — don't fail the install
+}
+
+// Telemetry (best-effort, fire-and-forget)
+trackInstallEvent("package_installed", {
+  platform: platform(),
+  arch: arch(),
+  os_release: release(),
+  hostname_hash: hashToId(hostname()),
+  hooks_configured: hooksResult.configured,
+  hooks_registered: hooksResult.registered,
+  enabled_policy_count: hooksResult.policyCount,
+}).catch(() => {});