@aliou/pi-guardrails 0.5.4 → 0.6.1

package/README.md

@@ -35,11 +35,12 @@ pi install npm:@aliou/pi-guardrails
 
 ## Features
 
-- **prevent-brew**: Blocks Homebrew commands (disabled by default)
-- **prevent-python**: Blocks Python/pip/poetry commands, suggests uv instead (disabled by default)
 - **protect-env-files**: Prevents access to `.env` files (except `.example`/`.sample`/`.test`)
 - **permission-gate**: Prompts for confirmation on dangerous commands
-- **enforce-package-manager**: Enforces a specific Node package manager (npm, pnpm, or bun) (disabled by default)
+
+All hooks use structural shell parsing via `@aliou/sh` to avoid false positives from keywords inside commit messages, grep patterns, heredocs, or file paths. On parse failure, each hook falls back to regex matching (previous behavior).
+
+> **Migration note**: The `preventBrew`, `preventPython`, `enforcePackageManager`, and `packageManager` fields have been removed from guardrails and moved to the [`@aliou/pi-toolchain`](../toolchain) extension. Old configs containing these fields are auto-cleaned on first load with a one-time warning. Install `@aliou/pi-toolchain` and configure `.pi/extensions/toolchain.json` instead.
 
 ## Configuration
 
@@ -54,28 +55,35 @@ 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.
+Use `Tab` / `Shift+Tab` to switch tabs. Boolean settings can be toggled directly.
+
+### Migration from v0
+
+Configs without a `version` field are automatically migrated on first load. The migration:
+- Backs up the original as `guardrails.v0.json`
+- Converts all string patterns to `{ pattern, regex: true }` to preserve behavior
+- Adds a `version` field
 
 ### Configuration Schema
 
 ```json
 {
+  "version": "0.7.0-20260204",
   "enabled": true,
   "features": {
-    "preventBrew": false,
-    "preventPython": false,
     "protectEnvFiles": true,
-    "permissionGate": true,
-    "enforcePackageManager": false
-  },
-  "packageManager": {
-    "selected": "npm"
+    "permissionGate": true
   },
   "envFiles": {
-    "protectedPatterns": ["\\.env$", "\\.env\\.local$"],
+    "protectedPatterns": [
+      { "pattern": ".env" },
+      { "pattern": ".env.local" },
+      { "pattern": ".env.production" }
+    ],
     "allowedPatterns": [
-      "\\.(example|sample|test)\\.env$",
-      "\\.env\\.(example|sample|test)$"
+      { "pattern": ".env.example" },
+      { "pattern": ".env.sample" },
+      { "pattern": "*.example.env" }
     ],
     "protectedDirectories": [],
     "protectedTools": ["read", "write", "edit", "bash", "grep", "find", "ls"],
@@ -84,7 +92,8 @@ Use `Tab` / `Shift+Tab` to switch tabs. Boolean settings can be toggled directly
   },
   "permissionGate": {
     "patterns": [
-      { "pattern": "rm\\s+-rf", "description": "recursive force delete" }
+      { "pattern": "rm -rf", "description": "recursive force delete" },
+      { "pattern": "sudo", "description": "superuser command" }
     ],
     "customPatterns": [],
     "requireConfirmation": true,
@@ -96,31 +105,36 @@ Use `Tab` / `Shift+Tab` to switch tabs. Boolean settings can be toggled directly
 
 All fields are optional. Missing fields use defaults shown above.
 
+### Pattern Format
+
+Patterns support two modes controlled by the `regex` flag:
+
+**File patterns** (envFiles section):
+- Default (`regex` omitted or `false`): glob matching against the filename. `*` matches any non-`/` chars, `?` matches a single char. Example: `.env.*` matches `.env.local`, `.env.production`.
+- `regex: true`: full regex (case-insensitive) against the full path. Example: `{ "pattern": "\\.env$", "regex": true }`.
+
+**Command patterns** (permissionGate section):
+- Default (`regex` omitted or `false`): substring matching against the raw command string. Example: `"rm -rf"` matches any command containing `rm -rf`.
+- `regex: true`: full regex against the raw command string. Example: `{ "pattern": "rm\\s+-rf", "regex": true }`.
+
+Built-in dangerous command patterns (`rm -rf`, `sudo`, `dd if=`, `mkfs.*`, `chmod -R 777`, `chown -R`) are matched structurally via AST parsing, independent of the pattern format.
+
 ### Configuration Details
 
 #### `features`
 
 | Key | Default | Description |
 |---|---|---|
-| `preventBrew` | `false` | Block Homebrew install/upgrade commands |
-| `preventPython` | `false` | Block python/pip/poetry commands (use uv instead) |
 | `protectEnvFiles` | `true` | Block access to `.env` files containing secrets |
 | `permissionGate` | `true` | Prompt for confirmation on dangerous commands |
-| `enforcePackageManager` | `false` | Enforce a specific Node package manager |
-
-#### `packageManager`
-
-| Key | Default | Description |
-|---|---|---|
-| `selected` | `"npm"` | Package manager to enforce: `"npm"`, `"pnpm"`, or `"bun"` |
 
 #### `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 |
