@aliou/pi-guardrails 0.11.2 → 0.12.1

package/extensions/permission-gate/prompt.ts

@@ -0,0 +1,222 @@
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  Key,
+  matchesKey,
+  Spacer,
+  Text,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+
+interface MinimalTheme {
+  fg(color: string, text: string): string;
+  bg(color: string, text: string): string;
+  bold(text: string): string;
+}
+
+interface NumberedWrappedRow {
+  logicalLineNumber: number;
+  rendered: string;
+}
+
+interface CommandViewportState {
+  maxScrollOffset: number;
+  pinnedRows: NumberedWrappedRow[];
+  scrollWindowLines: number;
+  scrollableRows: NumberedWrappedRow[];
+}
+
+const COMMAND_VIEWPORT_LINES = 12;
+
+function buildNumberedWrappedLines(
+  command: string,
+  contentWidth: number,
+  theme: Pick<MinimalTheme, "fg">,
+): NumberedWrappedRow[] {
+  const logicalLines = command.split("\n");
+  const lineNumberWidth = Math.max(2, String(logicalLines.length).length);
+  const prefixSpacing = 1;
+  const textWidth = Math.max(1, contentWidth - lineNumberWidth - prefixSpacing);
+  const rows: Array<{ logicalLineNumber: number; rendered: string }> = [];
+
+  for (const [index, logicalLine] of logicalLines.entries()) {
+    const lineNumber = index + 1;
+    const wrapped = wrapTextWithAnsi(theme.fg("text", logicalLine), textWidth);
+    const wrappedLines = wrapped.length > 0 ? wrapped : [""];
+    const prefix = theme.fg(
+      "dim",
+      String(lineNumber).padStart(lineNumberWidth),
+    );
+
+    for (const line of wrappedLines) {
+      rows.push({
+        logicalLineNumber: lineNumber,
+        rendered: `${prefix} ${line}`,
+      });
+    }
+  }
+
+  return rows;
+}
+
+function getCommandViewportState(
+  command: string,
+  contentWidth: number,
+  theme: Pick<MinimalTheme, "fg">,
+): CommandViewportState {
+  const numberedRows = buildNumberedWrappedLines(command, contentWidth, theme);
+  const pinnedRows = numberedRows.filter((row) => row.logicalLineNumber === 1);
+  const scrollableRows = numberedRows.filter(
+    (row) => row.logicalLineNumber !== 1,
+  );
+  const scrollWindowLines = Math.max(
+    0,
+    COMMAND_VIEWPORT_LINES - pinnedRows.length,
+  );
+
+  return {
+    maxScrollOffset: Math.max(0, scrollableRows.length - scrollWindowLines),
+    pinnedRows,
+    scrollWindowLines,
+    scrollableRows,
+  };
+}
+
+function buildRightAlignedBorder(
+  width: number,
+  themeLine: (s: string) => string,
+  label: string,
+): string {
+  const safeWidth = Math.max(1, width);
+  const truncatedLabel = truncateToWidth(label, safeWidth);
+  const remaining = safeWidth - visibleWidth(truncatedLabel);
+  return themeLine("─".repeat(Math.max(0, remaining)) + truncatedLabel);
+}
+
+export function createPermissionGateConfirmComponent(
+  command: string,
+  description: string,
+) {
+  return (
+    tui: { terminal: { rows: number; columns: number }; requestRender(): void },
+    theme: MinimalTheme,
+    _kb: unknown,
+    done: (result: "allow" | "allow-session" | "deny") => void,
+  ) => {
+    const container = new Container();
+    const redBorder = (s: string) => theme.fg("error", s);
+    const dimBorder = (s: string) => theme.fg("dim", s);
+    let scrollOffset = 0;
+
+    container.addChild(new DynamicBorder(redBorder));
+    container.addChild(
+      new Text(
+        theme.fg("error", theme.bold("Dangerous Command Detected")),
+        1,
+        0,
+      ),
+    );
+    container.addChild(new Spacer(1));
+    container.addChild(
+      new Text(
+        theme.fg("warning", `This command contains ${description}:`),
+        1,
+        0,
+      ),
+    );
+    container.addChild(new Spacer(1));
+    const commandTopBorder = new Text("", 0, 0);
+    container.addChild(commandTopBorder);
+    const commandText = new Text("", 1, 0);
+    container.addChild(commandText);
+    const commandBottomBorder = new Text("", 0, 0);
+    container.addChild(commandBottomBorder);
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("text", "Allow execution?"), 1, 0));
+    container.addChild(new Spacer(1));
+    container.addChild(
+      new Text(
+        theme.fg(
+          "dim",
+          "↑/↓ or j/k: scroll • y/enter: allow • a: session • n/esc: deny",
+        ),
+        1,
+        0,
+      ),
+    );
+    container.addChild(new DynamicBorder(redBorder));
+
+    return {
+      render: (width: number) => {
+        const contentWidth = Math.max(1, width - 4);
+        const {
+          maxScrollOffset,
+          pinnedRows,
+          scrollWindowLines,
+          scrollableRows,
+        } = getCommandViewportState(command, contentWidth, theme);
+        scrollOffset = Math.max(0, Math.min(scrollOffset, maxScrollOffset));
+
+        const visibleScrollableRows = scrollableRows.slice(
+          scrollOffset,
+          scrollOffset + scrollWindowLines,
+        );
+        const visibleRows = [...pinnedRows, ...visibleScrollableRows];
+        const linesBelow = Math.max(
+          0,
+          scrollableRows.length - (scrollOffset + visibleScrollableRows.length),
+        );
+
+        commandTopBorder.setText(
+          buildRightAlignedBorder(
+            width,
+            dimBorder,
+            scrollOffset > 0 ? `↑ ${scrollOffset} more` : "",
+          ),
+        );
+        commandText.setText(visibleRows.map((row) => row.rendered).join("\n"));
+        commandBottomBorder.setText(
+          buildRightAlignedBorder(
+            width,
+            dimBorder,
+            linesBelow > 0 ? `↓ ${linesBelow} more` : "",
+          ),
+        );
+        return container.render(width);
+      },
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        const contentWidth = Math.max(1, tui.terminal.columns - 4);
+        const { maxScrollOffset } = getCommandViewportState(
+          command,
+          contentWidth,
+          theme,
+        );
+
+        if (matchesKey(data, Key.up) || data === "k") {
+          scrollOffset = Math.max(0, scrollOffset - 1);
+          tui.requestRender();
+        } else if (matchesKey(data, Key.down) || data === "j") {
+          scrollOffset = Math.min(maxScrollOffset, scrollOffset + 1);
+          tui.requestRender();
+        } else if (
+          matchesKey(data, Key.enter) ||
+          data === "y" ||
+          data === "Y"
+        ) {
+          done("allow");
+        } else if (data === "a" || data === "A") {
+          done("allow-session");
+        } else if (
+          matchesKey(data, Key.escape) ||
+          data === "n" ||
+          data === "N"
+        ) {
+          done("deny");
+        }
+      },
+    };
+  };
+}

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

