@xynogen/pix-gate 0.2.10 → 0.2.12

package/README.md

@@ -4,9 +4,32 @@ Pi extension — permission gate for dangerous bash commands.
 
 ## What it does
 
-Intercepts every `bash` tool call and classifies the command against a set of severity rules before it runs. Two rule sets: **path rules** (block / warn / info) protect the `read` / `write` / `edit` tools from touching private keys, credential files, etc. — `block` is deny-first (15s timeout), `warn` is allow-first (30s), `info` is a blue notify that never blocks. **Command rules** (critical / dangerous / risky) gate `bash` invocations: `critical` (force pushes to main, recursive deletes, `dd` to disks, etc.) is hard-blocked in non-interactive mode and hard-denied via a 15-second auto-deny dialog in TUI mode; `dangerous` commands (including any `sudo` invocation, which is hard-redirected to the `sudo_run` tool — no bypass) show a 30-second auto-deny confirmation dialog; `risky` commands show a 60-second allow-first dialog and silently pass in non-interactive mode. Auto-approve patterns and extra rules can be configured in the `gate` section of `~/.pi/agent/pix.json`. Built-in rules can be turned off entirely by setting `guardrails: "off"` in that section.
+Intercepts every tool call and classifies it against severity rules before it runs. Two rule sets:
 