+| `protectedPatterns` | `[".env", ".env.local", ...]` | Patterns for files to protect (glob by default) |
+| `allowedPatterns` | `[".env.example", "*.example.env", ...]` | Patterns for allowed exceptions |
+| `protectedDirectories` | `[]` | 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 |
@@ -132,54 +146,47 @@ All fields are optional. Missing fields use defaults shown above.
 | `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 |
+| `allowedPatterns` | `[]` | Patterns that bypass the gate |
+| `autoDenyPatterns` | `[]` | 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:
+Add a custom dangerous command pattern (substring match):
 
 ```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" }
+      { "pattern": "rm -rf", "description": "recursive force delete" },
+      { "pattern": "sudo", "description": "superuser command" },
+      { "pattern": "docker system prune", "description": "docker system prune" }
     ]
   }
 }
 ```
 
-Auto-deny certain commands:
+Add a regex-based pattern:
 
 ```json
 {
   "permissionGate": {
-    "autoDenyPatterns": ["rm\\s+-rf\\s+/(?!tmp)"]
+    "patterns": [
+      { "pattern": "rm\\s+-rf\\s+/(?!tmp)", "description": "rm -rf outside /tmp", "regex": true }
+    ]
   }
 }
 ```
 
-Enforce pnpm as the package manager:
+Protect env files with glob patterns:
 
 ```json
 {
-  "features": {
-    "enforcePackageManager": true
-  },
-  "packageManager": {
-    "selected": "pnpm"
+  "envFiles": {
+    "protectedPatterns": [
+      { "pattern": ".env" },
+      { "pattern": ".env.*" },
+      { "pattern": ".dev.vars" }
+    ]
   }
 }
 ```
@@ -194,7 +201,7 @@ Emitted when a tool call is blocked by any guardrail.
 
 ```typescript
 interface GuardrailsBlockedEvent {
-  feature: "preventBrew" | "preventPython" | "protectEnvFiles" | "permissionGate" | "enforcePackageManager";
+  feature: "protectEnvFiles" | "permissionGate";
   toolName: string;
   input: Record<string, unknown>;
   reason: string;
@@ -218,37 +225,11 @@ The [presenter extension](../presenter) listens for `guardrails:dangerous` event
 
 ## Hooks
 
-### prevent-brew
-
-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`
-- `brew cask install`
-- `brew bundle`
-- `brew upgrade`
-- `brew reinstall`
-
-### prevent-python
-
-Blocks bash commands that use Python tooling directly. Disabled by default. Enable if your project uses uv for Python management.
-
-Blocked patterns:
-- `python`, `python3`
-- `pip`, `pip3`
-- `poetry`
-- `pyenv`
-- `virtualenv`, `venv`
-
 ### protect-env-files
 
-Prevents accessing `.env` files that might contain secrets. Only allows access to safe variants:
-- `.env.example`
-- `.env.sample`
-- `.env.test`
-- `*.example.env`
-- `*.sample.env`
-- `*.test.env`
+Prevents accessing `.env` files that might contain secrets. Only allows access to safe variants like `.env.example`, `.env.sample`, `.env.test`.
+
+Shell globs (e.g. `.env*`) are expanded via `fd` to check if any expanded path matches a protected pattern.
 
 Covers tools: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls` (configurable).
 
@@ -257,21 +238,9 @@ Covers tools: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls` (configurabl
 Prompts user confirmation before executing dangerous commands:
 - `rm -rf` (recursive force delete)
 - `sudo` (superuser command)
-- `: | sh` (piped shell execution)
 - `dd if=` (disk write operation)
 - `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.
-
-### enforce-package-manager
-
-Enforces using a specific Node package manager. Disabled by default. When enabled, blocks commands using non-selected package managers.
-
-Configure via `packageManager.selected`:
-- `"npm"` (default)
-- `"pnpm"`
-- `"bun"`
-
-Example: If `selected` is `"pnpm"`, running `npm install` or `bun add` will be blocked with a message instructing the agent to use `pnpm` instead.
+Built-in patterns are matched structurally (AST-based). Custom patterns use substring or regex matching. Supports allow-lists and auto-deny lists.

package/commands/settings-command.ts

@@ -0,0 +1,278 @@
+import {
+  ArrayEditor,
+  getNestedValue,
+  registerSettingsCommand,
+  type SettingsSection,
+  setNestedValue,
+} from "@aliou/pi-utils-settings";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { getSettingsListTheme } from "@mariozechner/pi-coding-agent";
+import { PatternEditor } from "../components/pattern-editor";
+import type {
+  DangerousPattern,
+  GuardrailsConfig,
+  PatternConfig,
+  ResolvedConfig,
+} from "../config";
+import { configLoader } from "../config";
+
+type FeatureKey = keyof ResolvedConfig["features"];
+
+const FEATURE_UI: Record<FeatureKey, { label: string; description: string }> = {
+  protectEnvFiles: {
+    label: "Protect .env files",
+    description: "Block access to .env files containing secrets",
+  },
+  permissionGate: {
+    label: "Permission gate",
+    description:
+      "Prompt for confirmation on dangerous commands (rm -rf, sudo, etc.)",
+  },
+};
+
+export function registerGuardrailsSettings(pi: ExtensionAPI): void {
+  registerSettingsCommand<GuardrailsConfig, ResolvedConfig>(pi, {
+    commandName: "guardrails:settings",
+    title: "Guardrails Settings",
+    configStore: configLoader,
+    buildSections: (
+      tabConfig: GuardrailsConfig | null,
+      resolved: ResolvedConfig,
+      { setDraft },
+    ): SettingsSection[] => {
+      const settingsTheme = getSettingsListTheme();
+      // --- Helpers ---
+
+      function count(id: string): string {
+        const val =
+          (getNestedValue(tabConfig ?? {}, id) as unknown[] | undefined) ??
+          (getNestedValue(resolved, id) as unknown[]) ??
+          [];
+        return `${val.length} items`;
+      }
+
+      function applyDraft(id: string, value: unknown): void {
+        const updated = structuredClone(tabConfig ?? {}) as GuardrailsConfig;
+        setNestedValue(updated, id, value);
+        setDraft(updated);
+      }
+
+      // --- Submenu factories ---
+
+      function stringArraySubmenu(id: string, label: string) {
+        return (_val: string, submenuDone: (v?: string) => void) => {
+          const items =
+            (getNestedValue(tabConfig ?? {}, id) as string[] | undefined) ??
+            (getNestedValue(resolved, id) as string[]) ??
+            [];
+          let latest = [...items];
+          return new ArrayEditor({
+            label,
+            items: [...items],
+            theme: settingsTheme,
+            onSave: (newItems) => {
+              latest = newItems;
+              applyDraft(id, newItems);
+            },
+            onDone: () => submenuDone(`${latest.length} items`),
+          });
+        };
+      }
+
+      function patternSubmenu(
+        id: string,
+        label: string,
+        context?: "file" | "command",
+      ) {
+        return (_val: string, submenuDone: (v?: string) => void) => {
+          const items =
+            (getNestedValue(tabConfig ?? {}, id) as
+              | DangerousPattern[]
+              | undefined) ??
+            (getNestedValue(resolved, id) as DangerousPattern[]) ??
+            [];
+          let latestCount = items.length;
+          return new PatternEditor({
+            label,
+            items: [...items],
+            theme: settingsTheme,
+            context,
+            onSave: (newItems) => {
+              latestCount = newItems.length;
+              applyDraft(id, newItems);
+            },
+            onDone: () => submenuDone(`${latestCount} items`),
+          });
+        };
+      }
+
+      function patternConfigSubmenu(
+        id: string,
+        label: string,
+        context?: "file" | "command",
+      ) {
+        return (_val: string, submenuDone: (v?: string) => void) => {
+          const currentItems =
+            (getNestedValue(tabConfig ?? {}, id) as
+              | PatternConfig[]
+              | undefined) ??
+            (getNestedValue(resolved, id) as PatternConfig[]) ??
+            [];
+          const items = currentItems.map((p) => ({
+            pattern: p.pattern,
+            description: p.pattern,
+            regex: p.regex,
+          }));
+          let latestCount = items.length;
+          return new PatternEditor({
+            label,
+            items,
+            theme: settingsTheme,
+            context,
+            onSave: (newItems) => {
+              latestCount = newItems.length;
+              const configs: PatternConfig[] = newItems.map((p) => {
+                const cfg: PatternConfig = { pattern: p.pattern };
+                if (p.regex) cfg.regex = true;
+                return cfg;
+              });
+              applyDraft(id, configs);
+            },
+            onDone: () => submenuDone(`${latestCount} items`),
+          });
+        };
+      }
+
+      // --- Sections ---
+
+      const featureItems = (Object.keys(FEATURE_UI) as FeatureKey[]).map(
+        (key) => ({
+          id: `features.${key}`,
+          label: FEATURE_UI[key].label,
+          description: FEATURE_UI[key].description,
+          currentValue:
+            (tabConfig?.features?.[key] ?? resolved.features[key])
+              ? "enabled"
+              : "disabled",
+          values: ["enabled", "disabled"],
+        }),
+      );
+
+      return [
+        { label: "Features", items: featureItems },
+        {
+          label: "Env Files",
+          items: [
+            {
+              id: "envFiles.onlyBlockIfExists",
+              label: "Only block existing files",
+              description:
+                "Only block .env file access if the file exists on disk",
+              currentValue:
+                (tabConfig?.envFiles?.onlyBlockIfExists ??
+                resolved.envFiles.onlyBlockIfExists)
+                  ? "on"
+                  : "off",
+              values: ["on", "off"],
+            },
+            {
+              id: "envFiles.protectedPatterns",
+              label: "Protected patterns",
+              description: "Patterns for files to protect (e.g. .env.local)",
+              currentValue: count("envFiles.protectedPatterns"),
+              submenu: patternConfigSubmenu(
+                "envFiles.protectedPatterns",
+                "Protected Patterns",
+                "file",
+              ),
+            },
+            {
+              id: "envFiles.allowedPatterns",
+              label: "Allowed patterns",
+              description: "Patterns for exceptions (e.g. .env.example)",
+              currentValue: count("envFiles.allowedPatterns"),
+              submenu: patternConfigSubmenu(
+                "envFiles.allowedPatterns",
+                "Allowed Patterns",
+                "file",
+              ),
+            },
+            {
+              id: "envFiles.protectedDirectories",
+              label: "Protected directories",
+              description: "Patterns for directories to protect",
+              currentValue: count("envFiles.protectedDirectories"),
+              submenu: patternConfigSubmenu(
+                "envFiles.protectedDirectories",
+                "Protected Directories",
+                "file",
+              ),
+            },
+            {
+              id: "envFiles.protectedTools",
+              label: "Protected tools",
+              description:
+                "Tools to intercept (read, write, edit, bash, grep, find, ls)",
+              currentValue: count("envFiles.protectedTools"),
+              submenu: stringArraySubmenu(
+                "envFiles.protectedTools",
+                "Protected Tools",
+              ),
+            },
+          ],
+        },
+        {
+          label: "Permission Gate",
+          items: [
+            {
+              id: "permissionGate.requireConfirmation",
+              label: "Require confirmation",
+              description:
+                "Show confirmation dialog for dangerous commands (if off, just warns)",
+              currentValue:
+                (tabConfig?.permissionGate?.requireConfirmation ??
+                resolved.permissionGate.requireConfirmation)
+                  ? "on"
+                  : "off",
+              values: ["on", "off"],
+            },
+            {
+              id: "permissionGate.patterns",
+              label: "Dangerous patterns",
+              description: "Command patterns that trigger the permission gate",
+              currentValue: count("permissionGate.patterns"),
+              submenu: patternSubmenu(
+                "permissionGate.patterns",
+                "Dangerous Patterns",
+                "command",
+              ),
+            },
+            {
+              id: "permissionGate.allowedPatterns",
+              label: "Allowed commands",
+              description: "Patterns that bypass the permission gate entirely",
+              currentValue: count("permissionGate.allowedPatterns"),
+              submenu: patternConfigSubmenu(
+                "permissionGate.allowedPatterns",
+                "Allowed Commands",
+                "command",
+              ),
+            },
+            {
+              id: "permissionGate.autoDenyPatterns",
+              label: "Auto-deny patterns",
+              description:
+                "Patterns that block commands immediately without dialog",
+              currentValue: count("permissionGate.autoDenyPatterns"),
+              submenu: patternConfigSubmenu(
+                "permissionGate.autoDenyPatterns",
+                "Auto-Deny Patterns",
+                "command",
+              ),
+            },
+          ],
+        },
+      ];
+    },
+  });
+}