failproofai 0.0.11-beta.1 → 0.0.11-beta.3

package/lib/claude-sessions.ts

@@ -0,0 +1,181 @@
+/**
+ * Claude Code session transcript discovery helpers.
+ *
+ * Claude stores transcripts at:
+ *   <CLAUDE_PROJECTS_PATH>/<encoded-cwd>/<sessionId>.jsonl
+ *
+ * Subagent transcripts (when a session spawned subagents) live alongside:
+ *   <CLAUDE_PROJECTS_PATH>/<encoded-cwd>/<sessionId>/subagents/<agentId>.jsonl
+ *
+ * The parser for these files lives in `lib/log-entries.ts` (`parseLogContent`,
+ * `parseSessionLog`). This module exposes discovery only — the audit pipeline
+ * and any future Claude-specific tool walk the directory layout via these
+ * helpers instead of re-implementing the path conventions.
+ *
+ * Mirrors the shape of `lib/cursor-sessions.ts` for parity across CLIs.
+ */
+import { readdirSync, statSync, existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import { getClaudeProjectsPath, decodeFolderName } from "./paths";
+
+const UUID_RE = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+
+export interface ClaudeProjectFolder {
+  /** Encoded folder name on disk (e.g. "-home-user-project"). */
+  name: string;
+  /** Decoded filesystem path (e.g. "/home/user/project"). */
+  cwd: string;
+  /** Absolute path of the encoded folder. */
+  path: string;
+}
+
+export interface ClaudeTranscriptFile {
+  projectName: string;
+  /** Decoded cwd of the project. */
+  cwd: string;
+  sessionId: string;
+  /** Absolute path of `<sessionId>.jsonl`. */
+  transcriptPath: string;
+  mtimeMs: number;
+  sizeBytes: number;
+  /** True when this is a subagent transcript spawned from a parent session. */
+  isSubagent: boolean;
+}
+
+/** Returns the Claude projects root, honoring the CLAUDE_PROJECTS_PATH env var. */
+export function getClaudeProjectsRoot(): string {
+  return getClaudeProjectsPath();
+}
+
+/** Lists all Claude project folders (one per encoded cwd). Returns [] if the
+ *  projects root doesn't exist. Filenames that don't look like Claude project
+ *  encodings are still included — encoding is permissive. */
+export function listClaudeProjects(): ClaudeProjectFolder[] {
+  const root = getClaudeProjectsRoot();
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => ({
+      name: e.name,
+      cwd: decodeFolderName(e.name),
+      path: join(root, e.name),
+    }));
+}
+
+/** Lists every JSONL transcript under one Claude project folder, including
+ *  subagent transcripts under `<sessionId>/subagents/`. Returns [] on missing
+ *  or unreadable paths. */
+export function listClaudeTranscripts(project: ClaudeProjectFolder): ClaudeTranscriptFile[] {
+  const out: ClaudeTranscriptFile[] = [];
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = readdirSync(project.path, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+
+  for (const entry of entries) {
+    if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+      const sessionId = entry.name.slice(0, -".jsonl".length);
+      if (!UUID_RE.test(sessionId)) continue;
+      const transcriptPath = join(project.path, entry.name);
+      try {
+        const s = statSync(transcriptPath);
+        out.push({
+          projectName: project.name,
+          cwd: project.cwd,
+          sessionId,
+          transcriptPath,
+          mtimeMs: s.mtimeMs,
+          sizeBytes: s.size,
+          isSubagent: false,
+        });
+      } catch {
+        // unreadable — skip
+      }
+    } else if (entry.isDirectory() && UUID_RE.test(entry.name)) {
+      // Subagent transcripts at <sessionId>/subagents/<agentId>.jsonl
+      const subDir = join(project.path, entry.name, "subagents");
+      if (!existsSync(subDir)) continue;
+      let subEntries: import("node:fs").Dirent[];
+      try {
+        subEntries = readdirSync(subDir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const sub of subEntries) {
+        if (!sub.isFile() || !sub.name.endsWith(".jsonl")) continue;
+        const agentId = sub.name.slice(0, -".jsonl".length);
+        const transcriptPath = join(subDir, sub.name);
+        try {
+          const s = statSync(transcriptPath);
+          out.push({
+            projectName: project.name,
+            cwd: project.cwd,
+            sessionId: agentId,
+            transcriptPath,
+            mtimeMs: s.mtimeMs,
+            sizeBytes: s.size,
+            isSubagent: true,
+          });
+        } catch {
+          // unreadable — skip
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+/** Convenience: locate one Claude transcript file by session ID across all
+ *  project folders. Returns null if not found. */
+export function findClaudeTranscript(sessionId: string): string | null {
+  if (!UUID_RE.test(sessionId)) return null;
+  for (const project of listClaudeProjects()) {
+    const candidate = join(project.path, `${sessionId}.jsonl`);
+    if (existsSync(candidate)) return candidate;
+    // Subagent fallback
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = readdirSync(project.path, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !UUID_RE.test(entry.name)) continue;
+      const subCandidate = join(project.path, entry.name, "subagents", `${sessionId}.jsonl`);
+      if (existsSync(subCandidate)) return subCandidate;
+    }
+  }
+  return null;
+}
+
+/** For tests: list all session IDs across all projects. */
+export function _listAllSessionIds(): string[] {
+  const ids: string[] = [];
+  for (const project of listClaudeProjects()) {
+    for (const t of listClaudeTranscripts(project)) {
+      ids.push(t.sessionId);
+    }
+  }
+  return ids;
+}
+
+/** For tests: stat one transcript file. */
+export function _statTranscript(path: string): { mtimeMs: number; sizeBytes: number } | null {
+  try {
+    const s = statSync(path);
+    return { mtimeMs: s.mtimeMs, sizeBytes: s.size };
+  } catch {
+    return null;
+  }
+}
+
+/** Re-export for callers that want to construct paths from a basename. */
+export { basename };

package/lib/client-telemetry.ts

@@ -1,4 +1,5 @@
 import type { TelemetryConfig } from "@/app/actions/get-telemetry-config";
+import { POSTHOG_PRODUCT } from "@/src/posthog-key";
 
 let config: TelemetryConfig | null = null;
 
@@ -21,6 +22,7 @@ export function captureClientEvent(
       ...properties,
       $lib: "failproofai-web",
       failproofai_version: config.version,
+      product: POSTHOG_PRODUCT,
       $current_url: window.location.href,
       $pathname: window.location.pathname,
     },

package/lib/fetch-with-timeout.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared fetch wrapper with per-request timeout via AbortController.
+ *
+ * Replaces three byte-equivalent implementations that had drifted on the
+ * default timeout (15s in two client components, 10s in the server-side
+ * api-server-client). Co-locates the `isAbortError` predicate so callers
+ * can classify timeout vs network failures consistently.
+ *
+ * Server-side uses `AbortSignal.timeout` where available (cheaper); this
+ * helper uses the AbortController+setTimeout form because the client
+ * code-paths need a guaranteed cleanup hook.
+ */
+
+/** Hard cap on every fetch using this helper unless overridden. Picked to
+ *  exceed the server-side `REQUEST_TIMEOUT_MS` (10s) in `api-server-client.ts`
+ *  so a slow but successful upstream response still lands. */
+export const DEFAULT_FETCH_TIMEOUT_MS = 15_000;
+
+export async function fetchWithTimeout(
+  input: RequestInfo | URL,
+  init: RequestInit = {},
+  timeoutMs: number = DEFAULT_FETCH_TIMEOUT_MS,
+): Promise<Response> {
+  const controller = new AbortController();
+  const id = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(input, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(id);
+  }
+}
+
+/** True when an error came from an AbortController.abort() OR a
+ *  `AbortSignal.timeout` firing. Both surface as `Error` with `name`
+ *  set to "AbortError" or "TimeoutError" respectively. Keeping the two
+ *  in one predicate prevents the "I forgot TimeoutError" drift class. */
+export function isAbortError(err: unknown): boolean {
+  return (
+    err instanceof Error
+    && (err.name === "AbortError" || err.name === "TimeoutError")
+  );
+}

package/lib/share-card.ts

@@ -0,0 +1,120 @@
+/**
+ * Helpers for attaching the audit-card PNG to a social share.
+ *
+ *   X and LinkedIn intent URLs cannot carry image attachments — only text
+ *   and a target URL. To actually get an image into a post we have three
+ *   options at different levels of "automatic":
+ *
+ *     1. `shareCardNative` → `navigator.share({ files })` — the system
+ *        share sheet handles the image + text in one step. Works on
+ *        iOS, Android, recent Safari, recent Chrome desktop. When the
+ *        user picks their target (X / LinkedIn / …) the image is
+ *        already attached.
+ *     2. `copyOrDownloadCard` → clipboard + open intent URL — the user
+ *        pastes (⌘/Ctrl+V) in the share dialog and the image attaches.
+ *     3. `downloadCard` → straight download to disk, no other side
+ *        effects. Used by the dedicated "save audit-card" button so
+ *        the user gets a file every time, regardless of clipboard
+ *        permissions.
+ */
+
+export type ShareCardMethod = "native" | "clipboard" | "download" | "failed";
+
+/**
+ * Try the native Web Share API with a file attachment. Returns `true` on
+ * success, `false` if the API is unavailable, files-sharing isn't
+ * supported, or the user dismissed the sheet. Caller should fall back to
+ * `copyOrDownloadCard` on `false`.
+ */
+export async function shareCardNative(
+  blob: Blob,
+  filename: string,
+  text: string,
+): Promise<boolean> {
+  if (typeof navigator === "undefined" || typeof navigator.share !== "function") {
+    return false;
+  }
+  const file = new File([blob], filename, { type: "image/png" });
+  // Some browsers (older Chrome desktop) expose `navigator.share` but reject
+  // file payloads. `canShare({ files })` gates that cleanly.
+  type CanShareNav = Navigator & { canShare?: (data: ShareData) => boolean };
+  const navWithCan = navigator as CanShareNav;
+  if (typeof navWithCan.canShare === "function" && !navWithCan.canShare({ files: [file] })) {
+    return false;
+  }
+  try {
+    await navigator.share({ files: [file], text });
+    return true;
+  } catch (err) {
+    // AbortError → user dismissed the sheet. Treat as a soft failure so the
+    // caller can decide whether to open the intent URL anyway.
+    if (err instanceof Error && err.name === "AbortError") return false;
+    return false;
+  }
+}
+
+/**
+ * Copy a captured share-card PNG to the system clipboard, or fall back to a
+ * download if the browser doesn't support image clipboard writes (or the
+ * user denied permission). The caller MUST be inside an active user gesture
+ * (click handler) — Chromium gates `navigator.clipboard.write` on user
+ * activation.
+ */
+export async function copyOrDownloadCard(
+  blob: Blob,
+  filename: string,
+): Promise<Exclude<ShareCardMethod, "native">> {
+  if (
+    typeof ClipboardItem !== "undefined"
+    && typeof navigator !== "undefined"
+    && navigator.clipboard
+    && typeof navigator.clipboard.write === "function"
+  ) {
+    try {
+      await navigator.clipboard.write([
+        new ClipboardItem({ "image/png": blob }),
+      ]);
+      return "clipboard";
+    } catch {
+      /* permission denied, secure-context issue, browser fence, … */
+    }
+  }
+  return downloadCard(blob, filename) ? "download" : "failed";
+}
+
+/**
+ * Trigger a local download of the PNG. Returns `true` on success. No
+ * clipboard interaction — used by the explicit "save audit-card" CTA so the
+ * user reliably gets a file even when clipboard write would succeed.
+ */
+export function downloadCard(blob: Blob, filename: string): boolean {
+  try {
+    if (typeof document === "undefined" || typeof URL === "undefined") return false;
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = filename;
+    a.style.display = "none";
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    queueMicrotask(() => URL.revokeObjectURL(url));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Human-readable toast copy keyed by share method. */
+export function shareCardToastMessage(method: ShareCardMethod): string {
+  switch (method) {
+    case "native":
+      return "✅ image attached — pick where to post";
+    case "clipboard":
+      return "📋 image copied — paste it in the post (⌘/Ctrl+V)";
+    case "download":
+      return "⬇ image downloaded — attach it to your post";
+    case "failed":
+      return "couldn't capture image — opening text-only share";
+  }
+}

package/lib/telemetry.ts

@@ -10,7 +10,7 @@
 
 import { getInstanceId } from "./telemetry-id";
 import { version } from "../package.json";
-import { POSTHOG_API_KEY } from "../src/posthog-key";
+import { POSTHOG_API_KEY, POSTHOG_PRODUCT } from "../src/posthog-key";
 
 const DEFAULT_API_KEY = POSTHOG_API_KEY;
 const DEFAULT_HOST = "https://us.i.posthog.com";
@@ -81,13 +81,18 @@ export function isTelemetryEnabled(): boolean {
 
 /**
  * Lazily import posthog-node and create a client.
- * No-op when telemetry is disabled.
+ *
+ * No-op when telemetry is disabled. **Never throws** — callers (the
+ * Next.js API routes and the CLI subcommands) can `await initTelemetry()`
+ * unguarded and a posthog init failure can't 500 a valid auth response.
+ * The outer try/catch is the single source of truth; do NOT add a
+ * per-call wrapper at the call sites.
  */
 export async function initTelemetry(): Promise<void> {
-  if (!isTelemetryEnabled()) return;
-  if (globalThis.__FAILPROOFAI_POSTHOG__) return;
-
   try {
+    if (!isTelemetryEnabled()) return;
+    if (globalThis.__FAILPROOFAI_POSTHOG__) return;
+
     const mod: { PostHog: new (key: string, opts: PostHogOptions) => PostHogClient } =
       await import("posthog-node");
     const apiKey = process.env.FAILPROOFAI_POSTHOG_KEY ?? DEFAULT_API_KEY;
@@ -110,7 +115,7 @@ export async function initTelemetry(): Promise<void> {
     process.on("SIGINT", onExit);
   } catch (err) {
     // Always log init failures — silent swallowing makes standalone debugging impossible
-    console.warn("[failproofai:telemetry] PostHog init failed:", err instanceof Error ? err.message : err);
+    console.warn("[failproofai:telemetry] init failed:", err instanceof Error ? err.message : err);
   }
 }
 
@@ -129,7 +134,7 @@ export function trackEvent(
   client.capture({
     distinctId: getInstanceId(),
     event: name,
-    properties: { ...properties, $lib: "failproofai", failproofai_version: version },
+    properties: { ...properties, $lib: "failproofai", failproofai_version: version, product: POSTHOG_PRODUCT },
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "0.0.11-beta.1",
+  "version": "0.0.11-beta.3",
   "description": "The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously — for Claude Code & the Agents SDK",
   "bin": {
     "failproofai": "./dist/cli.mjs"
@@ -71,7 +71,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.96.0",
+    "@anthropic-ai/sdk": "^0.102.0",
     "@tailwindcss/postcss": "^4.1.18",
     "@tanstack/react-virtual": "^3.13.18",
     "@testing-library/jest-dom": "^6.9.1",
@@ -84,7 +84,7 @@
     "clsx": "^2.1.1",
     "eslint": "^10.2.0",
     "eslint-config-next": "^16.2.2",
-    "happy-dom": "^20.7.0",
+    "jsdom": "^29.1.1",
     "lucide-react": "^1.0.1",
     "next": "^16.2.2",
     "react": "^19.2.4",
@@ -95,6 +95,11 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
+    "html2canvas": "^1.4.1",
     "posthog-node": "^5.28.11"
+  },
+  "overrides": {
+    "postcss": "8.5.14",
+    "eslint-plugin-react-hooks": "7.0.1"
   }
 }

package/scripts/install-telemetry.mjs

@@ -13,6 +13,9 @@ import { join } from "node:path";
 const NAMESPACE = "failproofai-telemetry-v1";
 const API_KEY = "phc_Ac1Ww1GqKc0z1SyrRWbmatEeQdlOQIsDEEdP8l8JRgX";
 const CAPTURE_URL = "https://us.i.posthog.com/capture/";
+// Mirrors POSTHOG_PRODUCT in src/posthog-key.ts — this standalone npm-lifecycle
+// script can't import the TS module at install time, so the literal is inlined.
+const PRODUCT = "failproofai-oss";
 
 function hashToId(raw) {
   return createHmac("sha256", NAMESPACE).update(raw).digest("hex");
@@ -91,6 +94,7 @@ export async function trackInstallEvent(event, properties = {}) {
       ...properties,
       $lib: "failproofai-install",
       failproofai_version: version,
+      product: PRODUCT,
     },
   });
 

package/scripts/postinstall.mjs

@@ -7,7 +7,7 @@
  *
  * No external dependencies — Node.js built-ins only.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { resolve } from "node:path";
 import { platform, arch, release, homedir, hostname } from "node:os";
 import { createHmac } from "node:crypto";
@@ -134,6 +134,94 @@ try {
   // Non-critical — don't fail the install
 }
 
+if (!hooksResult.configured && !hooksResult.registered) {
+  console.log(
+    `\n[failproofai] Installed. Next steps:\n` +
+    `  1. Run \`failproofai policies --install\` to enable safety policies.\n` +
+    `  2. Run \`failproofai\` to open the dashboard (or just \`failproofai\` to start now — it'll offer to set up policies for you).\n` +
+    `  Disable first-run prompt: FAILPROOFAI_NO_FIRST_RUN=1\n`
+  );
+}
+
+// First-run + version_changed detection. The presence of ~/.failproofai/last-version
+// is a stable signal: written on every postinstall, absent before the first one.
+// Cannot piggy-back on instance-id because most users hit Tier 2 (OS machine ID)
+// and never create that file.
+//
+// Semver comparison: a release (no prerelease tag) is greater than the same
+// version with a prerelease tag (semver §11). Inside the prerelease, numeric
+// identifiers are lower than non-numeric ones of the same length.
+function compareSemver(a, b) {
+  const parse = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(v);
+    if (!m) return null;
+    return { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return a < b ? -1 : a > b ? 1 : 0;
+  for (let i = 0; i < 3; i++) {
+    if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] < pb.nums[i] ? -1 : 1;
+  }
+  if (pa.pre === null && pb.pre === null) return 0;
+  if (pa.pre === null) return 1;
+  if (pb.pre === null) return -1;
+  const ax = pa.pre.split(/[.-]/);
+  const bx = pb.pre.split(/[.-]/);
+  for (let i = 0; i < Math.max(ax.length, bx.length); i++) {
+    const ai = ax[i], bi = bx[i];
+    if (ai === undefined) return -1;
+    if (bi === undefined) return 1;
+    const aNum = /^\d+$/.test(ai), bNum = /^\d+$/.test(bi);
+    if (aNum && bNum) {
+      const d = Number(ai) - Number(bi);
+      if (d !== 0) return d < 0 ? -1 : 1;
+    } else if (aNum) {
+      return -1;
+    } else if (bNum) {
+      return 1;
+    } else if (ai !== bi) {
+      return ai < bi ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+const currentVersion = process.env.npm_package_version ?? "unknown";
+const lastVersionFile = resolve(homedir(), ".failproofai", "last-version");
+let previousVersion = null;
+try {
+  if (existsSync(lastVersionFile)) {
+    previousVersion = readFileSync(lastVersionFile, "utf8").trim() || null;
+  }
+} catch {}
+
+if (previousVersion === null) {
+  trackInstallEvent("first_install", {
+    platform: platform(),
+    arch: arch(),
+    os_release: release(),
+    node_version: process.versions.node,
+    version: currentVersion,
+  }).catch(() => {});
+} else {
+  // Same version is a reinstall — still worth tracking; users hitting `npm install -g`
+  // repeatedly is itself signal. Drop the `!==` guard so cmp===0 reaches the event.
+  const cmp = compareSemver(previousVersion, currentVersion);
+  trackInstallEvent("version_changed", {
+    from_version: previousVersion,
+    to_version: currentVersion,
+    direction: cmp < 0 ? "upgrade" : cmp > 0 ? "downgrade" : "reinstall",
+    platform: platform(),
+    arch: arch(),
+  }).catch(() => {});
+}
+
+try {
+  mkdirSync(resolve(homedir(), ".failproofai"), { recursive: true });
+  writeFileSync(lastVersionFile, currentVersion, "utf8");
+} catch {}
+
 // Telemetry (best-effort, fire-and-forget)
 trackInstallEvent("package_installed", {
   platform: platform(),