@aliou/pi-guardrails 0.2.1 → 0.3.0

package/README.md

@@ -35,15 +35,164 @@ pi install npm:@aliou/pi-guardrails
 
 ## Features
 
-- **prevent-brew**: Blocks Homebrew commands (project uses Nix)
+- **prevent-brew**: Blocks Homebrew commands (disabled by default)
 - **protect-env-files**: Prevents access to `.env` files (except `.example`/`.sample`/`.test`)
 - **permission-gate**: Prompts for confirmation on dangerous commands
 
+## Configuration
+
+Configuration is loaded from two optional JSON files, merged in order (project overrides global):
+
+- **Global**: `~/.pi/agent/extensions/guardrails.json`
+- **Project**: `.pi/extensions/guardrails.json`
+
+### Settings Command
+
+Run `/guardrails:settings` to open an interactive settings UI with two tabs:
+- **Local**: edit project-scoped config (`.pi/extensions/guardrails.json`)
+- **Global**: edit global config (`~/.pi/agent/extensions/guardrails.json`)
+
+Use `Tab` / `Shift+Tab` to switch tabs. Boolean settings can be toggled directly. Array/object settings (patterns, tools) require manual JSON editing.
+
+### Configuration Schema
+
+```json
+{
+  "enabled": true,
+  "features": {
+    "preventBrew": false,
+    "protectEnvFiles": true,
+    "permissionGate": true
+  },
+  "envFiles": {
+    "protectedPatterns": ["\\.env$", "\\.env\\.local$"],
+    "allowedPatterns": [
+      "\\.(example|sample|test)\\.env$",
+      "\\.env\\.(example|sample|test)$"
+    ],
+    "protectedDirectories": [],
+    "protectedTools": ["read", "write", "edit", "bash", "grep", "find", "ls"],
+    "onlyBlockIfExists": true,
+    "blockMessage": "Accessing {file} is not allowed. ..."
+  },
+  "permissionGate": {
+    "patterns": [
+      { "pattern": "rm\\s+-rf", "description": "recursive force delete" }
+    ],
+    "customPatterns": [],
+    "requireConfirmation": true,
+    "allowedPatterns": [],
+    "autoDenyPatterns": []
+  }
+}
+```
+
+All fields are optional. Missing fields use defaults shown above.
+
+### Configuration Details
+
+#### `features`
+
+| Key | Default | Description |
+|---|---|---|
+| `preventBrew` | `false` | Block Homebrew install/upgrade commands |
+| `protectEnvFiles` | `true` | Block access to `.env` files containing secrets |
+| `permissionGate` | `true` | Prompt for confirmation on dangerous commands |
+
+#### `envFiles`
+
+| Key | Default | Description |
+|---|---|---|
+| `protectedPatterns` | `["\\.env$", "\\.env\\.local$"]` | Regex patterns for files to protect |
+| `allowedPatterns` | `["\\.(example\|sample\|test)\\.env$", ...]` | Regex patterns for allowed exceptions |
+| `protectedDirectories` | `[]` | Regex patterns for directories to protect |
+| `protectedTools` | `["read", "write", "edit", "bash", "grep", "find", "ls"]` | Tools to intercept |
+| `onlyBlockIfExists` | `true` | Only block if the file exists on disk |
+| `blockMessage` | See defaults | Message shown when blocked. Supports `{file}` placeholder |
+
+#### `permissionGate`
+
+| Key | Default | Description |
+|---|---|---|
+| `patterns` | See defaults | Array of `{ pattern, description }` for dangerous commands |
+| `customPatterns` | Not set | If set, replaces `patterns` entirely |
+| `requireConfirmation` | `true` | Show confirmation dialog (if `false`, just warns) |
+| `allowedPatterns` | `[]` | Regex patterns that bypass the gate |
+| `autoDenyPatterns` | `[]` | Regex patterns that are blocked immediately without dialog |
+
+### Examples
+
+Enable `prevent-brew` for a project using Nix:
+
+```json
+{
+  "features": {
+    "preventBrew": true
+  }
+}
+```
+
+Add a custom dangerous command pattern:
+
+```json
+{
+  "permissionGate": {
+    "patterns": [
+      { "pattern": "rm\\s+-rf", "description": "recursive force delete" },
+      { "pattern": "\\bsudo\\b", "description": "superuser command" },
+      { "pattern": "docker\\s+system\\s+prune", "description": "docker system prune" }
+    ]
+  }
+}
+```
+
+Auto-deny certain commands:
+
+```json
+{
+  "permissionGate": {
+    "autoDenyPatterns": ["rm\\s+-rf\\s+/(?!tmp)"]
+  }
+}
+```
+
+## Events
+
+The extension emits events on the pi event bus for inter-extension communication.
+
+### `guardrails:blocked`
+
+Emitted when a tool call is blocked by any guardrail.
+
+```typescript
+interface GuardrailsBlockedEvent {
+  feature: "preventBrew" | "protectEnvFiles" | "permissionGate";
+  toolName: string;
+  input: Record<string, unknown>;
+  reason: string;
+  userDenied?: boolean;
+}
+```
+
+### `guardrails:dangerous`
+
+Emitted when a dangerous command is detected (before the confirmation dialog).
+
+```typescript
+interface GuardrailsDangerousEvent {
+  command: string;
+  description: string;
+  pattern: string;
+}
+```
+
+The [presenter extension](../presenter) listens for `guardrails:dangerous` events and plays a notification sound.
+
 ## Hooks
 
 ### prevent-brew
 
