@aliou/pi-guardrails 0.12.0 → 0.13.0

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.0",
+  "version": "0.13.0",
   "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,7 +30,9 @@
     "src",
     "extensions",
     "README.md",
-    "schema.json"
+    "schema.json",
+    "!src/**/*.test.ts",
+    "!extensions/**/*.test.ts"
   ],
   "dependencies": {
     "@aliou/pi-utils-settings": "^0.15.1",
@@ -41,8 +43,8 @@
     "@earendil-works/pi-tui": "0.74.0"
   },
   "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/core/shell/command-args.ts

@@ -32,6 +32,7 @@ export function classifyCommandArgs(
   ) {
     return classifyInterpreterArgs(cmd, args);
   }
+  if (cmd === "go") return classifyGoArgs(args);
   if (cmd === "cut")
     return skipOptionValues(args, new Set(["-d", "--delimiter"]));
   if (cmd === "sort")
@@ -224,3 +225,73 @@ function skipOptionValues(
   }
   return out;
 }
+
+/**
+ * Classify `go` subcommand arguments.
+ *
+ * Go commands take package patterns, not file paths, as positional args
+ * for most subcommands. Package patterns like `./...`, `pkg/...`,
+ * or `github.com/user/repo/...` use Go's `...` wildcard and are not
+ * filesystem paths.
+ *
+ * `go run` is an exception: it takes .go file operands, emitted with
+ * `forcePath` since bare filenames like `main.go` don't pass
+ * `maybePathLike`.
+ *
+ * File-valued flags (e.g. `-o`, `-modfile`, `-overlay`) are kept
+ * so that policy checks can still gate them.
+ *
+ * Global flags like `-C dir` are handled before subcommand detection
+ * so their values aren't mistaken for the subcommand.
+ */
+function classifyGoArgs(args: string[]): ClassifiedArg[] {
+  const out: ClassifiedArg[] = [];
+  const fileFlags = new Set(["-o", "-modfile", "-overlay"]);
+
+  // Global flags that consume a value and must be skipped before
+  // subcommand detection. E.g. `go -C /tmp test ./...`
+  const globalFlagsWithValues = new Set(["-C"]);
+
+  let subcommand: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+
+    // Handle file-valued flags
+    if (fileFlags.has(arg)) {
+      if (args[i + 1]) out.push({ token: args[++i] as string });
+      continue;
+    }
+
+    // Handle joined file flags like -o=./bin/app
+    if (arg.startsWith("-o=")) {
+      out.push({ token: arg.slice(3) });
+      continue;
+    }
+
+    // Skip global flags with values before subcommand detection
+    if (!subcommand && globalFlagsWithValues.has(arg)) {
+      i++; // skip value
+      continue;
+    }
+    if (!subcommand && arg.startsWith("-C=")) {
+      // joined form -C=/tmp
+      continue;
+    }
+
+    if (isOption(arg)) continue;
+
+    // First non-flag positional is the subcommand
+    if (!subcommand) {
+      subcommand = arg;
+      continue;
+    }
+
+    // `go run` takes .go file operands; emit with forcePath since
+    // bare filenames like main.go don't pass maybePathLike.
+    // All other subcommands take package patterns; skip them.
+    if (subcommand === "run" && arg.endsWith(".go")) {
+      out.push({ token: arg, forcePath: true });
+    }
+  }
+  return out;
+}

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([]);
-  });
-});