failproofai 0.0.1 → 0.0.2-beta.2

package/.next/standalone/README.md

@@ -9,6 +9,12 @@
 
 # Failproof AI
 
+[![Docs](https://img.shields.io/badge/docs-befailproof.ai-002CA7?style=flat-square)](https://befailproof.ai)
+[![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai)
+[![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](LICENSE)
+[![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)
+[![Discord](https://img.shields.io/discord/1234567890?style=flat-square&label=Discord&color=5865F2)](https://discord.com/invite/zT92CAgvkj)
+
 Open-source hooks, policies, and project visualization for **Claude Code** & the **Agents SDK**.
 
 - **Hooks & Policies** — 35+ built-in security policies that run as Claude Code hooks. Block dangerous commands, sanitize secrets, restrict file access, and more.
@@ -23,7 +29,7 @@ Everything runs locally — no data leaves your machine.
 ## Requirements
 
 - Node.js >= 20.9.0
-- Bun >= 1.3.0
+- Bun >= 1.3.0 (optional — only needed for development / building from source)
 
 ---
 
@@ -31,6 +37,8 @@ Everything runs locally — no data leaves your machine.
 
 ```bash
 npm install -g failproofai
+# or
+bun add -g failproofai
 ```
 
 ---
@@ -40,7 +48,7 @@ npm install -g failproofai
 ### 1. Enable policies globally
 
 ```bash
-failproofai --install-policies
+failproofai policies --install
 ```
 
 Writes hook entries into `~/.claude/settings.json`. Claude Code will now invoke failproofai before and after each tool call.
@@ -56,7 +64,7 @@ Opens `http://localhost:8020` — browse sessions, inspect logs, manage policies
 ### 3. Check what's active
 
 ```bash
-failproofai --list-policies
+failproofai policies
 ```
 
 ---
@@ -67,22 +75,22 @@ failproofai --list-policies
 
 | Scope | Command | Where it writes |
 |-------|---------|-----------------|
-| Global (default) | `failproofai --install-policies` | `~/.claude/settings.json` |
-| Project | `failproofai --install-policies --scope project` | `.claude/settings.json` |
-| Local | `failproofai --install-policies --scope local` | `.claude/settings.local.json` |
+| Global (default) | `failproofai policies --install` | `~/.claude/settings.json` |
+| Project | `failproofai policies --install --scope project` | `.claude/settings.json` |
+| Local | `failproofai policies --install --scope local` | `.claude/settings.local.json` |
 
 ### Install specific policies
 
 ```bash
-failproofai --install-policies block-sudo block-rm-rf sanitize-api-keys
+failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
 ```
 
 ### Remove policies
 
 ```bash
-failproofai --remove-policies
+failproofai policies --uninstall
 # or for a specific scope:
-failproofai --remove-policies --scope project
+failproofai policies --uninstall --scope project
 ```
 
 ---
@@ -182,7 +190,7 @@ customPolicies.add({
 Install with:
 
 ```bash
-failproofai --install-policies --custom ./my-policies.js
+failproofai policies --install --custom ./my-policies.js
 ```
 
 ### Decision helpers

package/.next/standalone/bin/failproofai.mjs

@@ -37,10 +37,40 @@ const args = process.argv.slice(2);
 // Normalize 'p' → 'policies' (shorthand alias)
 if (args[0] === "p") args[0] = "policies";
 
-// --help / -h  (only when not inside a subcommand that handles its own --help)
-const SUBCOMMANDS = ["policies"];
-if ((args.includes("--help") || args.includes("-h")) && !SUBCOMMANDS.includes(args[0])) {
-  console.log(`
+// --hook <event> — called by Claude Code hooks; fast path, outside runCli()
+// because it has its own exit code contract with Claude Code.
+const hookIdx = args.indexOf("--hook");
+if (hookIdx >= 0) {
+  if (!args[hookIdx + 1]) {
+    console.error("Error: Missing event type after --hook");
+    console.error("Usage: failproofai --hook <event>  (e.g. PreToolUse, PostToolUse)");
+    process.exit(1);
+  }
+  try {
+    const { handleHookEvent } = await import("../src/hooks/handler");
+    const exitCode = await handleHookEvent(args[hookIdx + 1]);
+    process.exit(exitCode);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`Unexpected error: ${msg}`);
+    process.exit(2);
+  }
+}
+
+/**
+ * Centralised error handler for all CLI subcommands.
+ * CliError  → clean message, no stack trace, exit exitCode (1 or 2)
+ * Error     → unexpected; shows message only, exits 2
+ */
+async function runCli() {
+  // --help / -h  (only when not inside a subcommand that handles its own --help)
+  const SUBCOMMANDS = ["policies"];
+  if ((args.includes("--help") || args.includes("-h")) && !SUBCOMMANDS.includes(args[0])) {
+    const extraArgs = args.filter((a) => a !== "--help" && a !== "-h");
+    if (extraArgs.length > 0) {
+      throw new CliError(`Unexpected argument: ${extraArgs[0]}\nRun \`failproofai --help\` for usage.`);
+    }
+    console.log(`
 failproofai v${version}
 
 USAGE
@@ -80,33 +110,29 @@ LINKS
   ⭐ Star us:      https://github.com/exospherehost/failproofai
   📖 Docs:         https://befailproof.ai
 `.trimStart());
-  process.exit(0);
-}
-
-// --version / -v
-if (args.includes("--version") || args.includes("-v")) {
-  console.log(version);
-  process.exit(0);
-}
+    process.exit(0);
+  }
 
-// --hook <event> — called by Claude Code hooks; fast path, no dashboard startup
-const hookIdx = args.indexOf("--hook");
-if (hookIdx >= 0 && args[hookIdx + 1]) {
-  const { handleHookEvent } = await import("../src/hooks/handler");
-  const exitCode = await handleHookEvent(args[hookIdx + 1]);
-  process.exit(exitCode);
-}
+  // --version / -v
+  if ((args.includes("--version") || args.includes("-v")) && !SUBCOMMANDS.includes(args[0])) {
+    const extraArgs = args.filter((a) => a !== "--version" && a !== "-v");
+    if (extraArgs.length > 0) {
+      throw new CliError(`Unexpected argument: ${extraArgs[0]}\nRun \`failproofai --help\` for usage.`);
+    }
+    console.log(version);
+    process.exit(0);
+  }
 
-// policies [--install|-i|--uninstall|-u|--help|-h] [names...] [--scope] [--beta] [--custom|-c <path>]
-if (args[0] === "policies") {
-  const subArgs = args.slice(1);
+  // policies [--install|-i|--uninstall|-u|--help|-h] [names...] [--scope] [--beta] [--custom|-c <path>]
+  if (args[0] === "policies") {
+    const subArgs = args.slice(1);
 
-  const isInstall   = subArgs.includes("--install")   || subArgs.includes("-i");
-  const isUninstall = subArgs.includes("--uninstall")  || subArgs.includes("-u");
-  const isHelp      = subArgs.includes("--help")       || subArgs.includes("-h");
+    const isInstall   = subArgs.includes("--install")   || subArgs.includes("-i");
+    const isUninstall = subArgs.includes("--uninstall")  || subArgs.includes("-u");
+    const isHelp      = subArgs.includes("--help")       || subArgs.includes("-h");
 
-  if (isHelp) {
-    console.log(`
+    if (isHelp) {
+      console.log(`
 failproofai policies — manage Failproof AI policies
 
 USAGE
@@ -137,118 +163,185 @@ EXAMPLES
   failproofai policies -u
   failproofai policies --uninstall --custom
 `.trimStart());
+      process.exit(0);
+    }
+
+    if (isInstall) {
+      const { installHooks } = await import("../src/hooks/manager");
+
+      const scopeIdx = subArgs.indexOf("--scope");
+      const scope = scopeIdx >= 0 ? subArgs[scopeIdx + 1] : "user";
+      if (scopeIdx >= 0 && (!scope || scope.startsWith("-"))) {
+        throw new CliError("Missing value for --scope. Valid values: user, project, local");
+      }
+      if (scopeIdx >= 0 && !["user", "project", "local"].includes(scope)) {
+        throw new CliError(`Invalid scope: ${scope}. Valid values: user, project, local`);
+      }
+
+      const customIdx = subArgs.includes("--custom") ? subArgs.indexOf("--custom")
+                      : subArgs.includes("-c")        ? subArgs.indexOf("-c")
+                      : -1;
+      const customPoliciesPath = customIdx >= 0 ? subArgs[customIdx + 1] : undefined;
+      if (customIdx >= 0 && (!customPoliciesPath || customPoliciesPath.startsWith("-"))) {
+        throw new CliError("Missing path after --custom/-c\nUsage: --custom <path>  (e.g. --custom ./my-policies.js)");
+      }
+
+      const includeBeta = subArgs.includes("--beta");
+
+      // Collect positional policy names — args that don't start with - and aren't
+      // values consumed by --scope or --custom/-c (tracked by index, not value,
+      // so a policy named "user" isn't incorrectly dropped by the default scope).
+      const consumedIdxs = new Set();
+      if (scopeIdx >= 0) consumedIdxs.add(scopeIdx + 1);
+      if (customIdx >= 0) consumedIdxs.add(customIdx + 1);
+      const flags = new Set(["--install", "-i", "--scope", "--beta", "--custom", "-c"]);
+      const unknownInstallFlag = subArgs.find((a) => a.startsWith("-") && !flags.has(a));
+      if (unknownInstallFlag) {
+        throw new CliError(`Unknown flag: ${unknownInstallFlag}\nRun \`failproofai policies --help\` for usage.`);
+      }
+
+      const explicitPolicyNames = subArgs.filter(
+        (a, idx) => !a.startsWith("-") && !consumedIdxs.has(idx)
+      );
+
+      // When --custom/-c is present but no explicit policy names, pass [] so
+      // installHooks uses the existing enabled policies and skips the interactive
+      // prompt — validation of the custom file happens inside installHooks.
+      const policyNames =
+        explicitPolicyNames.length > 0 ? explicitPolicyNames
+        : customPoliciesPath !== undefined ? []
+        : undefined;
+
+      await installHooks(
+        policyNames,
+        scope,
+        undefined,
+        includeBeta,
+        undefined,
+        customPoliciesPath,
+      );
+      process.exit(0);
+    }
+
+    if (isUninstall) {
+      const { removeHooks } = await import("../src/hooks/manager");
+
+      const scopeIdx = subArgs.indexOf("--scope");
+      const scope = scopeIdx >= 0 ? subArgs[scopeIdx + 1] : "user";
+      if (scopeIdx >= 0 && (!scope || scope.startsWith("-"))) {
+        throw new CliError("Missing value for --scope. Valid values: user, project, local, all");
+      }
+      if (scopeIdx >= 0 && !["user", "project", "local", "all"].includes(scope)) {
+        throw new CliError(`Invalid scope: ${scope}. Valid values: user, project, local, all`);
+      }
+
+      const betaOnly = subArgs.includes("--beta");
+      const removeCustomHooks = subArgs.includes("--custom") || subArgs.includes("-c");
+
+      const consumedIdxs = new Set();
+      if (scopeIdx >= 0) consumedIdxs.add(scopeIdx + 1);
+      const flags = new Set(["--uninstall", "-u", "--scope", "--beta", "--custom", "-c"]);
+      const unknownUninstallFlag = subArgs.find((a) => a.startsWith("-") && !flags.has(a));
+      if (unknownUninstallFlag) {
+        throw new CliError(`Unknown flag: ${unknownUninstallFlag}\nRun \`failproofai policies --help\` for usage.`);
+      }
+
+      const policyNames = subArgs.filter(
+        (a, idx) => !a.startsWith("-") && !consumedIdxs.has(idx)
+      );
+
+      await removeHooks(
+        policyNames.length > 0 ? policyNames : undefined,
+        scope,
+        undefined,
+        { betaOnly, removeCustomHooks },
+      );
+      process.exit(0);
+    }
+
+    // Default: list policies
+    // Accept --list as a no-op alias (common intuition), reject all other unknown flags
+    // and unexpected positional args (e.g. "hi").
+    const knownListFlags = new Set(["--install", "-i", "--uninstall", "-u", "--help", "-h", "--list"]);
+    const unknownListArg = subArgs.find((a) => a.startsWith("-") && !knownListFlags.has(a));
+    if (unknownListArg) {
+      throw new CliError(
+        `Unknown flag: ${unknownListArg}\n` +
+        `Run \`failproofai policies --help\` for usage.`
+      );
+    }
+    const positionalArgs = subArgs.filter((a) => !a.startsWith("-"));
+    if (positionalArgs.length > 0) {
+      throw new CliError(
+        `Unexpected argument: ${positionalArgs[0]}\n` +
+        `Run \`failproofai policies --help\` for usage.`
+      );
+    }
+
+    const { listHooks } = await import("../src/hooks/manager");
+    await listHooks();
     process.exit(0);
   }
 
-  if (isInstall) {
-    const { installHooks } = await import("../src/hooks/manager");
-
-    const scopeIdx = subArgs.indexOf("--scope");
-    const scope = scopeIdx >= 0 ? subArgs[scopeIdx + 1] : "user";
-
-    const customIdx = subArgs.includes("--custom") ? subArgs.indexOf("--custom")
-                    : subArgs.includes("-c")        ? subArgs.indexOf("-c")
-                    : -1;
-    const customPoliciesPath = customIdx >= 0 ? subArgs[customIdx + 1] : undefined;
-
-    const includeBeta = subArgs.includes("--beta");
-
-    // Collect positional policy names — args that don't start with - and aren't
-    // values consumed by --scope or --custom/-c.
-    const consumed = new Set([scope, customPoliciesPath].filter(Boolean));
-    const flags = new Set(["--install", "-i", "--scope", "--beta", "--custom", "-c"]);
-    const explicitPolicyNames = subArgs.filter(
-      (a) => !a.startsWith("-") && !flags.has(a) && !consumed.has(a)
-    );
-
-    // When --custom/-c is present but no explicit policy names, pass [] so
-    // installHooks uses the existing enabled policies and skips the interactive
-    // prompt — validation of the custom file happens inside installHooks.
-    const policyNames =
-      explicitPolicyNames.length > 0 ? explicitPolicyNames
-      : customPoliciesPath !== undefined ? []
-      : undefined;
-
-    await installHooks(
-      policyNames,
-      scope,
-      undefined,
-      includeBeta,
-      undefined,
-      customPoliciesPath,
+  // Unknown flag guard — must appear after all known-flag branches
+  const knownFlags = ["--version", "-v", "--help", "-h", "--hook"];
+  const unknownFlag = args.find(a => a.startsWith("-") && !knownFlags.includes(a));
+
+  if (unknownFlag) {
+    function levenshtein(a, b) {
+      const m = a.length, n = b.length;
+      const dp = Array.from({ length: m + 1 }, (_, i) =>
+        Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0))
+      );
+      for (let i = 1; i <= m; i++)
+        for (let j = 1; j <= n; j++)
+          dp[i][j] = a[i - 1] === b[j - 1]
+            ? dp[i - 1][j - 1]
+            : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+      return dp[m][n];
+    }
+
+    const primary = ["--version", "--help", "--hook", "policies"];
+    const closest = primary.reduce((best, flag) => {
+      const dist = levenshtein(unknownFlag, flag);
+      return dist < best.dist ? { flag, dist } : best;
+    }, { flag: primary[0], dist: Infinity });
+
+    throw new CliError(
+      `Unknown flag: ${unknownFlag}\n` +
+      `Did you mean: ${closest.flag}?\n` +
+      `Run \`failproofai --help\` for usage details.`
     );
-    process.exit(0);
   }
 
-  if (isUninstall) {
-    const { removeHooks } = await import("../src/hooks/manager");
-
-    const scopeIdx = subArgs.indexOf("--scope");
-    const scope = scopeIdx >= 0 ? subArgs[scopeIdx + 1] : "user";
-
-    const betaOnly = subArgs.includes("--beta");
-    const removeCustomHooks = subArgs.includes("--custom") || subArgs.includes("-c");
-
-    const consumed = new Set([scope].filter(Boolean));
-    const flags = new Set(["--uninstall", "-u", "--scope", "--beta", "--custom", "-c"]);
-    const policyNames = subArgs.filter(
-      (a) => !a.startsWith("-") && !flags.has(a) && !consumed.has(a)
+  // Unknown subcommand guard (non-flag args that aren't "policies")
+  const unknownSubcommand = args.find(a => !a.startsWith("-") && a !== "policies");
+  if (unknownSubcommand) {
+    throw new CliError(
+      `Unknown command: ${unknownSubcommand}\n` +
+      `Did you mean: failproofai policies?\n` +
+      `Run \`failproofai --help\` for usage details.`
     );
-
-    await removeHooks(
-      policyNames.length > 0 ? policyNames : undefined,
-      scope,
-      undefined,
-      { betaOnly, removeCustomHooks },
-    );
-    process.exit(0);
   }
 
-  // Default: list policies
-  const { listHooks } = await import("../src/hooks/manager");
-  await listHooks();
-  process.exit(0);
+  // Dashboard launch — always production mode
+  const { launch } = await import("../scripts/launch");
+  launch("start");
 }
 
-// Unknown flag guard — must appear after all known-flag branches
-const knownFlags = ["--version", "-v", "--help", "-h", "--hook"];
-const unknownFlag = args.find(a => a.startsWith("-") && !knownFlags.includes(a));
+// ── Import CliError for use in the guard above ────────────────────────────────
+const { CliError } = await import("../src/cli-error");
 
-if (unknownFlag) {
-  function levenshtein(a, b) {
-    const m = a.length, n = b.length;
-    const dp = Array.from({ length: m + 1 }, (_, i) =>
-      Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0))
-    );
-    for (let i = 1; i <= m; i++)
-      for (let j = 1; j <= n; j++)
-        dp[i][j] = a[i - 1] === b[j - 1]
-          ? dp[i - 1][j - 1]
-          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
-    return dp[m][n];
+// ── Run ───────────────────────────────────────────────────────────────────────
+try {
+  await runCli();
+} catch (err) {
+  if (err instanceof CliError) {
+    console.error(`Error: ${err.message}`);
+    process.exit(err.exitCode);
   }
-
-  const primary = ["--version", "--help", "--hook", "policies"];
-  const closest = primary.reduce((best, flag) => {
-    const dist = levenshtein(unknownFlag, flag);
-    return dist < best.dist ? { flag, dist } : best;
-  }, { flag: primary[0], dist: Infinity });
-
-  console.error(`Unknown flag: ${unknownFlag}`);
-  console.error(`Did you mean: ${closest.flag}?`);
-  console.error(`Run \`failproofai --help\` for usage details.`);
-  process.exit(1);
-}
-
-// Unknown subcommand guard (non-flag args that aren't "policies")
-const unknownSubcommand = args.find(a => !a.startsWith("-") && a !== "policies");
-if (unknownSubcommand) {
-  console.error(`Unknown command: ${unknownSubcommand}`);
-  console.error(`Did you mean: failproofai policies?`);
-  console.error(`Run \`failproofai --help\` for usage details.`);
-  process.exit(1);
+  // Unexpected internal error — show message only, no stack trace
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(`Unexpected error: ${msg}`);
+  process.exit(2);
 }
-
-// Dashboard launch — always production mode
-const { launch } = await import("../scripts/launch");
-launch("start");