-Blocks bash commands that attempt to install packages using Homebrew. Notifies the user that the project uses Nix for package management.
+Blocks bash commands that attempt to install packages using Homebrew. Disabled by default. Enable via config if your project uses Nix.
 
 Blocked patterns:
 - `brew install`
@@ -62,7 +211,7 @@ Prevents accessing `.env` files that might contain secrets. Only allows access t
 - `*.sample.env`
 - `*.test.env`
 
-Covers tools: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`
+Covers tools: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls` (configurable).
 
 ### permission-gate
 
@@ -74,3 +223,5 @@ Prompts user confirmation before executing dangerous commands:
 - `mkfs.` (filesystem format)
 - `chmod -R 777` (insecure recursive permissions)
 - `chown -R` (recursive ownership change)
+
+All patterns are configurable. Supports allow-lists and auto-deny lists.

package/array-editor.ts

@@ -0,0 +1,213 @@
+import type { Component, SettingsListTheme } from "@mariozechner/pi-tui";
+import {
+  Input,
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+} from "@mariozechner/pi-tui";
+
+/**
+ * A submenu component for editing string arrays inside a SettingsList.
+ *
+ * Modes:
+ * - list: navigate items, delete with 'd', add with 'a', edit with 'e'/Enter
+ * - add: text input for new item, confirm with Enter, cancel with Escape
+ * - edit: text input pre-filled with current value, Enter saves, Escape cancels
+ */
+
+export interface ArrayEditorOptions {
+  label: string;
+  items: string[];
+  theme: SettingsListTheme;
+  onSave: (items: string[]) => void;
+  onDone: () => void;
+  /** Max visible items before scrolling */
+  maxVisible?: number;
+}
+
+export class ArrayEditor implements Component {
+  private items: string[];
+  private label: string;
+  private theme: SettingsListTheme;
+  private onSave: (items: string[]) => void;
+  private onDone: () => void;
+  private selectedIndex = 0;
+  private maxVisible: number;
+  private mode: "list" | "add" | "edit" = "list";
+  private input: Input;
+  private editIndex = -1;
+
+  constructor(options: ArrayEditorOptions) {
+    this.items = [...options.items];
+    this.label = options.label;
+    this.theme = options.theme;
+    this.onSave = options.onSave;
+    this.onDone = options.onDone;
+    this.maxVisible = options.maxVisible ?? 10;
+    this.input = new Input();
+    this.input.onSubmit = (value: string) => {
+      if (this.mode === "edit") {
+        this.submitEdit(value);
+      } else {
+        this.submitAdd(value);
+      }
+    };
+    this.input.onEscape = () => {
+      this.mode = "list";
+      this.editIndex = -1;
+    };
+  }
+
+  private submitAdd(value: string) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      this.mode = "list";
+      return;
+    }
+    this.items.push(trimmed);
+    this.selectedIndex = this.items.length - 1;
+    this.save();
+    this.mode = "list";
+    this.input.setValue("");
+  }
+
+  private submitEdit(value: string) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      // Empty value = cancel edit
+      this.mode = "list";
+      this.editIndex = -1;
+      return;
+    }
+    this.items[this.editIndex] = trimmed;
+    this.save();
+    this.mode = "list";
+    this.editIndex = -1;
+    this.input.setValue("");
+  }
+
+  private deleteSelected() {
+    if (this.items.length === 0) return;
+    this.items.splice(this.selectedIndex, 1);
+    if (this.selectedIndex >= this.items.length) {
+      this.selectedIndex = Math.max(0, this.items.length - 1);
+    }
+    this.save();
+  }
+
+  private startEdit() {
+    if (this.items.length === 0) return;
+    this.editIndex = this.selectedIndex;
+    this.mode = "edit";
+    this.input.setValue(this.items[this.selectedIndex] as string);
+  }
+
+  private save() {
+    this.onSave([...this.items]);
+  }
+
+  invalidate() {}
+
+  render(width: number): string[] {
+    const lines: string[] = [];
+
+    // Header
+    lines.push(this.theme.label(` ${this.label}`, true));
+    lines.push("");
+
+    if (this.mode === "add" || this.mode === "edit") {
+      return [...lines, ...this.renderInputMode(width)];
+    }
+
+    return [...lines, ...this.renderListMode(width)];
+  }
+
+  private renderListMode(width: number): string[] {
+    const lines: string[] = [];
+
+    if (this.items.length === 0) {
+      lines.push(this.theme.hint("  (empty)"));
+    } else {
+      const startIndex = Math.max(
+        0,
+        Math.min(
+          this.selectedIndex - Math.floor(this.maxVisible / 2),
+          this.items.length - this.maxVisible,
+        ),
+      );
+      const endIndex = Math.min(
+        startIndex + this.maxVisible,
+        this.items.length,
+      );
+
+      for (let i = startIndex; i < endIndex; i++) {
+        const item = this.items[i];
+        if (!item) continue;
+        const isSelected = i === this.selectedIndex;
+        const prefix = isSelected ? this.theme.cursor : "  ";
+        const prefixWidth = visibleWidth(prefix);
+        const maxItemWidth = width - prefixWidth - 2;
+        const text = this.theme.value(
+          truncateToWidth(item, maxItemWidth, ""),
+          isSelected,
+        );
+        lines.push(prefix + text);
+      }
+
+      if (startIndex > 0 || endIndex < this.items.length) {
+        lines.push(
+          this.theme.hint(`  (${this.selectedIndex + 1}/${this.items.length})`),
+        );
+      }
+    }
+
+    lines.push("");
+    lines.push(
+      this.theme.hint("  a: add · e/Enter: edit · d: delete · Esc: back"),
+    );
+
+    return lines;
+  }
+
+  private renderInputMode(width: number): string[] {
+    const lines: string[] = [];
+    const label = this.mode === "edit" ? "  Edit item:" : "  New item:";
+    lines.push(this.theme.hint(label));
+    lines.push(`  ${this.input.render(width - 4).join("")}`);
+    lines.push("");
+    lines.push(this.theme.hint("  Enter: confirm · Esc: cancel"));
+    return lines;
+  }
+
+  handleInput(data: string) {
+    if (this.mode === "add" || this.mode === "edit") {
+      this.input.handleInput(data);
+      return;
+    }
+
+    // List mode
+    if (matchesKey(data, Key.up) || data === "k") {
+      if (this.items.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === 0
+          ? this.items.length - 1
+          : this.selectedIndex - 1;
+    } else if (matchesKey(data, Key.down) || data === "j") {
+      if (this.items.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === this.items.length - 1
+          ? 0
+          : this.selectedIndex + 1;
+    } else if (data === "a" || data === "A") {
+      this.mode = "add";
+      this.input.setValue("");
+    } else if (data === "e" || data === "E" || matchesKey(data, Key.enter)) {
+      this.startEdit();
+    } else if (data === "d" || data === "D") {
+      this.deleteSelected();
+    } else if (matchesKey(data, Key.escape)) {
+      this.onDone();
+    }
+  }
+}

package/config-schema.ts

@@ -0,0 +1,54 @@
+/**
+ * Configuration schema for the guardrails extension.
+ *
+ * GuardrailsConfig is the user-facing schema (all fields optional).
+ * ResolvedConfig is the internal schema (all fields required, defaults applied).
+ */
+
+export interface GuardrailsConfig {
+  enabled?: boolean;
+  features?: {
+    preventBrew?: boolean;
+    protectEnvFiles?: boolean;
+    permissionGate?: boolean;
+  };
+  envFiles?: {
+    protectedPatterns?: string[];
+    allowedPatterns?: string[];
+    protectedDirectories?: string[];
+    protectedTools?: string[];
+    onlyBlockIfExists?: boolean;
+    blockMessage?: string;
+  };
+  permissionGate?: {
+    patterns?: Array<{ pattern: string; description: string }>;
+    /** If set, replaces the default patterns entirely. */
+    customPatterns?: Array<{ pattern: string; description: string }>;
+    requireConfirmation?: boolean;
+    allowedPatterns?: string[];
+    autoDenyPatterns?: string[];
+  };
+}
+
+export interface ResolvedConfig {
+  enabled: boolean;
+  features: {
+    preventBrew: boolean;
+    protectEnvFiles: boolean;
+    permissionGate: boolean;
+  };
+  envFiles: {
+    protectedPatterns: string[];
+    allowedPatterns: string[];
+    protectedDirectories: string[];
+    protectedTools: string[];
+    onlyBlockIfExists: boolean;
+    blockMessage: string;
+  };
+  permissionGate: {
+    patterns: Array<{ pattern: string; description: string }>;
+    requireConfirmation: boolean;
+    allowedPatterns: string[];
+    autoDenyPatterns: string[];
+  };
+}

package/config.ts

@@ -0,0 +1,160 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import type { GuardrailsConfig, ResolvedConfig } from "./config-schema";
+
+const GLOBAL_CONFIG_PATH = resolve(
+  homedir(),
+  ".pi/agent/extensions/guardrails.json",
+);
+const PROJECT_CONFIG_PATH = resolve(
+  process.cwd(),
+  ".pi/extensions/guardrails.json",
+);
+
+const DEFAULT_CONFIG: ResolvedConfig = {
+  enabled: true,
+  features: {
+    preventBrew: false,
+    protectEnvFiles: true,
+    permissionGate: true,
+  },
+  envFiles: {
+    protectedPatterns: ["\\.env$", "\\.env\\.local$"],
+    allowedPatterns: [
+      "\\.(example|sample|test)\\.env$",
+      "\\.env\\.(example|sample|test)$",
+    ],
+    protectedDirectories: [],
+    protectedTools: ["read", "write", "edit", "bash", "grep", "find", "ls"],
+    onlyBlockIfExists: true,
+    blockMessage:
+      "Accessing {file} is not allowed. Environment files containing secrets are protected. " +
+      "Explain to the user why you want to access this .env file, and if changes are needed ask the user to make them. " +
+      "Only .env.example, .env.sample, or .env.test files can be accessed.",
+  },
+  permissionGate: {
+    patterns: [
+      { pattern: "rm\\s+-rf", description: "recursive force delete" },
+      { pattern: "\\bsudo\\b", description: "superuser command" },
+      { pattern: ":\\s*\\|\\s*sh", description: "piped shell execution" },
+      { pattern: "\\bdd\\s+if=", description: "disk write operation" },
+      { pattern: "mkfs\\.", description: "filesystem format" },
+      {
+        pattern: "\\bchmod\\s+-R\\s+777",
+        description: "insecure recursive permissions",
+      },
+      {
+        pattern: "\\bchown\\s+-R",
+        description: "recursive ownership change",
+      },
+    ],
+    requireConfirmation: true,
+    allowedPatterns: [],
+    autoDenyPatterns: [],
+  },
+};
+
+class ConfigLoader {
+  private globalConfig: GuardrailsConfig | null = null;
+  private projectConfig: GuardrailsConfig | null = null;
+  private resolved: ResolvedConfig | null = null;
+
+  async load(): Promise<void> {
+    this.globalConfig = await this.loadConfigFile(GLOBAL_CONFIG_PATH);
+    this.projectConfig = await this.loadConfigFile(PROJECT_CONFIG_PATH);
+    this.resolved = this.mergeConfigs();
+  }
+
+  private async loadConfigFile(path: string): Promise<GuardrailsConfig | null> {
+    try {
+      const content = await readFile(path, "utf-8");
+      return JSON.parse(content) as GuardrailsConfig;
+    } catch {
+      return null;
+    }
+  }
+
+  private mergeConfigs(): ResolvedConfig {
+    const merged = structuredClone(DEFAULT_CONFIG);
+
+    if (this.globalConfig) {
+      this.mergeInto(merged, this.globalConfig);
+    }
+    if (this.projectConfig) {
+      this.mergeInto(merged, this.projectConfig);
+    }
+
+    // customPatterns replaces entire patterns array
+    if (this.projectConfig?.permissionGate?.customPatterns) {
+      merged.permissionGate.patterns =
+        this.projectConfig.permissionGate.customPatterns;
+    } else if (this.globalConfig?.permissionGate?.customPatterns) {
+      merged.permissionGate.patterns =
+        this.globalConfig.permissionGate.customPatterns;
+    }
+
+    return merged;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private mergeInto(target: any, source: any): void {
+    for (const key in source) {
+      if (source[key] === undefined) continue;
+
+      if (
+        typeof source[key] === "object" &&
+        !Array.isArray(source[key]) &&
+        source[key] !== null
+      ) {
+        if (!target[key]) target[key] = {};
+        this.mergeInto(target[key], source[key]);
+      } else {
+        target[key] = source[key];
+      }
+    }
+  }
+
+  getConfig(): ResolvedConfig {
+    if (!this.resolved) {
+      throw new Error("Config not loaded. Call load() first.");
+    }
+    return this.resolved;
+  }
+
+  async saveGlobal(config: GuardrailsConfig): Promise<void> {
+    await this.saveConfigFile(GLOBAL_CONFIG_PATH, config);
+    await this.load();
+  }
+
+  async saveProject(config: GuardrailsConfig): Promise<void> {
+    await this.saveConfigFile(PROJECT_CONFIG_PATH, config);
+    await this.load();
+  }
+
+  private async saveConfigFile(
+    path: string,
+    config: GuardrailsConfig,
+  ): Promise<void> {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(config, null, 2) + "\n", "utf-8");
+  }
+
+  hasGlobalConfig(): boolean {
+    return this.globalConfig !== null;
+  }
+
+  hasProjectConfig(): boolean {
+    return this.projectConfig !== null;
+  }
+
+  getGlobalConfig(): GuardrailsConfig {
+    return this.globalConfig ?? {};
+  }
+
+  getProjectConfig(): GuardrailsConfig {
+    return this.projectConfig ?? {};
+  }
+}
+
+export const configLoader = new ConfigLoader();

package/events.ts

@@ -0,0 +1,32 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export const GUARDRAILS_BLOCKED_EVENT = "guardrails:blocked";
+export const GUARDRAILS_DANGEROUS_EVENT = "guardrails:dangerous";
+
+export interface GuardrailsBlockedEvent {
+  feature: "preventBrew" | "protectEnvFiles" | "permissionGate";
+  toolName: string;
+  input: Record<string, unknown>;
+  reason: string;
+  userDenied?: boolean;
+}
+
+export interface GuardrailsDangerousEvent {
+  command: string;
+  description: string;
+  pattern: string;
+}
+
+export function emitBlocked(
+  pi: ExtensionAPI,
+  event: GuardrailsBlockedEvent,
+): void {
+  pi.events.emit(GUARDRAILS_BLOCKED_EVENT, event);
+}
+
+export function emitDangerous(
+  pi: ExtensionAPI,
+  event: GuardrailsDangerousEvent,
+): void {
+  pi.events.emit(GUARDRAILS_DANGEROUS_EVENT, event);
+}

package/hooks/index.ts

@@ -1,10 +1,11 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ResolvedConfig } from "../config-schema";
 import { setupPermissionGateHook } from "./permission-gate";
 import { setupPreventBrewHook } from "./prevent-brew";
 import { setupProtectEnvFilesHook } from "./protect-env-files";
 
-export function setupGuardrailsHooks(pi: ExtensionAPI) {
-  setupPreventBrewHook(pi);
-  setupProtectEnvFilesHook(pi);
-  setupPermissionGateHook(pi);
+export function setupGuardrailsHooks(pi: ExtensionAPI, config: ResolvedConfig) {
+  setupPreventBrewHook(pi, config);
+  setupProtectEnvFilesHook(pi, config);
+  setupPermissionGateHook(pi, config);
 }