@aliou/pi-guardrails 0.5.3 → 0.6.0

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/config-schema.ts

@@ -5,60 +5,72 @@
  * ResolvedConfig is the internal schema (all fields required, defaults applied).
  */
 
+/**
+ * A pattern with explicit matching mode.
+ * Default: glob for files, substring for commands.
+ * regex: true means full regex matching.
+ */
+export interface PatternConfig {
+  pattern: string;
+  regex?: boolean;
+}
+
+/**
+ * Permission gate pattern. When regex is false (default), the pattern
+ * is matched as substring against the raw command string.
+ * When regex is true, uses full regex against the raw string.
+ */
+export interface DangerousPattern extends PatternConfig {
+  description: string;
+}
+
 export interface GuardrailsConfig {
+  version?: string;
   enabled?: boolean;
   features?: {
-    preventBrew?: boolean;
-    preventPython?: boolean;
     protectEnvFiles?: boolean;
     permissionGate?: boolean;
-    enforcePackageManager?: boolean;
-  };
-  packageManager?: {
-    selected?: "bun" | "pnpm" | "npm";
   };
   envFiles?: {
-    protectedPatterns?: string[];
-    allowedPatterns?: string[];
-    protectedDirectories?: string[];
+    protectedPatterns?: PatternConfig[];
+    allowedPatterns?: PatternConfig[];
+    protectedDirectories?: PatternConfig[];
     protectedTools?: string[];
     onlyBlockIfExists?: boolean;
     blockMessage?: string;
   };
   permissionGate?: {
-    patterns?: Array<{ pattern: string; description: string }>;
+    patterns?: DangerousPattern[];
     /** If set, replaces the default patterns entirely. */
-    customPatterns?: Array<{ pattern: string; description: string }>;
+    customPatterns?: DangerousPattern[];
     requireConfirmation?: boolean;
-    allowedPatterns?: string[];
-    autoDenyPatterns?: string[];
+    allowedPatterns?: PatternConfig[];
+    autoDenyPatterns?: PatternConfig[];
   };
 }
 
 export interface ResolvedConfig {
+  version: string;
   enabled: boolean;
   features: {
-    preventBrew: boolean;
-    preventPython: boolean;
     protectEnvFiles: boolean;
     permissionGate: boolean;
-    enforcePackageManager: boolean;
-  };
-  packageManager: {
-    selected: "bun" | "pnpm" | "npm";
   };
   envFiles: {
-    protectedPatterns: string[];
-    allowedPatterns: string[];
-    protectedDirectories: string[];
+    protectedPatterns: PatternConfig[];
+    allowedPatterns: PatternConfig[];
+    protectedDirectories: PatternConfig[];
     protectedTools: string[];
     onlyBlockIfExists: boolean;
     blockMessage: string;
   };
   permissionGate: {
-    patterns: Array<{ pattern: string; description: string }>;
+    patterns: DangerousPattern[];
+    /** When true, use hardcoded structural matchers for built-in patterns.
+     *  Set to false when customPatterns replaces the defaults. */
+    useBuiltinMatchers: boolean;
     requireConfirmation: boolean;
-    allowedPatterns: string[];
-    autoDenyPatterns: string[];
+    allowedPatterns: PatternConfig[];
+    autoDenyPatterns: PatternConfig[];
   };
 }

package/config.ts

@@ -1,40 +1,98 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
+import { ConfigLoader, type Migration } from "@aliou/pi-utils-settings";
 import type { GuardrailsConfig, ResolvedConfig } from "./config-schema";
+import {
+  backupConfig,
+  CURRENT_VERSION,
+  migrateV0,
+  needsMigration,
+} from "./migration";
+
+/**
+ * Config fields removed in the toolchain extraction.
+ * Old configs containing these are auto-cleaned on first load.
+ */
+const REMOVED_FEATURE_KEYS = [
+  "preventBrew",
+  "preventPython",
+  "enforcePackageManager",
+] as const;
+
+const TOOLCHAIN_MIGRATION_VERSION = "0.7.0-20260204";
+
+function hasRemovedFields(config: GuardrailsConfig): boolean {
+  const raw = config as Record<string, unknown>;
+  const features = raw.features as Record<string, unknown> | undefined;
+  if (features) {
+    for (const key of REMOVED_FEATURE_KEYS) {
+      if (key in features) return true;
+    }
+  }
+  return "packageManager" in raw;
+}
 
