@aliou/pi-guardrails 0.12.1 → 0.13.1

package/README.md

@@ -1,4 +1,4 @@
-![banner](https://assets.aliou.me/pi-extensions/banners/pi-guardrails.png)
+![banner](https://assets.aliou.me/github/aliou/pi-guardrails/banner.png)
 
 # Guardrails
 
@@ -24,7 +24,7 @@ After installing, run the onboarding command to choose a starting setup:
 /guardrails:onboarding
 ```
 
-![Guardrails onboarding walkthrough](https://assets.aliou.me/pi-extensions/demos/guardrails/v0.12.0/onboarding.gif)
+[![Guardrails onboarding walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/onboarding.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/onboarding.mp4)
 
 You can change everything later with:
 
@@ -40,7 +40,7 @@ The `guardrails` extension owns file protection policies and the user-facing com
 
 Use it to protect files like `.env`, private keys, local credentials, generated logs, database dumps, or any project-specific path you do not want Pi to read or modify without clear intent.
 
-![Guardrails policies and settings walkthrough](https://assets.aliou.me/pi-extensions/demos/guardrails/v0.12.0/policies.gif)
+[![Guardrails policies and settings walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/policies.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/policies.mp4)
 
 Useful commands:
 
@@ -56,7 +56,7 @@ The `path-access` extension checks tool calls that target paths outside the curr
 
 It can allow, block, or ask before Pi accesses files elsewhere on your machine. In ask mode, you can allow one file or a directory once, for the session, or always.
 
-![Guardrails path access prompt walkthrough](https://assets.aliou.me/pi-extensions/demos/guardrails/v0.12.0/path-access.gif)
+[![Guardrails path access prompt walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/path-access.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/path-access.mp4)
 
 ### permission-gate
 
@@ -64,7 +64,7 @@ The `permission-gate` extension detects dangerous bash commands before they run.
 
 It catches built-in risky patterns like recursive deletes, privileged commands, disk formatting, broad permission changes, and configured custom patterns. You can allow once, allow for the session, deny, or configure auto-deny rules.
 
-![Guardrails permission gate walkthrough](https://assets.aliou.me/pi-extensions/demos/guardrails/v0.12.0/permission-gate.gif)
+[![Guardrails permission gate walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/permission-gate.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/permission-gate.mp4)
 
 ## Configuration
 
@@ -89,7 +89,7 @@ Use the examples command to add common policy and command presets without replac
 /guardrails:examples
 ```
 
-![Guardrails examples command walkthrough](https://assets.aliou.me/pi-extensions/demos/guardrails/v0.12.0/examples.gif)
+[![Guardrails examples command walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/examples.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/examples.mp4)
 
 The available presets live in [`extensions/guardrails/commands/settings/examples.ts`](extensions/guardrails/commands/settings/examples.ts).
 
@@ -97,6 +97,8 @@ The available presets live in [`extensions/guardrails/commands/settings/examples
 
 Pi is designed to make agent safety extensible. Guardrails focuses on deterministic, configurable file policies, outside-workspace path access, and dangerous-command prompts. Other packages tend to fall into two useful groups.
 
+See [pi.dev/packages](https://pi.dev/packages) for the full registry of Pi extensions.
+
 ### Make one yourself!
 
 If Guardrails or the alternatives below do not fit your needs, you can also make your own. Start from the [Pi permission gate example](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/examples/extensions/permission-gate.ts), then ask Pi to customize it for your workflow.

package/extensions/path-access/index.ts

@@ -9,6 +9,7 @@ import { configLoader } from "../../src/shared/config";
 import {
   createFeatureRegisterPayload,
   emitActionBlocked,
+  emitActionPrompted,
   GUARDRAILS_FEATURE_REGISTER_EVENT,
   GUARDRAILS_FEATURE_REQUEST_EVENT,
 } from "../../src/shared/events";
@@ -85,6 +86,17 @@ export default async function pathAccess(pi: ExtensionAPI) {
       const parentDir = dirname(absolutePath);
       const showFileOptions =
         event.toolName !== "ls" && event.toolName !== "find";
+      emitActionPrompted(pi, {
+        feature: "pathAccess",
+        action: safety.action,
+        reason: safety.reason,
+        prompt: {
+          kind: "confirmation",
+          metadata: safety.metadata,
+        },
+        context: { toolName: event.toolName, input },
+      });
+
       const result = await ctx.ui.custom<PromptResult>(
         createPathAccessPromptComponent(
           event.toolName,

package/extensions/permission-gate/index.ts

@@ -7,6 +7,7 @@ import { configLoader } from "../../src/shared/config";
 import {
   createFeatureRegisterPayload,
   emitActionBlocked,
+  emitActionPrompted,
   emitRiskDetected,
   GUARDRAILS_FEATURE_REGISTER_EVENT,
   GUARDRAILS_FEATURE_REQUEST_EVENT,
@@ -89,6 +90,17 @@ export default async function permissionGate(pi: ExtensionAPI) {
     }
 
     type ConfirmResult = "allow" | "allow-session" | "deny";
+    emitActionPrompted(pi, {
+      feature: "permissionGate",
+      action: safety.action,
+      reason: safety.reason,
+      prompt: {
+        kind: "permission",
+        metadata: safety.metadata,
+      },
+      context: { toolName: "bash", input: event.input },
+    });
+
     let result = await ctx.ui.custom<ConfirmResult>(
       createPermissionGateConfirmComponent(command, safety.reason),
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-guardrails",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -21,7 +21,7 @@
       "./extensions/guardrails/index.ts",
       "./extensions/permission-gate/index.ts"
     ],
-    "video": "https://assets.aliou.me/pi-extensions/demos/pi-guardrails.mp4"
+    "video": "https://assets.aliou.me/github/aliou/pi-guardrails/demo.mp4"
   },
   "publishConfig": {
     "access": "public"
@@ -30,19 +30,21 @@
     "src",
     "extensions",
     "README.md",
-    "schema.json"
+    "schema.json",
+    "!src/**/*.test.ts",
+    "!extensions/**/*.test.ts"
   ],
   "dependencies": {
     "@aliou/pi-utils-settings": "^0.15.1",
     "@aliou/sh": "^0.1.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "0.74.0",
-    "@earendil-works/pi-tui": "0.74.0"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@aliou/biome-plugins": "^0.3.2",
-    "@biomejs/biome": "^2.3.13",
+    "@aliou/biome-plugins": "^0.8.1",
+    "@biomejs/biome": "^2.4.15",
     "@changesets/cli": "^2.27.11",
     "@earendil-works/pi-coding-agent": "0.74.0",
     "@earendil-works/pi-tui": "0.74.0",

package/src/shared/events.ts

@@ -5,6 +5,7 @@ export const GUARDRAILS_ACTION_BLOCKED_EVENT = "guardrails:action:blocked";
 export const GUARDRAILS_RISK_DETECTED_EVENT = "guardrails:risk:detected";
 export const GUARDRAILS_FEATURE_REQUEST_EVENT = "guardrails:feature:request";
 export const GUARDRAILS_FEATURE_REGISTER_EVENT = "guardrails:feature:register";
+export const GUARDRAILS_ACTION_PROMPTED_EVENT = "guardrails:action:prompted";
 
 export type GuardrailsFeatureId = "policies" | "permissionGate" | "pathAccess";
 
@@ -47,6 +48,22 @@ export type GuardrailsActionBlockedPayload<TMeta = unknown> =
     };
   };
 
+export type GuardrailsActionPromptedPayload<TMeta = unknown> =
+  GuardrailsEventBase & {
+    action: Action;
+    reason: string;
+    prompt: {
+      /** What kind of prompt was shown */
+      kind: "confirmation" | "permission";
+      /** The feature-specific metadata about the risk */
+      metadata?: TMeta;
+    };
+    context?: {
+      toolName?: string;
+      input?: Record<string, unknown>;
+    };
+  };
+
 export type GuardrailsRiskDetectedPayload<TMeta = unknown> =
   GuardrailsEventBase & {
     risk: Safety<TMeta> & { kind: "dangerous" };
@@ -98,3 +115,14 @@ export function emitRiskDetected<TMeta = unknown>(
     ...event,
   });
 }
+
+export function emitActionPrompted<TMeta = unknown>(
+  pi: ExtensionAPI,
+  event: Omit<GuardrailsActionPromptedPayload<TMeta>, "source" | "timestamp">,
+): void {
+  pi.events.emit(GUARDRAILS_ACTION_PROMPTED_EVENT, {
+    source: "guardrails",
+    timestamp: timestamp(),
+    ...event,
+  });
+}

package/extensions/guardrails/rules.test.ts

@@ -1,107 +0,0 @@
-import { join } from "node:path";
-import { vol } from "memfs";
-import { describe, expect, it } from "vitest";
-import { compilePolicies, createPolicyRules, normalizeTarget } from "./rules";
-
-function singleRule(
-  cwd: string,
-  policy: Parameters<typeof compilePolicies>[0][number],
-) {
-  const [rule] = createPolicyRules(compilePolicies([policy]), cwd);
-  return rule;
-}
-
-describe("normalizeTarget", () => {
-  it("prefers cwd-relative paths for targets inside cwd", () => {
-    const cwd = "/repo";
-    expect(normalizeTarget("/repo/config/locked.json", cwd)).toBe(
-      "config/locked.json",
-    );
-  });
-});
-
-describe("compilePolicies", () => {
-  it("skips disabled and empty rules", () => {
-    const policies = compilePolicies([
-      {
-        id: "disabled",
-        name: "Disabled",
-        enabled: false,
-        patterns: [{ pattern: "*.env" }],
-        protection: "noAccess",
-      },
-      { id: "empty", name: "Empty", patterns: [], protection: "noAccess" },
-      {
-        id: "active",
-        name: "Active",
-        patterns: [{ pattern: "*.env" }],
-        protection: "readOnly",
-      },
-    ]);
-
-    expect(policies.map((policy) => policy.id)).toEqual(["active"]);
-  });
-});
-
-describe("createPolicyRules", () => {
-  const cwd = "/repo";
-
-  it("matches protected files and returns policy metadata", async () => {
-    vol.fromJSON({ "/repo/.env": "SECRET=1" });
-    const rule = singleRule(cwd, {
-      id: "secrets",
-      name: "Secrets",
-      patterns: [{ pattern: ".env" }],
-      protection: "noAccess",
-    });
-
-    await expect(
-      rule.check({ kind: "file", path: join(cwd, ".env") }),
-    ).resolves.toMatchObject({
-      kind: "match",
-      metadata: { ruleId: "secrets", protection: "noAccess", path: ".env" },
-    });
-  });
-
-  it("passes allowed patterns", async () => {
-    vol.fromJSON({ "/repo/.env.example": "SECRET=" });
-    const rule = singleRule(cwd, {
-      id: "secrets",
-      name: "Secrets",
-      patterns: [{ pattern: ".env*" }],
-      allowedPatterns: [{ pattern: ".env.example" }],
-      protection: "noAccess",
-    });
-
-    await expect(
-      rule.check({ kind: "file", path: join(cwd, ".env.example") }),
-    ).resolves.toEqual({ kind: "pass" });
-  });
-
-  it("passes missing files when onlyIfExists is true", async () => {
-    const rule = singleRule(cwd, {
-      id: "secrets",
-      name: "Secrets",
-      patterns: [{ pattern: ".env" }],
-      protection: "noAccess",
-    });
-
-    await expect(
-      rule.check({ kind: "file", path: join(cwd, ".env") }),
-    ).resolves.toEqual({ kind: "pass" });
-  });
-
-  it("matches missing files when onlyIfExists is false", async () => {
-    const rule = singleRule(cwd, {
-      id: "secrets",
-      name: "Secrets",
-      patterns: [{ pattern: ".env" }],
-      protection: "noAccess",
-      onlyIfExists: false,
-    });
-
-    await expect(
-      rule.check({ kind: "file", path: join(cwd, ".env") }),
-    ).resolves.toMatchObject({ kind: "match" });
-  });
-});

package/extensions/guardrails/targets.test.ts

@@ -1,44 +0,0 @@
-import { join } from "node:path";
-import { vol } from "memfs";
-import { describe, expect, it } from "vitest";
-import { compilePolicies } from "./rules";
-import { extractTargets } from "./targets";
-
-describe("extractTargets", () => {
-  it("returns direct file tool targets", async () => {
-    await expect(
-      extractTargets(
-        { toolName: "read", input: { path: "config/locked.json" } },
-        "/repo",
-        [],
-      ),
-    ).resolves.toEqual(["config/locked.json"]);
-  });
-
-  it("extracts only bash targets matching configured policies", async () => {
-    const cwd = "/repo";
-    vol.fromJSON({
-      "/repo/config/locked.json": "{}",
-      "/repo/README.md": "hello",
-    });
-    const policies = compilePolicies([
-      {
-        id: "locked",
-        name: "Locked",
-        patterns: [{ pattern: "config/locked.json" }],
-        protection: "readOnly",
-      },
-    ]);
-
-    await expect(
-      extractTargets(
-        {
-          toolName: "bash",
-          input: { command: "cat README.md config/locked.json" },
-        },
-        cwd,
-        policies,
-      ),
-    ).resolves.toEqual([join("config", "locked.json")]);
-  });
-});

package/extensions/path-access/grants.test.ts

@@ -1,47 +0,0 @@
-import { homedir } from "node:os";
-import { describe, expect, it } from "vitest";
-import {
-  createPendingGrant,
-  isGrantTooBroad,
-  pendingAllowedPaths,
-  resolveAllowedPaths,
-} from "./grants";
-
-describe("path access grants", () => {
-  it("resolves allowed paths relative to cwd", () => {
-    expect(resolveAllowedPaths(["../shared", "logs/"], "/repo/app")).toEqual([
-      "/repo/shared",
-      "/repo/app/logs/",
-    ]);
-  });
-
-  it("converts pending grants to absolute allowed paths", () => {
-    expect(
-      pendingAllowedPaths([
-        {
-          storagePath: "/tmp/file.txt",
-          absolutePath: "/tmp/file.txt",
-          scope: "memory",
-        },
-        {
-          storagePath: "/tmp/logs/",
-          absolutePath: "/tmp/logs",
-          scope: "local",
-        },
-      ]),
-    ).toEqual(["/tmp/file.txt", "/tmp/logs/"]);
-  });
-
-  it("rejects home grants as too broad", () => {
-    expect(isGrantTooBroad(`${homedir()}/`)).toBe(true);
-    expect(isGrantTooBroad(`${homedir()}/project`)).toBe(false);
-  });
-
-  it("creates pending grants with storage form", () => {
-    expect(createPendingGrant("/tmp/logs", true, "local")).toEqual({
-      absolutePath: "/tmp/logs",
-      scope: "local",
-      storagePath: "/tmp/logs/",
-    });
-  });
-});

package/extensions/path-access/rules.test.ts

@@ -1,46 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { createPathAccessRule } from "./rules";
-
-const cwd = "/repo";
-const state = (allowedPaths: string[] = []) => ({
-  cwd,
-  mode: "block" as const,
-  allowedPaths,
-  hasUI: true,
-});
-
-describe("createPathAccessRule", () => {
-  it("passes command actions", () => {
-    const rule = createPathAccessRule(state());
-    expect(rule.check({ kind: "command", command: "cat /tmp/a" })).toEqual({
-      kind: "pass",
-    });
-  });
-
-  it("passes files inside cwd", () => {
-    const rule = createPathAccessRule(state());
-    expect(rule.check({ kind: "file", path: "/repo/src/index.ts" })).toEqual({
-      kind: "pass",
-    });
-  });
-
-  it("matches outside files in block mode", () => {
-    const rule = createPathAccessRule(state());
-    expect(rule.check({ kind: "file", path: "/tmp/secret.txt" })).toMatchObject(
-      {
-        kind: "match",
-        metadata: {
-          absolutePath: "/tmp/secret.txt",
-          displayPath: "/tmp/secret.txt",
-        },
-      },
-    );
-  });
-
-  it("passes explicitly allowed outside paths", () => {
-    const rule = createPathAccessRule(state(["/tmp/"]));
-    expect(rule.check({ kind: "file", path: "/tmp/secret.txt" })).toEqual({
-      kind: "pass",
-    });
-  });
-});

package/extensions/path-access/targets.test.ts

@@ -1,40 +0,0 @@
-import { join } from "node:path";
-import { vol } from "memfs";
-import { describe, expect, it } from "vitest";
-import { targetsForTool } from "./targets";
-
-describe("targetsForTool", () => {
-  it("resolves direct file tool targets from cwd", async () => {
-    await expect(
-      targetsForTool("read", { path: "README.md" }, "/repo"),
-    ).resolves.toEqual(["/repo/README.md"]);
-  });
-
-  it("extracts bash path candidates", async () => {
-    const cwd = "/repo";
-    vol.fromJSON({ "/repo/README.md": "hello" });
-
-    await expect(
-      targetsForTool("bash", { command: "cat ./README.md" }, cwd),
-    ).resolves.toEqual([join(cwd, "README.md")]);
-  });
-
-  it("does not treat awk regexes as paths", async () => {
-    const cwd = "/repo";
-    vol.fromJSON({ "/repo/test.txt": "aaa" });
-
-    await expect(
-      targetsForTool(
-        "bash",
-        { command: "awk '/aaa/{flag=1} flag{print}' ./test.txt" },
-        cwd,
-      ),
-    ).resolves.toEqual([join(cwd, "test.txt")]);
-  });
-
-  it("ignores unrelated tools", async () => {
-    await expect(
-      targetsForTool("custom", { path: "README.md" }, "/repo"),
-    ).resolves.toEqual([]);
-  });
-});

package/extensions/permission-gate/rules.test.ts

@@ -1,132 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  createPermissionGateRule,
-  formatAutoDenyReason,
-  matchCommandPattern,
-  matchesAnyCommandPattern,
-} from "./rules";
-
-describe("createPermissionGateRule", () => {
-  it("passes file actions", async () => {
-    const rule = createPermissionGateRule({
-      patterns: [{ pattern: "rm -rf", description: "recursive delete" }],
-      useBuiltinMatchers: false,
-    });
-    expect(rule.check({ kind: "file", path: "package.json" })).toEqual({
-      kind: "pass",
-    });
-  });
-
-  it("matches configured dangerous command patterns", async () => {
-    const rule = createPermissionGateRule({
-      patterns: [
-        { pattern: "terraform destroy", description: "Destroy infra" },
-      ],
-      useBuiltinMatchers: false,
-    });
-
-    expect(
-      rule.check({
-        kind: "command",
-        command: "terraform destroy -auto-approve",
-      }),
-    ).toEqual({
-      kind: "match",
-      reason: "Destroy infra",
-      metadata: {
-        command: "terraform destroy -auto-approve",
-        description: "Destroy infra",
-        pattern: "terraform destroy",
-      },
-    });
-  });
-
-  it("can use builtin dangerous command matchers", async () => {
-    const rule = createPermissionGateRule({
-      patterns: [],
-      useBuiltinMatchers: true,
-    });
-    expect(
-      rule.check({ kind: "command", command: "rm -rf dist" }),
-    ).toMatchObject({ kind: "match" });
-  });
-});
-
-describe("matchesAnyCommandPattern", () => {
-  it("matches substring and regex command patterns", () => {
-    expect(
-      matchesAnyCommandPattern("npm publish --dry-run", [
-        { pattern: "npm publish" },
-      ]),
-    ).toBe(true);
-    expect(
-      matchesAnyCommandPattern("DROP TABLE users", [
-        { pattern: "^DROP TABLE", regex: true },
-      ]),
-    ).toBe(true);
-    expect(
-      matchesAnyCommandPattern("npm test", [{ pattern: "npm publish" }]),
-    ).toBe(false);
-  });
-});
-
-describe("matchCommandPattern", () => {
-  it("returns the matched PatternConfig", () => {
-    const patterns = [{ pattern: "npm publish" }, { pattern: "rm -rf" }];
-    expect(matchCommandPattern("npm publish --dry-run", patterns)).toBe(
-      patterns[0],
-    );
-  });
-
-  it("returns the matching regex pattern", () => {
-    const patterns = [{ pattern: "^DROP TABLE", regex: true }];
-    expect(matchCommandPattern("DROP TABLE users", patterns)).toBe(patterns[0]);
-  });
-
-  it("returns null when no pattern matches", () => {
-    expect(
-      matchCommandPattern("npm test", [{ pattern: "npm publish" }]),
-    ).toBeNull();
-  });
-
-  it("preserves description on the returned pattern", () => {
-    const patterns = [
-      {
-        pattern: "python -m venv",
-        description: "Use the project .venv instead",
-      },
-    ];
-    const result = matchCommandPattern("python -m venv .venv", patterns);
-    expect(result).not.toBeNull();
-    expect(result?.description).toBe("Use the project .venv instead");
-  });
-});
-
-describe("formatAutoDenyReason", () => {
-  it("uses description when present", () => {
-    expect(
-      formatAutoDenyReason({
-        pattern: "python -m venv",
-        description: "Use the project .venv instead",
-      }),
-    ).toBe("Command auto-denied: Use the project .venv instead");
-  });
-
-  it("falls back to generic reason when description is missing", () => {
-    expect(formatAutoDenyReason({ pattern: "python -m venv" })).toBe(
-      "Command matched auto-deny pattern and was blocked automatically.",
-    );
-  });
-
-  it("falls back when description is empty string", () => {
-    expect(
-      formatAutoDenyReason({ pattern: "python -m venv", description: "" }),
-    ).toBe("Command matched auto-deny pattern and was blocked automatically.");
-  });
-
-  it("falls back when description is whitespace-only", () => {
-    expect(
-      formatAutoDenyReason({ pattern: "python -m venv", description: "  " }),
-    ).toBe("Command matched auto-deny pattern and was blocked automatically.");
-  });
-});