failproofai 0.0.10 → 0.0.11-beta.10

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,59 @@
+/**
+ * Shared fetch wrapper with per-request timeout and external-signal
+ * composition.
+ *
+ * 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.
+ *
+ * Built on the platform primitives `AbortSignal.timeout()` — which
+ * aborts with a typed `DOMException(..., "TimeoutError")` rather than
+ * the default bare abort that surfaces as Next.js 16's dev-overlay
+ * "signal is aborted without reason" warning — and `AbortSignal.any()`,
+ * which composes the timeout signal with any caller-supplied
+ * `init.signal` so a component-unmount or parent-controller abort
+ * actually stops the in-flight fetch. The prior `AbortController` +
+ * `setTimeout` implementation called `controller.abort()` with no
+ * reason AND silently dropped `init.signal` by spreading then
+ * overwriting it with the controller's own signal.
+ *
+ * Both APIs are available in every runtime Next.js 16 supports:
+ * `AbortSignal.timeout` since Node 17.3 / 16.14, `AbortSignal.any`
+ * since Node 20.3 (also backported to 18.17). Next.js 16's minimum
+ * runtime (Node >= 20.9, per its engines field) covers both. Browser
+ * support: Chrome 116+, Firefox 124+, Safari 17.4+.
+ */
+
+/** 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 function fetchWithTimeout(
+  input: RequestInfo | URL,
+  init: RequestInit = {},
+  timeoutMs: number = DEFAULT_FETCH_TIMEOUT_MS,
+): Promise<Response> {
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  const signal = init.signal
+    ? AbortSignal.any([init.signal, timeoutSignal])
+    : timeoutSignal;
+  return fetch(input, { ...init, signal });
+}
+
+/** True when an error came from an `AbortController.abort()` OR an
+ *  `AbortSignal.timeout()` firing. Both surface as objects whose `name`
+ *  is "AbortError" or "TimeoutError" respectively — depending on the
+ *  runtime, they may be `Error` subclasses, `DOMException` instances,
+ *  both, or neither (the jsdom polyfill, for one, breaks the Error
+ *  prototype chain), so we duck-type on `name` rather than the
+ *  provenance. Callers always pass values caught from a try/catch, so
+ *  the universe of inputs is narrow enough that name-matching is
+ *  unambiguous. Keeping the two names in one predicate prevents the
+ *  "I forgot TimeoutError" drift class. */
+export function isAbortError(err: unknown): boolean {
+  if (err === null || typeof err !== "object") return false;
+  const name = (err as { name?: unknown }).name;
+  return name === "AbortError" || name === "TimeoutError";
+}

package/lib/share-card.ts

@@ -0,0 +1,144 @@
+/**
+ * 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";
+
+/**
+ * Best-effort "is this a mobile device" check. On mobile, the system share
+ * sheet exposes the actual X / LinkedIn apps as targets so `navigator.share`
+ * is a one-tap UX win. On desktop (notably Windows Chromium / Edge) the same
+ * call opens the OS share dialog — useless for X / LinkedIn — so we
+ * deliberately skip it and fall back to clipboard + intent URL.
+ *
+ * Prefers `userAgentData.mobile` (Chromium UA-Client-Hints, no sniffing),
+ * falls back to a tight UA pattern for Safari / Firefox, and treats
+ * iPadOS 13+ (UA says Mac but multi-touch is available) as mobile.
+ */
+function isLikelyMobile(): boolean {
+  if (typeof navigator === "undefined") return false;
+  type UADataNav = Navigator & { userAgentData?: { mobile?: boolean } };
+  const uaData = (navigator as UADataNav).userAgentData;
+  if (uaData && typeof uaData.mobile === "boolean") return uaData.mobile;
+  const ua = navigator.userAgent || "";
+  if (/Android|iPhone|iPad|iPod|webOS|BlackBerry|IEMobile|Opera Mini/i.test(ua)) return true;
+  if (ua.includes("Mac") && typeof navigator.maxTouchPoints === "number" && navigator.maxTouchPoints > 1) return true;
+  return false;
+}
+
+/**
+ * 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, the device is desktop (where the OS share sheet doesn't
+ * include X / LinkedIn), 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;
+  }
+  if (!isLikelyMobile()) 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.10",
+  "version": "0.0.11-beta.10",
   "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"
@@ -59,42 +59,50 @@
   ],
   "author": "ExosphereHost Inc. <failproofai@exosphere.host>",
   "license": "SEE LICENSE IN LICENSE",
-  "homepage": "https://github.com/exospherehost/failproofai",
+  "homepage": "https://github.com/FailproofAI/failproofai",
   "repository": {
     "type": "git",
-    "url": "https://github.com/exospherehost/failproofai.git"
+    "url": "https://github.com/FailproofAI/failproofai.git"
   },
   "bugs": {
-    "url": "https://github.com/exospherehost/failproofai/issues"
+    "url": "https://github.com/FailproofAI/failproofai/issues"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.93.0",
-    "@tailwindcss/postcss": "^4.1.18",
-    "@tanstack/react-virtual": "^3.13.18",
+    "@anthropic-ai/sdk": "^0.105.0",
+    "@tailwindcss/postcss": "^4.3.1",
+    "@tanstack/react-virtual": "^3.14.3",
     "@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/node": "26.0.0",
+    "@types/react": "19.2.17",
     "@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",
+    "eslint": "^10.5.0",
+    "eslint-config-next": "^16.2.9",
+    "jsdom": "^29.1.1",
+    "lucide-react": "^1.18.0",
+    "next": "^16.2.9",
     "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"
+    "tailwindcss": "^4.3.1",
+    "typescript": "6.0.3",
+    "vitest": "^4.1.9"
   },
   "dependencies": {
-    "posthog-node": "^5.28.11"
+    "html-to-image": "^1.11.13",
+    "html2canvas": "^1.4.1",
+    "posthog-node": "^5.37.1"
+  },
+  "overrides": {
+    "postcss": "8.5.14",
+    "eslint-plugin-react-hooks": "7.0.1",
+    "vite": "8.0.16",
+    "undici": "7.28.0"
   }
 }

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/launch.ts

@@ -17,9 +17,9 @@ export function launch(mode: "dev" | "start"): void {
   // same column so the values form a clean right-hand column).
   console.log(`\n  failproof ai\n`);
   console.log(`  📦 Version:      ${version}`);
-  console.log(`  ⭐ Star us:      https://github.com/exospherehost/failproofai`);
+  console.log(`  ⭐ Star us:      https://github.com/failproofai/failproofai`);
   console.log(`  📖 Docs:         https://befailproof.ai`);
-  console.log(`  💬 Slack:        https://join.slack.com/t/failproofai/shared_invite/zt-3v63b7k5e-O3NBHmj8X6n9gZSGDx6ggQ\n`);
+  console.log(`  💬 Discord:      https://discord.gg/2zjBZP7yQJ\n`);
 
   let cmd: string;
   let cmdArgs: string[];

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(),