@aliou/pi-guardrails 0.5.3 → 0.6.0

package/hooks/protect-env-files.ts

@@ -1,14 +1,19 @@
 import { stat } from "node:fs/promises";
 import { resolve } from "node:path";
+import { parse } from "@aliou/sh";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { ResolvedConfig } from "../config-schema";
 import { emitBlocked } from "../events";
+import { expandGlob, hasGlobChars } from "../glob-expander";
+import { type CompiledPattern, compileFilePatterns } from "../matching";
+import { walkCommands, wordToString } from "../shell-utils";
 
 /**
  * Prevents accessing .env files unless they match an allowed pattern.
  * Protects sensitive environment files from being accessed accidentally.
  *
- * Covers configurable set of tools (default: read, write, edit, bash, grep, find, ls).
+ * Uses AST-based parsing for bash commands to extract file references,
+ * with glob expansion via `fd` when args contain shell glob characters.
  */
 
 async function fileExists(filePath: string): Promise<boolean> {
@@ -20,48 +25,115 @@ async function fileExists(filePath: string): Promise<boolean> {
   }
 }
 
-function compilePatterns(patterns: string[]): RegExp[] {
-  return patterns
-    .map((p) => {
-      try {
-        return new RegExp(p, "i");
-      } catch {
-        console.error(`Invalid regex pattern in guardrails config: ${p}`);
-        return null;
-      }
-    })
-    .filter((r): r is RegExp => r !== null);
-}
-
 async function isProtectedEnvFile(
   filePath: string,
-  config: ResolvedConfig,
+  protectedPatterns: CompiledPattern[],
+  allowedPatterns: CompiledPattern[],
+  dirPatterns: CompiledPattern[],
+  onlyBlockIfExists: boolean,
 ): Promise<boolean> {
-  const protectedRegexes = compilePatterns(config.envFiles.protectedPatterns);
-  const isProtected = protectedRegexes.some((r) => r.test(filePath));
+  const isProtected = protectedPatterns.some((p) => p.test(filePath));
   if (!isProtected) return false;
 
-  const allowedRegexes = compilePatterns(config.envFiles.allowedPatterns);
-  const isAllowed = allowedRegexes.some((r) => r.test(filePath));
+  const isAllowed = allowedPatterns.some((p) => p.test(filePath));
   if (isAllowed) return false;
 
   // Check protected directories (if any configured)
-  if (config.envFiles.protectedDirectories.length > 0) {
-    const dirRegexes = compilePatterns(config.envFiles.protectedDirectories);
-    const inProtectedDir = dirRegexes.some((r) => r.test(filePath));
+  if (dirPatterns.length > 0) {
+    const inProtectedDir = dirPatterns.some((p) => p.test(filePath));
     if (inProtectedDir) {
-      return config.envFiles.onlyBlockIfExists
-        ? await fileExists(filePath)
-        : true;
+      return onlyBlockIfExists ? await fileExists(filePath) : true;
+    }
+  }
+
+  return onlyBlockIfExists ? await fileExists(filePath) : true;
+}
+
+/**
+ * Extract file references from a bash command using AST parsing.
+ * Falls back to regex extraction on parse failure.
+ */
+async function extractBashFileTargets(command: string): Promise<string[]> {
+  try {
+    const { ast } = parse(command);
+    const files: string[] = [];
+
+    walkCommands(ast, (cmd) => {
+      const words = (cmd.words ?? []).map(wordToString);
+      // Skip command name (words[0]), check args for env file references
+      for (let i = 1; i < words.length; i++) {
+        const arg = words[i] as string;
+        if (isEnvLikeReference(arg)) {
+          files.push(arg);
+        }
+      }
+
+      // Also check redirect targets
+      for (const redir of cmd.redirects ?? []) {
+        const target = wordToString(redir.target);
+        if (isEnvLikeReference(target)) {
+          files.push(target);
+        }
+      }
+      return false;
+    });
+
+    // Expand globs
+    const expanded: string[] = [];
+    for (const file of files) {
+      if (hasGlobChars(file)) {
+        const matches = await expandGlob(file);
+        if (matches.length > 0) {
+          expanded.push(...matches);
+        } else {
+          // Expansion returned nothing -- could be fd not found or no matches.
+          // Keep original as-is so pattern matching can still catch it.
+          expanded.push(file);
+        }
+      } else {
+        expanded.push(file);
+      }
     }
+
+    return expanded;
+  } catch {
+    // Fallback: regex extraction from raw string
+    return extractEnvFilesRegex(command);
+  }
+}
+
+/**
+ * Check if a string looks like an env file reference.
+ * Matches anything containing ".env" as a path component.
+ */
+function isEnvLikeReference(arg: string): boolean {
+  // Must contain ".env" somewhere
+  if (!arg.includes(".env") && !arg.includes(".dev.vars")) return false;
+  // Skip flags
+  if (arg.startsWith("-") && !arg.startsWith("-/") && !arg.startsWith("-."))
+    return false;
+  return true;
+}
+
+/**
+ * Fallback regex extraction for env file references in bash commands.
+ */
+function extractEnvFilesRegex(command: string): string[] {
+  const files: string[] = [];
+  const envFileRegex =
+    /(?:^|\s|[<>|;&"'`])([^\s<>|;&"'`]*\.env[^\s<>|;&"'`]*)(?:\s|$|[<>|;&"'`])/gi;
+
+  for (const match of command.matchAll(envFileRegex)) {
+    const file = match[1];
+    if (file) files.push(file);
   }
 
-  return config.envFiles.onlyBlockIfExists ? await fileExists(filePath) : true;
+  return files;
 }
 
 interface ToolProtectionRule {
   tools: string[];
-  extractTargets: (input: Record<string, unknown>) => string[];
+  extractTargets: (input: Record<string, unknown>) => Promise<string[]>;
   shouldBlock: (target: string) => Promise<boolean>;
   blockMessage: (target: string) => string;
 }
@@ -72,36 +144,41 @@ export function setupProtectEnvFilesHook(
 ) {
   if (!config.features.protectEnvFiles) return;
 
+  const protectedPatterns = compileFilePatterns(
+    config.envFiles.protectedPatterns,
+  );
+  const allowedPatterns = compileFilePatterns(config.envFiles.allowedPatterns);
+  const dirPatterns = compileFilePatterns(config.envFiles.protectedDirectories);
+
+  const shouldBlock = (target: string) =>
+    isProtectedEnvFile(
+      target,
+      protectedPatterns,
+      allowedPatterns,
+      dirPatterns,
+      config.envFiles.onlyBlockIfExists,
+    );
+
   const protectionRules: ToolProtectionRule[] = [
     {
       tools: config.envFiles.protectedTools.filter((t) =>
         ["read", "write", "edit", "grep", "find", "ls"].includes(t),
       ),
-      extractTargets: (input) => {
+      extractTargets: async (input) => {
         const path = String(input.file_path ?? input.path ?? "");
         return path ? [path] : [];
       },
-      shouldBlock: (target) => isProtectedEnvFile(target, config),
+      shouldBlock,
       blockMessage: (target) =>
         config.envFiles.blockMessage.replace("{file}", target),
     },
     {
       tools: config.envFiles.protectedTools.includes("bash") ? ["bash"] : [],
-      extractTargets: (input) => {
+      extractTargets: async (input) => {
         const command = String(input.command ?? "");
-        const files: string[] = [];
-
-        const envFileRegex =
-          /(?:^|\s|[<>|;&"'`])([^\s<>|;&"'`]*\.env[^\s<>|;&"'`]*)(?:\s|$|[<>|;&"'`])/gi;
-
-        for (const match of command.matchAll(envFileRegex)) {
-          const file = match[1];
-          if (file) files.push(file);
-        }
-
-        return files;
+        return extractBashFileTargets(command);
       },
-      shouldBlock: (target) => isProtectedEnvFile(target, config),
+      shouldBlock,
       blockMessage: (target) =>
         `Command references protected file ${target}. ` +
         config.envFiles.blockMessage.replace("{file}", target),
@@ -120,7 +197,7 @@ export function setupProtectEnvFilesHook(
     const rule = rulesByTool.get(event.toolName);
     if (!rule) return;
 
-    const targets = rule.extractTargets(event.input);
+    const targets = await rule.extractTargets(event.input);
 
     for (const target of targets) {
       if (await rule.shouldBlock(target)) {

package/index.ts

@@ -1,16 +1,19 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { configLoader } from "./config";
 import { setupGuardrailsHooks } from "./hooks";
-import { registerSettingsCommand } from "./settings-command";
+import { registerGuardrailsSettings } from "./settings-command";
 
 /**
  * Guardrails Extension
  *
  * Security hooks to prevent potentially dangerous operations:
- * - prevent-brew: Blocks Homebrew commands (project uses Nix)
  * - protect-env-files: Prevents access to .env files (except .example/.sample/.test)
  * - permission-gate: Prompts for confirmation on dangerous commands
  *
+ * Toolchain features (preventBrew, preventPython, enforcePackageManager,
+ * packageManager) have been moved to @aliou/pi-toolchain. Old configs
+ * containing these fields are auto-migrated on first load.
+ *
  * Configuration:
  * - Global: ~/.pi/agent/extensions/guardrails.json
  * - Project: .pi/extensions/guardrails.json
@@ -23,5 +26,5 @@ export default async function (pi: ExtensionAPI) {
   if (!config.enabled) return;
 
   setupGuardrailsHooks(pi, config);
-  registerSettingsCommand(pi);
+  registerGuardrailsSettings(pi);
 }

package/matching.ts

@@ -0,0 +1,119 @@
+/**
+ * Pattern compilation for guardrails matching.
+ *
+ * Two contexts with different default semantics:
+ * - File context: default is glob matching against filename.
+ * - Command context: default is substring matching against raw command string.
+ *
+ * Both support `regex: true` for full regex matching.
+ */
+
+import type { PatternConfig } from "./config-schema";
+
+export interface CompiledPattern {
+  test: (input: string) => boolean;
+  source: PatternConfig;
+}
+
+/**
+ * Convert a glob pattern to a regex.
+ * `*` matches any non-`/` chars, `?` matches a single char.
+ * The rest is escaped.
+ */
+export function globToRegex(glob: string): RegExp {
+  let regex = "";
+  for (const ch of glob) {
+    switch (ch) {
+      case "*":
+        regex += "[^/]*";
+        break;
+      case "?":
+        regex += "[^/]";
+        break;
+      case ".":
+      case "(":
+      case ")":
+      case "+":
+      case "^":
+      case "$":
+      case "{":
+      case "}":
+      case "|":
+      case "\\":
+      case "[":
+      case "]":
+        regex += `\\${ch}`;
+        break;
+      default:
+        regex += ch;
+    }
+  }
+  return new RegExp(`^${regex}$`, "i");
+}
+
+/**
+ * Compile a single pattern for file-context matching.
+ * Default: glob against the basename of the path.
+ * regex: true -> full regex (case-insensitive) against the full path.
+ */
+export function compileFilePattern(config: PatternConfig): CompiledPattern {
+  if (config.regex) {
+    try {
+      const re = new RegExp(config.pattern, "i");
+      return { test: (input) => re.test(input), source: config };
+    } catch {
+      console.error(`Invalid regex in guardrails config: ${config.pattern}`);
+      return { test: () => false, source: config };
+    }
+  }
+
+  const re = globToRegex(config.pattern);
+  return {
+    test: (input) => {
+      // Match against basename
+      const basename = input.split("/").pop() ?? input;
+      return re.test(basename);
+    },
+    source: config,
+  };
+}
+
+/**
+ * Compile a single pattern for command-context matching.
+ * Default: substring match against raw command string.
+ * regex: true -> full regex against raw command string.
+ */
+export function compileCommandPattern(config: PatternConfig): CompiledPattern {
+  if (config.regex) {
+    try {
+      const re = new RegExp(config.pattern);
+      return { test: (input) => re.test(input), source: config };
+    } catch {
+      console.error(`Invalid regex in guardrails config: ${config.pattern}`);
+      return { test: () => false, source: config };
+    }
+  }
+
+  return {
+    test: (input) => input.includes(config.pattern),
+    source: config,
+  };
+}
+
+/**
+ * Compile an array of patterns for file-context matching.
+ */
+export function compileFilePatterns(
+  configs: PatternConfig[],
+): CompiledPattern[] {
+  return configs.map(compileFilePattern);
+}
+
+/**
+ * Compile an array of patterns for command-context matching.
+ */
+export function compileCommandPatterns(
+  configs: PatternConfig[],
+): CompiledPattern[] {
+  return configs.map(compileCommandPattern);
+}

package/migration.ts

@@ -0,0 +1,135 @@
+/**
+ * Config migration from v0 (no version field) to current format.
+ *
+ * v0 configs store patterns as plain strings (regex). The migration
+ * converts them to PatternConfig objects with `regex: true` to preserve
+ * existing behavior.
+ */
+
+import { copyFile, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import type {
+  DangerousPattern,
+  GuardrailsConfig,
+  PatternConfig,
+} from "./config-schema";
+
+export const CURRENT_VERSION = "0.6.0-20260204";
+
+/**
+ * Check if a config needs migration (no version field = v0).
+ */
+export function needsMigration(config: GuardrailsConfig): boolean {
+  return config.version === undefined;
+}
+
+/**
+ * Migrate a v0 config to the current format.
+ * All string patterns become `{ pattern, regex: true }` to preserve behavior.
+ */
+export function migrateV0(config: GuardrailsConfig): GuardrailsConfig {
+  const migrated = structuredClone(config);
+
+  // Migrate envFiles patterns
+  if (migrated.envFiles) {
+    if (migrated.envFiles.protectedPatterns) {
+      migrated.envFiles.protectedPatterns = migrateStringArray(
+        migrated.envFiles.protectedPatterns,
+      );
+    }
+    if (migrated.envFiles.allowedPatterns) {
+      migrated.envFiles.allowedPatterns = migrateStringArray(
+        migrated.envFiles.allowedPatterns,
+      );
+    }
+    if (migrated.envFiles.protectedDirectories) {
+      migrated.envFiles.protectedDirectories = migrateStringArray(
+        migrated.envFiles.protectedDirectories,
+      );
+    }
+  }
+
+  // Migrate permissionGate patterns
+  if (migrated.permissionGate) {
+    if (migrated.permissionGate.patterns) {
+      migrated.permissionGate.patterns = migrateDangerousPatterns(
+        migrated.permissionGate.patterns,
+      );
+    }
+    if (migrated.permissionGate.customPatterns) {
+      migrated.permissionGate.customPatterns = migrateDangerousPatterns(
+        migrated.permissionGate.customPatterns,
+      );
+    }
+    if (migrated.permissionGate.allowedPatterns) {
+      migrated.permissionGate.allowedPatterns = migrateStringArray(
+        migrated.permissionGate.allowedPatterns,
+      );
+    }
+    if (migrated.permissionGate.autoDenyPatterns) {
+      migrated.permissionGate.autoDenyPatterns = migrateStringArray(
+        migrated.permissionGate.autoDenyPatterns,
+      );
+    }
+  }
+
+  migrated.version = CURRENT_VERSION;
+  return migrated;
+}
+
+/**
+ * Migrate a string[] or PatternConfig[] to PatternConfig[] with regex: true.
+ * Handles mixed arrays (some already migrated, some still strings).
+ */
+function migrateStringArray(
+  items: (string | PatternConfig)[],
+): PatternConfig[] {
+  return items.map((item) => {
+    if (typeof item === "string") {
+      return { pattern: item, regex: true };
+    }
+    // Already a PatternConfig, ensure regex is set
+    if (item.regex === undefined) {
+      return { ...item, regex: true };
+    }
+    return item;
+  });
+}
+
+/**
+ * Migrate dangerous pattern arrays. Handles both legacy
+ * `{ pattern: string, description: string }` and already-migrated formats.
+ */
+function migrateDangerousPatterns(
+  items: (DangerousPattern | { pattern: string; description: string })[],
+): DangerousPattern[] {
+  return items.map((item) => {
+    if ("regex" in item && item.regex !== undefined) {
+      return item as DangerousPattern;
+    }
+    return { ...item, regex: true };
+  });
+}
+
+/**
+ * Back up a config file before migration.
+ * Creates `<name>.v0.json` in the same directory.
+ * Skips if backup already exists.
+ */
+export async function backupConfig(configPath: string): Promise<void> {
+  const dir = dirname(configPath);
+  const basename = configPath.split("/").pop() ?? "guardrails.json";
+  const backupName = basename.replace(".json", ".v0.json");
+  const backupPath = resolve(dir, backupName);
+
+  try {
+    await stat(backupPath);
+    // Backup already exists, skip
+  } catch {
+    try {
+      await copyFile(configPath, backupPath);
+    } catch (err) {
+      console.warn(`guardrails: could not back up config: ${err}`);
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-guardrails",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "type": "module",
   "private": false,
   "keywords": [
@@ -18,7 +18,7 @@
     "extensions": [
       "./index.ts"
     ],
-    "video": "https://assets.aliou.me/pi-extensions/2026-01-26-guardrails-demo.mp4"
+    "video": "https://assets.aliou.me/pi-extensions/demos/pi-guardrails.mp4"
   },
   "publishConfig": {
     "access": "public"
@@ -28,8 +28,11 @@
     "hooks",
     "README.md"
   ],
+  "dependencies": {
+    "@aliou/pi-utils-settings": "^0.1.0",
+    "@aliou/sh": "github:aliou/sh#v0.1.0"
+  },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "0.51.0",
-    "@mariozechner/pi-tui": "0.51.0"
+    "@mariozechner/pi-coding-agent": ">=0.51.0"
   }
 }