failproofai 0.0.2-beta.1 → 0.0.2-beta.3

package/.next/standalone/docs/{testing.md → testing.mdx}

@@ -17,7 +17,7 @@ bun run test:run
 # Run unit tests in watch mode
 bun run test
 
-# Run E2E tests (requires setup — see below)
+# Run E2E tests (requires setup - see below)
 bun run test:e2e
 
 # Type-check without building
@@ -33,7 +33,7 @@ bun run lint
 
 Unit tests live in `__tests__/` and use [Vitest](https://vitest.dev) with `happy-dom`.
 
-```
+```text
 __tests__/
   hooks/
     builtin-policies.test.ts      # Policy logic for each builtin
@@ -130,7 +130,7 @@ Rebuild `dist/` whenever you change the public hook API (`src/hooks/custom-hooks
 
 ### E2E test structure
 
-```
+```text
 __tests__/e2e/
   helpers/
     hook-runner.ts      # Spawn the binary, pipe payload JSON, capture exit code + stdout + stderr
@@ -145,14 +145,14 @@ __tests__/e2e/
 
 ### Using the E2E helpers
 
-**`FixtureEnv`** — isolated per-test environment:
+**`FixtureEnv`** - isolated per-test environment:
 
 ```typescript
 import { createFixtureEnv } from "../helpers/fixture-env";
 
 const env = createFixtureEnv();
-// env.cwd    — temp dir; pass as payload.cwd to pick up .failproofai/policies-config.json
-// env.home   — isolated home dir; no real ~/.failproofai leaks in
+// env.cwd    - temp dir; pass as payload.cwd to pick up .failproofai/policies-config.json
+// env.home   - isolated home dir; no real ~/.failproofai leaks in
 
 env.writeConfig({
   enabledPolicies: ["block-sudo"],
@@ -164,7 +164,7 @@ env.writeConfig({
 
 `createFixtureEnv()` registers `afterEach` cleanup automatically.
 
-**`runHook`** — invoke the binary:
+**`runHook`** - invoke the binary:
 
 ```typescript
 import { runHook } from "../helpers/hook-runner";
@@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0);
 expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
 ```
 
-**`Payloads`** — ready-made payload factories:
+**`Payloads`** - ready-made payload factories:
 
 ```typescript
 Payloads.preToolUse.bash(command, cwd)
@@ -245,9 +245,9 @@ describe("block-rm-rf (E2E)", () => {
 
 E2E tests use `vitest.config.e2e.mts` with:
 
-- `environment: "node"` — no browser globals needed
-- `pool: "forks"` — true process isolation (tests spawn subprocesses)
-- `testTimeout: 20_000` — 20s per test (binary startup + hook eval)
+- `environment: "node"` - no browser globals needed
+- `pool: "forks"` - true process isolation (tests spawn subprocesses)
+- `testTimeout: 20_000` - 20s per test (binary startup + hook eval)
 
 The `forks` pool is important: thread-based workers share `globalThis`, which can interfere with subprocess-spawning tests. Process-based forks avoid this.
 

package/.next/standalone/package.json

@@ -1,7 +1,7 @@
 {
   "name": "failproofai",
-  "version": "0.0.2-beta.1",
-  "description": "Open-source hooks, policies, and project visualization for Claude Code & Agents SDK",
+  "version": "0.0.2-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"
   },
@@ -40,17 +40,14 @@
     "claude-agents-sdk",
     "anthropic",
     "ai-agent",
-    "llm-observability",
-    "agent-observability",
-    "log-viewer",
-    "session-replay",
+    "agent-reliability",
+    "agent-monitoring",
+    "autonomous-agent",
+    "failure-prevention",
     "developer-tools",
     "devtools",
     "cli",
     "local-first",
-    "monitoring",
-    "debugging",
-    "tracing",
     "hooks",
     "policies"
   ],

package/.next/standalone/scripts/publish-aliases.mjs

@@ -8,6 +8,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const rootPkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 const VERSION = rootPkg.version;
 const DRY_RUN = process.argv.includes('--dry-run');
+const distTagIdx = process.argv.indexOf('--dist-tag');
+const DIST_TAG = distTagIdx !== -1 ? process.argv[distTagIdx + 1] : (VERSION.includes('-') ? 'beta' : 'latest');
 
 const ALIASES = [
   // Formatting variants — no "ai", or hyphen/underscore separators
@@ -54,7 +56,7 @@ for (const name of ALIASES) {
   cpSync(join(__dirname, 'alias-proxy.js'), join(binDir, 'proxy.js'));
 
   if (DRY_RUN) {
-    console.log(`[dry-run] Would publish ${name}@${VERSION}`);
+    console.log(`[dry-run] Would publish ${name}@${VERSION} (tag: ${DIST_TAG})`);
     console.log(JSON.stringify(pkg, null, 2));
     console.log('---');
     rmSync(tmpDir, { recursive: true, force: true });
@@ -63,7 +65,7 @@ for (const name of ALIASES) {
 
   console.log(`Publishing ${name}@${VERSION}...`);
   try {
-    execSync('npm publish', { cwd: tmpDir, stdio: 'pipe' });
+    execSync(`npm publish --tag ${DIST_TAG}`, { cwd: tmpDir, stdio: 'pipe' });
     console.log(`Done: ${name}`);
   } catch (err) {
     const output = (err.stdout?.toString() ?? '') + (err.stderr?.toString() ?? '');

package/.next/standalone/skills-lock.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "skills": {
+    "mintlify": {
+      "source": "mintlify.com",
+      "sourceType": "well-known",
+      "computedHash": "d43d5294c5a569cf6d2878943309eca46f994544693b65f477a8216d3215c0b0"
+    }
+  }
+}

package/.next/standalone/src/cli-error.ts

@@ -0,0 +1,18 @@
+/**
+ * CliError — structured error for the failproofai CLI.
+ *
+ * Throw this for any error that should be reported to the user as a clean
+ * message (no stack trace). The exit code communicates the failure class:
+ *
+ *   1 — user error   (bad args, unknown policy name, invalid flag)
+ *   2 — internal     (file I/O failure, unexpected state)
+ */
+export class CliError extends Error {
+  readonly exitCode: 1 | 2;
+
+  constructor(message: string, exitCode: 1 | 2 = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}

package/.next/standalone/src/hooks/builtin-policies.ts

@@ -3,7 +3,7 @@
  */
 import { resolve, join } from "node:path";
 import { readFile, writeFile, stat, open } from "node:fs/promises";
-import { execSync } from "node:child_process";
+import { execSync, execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import type { BuiltinPolicyDefinition, PolicyContext, PolicyResult, PolicyParamsSchema } from "./policy-types";
 import { allow, deny, instruct } from "./policy-helpers";
@@ -145,12 +145,29 @@ const TMUX_DETACH_RE = /\btmux\s+(?:new-session|new)\b[^|&;]*-d\b/;
 const DISOWN_RE = /\bdisown\b/;
 const BACKGROUND_AMPERSAND_RE = /(?<![&|])\s?&\s*(?:$|#|;)/;
 
-// blockWorkOnMain: caches the current branch per cwd to avoid repeated execSync calls.
+// Caches the current branch per cwd to avoid repeated execSync calls.
 // Trade-off: if the user switches branches externally mid-session, the cache serves
 // the stale value until the process restarts. This is acceptable since branch switches
 // during an active Claude session are rare.
 const gitBranchCache = new Map<string, string>();
 
+function getCurrentBranch(cwd: string): string | null {
+  try {
+    let branch = gitBranchCache.get(cwd);
+    if (branch === undefined) {
+      branch = execSync("git rev-parse --abbrev-ref HEAD", {
+        cwd,
+        encoding: "utf8",
+        timeout: 3000,
+      }).trim();
+      gitBranchCache.set(cwd, branch);
+    }
+    return branch || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Check if a command matches an allow pattern using token-by-token comparison.
  * The "*" token is a wildcard. Extra command tokens beyond the pattern are allowed,
@@ -627,24 +644,14 @@ function blockWorkOnMain(ctx: PolicyContext): PolicyResult {
   const cwd = ctx.session?.cwd;
   if (!cwd) return allow();
 
-  try {
-    let branch = gitBranchCache.get(cwd);
-    if (branch === undefined) {
-      branch = execSync("git rev-parse --abbrev-ref HEAD", {
-        cwd,
-        encoding: "utf8",
-        timeout: 3000,
-      }).trim();
-      gitBranchCache.set(cwd, branch);
-    }
-    const protectedBranches = ((ctx.params?.protectedBranches ?? ["main", "master"]) as string[]);
-    if (protectedBranches.includes(branch)) {
-      return deny(
-        `Git ${cmd.match(/git\s+(\S+)/)?.[1] ?? "operation"} on ${branch} is blocked. Create a feature branch first.`,
-      );
-    }
-  } catch {
-    return allow();
+  const branch = getCurrentBranch(cwd);
+  if (!branch) return allow();
+
+  const protectedBranches = ((ctx.params?.protectedBranches ?? ["main", "master"]) as string[]);
+  if (protectedBranches.includes(branch)) {
+    return deny(
+      `Git ${cmd.match(/git\s+(\S+)/)?.[1] ?? "operation"} on ${branch} is blocked. Create a feature branch first.`,
+    );
   }
   return allow();
 }
@@ -786,6 +793,195 @@ function warnBackgroundProcess(ctx: PolicyContext): PolicyResult {
   return allow();
 }
 
+// -- Workflow (Stop event) policies --
+
+function requireCommitBeforeStop(ctx: PolicyContext): PolicyResult {
+  const cwd = ctx.session?.cwd;
+  if (!cwd) return allow("No working directory available, skipping commit check.");
+
+  try {
+    const status = execSync("git status --porcelain", {
+      cwd,
+      encoding: "utf8",
+      timeout: 5000,
+    }).trim();
+
+    if (status.length > 0) {
+      return deny(
+        "You have uncommitted changes in the working directory. Commit all changes before stopping.",
+      );
+    }
+    return allow("All changes are committed.");
+  } catch {
+    return allow("Not a git repository, skipping commit check.");
+  }
+}
+
+function requirePushBeforeStop(ctx: PolicyContext): PolicyResult {
+  const cwd = ctx.session?.cwd;
+  if (!cwd) return allow("No working directory available, skipping push check.");
+
+  try {
+    const remotes = execSync("git remote", {
+      cwd,
+      encoding: "utf8",
+      timeout: 3000,
+    }).trim();
+
+    if (!remotes) return allow("No git remote configured, skipping push check.");
+
+    const remote = (ctx.params?.remote as string) ?? "origin";
+
+    const branch = getCurrentBranch(cwd);
+    if (!branch || branch === "HEAD") return allow("Detached HEAD, skipping push check.");
+
+    // Check if remote tracking branch exists
+    let hasTracking = false;
+    try {
+      execFileSync("git", ["rev-parse", "--verify", `${remote}/${branch}`], {
+        cwd,
+        encoding: "utf8",
+        timeout: 3000,
+      });
+      hasTracking = true;
+    } catch {
+      // Remote tracking branch does not exist
+    }
+
+    if (!hasTracking) {
+      return deny(
+        `Branch "${branch}" has not been pushed to remote "${remote}". ` +
+        `Push your branch with: git push -u ${remote} ${branch}`,
+      );
+    }
+
+    // Check for unpushed commits
+    const unpushed = execFileSync("git", ["log", `${remote}/${branch}..HEAD`, "--oneline"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 5000,
+    }).trim();
+
+    if (unpushed.length > 0) {
+      const commitCount = unpushed.split("\n").length;
+      return deny(
+        `You have ${commitCount} unpushed commit${commitCount > 1 ? "s" : ""} on branch "${branch}". ` +
+        `Push your changes with: git push`,
+      );
+    }
+
+    return allow(`All commits pushed to "${remote}".`);
+  } catch {
+    return allow("Could not check push status, skipping.");
+  }
+}
+
+function requirePrBeforeStop(ctx: PolicyContext): PolicyResult {
+  const cwd = ctx.session?.cwd;
+  if (!cwd) return allow("No working directory available, skipping PR check.");
+
+  try {
+    // Check if gh CLI is available
+    try {
+      execSync("gh --version", { cwd, encoding: "utf8", timeout: 3000 });
+    } catch {
+      return allow("GitHub CLI (gh) not installed, skipping PR check.");
+    }
+
+    const branch = getCurrentBranch(cwd);
+    if (!branch || branch === "HEAD") return allow("Detached HEAD, skipping PR check.");
+
+    // Check if a PR exists for this branch
+    let prJson: string;
+    try {
+      prJson = execSync("gh pr view --json number,url,state", {
+        cwd,
+        encoding: "utf8",
+        timeout: 15000,
+      }).trim();
+    } catch {
+      // gh pr view exits non-zero when no PR exists
+      return deny(
+        `No pull request found for branch "${branch}". ` +
+        `Create one with: gh pr create`,
+      );
+    }
+
+    const pr = JSON.parse(prJson) as { number: number; url: string; state: string };
+
+    if (pr.state === "OPEN") {
+      return allow(`PR #${pr.number} exists: ${pr.url}`);
+    }
+
+    return deny(
+      `Pull request for branch "${branch}" is ${pr.state.toLowerCase()}. Create a new PR with: gh pr create`,
+    );
+  } catch {
+    return allow("Could not check PR status, skipping.");
+  }
+}
+
+function requireCiGreenBeforeStop(ctx: PolicyContext): PolicyResult {
+  const cwd = ctx.session?.cwd;
+  if (!cwd) return allow("No working directory available, skipping CI check.");
+
+  try {
+    // Check if gh CLI is available
+    try {
+      execSync("gh --version", { cwd, encoding: "utf8", timeout: 3000 });
+    } catch {
+      return allow("GitHub CLI (gh) not installed, skipping CI check.");
+    }
+
+    const branch = getCurrentBranch(cwd);
+    if (!branch || branch === "HEAD") return allow("Detached HEAD, skipping CI check.");
+
+    const runsJson = execFileSync(
+      "gh",
+      ["run", "list", "--branch", branch, "--limit", "5", "--json", "status,conclusion,name"],
+      {
+        cwd,
+        encoding: "utf8",
+        timeout: 15000,
+      },
+    ).trim();
+
+    if (!runsJson || runsJson === "[]") return allow(`No CI runs found for branch "${branch}".`);
+
+    const runs = JSON.parse(runsJson) as Array<{
+      status: string;
+      conclusion: string;
+      name: string;
+    }>;
+
+    if (runs.length === 0) return allow(`No CI runs found for branch "${branch}".`);
+
+    const failing = runs.filter(
+      (r) => r.status === "completed" && r.conclusion !== "success" && r.conclusion !== "skipped",
+    );
+    if (failing.length > 0) {
+      const names = failing.map((r) => `"${r.name}"`).join(", ");
+      return deny(
+        `CI checks are failing on branch "${branch}": ${names}. Fix the failing checks before stopping.`,
+      );
+    }
+
+    const pending = runs.filter(
+      (r) => r.status === "in_progress" || r.status === "queued" || r.status === "waiting",
+    );
+    if (pending.length > 0) {
+      const names = pending.map((r) => `"${r.name}"`).join(", ");
+      return deny(
+        `CI checks are still running on branch "${branch}": ${names}. Wait for all checks to complete and verify they pass.`,
+      );
+    }
+
+    return allow(`All CI checks passed on branch "${branch}".`);
+  } catch {
+    return allow("Could not check CI status, skipping.");
+  }
+}
+
 // -- Registry --
 
 export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
@@ -1053,6 +1249,49 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
     defaultEnabled: false,
     category: "AI Behavior",
   },
+  {
+    name: "require-commit-before-stop",
+    description: "Require all changes to be committed before Claude stops",
+    fn: requireCommitBeforeStop,
+    match: { events: ["Stop"] },
+    defaultEnabled: false,
+    category: "Workflow",
+    beta: true,
+  },
+  {
+    name: "require-push-before-stop",
+    description: "Require all commits to be pushed to remote before Claude stops",
+    fn: requirePushBeforeStop,
+    match: { events: ["Stop"] },
+    defaultEnabled: false,
+    category: "Workflow",
+    beta: true,
+    params: {
+      remote: {
+        type: "string",
+        description: "Remote name to push to (default: origin)",
+        default: "origin",
+      },
+    } satisfies PolicyParamsSchema,
+  },
+  {
+    name: "require-pr-before-stop",
+    description: "Require a pull request to exist for the current branch before Claude stops",
+    fn: requirePrBeforeStop,
+    match: { events: ["Stop"] },
+    defaultEnabled: false,
+    category: "Workflow",
+    beta: true,
+  },
+  {
+    name: "require-ci-green-before-stop",
+    description: "Require CI checks to pass on the current branch before Claude stops",
+    fn: requireCiGreenBeforeStop,
+    match: { events: ["Stop"] },
+    defaultEnabled: false,
+    category: "Workflow",
+    beta: true,
+  },
 ];
 
 export function registerBuiltinPolicies(enabledNames: string[]): void {

package/.next/standalone/src/hooks/manager.ts

@@ -21,6 +21,7 @@ import { BUILTIN_POLICIES } from "./builtin-policies";
 import { loadCustomHooks } from "./custom-hooks-loader";
 import { trackHookEvent } from "./hook-telemetry";
 import { getInstanceId, hashToId } from "../../lib/telemetry-id";
+import { CliError } from "../cli-error";
 
 const VALID_POLICY_NAMES = new Set(BUILTIN_POLICIES.map((p) => p.name));
 
@@ -67,7 +68,7 @@ function resolveFailproofaiBinary(): string {
     // `where` on Windows may return multiple lines; take the first
     return result.split("\n")[0].trim();
   } catch {
-    throw new Error(
+    throw new CliError(
       "failproofai binary not found in PATH.\n" +
       "Install it globally first: npm install -g failproofai"
     );
@@ -85,7 +86,7 @@ function validatePolicyNames(names: string[]): void {
   const invalid = names.filter((n) => !VALID_POLICY_NAMES.has(n));
   if (invalid.length > 0) {
     const validList = [...VALID_POLICY_NAMES].join(", ");
-    throw new Error(
+    throw new CliError(
       `Unknown policy name(s): ${invalid.join(", ")}\n` +
       `Valid policies: ${validList}`
     );
@@ -185,6 +186,20 @@ export async function installHooks(
   customPoliciesPath?: string,
   removeCustomHooks = false,
 ): Promise<void> {
+  // Validate user input first before any system checks
+  if (policyNames !== undefined && policyNames.length > 0) {
+    const nonAllNames = policyNames.filter((n) => n !== "all");
+    // Check unknown names first (most actionable error for the user)
+    if (nonAllNames.length > 0) validatePolicyNames(nonAllNames);
+    // Then check if "all" is mixed with valid specific names
+    if (policyNames.includes("all") && nonAllNames.length > 0) {
+      throw new CliError(
+        `"all" cannot be combined with specific policy names.\n` +
+        `Use either: --install all  or  --install block-sudo sanitize-jwt ...`
+      );
+    }
+  }
+
   const binaryPath = resolveFailproofaiBinary();
 
   // Capture existing config before overwriting (used for telemetry diff)
@@ -201,7 +216,6 @@ export async function installHooks(
         .filter((p) => includeBeta || !p.beta)
         .map((p) => p.name);
     } else {
-      if (policyNames.length > 0) validatePolicyNames(policyNames);
       incoming = policyNames;
     }
     // Additive: union with whatever was already enabled, deduplicated.

package/.next/standalone/src/hooks/policy-evaluator.ts

@@ -51,6 +51,9 @@ export async function evaluatePolicies(
   let instructPolicyName: string | null = null;
   let instructReason: string | null = null;
 
+  // Track informational messages from allow decisions
+  const allowMessages: string[] = [];
+
   for (const policy of policies) {
     // Inject params: merge policyParams[policy.name] over schema defaults
     const schema = POLICY_PARAMS_MAP.get(policy.name);
@@ -133,6 +136,11 @@ export async function evaluatePolicies(
       instructReason = result.reason ?? `Instruction from policy: ${policy.name}`;
       hookLogInfo(`instruct by "${policy.name}": ${instructReason}`);
     }
+
+    // Accumulate informational messages from allow decisions
+    if (result.decision === "allow" && result.reason) {
+      allowMessages.push(result.reason);
+    }
   }
 
   // No deny — check if we accumulated an instruct
@@ -166,6 +174,16 @@ export async function evaluatePolicies(
     };
   }
 
-  // All policies allowed
+  // All policies allowed — pass along any informational messages
+  if (allowMessages.length > 0) {
+    const combined = allowMessages.join("\n");
+    const response = {
+      hookSpecificOutput: {
+        hookEventName: eventType,
+        additionalContext: combined,
+      },
+    };
+    return { exitCode: 0, stdout: JSON.stringify(response), stderr: "", policyName: null, reason: combined, decision: "allow" };
+  }
   return { exitCode: 0, stdout: "", stderr: "", policyName: null, reason: null, decision: "allow" };
 }

package/.next/standalone/src/hooks/policy-helpers.ts

@@ -3,8 +3,8 @@
  */
 import type { PolicyResult } from "./policy-types";
 
-export function allow(): PolicyResult {
-  return { decision: "allow" };
+export function allow(reason?: string): PolicyResult {
+  return reason ? { decision: "allow", reason } : { decision: "allow" };
 }
 
 export function deny(reason: string): PolicyResult {

package/.next/standalone/vitest.config.e2e.mts

@@ -17,5 +17,8 @@ export default defineConfig({
     // forks pool: true process isolation — tests spawn subprocesses,
     // thread workers share globalThis which can interfere.
     pool: "forks",
+    env: {
+      FAILPROOFAI_TELEMETRY_DISABLED: "1",
+    },
   },
 });

package/.next/standalone/vitest.config.mts

@@ -16,5 +16,8 @@ export default defineConfig({
     include: ["__tests__/**/*.test.{ts,tsx}"],
     exclude: ["__tests__/e2e/**"],
     css: false,
+    env: {
+      FAILPROOFAI_TELEMETRY_DISABLED: "1",
+    },
   },
 });