@@ -0,0 +1,132 @@
+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.");
+  });
+});

package/extensions/permission-gate/rules.ts

@@ -0,0 +1,72 @@
+import type { Action, Rule } from "../../src/core";
+import { checkDangerousCommand } from "../../src/core/commands";
+import type { DangerousPattern, PatternConfig } from "../../src/shared/config";
+import { compileCommandPatterns } from "../../src/shared/matching";
+
+export type PermissionGateMeta = {
+  command: string;
+  description: string;
+  pattern: string;
+};
+
+export type PermissionGateRuleOptions = {
+  patterns: DangerousPattern[];
+  useBuiltinMatchers: boolean;
+};
+
+export function createPermissionGateRule({
+  patterns,
+  useBuiltinMatchers,
+}: PermissionGateRuleOptions): Rule<PermissionGateMeta> {
+  const compiledPatterns = compileCommandPatterns(patterns);
+
+  return {
+    key: "permission-gate.dangerous-command",
+    check(action: Action) {
+      if (action.kind !== "command") return { kind: "pass" };
+
+      const match = checkDangerousCommand({
+        command: action.command,
+        patterns: compiledPatterns,
+        useBuiltinMatchers,
+        fallbackPatterns: patterns,
+      });
+      if (!match) return { kind: "pass" };
+
+      return {
+        kind: "match",
+        reason: match.description,
+        metadata: {
+          command: action.command,
+          description: match.description,
+          pattern: match.pattern,
+        },
+      };
+    },
+  };
+}
+
+export function matchCommandPattern(
+  command: string,
+  patterns: PatternConfig[],
+): PatternConfig | null {
+  const compiled = compileCommandPatterns(patterns);
+  for (let i = 0; i < compiled.length; i++) {
+    if (compiled[i].test(command)) return patterns[i];
+  }
+  return null;
+}
+
+export function matchesAnyCommandPattern(
+  command: string,
+  patterns: PatternConfig[],
+): boolean {
+  return matchCommandPattern(command, patterns) !== null;
+}
+
+export function formatAutoDenyReason(pattern: PatternConfig): string {
+  const description = pattern.description?.trim();
+  return description
+    ? `Command auto-denied: ${description}`
+    : "Command matched auto-deny pattern and was blocked automatically.";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-guardrails",
-  "version": "0.11.2",
+  "version": "0.12.1",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -17,7 +17,9 @@
   },
   "pi": {
     "extensions": [
-      "./src/index.ts"
+      "./extensions/path-access/index.ts",
+      "./extensions/guardrails/index.ts",
+      "./extensions/permission-gate/index.ts"
     ],
     "video": "https://assets.aliou.me/pi-extensions/demos/pi-guardrails.mp4"
   },
