@aliou/pi-guardrails 0.5.4 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-guardrails",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "type": "module",
   "private": false,
   "keywords": [
@@ -26,10 +26,16 @@
   "files": [
     "*.ts",
     "hooks",
+    "commands",
+    "components",
+    "utils",
     "README.md"
   ],
+  "dependencies": {
+    "@aliou/pi-utils-settings": "^0.1.0",
+    "@aliou/sh": "^0.1.0"
+  },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "0.51.0",
-    "@mariozechner/pi-tui": "0.51.0"
+    "@mariozechner/pi-coding-agent": ">=0.51.0"
   }
 }

package/{events.ts → utils/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;

package/utils/glob-expander.ts

@@ -0,0 +1,128 @@
+/**
+ * Glob expansion using `fd` for env file protection.
+ *
+ * When a bash command contains shell globs referencing env files
+ * (e.g. `.env*`), we expand them against the filesystem to check
+ * if any expanded path matches a protected pattern.
+ */
+
+import { execFile } from "node:child_process";
+import { resolve } from "node:path";
+
+interface ExpandGlobOptions {
+  cwd?: string;
+  maxDepth?: number;
+  maxResults?: number;
+  timeout?: number;
+}
+
+/**
+ * Expand a glob pattern using `fd`.
+ * Returns matching file paths, or empty array on failure.
+ *
+ * fd is available at `~/.pi/agent/bin/fd` (in pi's PATH).
+ */
+export async function expandGlob(
+  pattern: string,
+  options: ExpandGlobOptions = {},
+): Promise<string[]> {
+  const {
+    cwd = process.cwd(),
+    maxDepth = 3,
+    maxResults = 50,
+    timeout = 2000,
+  } = options;
+
+  // Convert glob to fd-compatible regex.
+  // fd uses regex by default, so we convert glob chars.
+  const fdPattern = globToFdRegex(pattern);
+
+  return new Promise((res) => {
+    const args = [
+      "--type",
+      "f",
+      "--max-depth",
+      String(maxDepth),
+      "--max-results",
+      String(maxResults),
+      "--no-ignore",
+      "--hidden",
+      fdPattern,
+    ];
+
+    const child = execFile("fd", args, { cwd, timeout }, (err, stdout) => {
+      if (err) {
+        res([]);
+        return;
+      }
+
+      const files = stdout
+        .trim()
+        .split("\n")
+        .filter(Boolean)
+        .map((f) => resolve(cwd, f));
+
+      res(files);
+    });
+
+    // Safety net: kill if timeout isn't handled by execFile
+    setTimeout(() => {
+      child.kill();
+      res([]);
+    }, timeout + 500);
+  });
+}
+
+/**
+ * Convert a shell glob to an fd-compatible regex pattern.
+ * Handles `*`, `?`, and character classes `[...]`.
+ */
+function globToFdRegex(glob: string): string {
+  let regex = "";
+  let i = 0;
+  while (i < glob.length) {
+    const ch = glob[i] as string;
+    switch (ch) {
+      case "*":
+        regex += "[^/]*";
+        break;
+      case "?":
+        regex += "[^/]";
+        break;
+      case "[": {
+        // Pass character classes through
+        const end = glob.indexOf("]", i + 1);
+        if (end !== -1) {
+          regex += glob.slice(i, end + 1);
+          i = end;
+        } else {
+          regex += "\\[";
+        }
+        break;
+      }
+      case ".":
+      case "(":
+      case ")":
+      case "+":
+      case "^":
+      case "$":
+      case "{":
+      case "}":
+      case "|":
+      case "\\":
+        regex += `\\${ch}`;
+        break;
+      default:
+        regex += ch;
+    }
+    i++;
+  }
+  return `^${regex}$`;
+}
+
+/**
+ * Check if a string contains shell glob characters.
+ */
+export function hasGlobChars(s: string): boolean {
+  return /[*?[\]]/.test(s);
+}

package/utils/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";
+
+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/utils/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";
+
+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/utils/shell-utils.ts

@@ -0,0 +1,139 @@
+/**
+ * Shared shell AST helpers used by guardrails hooks.
+ *
+ * Each hook imports `parse` from `@aliou/sh` directly and uses these
+ * for common AST operations.
+ */
+
+import type {
+  Command,
+  Program,
+  SimpleCommand,
+  Statement,
+  Word,
+  WordPart,
+} from "@aliou/sh";
+
+/**
+ * Resolve a Word node to its literal string value.
+ * Concatenates Literal, SglQuoted, and simple DblQuoted parts.
+ * For parts containing parameter expansions, command substitutions, etc.,
+ * includes the raw text representation (e.g. `$VAR`).
+ */
+export function wordToString(word: Word): string {
+  return word.parts.map(partToString).join("");
+}
+
+function partToString(part: WordPart): string {
+  switch (part.type) {
+    case "Literal":
+      return part.value;
+    case "SglQuoted":
+      return part.value;
+    case "DblQuoted":
+      return part.parts.map(partToString).join("");
+    case "ParamExp":
+      return part.short
+        ? `$${part.param.value}`
+        : `\${${part.param.value}${part.op ?? ""}${part.value ? wordToString(part.value) : ""}}`;
+    case "CmdSubst":
+      return "$(...)";
+    case "ArithExp":
+      return `$((${part.expr}))`;
+    case "ProcSubst":
+      return `${part.op}(...)`;
+  }
+}
+
+/**
+ * Walk the AST and call `callback` for every SimpleCommand found at any
+ * nesting depth. Returns early if callback returns `true`.
+ */
+export function walkCommands(
+  node: Program,
+  callback: (cmd: SimpleCommand) => boolean | undefined,
+): void {
+  for (const stmt of node.body) {
+    if (walkStatement(stmt, callback)) return;
+  }
+}
+
+function walkStatement(
+  stmt: Statement,
+  callback: (cmd: SimpleCommand) => boolean | undefined,
+): boolean {
+  return walkCommand(stmt.command, callback);
+}
+
+function walkStatements(
+  stmts: Statement[],
+  callback: (cmd: SimpleCommand) => boolean | undefined,
+): boolean {
+  for (const stmt of stmts) {
+    if (walkStatement(stmt, callback)) return true;
+  }
+  return false;
+}
+
+function walkCommand(
+  cmd: Command,
+  callback: (cmd: SimpleCommand) => boolean | undefined,
+): boolean {
+  switch (cmd.type) {
+    case "SimpleCommand":
+      return callback(cmd) === true;
+
+    case "Pipeline":
+      return walkStatements(cmd.commands, callback);
+
+    case "Logical":
+      return (
+        walkStatement(cmd.left, callback) || walkStatement(cmd.right, callback)
+      );
+
+    case "Subshell":
+    case "Block":
+      return walkStatements(cmd.body, callback);
+
+    case "IfClause":
+      return (
+        walkStatements(cmd.cond, callback) ||
+        walkStatements(cmd.then, callback) ||
+        (cmd.else ? walkStatements(cmd.else, callback) : false)
+      );
+
+    case "ForClause":
+    case "SelectClause":
+    case "WhileClause":
+      return (
+        ("cond" in cmd && cmd.cond
+          ? walkStatements(cmd.cond, callback)
+          : false) || walkStatements(cmd.body, callback)
+      );
+
+    case "CaseClause":
+      for (const item of cmd.items) {
+        if (walkStatements(item.body, callback)) return true;
+      }
+      return false;
+
+    case "FunctionDecl":
+      return walkStatements(cmd.body, callback);
+
+    case "TimeClause":
+      return walkStatement(cmd.command, callback);
+
+    case "CoprocClause":
+      return walkStatement(cmd.body, callback);
+
+    case "CStyleLoop":
+      return walkStatements(cmd.body, callback);
+
+    // These don't contain nested commands we need to walk
+    case "TestClause":
+    case "ArithCmd":
+    case "DeclClause":
+    case "LetClause":
+      return false;
+  }
+}