failproofai 0.0.10 → 0.0.11-beta.10

package/README.md

@@ -1,9 +1,10 @@
 <div align="center">
 
-<img src="https://d2wq11aau0arks.cloudfront.net/failproof/logo-wordmark.png" alt="failproof ai" width="220" />
+<img src="https://d2wq11aau0arks.cloudfront.net/failproof/fa_updated_full.svg" alt="failproof ai" width="220" />
 
 [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai)
-[![CI](https://img.shields.io/github/actions/workflow/status/exospherehost/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/exospherehost/failproofai/actions)
+[![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions)
+[![Supply Chain](https://img.shields.io/badge/supply%20chain-secure-brightgreen?style=flat-square)](https://github.com/failproofai/failproofai/actions/workflows/osv-scanner.yml)
 [![Slack](https://img.shields.io/badge/Slack-join%20us-4A154B?style=flat-square&logo=slack)](https://join.slack.com/t/failproofai/shared_invite/zt-3v63b7k5e-O3NBHmj8X6n9gZSGDx6ggQ)
 [![Docs](https://img.shields.io/badge/docs-befailproof.ai-002CA7?style=flat-square)](https://docs.befailproof.ai)
 [![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](./LICENSE)
@@ -73,7 +74,7 @@ before they become incidents. Zero latency. Runs locally.
   </a>
 </p>
 
-> Install hooks for one or any combination: `failproofai policies --install --cli opencode pi gemini` (or `--cli claude codex copilot cursor opencode pi gemini`). Omit `--cli` to auto-detect installed CLIs and prompt. **GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, and Gemini CLI support are in beta — testing is ongoing.**
+> Install hooks for one or any combination: `failproofai policies --install --cli opencode pi gemini` (or `--cli claude codex copilot cursor opencode pi gemini`). Omit `--cli` to auto-detect installed CLIs and prompt.
 
 ---
 
@@ -81,11 +82,11 @@ before they become incidents. Zero latency. Runs locally.
 
 ```sh
 npm install -g failproofai
-failproofai policies --install
+failproofai policies --install   # or just run `failproofai` and accept the first-run prompt
 failproofai
 ```
 
-30 built-in policies activate immediately. Dashboard at `localhost:8020`.
+30 built-in policies activate immediately. Dashboard at `localhost:8020`. Disable the first-run prompt with `FAILPROOFAI_NO_FIRST_RUN=1`.
 
 ---
 
@@ -165,6 +166,12 @@ MIT with [Commons Clause](https://commonsclause.com/) — free for internal and
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md). New policies, edge cases, and translations all welcome.
 
+> **Build before you start.** Run `bun install && bun run build` first. This repo runs
+> failproofai's own hooks on itself, and they resolve the `failproofai` import against the
+> compiled `dist/` bundle — without a build you'll hit `Cannot find package 'failproofai'`
+> hook errors. Rebuild after changing `src/`. See
+> [Build before the in-repo dev hooks will work](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work).
+
 ---
 
 Built by [Nivedit Jain](https://github.com/NiveditJain) and [Nikita Agarwal](https://github.com/nk-ag).

package/bin/failproofai.mjs

@@ -37,6 +37,28 @@ const args = process.argv.slice(2);
 // Normalize 'p' → 'policies' (shorthand alias)
 if (args[0] === "p") args[0] = "policies";
 
+// Lightweight telemetry helper for CLI lifecycle events. Lazy-loads to avoid
+// pulling in the hook-telemetry / telemetry-id modules on the fast --hook path.
+let _telemetry;
+let lastSubcommand = null;
+// When `policy add|remove` is mid-execution we stash the action here so the
+// top-level catch can emit `cli_policy_add_failure` / `cli_policy_remove_failure`
+// with the right event name. Mirrors the cli_install_failure / cli_uninstall_failure
+// pattern below for parity. Cleared back to null after the success track.
+let lastPolicyAction = null;
+async function track(name, props) {
+  try {
+    if (!_telemetry) {
+      const [t, i] = await Promise.all([
+        import("../src/hooks/hook-telemetry"),
+        import("../lib/telemetry-id"),
+      ]);
+      _telemetry = { trackHookEvent: t.trackHookEvent, getInstanceId: i.getInstanceId };
+    }
+    await _telemetry.trackHookEvent(_telemetry.getInstanceId(), name, props);
+  } catch {}
+}
+
 // --hook <event> [--cli <name>] — called by an agent CLI hook; fast path, outside
 // runCli() because it has its own exit code contract with the calling agent.
 const hookIdx = args.indexOf("--hook");
@@ -69,25 +91,16 @@ if (hookIdx >= 0) {
     process.exit(exitCode);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
+    await track("hook_dispatch_error", {
+      event_type: eventType,
+      cli,
+      error_type: err instanceof Error ? err.name : "unknown",
+    });
     console.error(`Unexpected error: ${msg}`);
     process.exit(2);
   }
 }
 
-// --relay-daemon — internal: long-running background process started by
-// ensureRelayRunning(). Streams queued events to the server via WebSocket.
-if (args.includes("--relay-daemon")) {
-  try {
-    const { runDaemon } = await import("../src/relay/daemon");
-    await runDaemon();
-    process.exit(0);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(`Relay daemon error: ${msg}`);
-    process.exit(1);
-  }
-}
-
 /**
  * Centralised error handler for all CLI subcommands.
  * CliError  → clean message, no stack trace, exit exitCode (1 or 2)
@@ -95,7 +108,7 @@ if (args.includes("--relay-daemon")) {
  */
 async function runCli() {
   // --help / -h  (only when not inside a subcommand that handles its own --help)
-  const SUBCOMMANDS = ["policies", "login", "logout", "whoami", "relay", "sync"];
+  const SUBCOMMANDS = ["policies", "policy", "auth", "audit"];
   if ((args.includes("--help") || args.includes("-h")) && !SUBCOMMANDS.includes(args[0])) {
     const extraArgs = args.filter((a) => a !== "--help" && a !== "-h");
     if (extraArgs.length > 0) {
@@ -110,6 +123,9 @@ USAGE
 COMMANDS
   (no args)                      Launch the policy dashboard
 
+  policy add <name>              Enable a single policy (see \`policy --help\`)
+  policy remove <name>           Disable a single policy
+
   policies, p                    List all available policies and their status
   policies --install, -i         Enable policies in agent CLI settings
     [names...]                     Specific policy names to enable
@@ -132,11 +148,15 @@ COMMANDS
 
   policies --help, -h            Show this help for the policies command
 
-  login                          Authenticate with the failproofai cloud (Google OAuth)
-  logout                         Clear local auth tokens and stop relay daemon
-  whoami                         Print current logged-in user
-  relay start|stop|status        Manage the event relay daemon
-  sync                           One-shot flush of pending events to the server
+  auth                           Sign in / out of FailproofAI from the CLI.
+    login                          Email + OTP flow; writes ~/.failproofai/auth.json
+    logout                         Revoke this session and remove auth.json
+    whoami                         Print the currently authenticated identity
+  auth --help, -h                Show this help for the auth command
+
+  audit                          Audit your agent's behavior, then open the
+                                 dashboard at http://localhost:8020/audit
+  audit --help, -h               Show this help for the audit command
 
   --version, -v                  Print version and exit
   --help, -h                     Show this help message
@@ -169,7 +189,7 @@ EXAMPLES
   failproofai policies --uninstall --custom
 
 LINKS
-  ⭐ Star us:      https://github.com/exospherehost/failproofai
+  ⭐ Star us:      https://github.com/failproofai/failproofai
   📖 Docs:         https://befailproof.ai
   💬 Slack:        https://join.slack.com/t/failproofai/shared_invite/zt-3v63b7k5e-O3NBHmj8X6n9gZSGDx6ggQ
 `.trimStart());
@@ -250,6 +270,7 @@ EXAMPLES
     }
 
     if (isInstall) {
+      lastSubcommand = "install";
       const { installHooks } = await import("../src/hooks/manager");
       const { resolveTargetClis } = await import("../src/hooks/install-prompt");
 
@@ -337,10 +358,19 @@ EXAMPLES
         false,
         cli,
       );
+      await track("cli_install_success", {
+        scope,
+        cli,
+        cli_count: cli.length,
+        explicit_policies: explicitPolicyNames.length > 0,
+        include_beta: includeBeta,
+        has_custom_path: !!customPoliciesPath,
+      });
       process.exit(0);
     }
 
     if (isUninstall) {
+      lastSubcommand = "uninstall";
       const { removeHooks } = await import("../src/hooks/manager");
       const { resolveTargetClis } = await import("../src/hooks/install-prompt");
 
@@ -402,6 +432,14 @@ EXAMPLES
         undefined,
         { betaOnly, removeCustomHooks, cli },
       );
+      await track("cli_uninstall_success", {
+        scope,
+        cli,
+        cli_count: cli.length,
+        beta_only: betaOnly,
+        remove_custom_hooks: removeCustomHooks,
+        explicit_policies: policyNames.length > 0,
+      });
       process.exit(0);
     }
 
@@ -424,75 +462,188 @@ EXAMPLES
       );
     }
 
+    lastSubcommand = "list";
     const { listHooks } = await import("../src/hooks/manager");
     await listHooks();
+    await track("cli_list_invoked", {});
     process.exit(0);
   }
 
-  // login — authenticate with failproofai server via Google OAuth
-  if (args[0] === "login") {
-    const { login } = await import("../src/auth/login");
-    await login();
-    process.exit(0);
+  // auth — email-OTP login flow against the FailproofAI api-server.
+  if (args[0] === "auth") {
+    lastSubcommand = "auth";
+    const { runAuthCli } = await import("../src/auth/cli");
+    await runAuthCli(args.slice(1));
+    await track("cli_auth_invoked", { args_count: args.length - 1 });
+    process.exit(process.exitCode ?? 0);
   }
 
-  // logout — clear local tokens and stop relay daemon
-  if (args[0] === "logout") {
-    const { logout } = await import("../src/auth/logout");
-    await logout();
-    process.exit(0);
+  // audit — scan local agent-CLI history, then launch the dashboard at /audit.
+  if (args[0] === "audit") {
+    lastSubcommand = "audit";
+    const { runAuditCli } = await import("../src/audit/cli");
+    await runAuditCli(args.slice(1));
+    // No process.exit(): on the success path runAuditCli calls launch(), which
+    // keeps this process alive running the dashboard. The --help / no-sessions
+    // paths exit inside runAuditCli; failures throw a CliError handled below.
+    return;
   }
 
-  // whoami — print current user and auth status
-  if (args[0] === "whoami") {
-    const { whoami } = await import("../src/auth/logout");
-    whoami();
-    process.exit(0);
-  }
+  // policy — single-policy shortcut over `policies --install <name>`.
+  //   failproofai policy add <name>     enable one policy (defaults: claude/user)
+  //   failproofai policy remove <name>  disable one policy
+  // Honors the same --cli / --scope / --beta flags as `policies --install`.
+  if (args[0] === "policy") {
+    lastSubcommand = "policy";
+    const subArgs = args.slice(1);
+
+    if (subArgs.length === 0 || subArgs.includes("--help") || subArgs.includes("-h")) {
+      console.log(`
+failproofai policy — manage a single FailproofAI policy
 
-  // relay start|stop|status — manage the event relay daemon
-  if (args[0] === "relay") {
-    const subcmd = args[1];
-    const { relayStatus, stopRelay } = await import("../src/relay/pid");
+USAGE
+  failproofai policy add <name>      Enable one policy
+  failproofai policy remove <name>   Disable one policy
+
+OPTIONS
+  --cli claude|codex|copilot|cursor|opencode|pi|gemini
+                                     Agent CLI(s) to apply to; space-separated or repeated.
+                                     Omit to detect installed CLIs and prompt.
+  --scope user|project|local         Config scope (default: user)
+  --beta                             Allow beta policies
 
-    if (subcmd === "status") {
-      const s = relayStatus();
-      if (s.running) console.log(`Relay daemon running (pid ${s.pid})`);
-      else if (s.pid !== null) console.log(`Stale PID file (${s.pid}); daemon not running`);
-      else console.log("Relay daemon not running");
+EXAMPLES
+  failproofai policy add block-sudo
+  failproofai policy add sanitize-api-keys --scope project
+  failproofai policy add block-force-push --cli claude codex
+  failproofai policy remove block-sudo
+`.trimStart());
       process.exit(0);
     }
 
-    if (subcmd === "stop") {
-      const stopped = stopRelay();
-      console.log(stopped ? "Relay daemon stopped" : "Relay daemon was not running");
-      process.exit(0);
+    const action = subArgs[0];
+    if (action !== "add" && action !== "remove") {
+      throw new CliError(
+        `Unknown policy subcommand: ${action}\n` +
+        `Run \`failproofai policy --help\` for usage.`,
+      );
     }
 
-    if (subcmd === "start") {
-      const { ensureRelayRunning, waitForRelayAlive } = await import("../src/relay/daemon");
-      ensureRelayRunning();
-      // Spawn is async — give the child a moment to write its PID file
-      const alive = await waitForRelayAlive();
-      const s = relayStatus();
-      if (alive && s.running) {
-        console.log(`Relay daemon started (pid ${s.pid})`);
-        process.exit(0);
+    const rest = subArgs.slice(1);
+
+    const scopeIdx = rest.indexOf("--scope");
+    const scope = scopeIdx >= 0 ? rest[scopeIdx + 1] : "user";
+    if (scopeIdx >= 0 && (!scope || scope.startsWith("-"))) {
+      throw new CliError("Missing value for --scope. Valid values: user, project, local");
+    }
+    const validScopes = action === "remove"
+      ? ["user", "project", "local", "all"]
+      : ["user", "project", "local"];
+    if (scopeIdx >= 0 && !validScopes.includes(scope)) {
+      throw new CliError(`Invalid scope: ${scope}. Valid values: ${validScopes.join(", ")}`);
+    }
+
+    // --cli accepts one or more space-separated values, optionally repeated.
+    const VALID_CLIS = new Set(["claude", "codex", "copilot", "cursor", "opencode", "pi", "gemini"]);
+    const cliFlagValues = [];
+    const cliConsumedIdxs = new Set();
+    const cliFlagIdxs = rest.map((a, i) => (a === "--cli" ? i : -1)).filter((i) => i >= 0);
+    for (const idx of cliFlagIdxs) {
+      let consumed = 0;
+      for (let j = idx + 1; j < rest.length; j++) {
+        const v = rest[j];
+        if (v.startsWith("-")) break;
+        if (!VALID_CLIS.has(v)) break;
+        cliFlagValues.push(v);
+        cliConsumedIdxs.add(j);
+        consumed++;
+      }
+      if (consumed === 0) {
+        throw new CliError("Missing value(s) for --cli. Usage: --cli claude codex copilot cursor opencode pi gemini (or any subset)");
       }
-      console.log("Failed to start daemon");
-      process.exit(1);
     }
 
-    throw new CliError(
-      `Usage: failproofai relay <start|stop|status>`
+    const includeBeta = rest.includes("--beta");
+
+    // Reject unknown flags.
+    const knownFlags = new Set(["--scope", "--cli", "--beta"]);
+    const unknownFlag = rest.find((a) => a.startsWith("-") && !knownFlags.has(a));
+    if (unknownFlag) {
+      throw new CliError(`Unknown flag: ${unknownFlag}\nRun \`failproofai policy --help\` for usage.`);
+    }
+
+    // Positional policy names = anything not consumed by --scope / --cli.
+    const consumedIdxs = new Set();
+    if (scopeIdx >= 0) consumedIdxs.add(scopeIdx + 1);
+    for (const i of cliConsumedIdxs) consumedIdxs.add(i);
+    const positional = rest.filter(
+      (a, idx) => !a.startsWith("-") && !consumedIdxs.has(idx),
     );
-  }
 
-  // sync — one-shot flush of pending events to server (fallback for no daemon)
-  if (args[0] === "sync") {
-    const { runOneShotSync } = await import("../src/relay/daemon");
-    const count = await runOneShotSync();
-    console.log(`Synced ${count} event${count === 1 ? "" : "s"} to server`);
+    if (positional.length === 0) {
+      throw new CliError(
+        `Missing policy name.\n` +
+        `Usage: failproofai policy ${action} <name>\n` +
+        `Run \`failproofai policies\` to see available names.`,
+      );
+    }
+    if (positional.length > 1) {
+      throw new CliError(
+        `\`policy ${action}\` takes exactly one policy name (got ${positional.length}).\n` +
+        `For multiple policies use \`failproofai policies --${action === "add" ? "install" : "uninstall"} ${positional.join(" ")}\`.`,
+      );
+    }
+    const policyName = positional[0];
+
+    const { resolveTargetClis } = await import("../src/hooks/install-prompt");
+    const cli = await resolveTargetClis(
+      cliFlagValues.length > 0 ? cliFlagValues : undefined,
+      action === "add" ? "install" : "uninstall",
+    );
+
+    lastPolicyAction = action;
+    if (action === "add") {
+      const { installHooks } = await import("../src/hooks/manager");
+      await installHooks(
+        [policyName],
+        scope,
+        undefined,
+        includeBeta,
+        undefined,
+        undefined,
+        false,
+        cli,
+      );
+      await track("cli_policy_add_success", {
+        scope,
+        cli,
+        cli_count: cli.length,
+        policy_name: policyName,
+        include_beta: includeBeta,
+      });
+    } else {
+      // `policy remove <name>` always removes the named policy regardless
+      // of whether it's beta or not — passing `betaOnly: includeBeta`
+      // here was a mislabel that only affected the telemetry field, not
+      // the actual remove. Drop the `--beta` semantic for remove and
+      // emit beta_only: false unconditionally so dashboards don't see
+      // ghost "beta removal" events.
+      const { removeHooks } = await import("../src/hooks/manager");
+      await removeHooks(
+        [policyName],
+        scope,
+        undefined,
+        { betaOnly: false, removeCustomHooks: false, cli },
+      );
+      await track("cli_policy_remove_success", {
+        scope,
+        cli,
+        cli_count: cli.length,
+        policy_name: policyName,
+        beta_only: false,
+      });
+    }
+    lastPolicyAction = null;
     process.exit(0);
   }
 
@@ -514,7 +665,7 @@ EXAMPLES
       return dp[m][n];
     }
 
-    const primary = ["--version", "--help", "--hook", "policies", "login", "logout", "whoami", "relay", "sync"];
+    const primary = ["--version", "--help", "--hook", "policies", "policy", "auth", "audit"];
     const closest = primary.reduce((best, flag) => {
       const dist = levenshtein(unknownFlag, flag);
       return dist < best.dist ? { flag, dist } : best;
@@ -537,6 +688,17 @@ EXAMPLES
     );
   }
 
+  // First-run nudge — only on truly bare `failproofai` invocations. Best-effort:
+  // any thrown error must not block the dashboard from launching.
+  if (args.length === 0) {
+    try {
+      const { maybeRunFirstRunNudge } = await import("../src/hooks/first-run-nudge");
+      await maybeRunFirstRunNudge();
+    } catch {
+      // Nudge is non-critical; fall through to dashboard.
+    }
+  }
+
   // Dashboard launch — always production mode
   const { launch } = await import("../scripts/launch");
   launch("start");
@@ -550,11 +712,42 @@ try {
   await runCli();
 } catch (err) {
   if (err instanceof CliError) {
+    if (lastSubcommand === "install") {
+      await track("cli_install_failure", { error_type: "cli_error", exit_code: err.exitCode });
+    } else if (lastSubcommand === "uninstall") {
+      await track("cli_uninstall_failure", { error_type: "cli_error", exit_code: err.exitCode });
+    } else if (lastSubcommand === "policy" && lastPolicyAction) {
+      // Mid-action failure: `policy add|remove` parsed but installHooks /
+      // removeHooks threw a CliError (e.g. unknown policy name, invalid scope).
+      await track(`cli_policy_${lastPolicyAction}_failure`, {
+        error_type: "cli_error",
+        exit_code: err.exitCode,
+      });
+    } else {
+      await track("cli_parse_error", {
+        subcommand: lastSubcommand ?? (args[0] ?? null),
+        exit_code: err.exitCode,
+      });
+    }
     console.error(`Error: ${err.message}`);
     process.exit(err.exitCode);
   }
   // Unexpected internal error — show message only, no stack trace
   const msg = err instanceof Error ? err.message : String(err);
+  if (lastSubcommand === "install") {
+    await track("cli_install_failure", { error_type: err instanceof Error ? err.name : "unknown" });
+  } else if (lastSubcommand === "uninstall") {
+    await track("cli_uninstall_failure", { error_type: err instanceof Error ? err.name : "unknown" });
+  } else if (lastSubcommand === "policy" && lastPolicyAction) {
+    await track(`cli_policy_${lastPolicyAction}_failure`, {
+      error_type: err instanceof Error ? err.name : "unknown",
+    });
+  } else {
+    await track("cli_unexpected_error", {
+      subcommand: lastSubcommand ?? (args[0] ?? null),
+      error_type: err instanceof Error ? err.name : "unknown",
+    });
+  }
   console.error(`Unexpected error: ${msg}`);
   process.exit(2);
 }