-const GLOBAL_CONFIG_PATH = resolve(
-  homedir(),
-  ".pi/agent/extensions/guardrails.json",
-);
-const PROJECT_CONFIG_PATH = resolve(
-  process.cwd(),
-  ".pi/extensions/guardrails.json",
-);
+function stripRemovedFields(config: GuardrailsConfig): GuardrailsConfig {
+  const cleaned = structuredClone(config) as Record<string, unknown>;
+  const features = cleaned.features as Record<string, unknown> | undefined;
+  if (features) {
+    for (const key of REMOVED_FEATURE_KEYS) {
+      delete features[key];
+    }
+  }
+  delete cleaned.packageManager;
+  cleaned.version = TOOLCHAIN_MIGRATION_VERSION;
+  return cleaned as GuardrailsConfig;
+}
+
+const migrations: Migration<GuardrailsConfig>[] = [
+  {
+    name: "v0-format-upgrade",
+    shouldRun: (config) => needsMigration(config),
+    run: async (config, filePath) => {
+      await backupConfig(filePath);
+      return migrateV0(config);
+    },
+  },
+  {
+    name: "strip-toolchain-fields",
+    shouldRun: (config) => hasRemovedFields(config),
+    run: (config) => {
+      const version = (config as Record<string, unknown>).version as
+        | string
+        | undefined;
+      if (!version || version < TOOLCHAIN_MIGRATION_VERSION) {
+        console.error(
+          "[guardrails] preventBrew, preventPython, enforcePackageManager, and packageManager " +
+            "have been removed from guardrails and moved to @aliou/pi-toolchain. " +
+            "These fields will be stripped from your config.",
+        );
+      }
+      return stripRemovedFields(config);
+    },
+  },
+];
 
 const DEFAULT_CONFIG: ResolvedConfig = {
+  version: CURRENT_VERSION,
   enabled: true,
   features: {
-    preventBrew: false,
-    preventPython: false,
     protectEnvFiles: true,
     permissionGate: true,
-    enforcePackageManager: false,
-  },
-  packageManager: {
-    selected: "npm",
   },
   envFiles: {
     protectedPatterns: [
-      "\\.env$",
-      "\\.env\\.local$",
-      "\\.env\\.production$",
-      "\\.env\\.prod$",
-      "\\.dev\\.vars$",
+      { pattern: ".env" },
+      { pattern: ".env.local" },
+      { pattern: ".env.production" },
+      { pattern: ".env.prod" },
+      { pattern: ".dev.vars" },
     ],
     allowedPatterns: [
-      "\\.(example|sample|test)\\.env$",
-      "\\.env\\.(example|sample|test)$",
+      { pattern: "*.example.env" },
+      { pattern: "*.sample.env" },
+      { pattern: "*.test.env" },
+      { pattern: ".env.example" },
+      { pattern: ".env.sample" },
+      { pattern: ".env.test" },
     ],
     protectedDirectories: [],
     protectedTools: ["read", "write", "edit", "bash", "grep", "find", "ls"],
@@ -46,131 +104,40 @@ const DEFAULT_CONFIG: ResolvedConfig = {
   },
   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: "rm -rf", description: "recursive force delete" },
+      { pattern: "sudo", description: "superuser command" },
+      { pattern: "dd if=", description: "disk write operation" },
+      { pattern: "mkfs.", description: "filesystem format" },
       {
-        pattern: "\\bchmod\\s+-R\\s+777",
+        pattern: "chmod -R 777",
         description: "insecure recursive permissions",
       },
-      {
-        pattern: "\\bchown\\s+-R",
-        description: "recursive ownership change",
-      },
+      { pattern: "chown -R", description: "recursive ownership change" },
     ],
+    useBuiltinMatchers: true,
     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;
-  }
-
-  private mergeInto<TTarget extends object, TSource extends object>(
-    target: TTarget,
-    source: TSource,
-  ): void {
-    const t = target as Record<string, unknown>;
-    const s = source as Record<string, unknown>;
-
-    for (const key in s) {
-      if (s[key] === undefined) continue;
-
-      if (
-        typeof s[key] === "object" &&
-        !Array.isArray(s[key]) &&
-        s[key] !== null
-      ) {
-        if (!t[key]) t[key] = {};
-        this.mergeInto(t[key] as object, s[key] as object);
-      } else {
-        t[key] = s[key];
+export const configLoader = new ConfigLoader<GuardrailsConfig, ResolvedConfig>(
+  "guardrails",
+  DEFAULT_CONFIG,
+  {
+    migrations,
+    afterMerge: (resolved, global, project) => {
+      // customPatterns replaces the entire patterns array and disables
+      // built-in structural matchers (user owns all matching).
+      if (project?.permissionGate?.customPatterns) {
+        resolved.permissionGate.patterns =
+          project.permissionGate.customPatterns;
+        resolved.permissionGate.useBuiltinMatchers = false;
+      } else if (global?.permissionGate?.customPatterns) {
+        resolved.permissionGate.patterns = global.permissionGate.customPatterns;
+        resolved.permissionGate.useBuiltinMatchers = false;
       }
-    }
-  }
-
-  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();
+      return resolved;
+    },
+  },
+);

package/events.ts

@@ -4,12 +4,7 @@ export const GUARDRAILS_BLOCKED_EVENT = "guardrails:blocked";
 export const GUARDRAILS_DANGEROUS_EVENT = "guardrails:dangerous";
 
 export interface GuardrailsBlockedEvent {
-  feature:
-    | "preventBrew"
-    | "preventPython"
-    | "protectEnvFiles"
-    | "permissionGate"
-    | "enforcePackageManager";
+  feature: "protectEnvFiles" | "permissionGate";
   toolName: string;
   input: Record<string, unknown>;
   reason: string;