rulereceipt 0.1.86 → 0.1.87

package/dist/guard.d.ts

@@ -74,5 +74,16 @@ export interface GuardDecision {
 export declare function guardDecision(cwd: string, toolName: string, toolInput: {
     command?: unknown;
 } & Record<string, unknown>, events?: TranscriptEvent[], permissionMode?: string): GuardDecision;
+/** One line for the guard receipt log — every block (or would-block) is recorded. */
+export declare function guardReceiptLine(decision: GuardDecision, command: string, shadow: boolean): {
+    ts: string;
+    mode: "shadow" | "enforce";
+    action: "deny" | "would-deny" | "ask" | "would-ask";
+    command: string;
+    rules: {
+        id: string;
+        title: string;
+    }[];
+};
 export declare function runGuard(): Promise<void>;
 export {};

package/dist/guard.js

@@ -25,9 +25,9 @@ function gitCurrentBranch(cwd) {
         return undefined;
     }
 }
-import { readFileSync } from "node:fs";
+import { readFileSync, appendFileSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
 /**
  * Modes where Claude Code shows NO permission prompt, so a hook's "ask" is
  * ignored and the call just runs (Claude Code #89561; "ask" also drops bypass
@@ -301,6 +301,38 @@ export function guardDecision(cwd, toolName, toolInput, events = [], permissionM
     }
     return allow;
 }
+/**
+ * Shadow mode (live-blocking rollout, vs Failproof): set RULERECEIPT_GUARD_SHADOW=1
+ * and the guard never blocks — it LOGS what it WOULD have blocked and allows the
+ * call. The honest way to turn on enforcement: run shadow first, read the log,
+ * then drop the flag. Enforcement is the default (no env needed).
+ */
+function guardShadowEnabled() {
+    const v = process.env.RULERECEIPT_GUARD_SHADOW;
+    return v === "1" || v === "true" || v === "yes";
+}
+/** One line for the guard receipt log — every block (or would-block) is recorded. */
+export function guardReceiptLine(decision, command, shadow) {
+    const base = decision.deny ? "deny" : "ask";
+    return {
+        ts: new Date().toISOString(),
+        mode: shadow ? "shadow" : "enforce",
+        action: (shadow ? `would-${base}` : base),
+        command: command.replace(/\s+/g, " ").trim().slice(0, 120),
+        rules: decision.blocks.map((b) => ({ id: b.rule.id, title: b.rule.title })),
+    };
+}
+/** Append a receipt line to .rulereceipt/guard-log.jsonl. Fail-open: never breaks the guard. */
+function writeGuardReceipt(cwd, line) {
+    try {
+        const p = join(cwd, ".rulereceipt", "guard-log.jsonl");
+        mkdirSync(dirname(p), { recursive: true });
+        appendFileSync(p, `${JSON.stringify(line)}\n`);
+    }
+    catch {
+        /* logging must never stop (or crash) the guard */
+    }
+}
 export async function runGuard() {
     const allow = () => {
         process.stdout.write(JSON.stringify({}));
@@ -321,6 +353,15 @@ export async function runGuard() {
             }
         }
         const decision = guardDecision(cwd, tool, toolInput, events, input.permission_mode);
+        const shadow = guardShadowEnabled();
+        const commandStr = typeof toolInput.command === "string" ? toolInput.command : tool;
+        // Every block (or would-block) writes a receipt line — the audit trail of
+        // what the guard stopped, in both shadow and enforce mode.
+        if (decision.deny || decision.ask)
+            writeGuardReceipt(cwd, guardReceiptLine(decision, commandStr, shadow));
+        // Shadow mode: log above, then ALLOW — never block, never ask.
+        if (shadow)
+            return allow();
         if (!decision.deny && decision.ask) {
             // "ask" is not a refusal: no exit 2. Claude Code shows its permission
             // prompt with this reason; the user's click decides.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.86",
+  "version": "0.1.87",
   "description": "Checks whether your AI coding agent followed your rules, with evidence. Works with Claude Code (Codex in testing); reads CLAUDE.md, AGENTS.md, Cursor, Copilot and Windsurf rules.",
   "repository": {
     "type": "git",