@@ -26,48 +28,44 @@
   },
   "files": [
     "src",
-    "docs",
-    "README.md"
+    "extensions",
+    "README.md",
+    "schema.json"
   ],
   "dependencies": {
-    "@aliou/pi-utils-settings": "^0.11.2",
+    "@aliou/pi-utils-settings": "^0.15.1",
     "@aliou/sh": "^0.1.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-agent-core": "0.61.0",
-    "@mariozechner/pi-ai": "0.61.0",
-    "@mariozechner/pi-coding-agent": "0.61.0",
-    "@mariozechner/pi-tui": "0.61.0"
+    "@earendil-works/pi-coding-agent": "0.74.0",
+    "@earendil-works/pi-tui": "0.74.0"
   },
   "devDependencies": {
     "@aliou/biome-plugins": "^0.3.2",
     "@biomejs/biome": "^2.3.13",
     "@changesets/cli": "^2.27.11",
-    "@mariozechner/pi-agent-core": "0.61.0",
-    "@mariozechner/pi-ai": "0.61.0",
-    "@mariozechner/pi-coding-agent": "0.61.0",
+    "@earendil-works/pi-coding-agent": "0.74.0",
+    "@earendil-works/pi-tui": "0.74.0",
     "@sinclair/typebox": "^0.34.48",
     "@types/node": "^25.0.10",
     "husky": "^9.1.7",
+    "memfs": "^4.57.2",
+    "ts-json-schema-generator": "^2.9.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.4"
   },
   "peerDependenciesMeta": {
-    "@mariozechner/pi-agent-core": {
+    "@earendil-works/pi-coding-agent": {
       "optional": true
     },
-    "@mariozechner/pi-ai": {
-      "optional": true
-    },
-    "@mariozechner/pi-coding-agent": {
-      "optional": true
-    },
-    "@mariozechner/pi-tui": {
+    "@earendil-works/pi-tui": {
       "optional": true
     }
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
+    "gen:schema": "ts-json-schema-generator --path src/shared/config/types.ts --type GuardrailsConfig --no-type-check -o schema.json",
+    "check:schema": "ts-json-schema-generator --path src/shared/config/types.ts --type GuardrailsConfig --no-type-check -o /tmp/pi-guardrails-schema-check.json && diff -q schema.json /tmp/pi-guardrails-schema-check.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "biome check",