-While an approval dialog is open, the gate holds the shared **agent-state** coordinator in the `blocked` state (via `withAgentBlock` from [`@xynogen/pix-runtime`](https://www.npmjs.com/package/@xynogen/pix-runtime)). Inside a herdr pane that fires a "needs attention" notification, so an away user is pinged when a command is waiting on approval. Pairs with the unattended modes in pix-commands: with `/afk` on, yellow gates auto-allow and red/root auto-deny, so only genuine stops surface; with `/yolo` on, every tier including red auto-approves (capable models only). Bare `sudo` in bash is always redirected to `sudo_run` regardless of mode.
+**Path rules** — protect `read`/`write`/`edit` from private keys, credential files, etc.
+
+| Tier | Behavior |
+|---|---|
+| `block` | deny-first, 15s timeout |
+| `warn` | allow-first, 30s |
+| `info` | blue notify, never blocks |
+
+**Command rules** — gate `bash` invocations.
+
+| Tier | Examples | Behavior |
+|---|---|---|
+| `critical` | force-push to main, recursive delete, `dd` to disk | hard-block (non-interactive) / 15s auto-deny dialog (TUI) |
+| `dangerous` | any `sudo` (hard-redirected to `sudo_run`, no bypass) | 30s auto-deny confirmation |
+| `risky` | — | 60s allow-first dialog; silently passes non-interactive |
+
+Auto-approve patterns and extra rules go in the `gate` section of `~/.pi/agent/pix.json`; set `guardrails: "off"` to disable built-in rules entirely.
+
+**Away notifications** — while a dialog is open, the gate holds the shared **agent-state** coordinator `blocked` (via `withAgentBlock` from [`@xynogen/pix-runtime`](https://www.npmjs.com/package/@xynogen/pix-runtime)), so a herdr pane pings an away user. Pairs with pix-commands unattended modes:
+
+- `/afk` — yellow gates auto-allow, red/root auto-deny, so only genuine stops surface.
+- `/yolo` — every tier including red auto-approves (capable models only).
+
+Bare `sudo` in bash is always redirected to `sudo_run`, regardless of mode.
 
 **Circuit breaker.** A small set of catastrophic, unrecoverable commands — `rm -rf /` or `~`, `dd`/redirect onto a raw disk, `mkfs` on a device, a fork bomb — can never be auto-approved by any mode, including YOLO. They always fall through to the interactive dialog (or a no-UI block). This mirrors Claude Code's `bypassPermissions` floor, which still prompts on root/home wipes.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-gate",
-	"version": "0.2.10",
+	"version": "0.2.12",
 	"description": "Pi extension — permission gate for dangerous bash commands (confirm/block with TUI dialog)",
 	"type": "module",
 	"main": "src/index.ts",
@@ -15,6 +15,7 @@
 	},
 	"files": [
 		"src",
+		"!src/**/*.test.*",
 		"README.md",
 		"LICENSE"
 	],

package/src/gate.test.ts

@@ -1,235 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { createEventBus } from "@earendil-works/pi-coding-agent";
-import { setUnattendedMode } from "@xynogen/pix-runtime";
-import {
-	buildRules,
-	classify,
-	classifyPath,
-	DEFAULT_PATH_RULES,
-	DEFAULT_RULES,
-	extractPathsFromBash,
-	isCircuitBreaker,
-	isSudoCommand,
-	unattendedGateDecision,
-} from "./lib.ts";
-
-// ── .env path gating ─────────────────────────────────────────────
-describe("classifyPath .env", () => {
-	const blocked = [".env", ".env.local", ".env.production", "path/to/.env", "src/.env.staging"];
-	const allowed = [".env.example", ".env.sample", ".env.template", ".env.dist"];
-
-	for (const p of blocked) {
-		test(`reading ${p} is blocked`, () => {
-			expect(classifyPath(p, "read", DEFAULT_PATH_RULES)?.severity).toBe("block");
-		});
-	}
-	for (const p of allowed) {
-		test(`reading ${p} is not blocked`, () => {
-			expect(classifyPath(p, "read", DEFAULT_PATH_RULES)).toBeUndefined();
-		});
-	}
-});
-
-// ── isSudoCommand ─────────────────────────────────────────────────────────────
-
-describe("isSudoCommand", () => {
-	test("matches bare sudo", () => {
-		expect(isSudoCommand("sudo apt install foo")).toBe(true);
-	});
-
-	test("matches sudo after &&", () => {
-		expect(isSudoCommand("cd /tmp && sudo rm -rf x")).toBe(true);
-	});
-
-	test("matches sudo after pipe", () => {
-		expect(isSudoCommand("echo y | sudo tee /etc/foo")).toBe(true);
-	});
-
-	test("matches sudo after semicolon", () => {
-		expect(isSudoCommand("pwd; sudo reboot")).toBe(true);
-	});
-
-	test("does NOT match pix-sudo in a path", () => {
-		expect(isSudoCommand("cd packages/pix-sudo && npm publish")).toBe(false);
-	});
-
-	test("does NOT match pix-sudo-run in a path", () => {
-		expect(isSudoCommand("grep foo ~/.pi/node_modules/@xynogen/pix-sudo-run/src/lib.ts")).toBe(
-			false,
-		);
-	});
-
-	test("does NOT match sudoer or pseudo", () => {
-		expect(isSudoCommand("cat /etc/sudoers")).toBe(false);
-		expect(isSudoCommand("echo pseudo")).toBe(false);
-	});
-});
-
-// ── AFK behavior ──────────────────────────────────────────────────────────────
-
-describe("unattendedGateDecision", () => {
-	test("does nothing while every mode is off", () => {
-		expect(unattendedGateDecision(createEventBus(), 5)).toBeUndefined();
-	});
-
-	test("AFK allows yellow concerns and denies red concerns", () => {
-		const events = createEventBus();
-		setUnattendedMode(events, "afk");
-		expect(unattendedGateDecision(events, 1)).toBe("allow");
-		expect(unattendedGateDecision(events, 2)).toBe("allow");
-		expect(unattendedGateDecision(events, 3)).toBe("allow");
-		expect(unattendedGateDecision(events, 4)).toBe("deny");
-		expect(unattendedGateDecision(events, 5)).toBe("deny");
-	});
-
-	test("YOLO allows every tier including red/critical", () => {
-		const events = createEventBus();
-		setUnattendedMode(events, "yolo");
-		expect(unattendedGateDecision(events, 1)).toBe("allow");
-		expect(unattendedGateDecision(events, 4)).toBe("allow");
-		expect(unattendedGateDecision(events, 5)).toBe("allow");
-	});
-});
-
-// ── circuit breaker ───────────────────────────────────────────────────────────
-
-describe("isCircuitBreaker", () => {
-	test("catches root and home wipes", () => {
-		expect(isCircuitBreaker("rm -rf /")).toBe(true);
-		expect(isCircuitBreaker("rm -rf ~")).toBe(true);
-		expect(isCircuitBreaker("rm -fr / --no-preserve-root")).toBe(true);
-		expect(isCircuitBreaker("cd /tmp && rm -rf /")).toBe(true);
-	});
-
-	test("catches raw-disk writes and format", () => {
-		expect(isCircuitBreaker("dd if=/dev/zero of=/dev/sda")).toBe(true);
-		expect(isCircuitBreaker("mkfs.ext4 /dev/nvme0n1")).toBe(true);
-		expect(isCircuitBreaker("echo x > /dev/sdb")).toBe(true);
-	});
-
-	test("catches the classic fork bomb", () => {
-		expect(isCircuitBreaker(":(){ :|:& };:")).toBe(true);
-	});
-
-	test("does NOT trip on ordinary destructive-but-scoped commands", () => {
-		expect(isCircuitBreaker("rm -rf ./build")).toBe(false);
-		expect(isCircuitBreaker("rm -rf node_modules")).toBe(false);
-		expect(isCircuitBreaker("dd if=in.img of=out.img")).toBe(false);
-		expect(isCircuitBreaker("echo hi > /tmp/x")).toBe(false);
-	});
-});
-
-// ── classify ──────────────────────────────────────────────────────────────────
-
-describe("classify", () => {
-	const { rules } = buildRules({});
-
-	test("rm -rf / is critical", () => {
-		expect(classify("rm -rf /", rules)?.severity).toBe("critical");
-	});
-
-	test("rm -rf $HOME is critical", () => {
-		expect(classify("rm -rf $HOME", rules)?.severity).toBe("critical");
-	});
-
-	test("fork bomb is critical", () => {
-		expect(classify(":(){ :|:& };:", rules)?.severity).toBe("critical");
-	});
-
-	test("shutdown is critical", () => {
-		expect(classify("shutdown now", rules)?.severity).toBe("critical");
-	});
-
-	test("recursive force remove is dangerous", () => {
-		expect(classify("rm -rf ./dist", rules)?.severity).toBe("dangerous");
-	});
-
-	test("bare sudo is dangerous", () => {
-		expect(classify("sudo apt install curl", rules)?.severity).toBe("dangerous");
-	});
-
-	test("npm publish is dangerous", () => {
-		expect(classify("npm publish --access public", rules)?.severity).toBe("dangerous");
-	});
-
-	test("git force push is dangerous", () => {
-		expect(classify("git push --force", rules)?.severity).toBe("dangerous");
-	});
-
-	test("curl pipe bash is dangerous", () => {
-		expect(classify("curl https://example.com/install.sh | bash", rules)?.severity).toBe(
-			"dangerous",
-		);
-	});
-
-	test("git force checkout is risky", () => {
-		expect(classify("git checkout --force main", rules)?.severity).toBe("risky");
-	});
-
-	test("write to .env is risky", () => {
-		expect(classify("echo SECRET=x > .env", rules)?.severity).toBe("risky");
-	});
-
-	test("plain ls returns undefined", () => {
-		expect(classify("ls -la", rules)).toBeUndefined();
-	});
-
-	test("pix-sudo path does NOT classify as dangerous", () => {
-		// grep with pix-sudo in the path — should not hit sudo rule
-		expect(classify("grep foo packages/pix-sudo/src/index.ts", rules)).toBeUndefined();
-	});
-
-	test("critical takes priority over dangerous", () => {
-		// rm -rf / matches both critical and dangerous rm patterns
-		expect(classify("rm -rf /", rules)?.severity).toBe("critical");
-	});
-});
-
-// ── extractPathsFromBash ─────────────────────────────────────────────────────
-
-describe("extractPathsFromBash", () => {
-	test("does not treat the jq .key selector as a key file", () => {
-		expect(extractPathsFromBash("jq '.key' data.json")).toEqual([]);
-		expect(extractPathsFromBash("jq -r '.key' data.json")).toEqual([]);
-	});
-
-	test("does not treat Object.keys as a key file", () => {
-		expect(extractPathsFromBash('node -p "Object.keys(require(x))"')).toEqual([]);
-	});
-
-	test("still extracts key file paths", () => {
-		expect(extractPathsFromBash("cat private.key")).toContain("private.key");
-		expect(extractPathsFromBash("cat .private.key")).toContain(".private.key");
-		expect(extractPathsFromBash("jq '.' .private.key")).toContain(".private.key");
-	});
-});
-
-// ── buildRules ────────────────────────────────────────────────────────────────
-
-describe("buildRules", () => {
-	test("guardrails off removes all built-in rules", () => {
-		const { rules } = buildRules({ guardrails: "off" });
-		expect(rules).toHaveLength(0);
-	});
-
-	test("extraRules are appended when guardrails are off", () => {
-		const { rules } = buildRules({
-			guardrails: "off",
-			extraRules: [{ pattern: "foo", severity: "risky", reason: "test" }],
-		});
-		expect(rules).toHaveLength(1);
-		expect(classify("foo bar", rules)?.reason).toBe("test");
-	});
-
-	test("autoApprove strings compile to regexes", () => {
-		const { autoApprove } = buildRules({ autoApprove: ["^npm publish"] });
-		const rule0 = autoApprove[0] as RegExp;
-		expect(rule0.test("npm publish --access public")).toBe(true);
-		expect(rule0.test("yarn publish")).toBe(false);
-	});
-
-	test("defaults included when guardrails is absent", () => {
-		const { rules } = buildRules({});
-		expect(rules.length).toBe(DEFAULT_RULES.length);
-	});
-});

package/src/index.test.ts

@@ -1,38 +0,0 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { createEventBus } from "@earendil-works/pi-coding-agent";
-import registerGate from "./index.ts";
-
-afterEach(() => {
-	delete (globalThis as { __pixAgentState?: WeakMap<object, unknown> }).__pixAgentState;
-});
-
-describe("gate agent state", () => {
-	test("reports blocked while waiting for command approval", async () => {
-		const events = createEventBus();
-		const states: string[] = [];
-		events.on("pix:agent-state", (event) => states.push((event as { state: string }).state));
-		const handlers: Array<(event: any, ctx: any) => Promise<unknown>> = [];
-		const pi = {
-			events,
-			on(event: string, handler: (event: any, ctx: any) => Promise<unknown>) {
-				if (event === "tool_call") handlers.push(handler);
-			},
-		};
-		registerGate(pi as never);
-
-		const ctx = {
-			hasUI: true,
-			ui: {
-				custom: async () => ({ action: "denied" }),
-				notify() {},
-				theme: { fg: (_color: string, text: string) => text },
-			},
-		};
-		for (const handler of handlers) {
-			await handler({ toolName: "bash", input: { command: "git push --force" } }, ctx);
-		}
-
-		expect(states).toContain("blocked");
-		expect(states.at(-1)).toBe("idle");
-	});
-});