@aliou/pi-guardrails 0.11.2 → 0.12.0

package/src/shared/config/migration/003-strip-command-explainer-fields.ts

@@ -0,0 +1,42 @@
+import { addPendingWarning } from "../../warnings";
+import type { GuardrailsConfig } from "../types";
+import { CURRENT_VERSION } from "./version";
+
+const REMOVED_PERMISSION_GATE_KEYS = [
+  "explainCommands",
+  "explainModel",
+  "explainTimeout",
+] as const;
+
+export function shouldRun(config: GuardrailsConfig): boolean {
+  const raw = config as Record<string, unknown>;
+  const permissionGate = raw.permissionGate as
+    | Record<string, unknown>
+    | undefined;
+  if (!permissionGate) return false;
+
+  for (const key of REMOVED_PERMISSION_GATE_KEYS) {
+    if (key in permissionGate) return true;
+  }
+
+  return false;
+}
+
+export function run(config: GuardrailsConfig): GuardrailsConfig {
+  addPendingWarning(
+    "[guardrails] permissionGate.explainCommands, explainModel, and explainTimeout " +
+      "have been removed. These fields will be stripped from your config.",
+  );
+
+  const cleaned = structuredClone(config) as Record<string, unknown>;
+  const permissionGate = cleaned.permissionGate as
+    | Record<string, unknown>
+    | undefined;
+  if (permissionGate) {
+    for (const key of REMOVED_PERMISSION_GATE_KEYS) {
+      delete permissionGate[key];
+    }
+  }
+  cleaned.version = CURRENT_VERSION;
+  return cleaned as GuardrailsConfig;
+}

package/src/shared/config/migration/004-env-files-to-policies.ts

@@ -0,0 +1,87 @@
+import { addPendingWarning } from "../../warnings";
+import type { GuardrailsConfig } from "../types";
+import { CURRENT_VERSION } from "./version";
+
+export function shouldRun(config: GuardrailsConfig): boolean {
+  const raw = config as Record<string, unknown>;
+  if (raw.envFiles !== undefined) return true;
+
+  const features = raw.features as Record<string, unknown> | undefined;
+  return features?.protectEnvFiles !== undefined;
+}
+
+export function run(config: GuardrailsConfig): GuardrailsConfig {
+  const migrated = structuredClone(config);
+  const raw = migrated as Record<string, unknown>;
+  const features = raw.features as Record<string, unknown> | undefined;
+  const envFiles = raw.envFiles as Record<string, unknown> | undefined;
+
+  if (features?.protectEnvFiles !== undefined) {
+    features.policies = features.protectEnvFiles;
+    delete features.protectEnvFiles;
+  }
+
+  if (envFiles) {
+    const rule: Record<string, unknown> = {
+      id: "secret-files",
+      description: "Files containing secrets (migrated from envFiles)",
+      protection: "noAccess",
+    };
+
+    if (envFiles.protectedPatterns) rule.patterns = envFiles.protectedPatterns;
+    if (envFiles.allowedPatterns)
+      rule.allowedPatterns = envFiles.allowedPatterns;
+    if (envFiles.onlyBlockIfExists !== undefined) {
+      rule.onlyIfExists = envFiles.onlyBlockIfExists;
+    }
+    if (typeof envFiles.blockMessage === "string") {
+      rule.blockMessage = envFiles.blockMessage;
+    }
+
+    if (Array.isArray(envFiles.protectedDirectories)) {
+      const dirs = envFiles.protectedDirectories as Array<
+        Record<string, unknown>
+      >;
+      const patterns = Array.isArray(rule.patterns)
+        ? ([...rule.patterns] as Array<Record<string, unknown>>)
+        : [];
+
+      for (const dir of dirs) {
+        const dirPattern = dir.pattern;
+        if (typeof dirPattern !== "string" || dirPattern.trim() === "") {
+          continue;
+        }
+
+        const normalized = dirPattern.endsWith("/**")
+          ? dirPattern
+          : `${dirPattern}/**`;
+        patterns.push({ pattern: normalized, regex: dir.regex });
+      }
+
+      if (patterns.length > 0) rule.patterns = patterns;
+    }
+
+    if (Array.isArray(envFiles.protectedTools)) {
+      addPendingWarning(
+        "[guardrails] envFiles.protectedTools is deprecated and has no direct policies equivalent. " +
+          "The migrated secret-files rule uses protection=noAccess.",
+      );
+    }
+
+    if (!Array.isArray(rule.patterns) || rule.patterns.length === 0) {
+      rule.patterns = [
+        { pattern: ".env" },
+        { pattern: ".env.local" },
+        { pattern: ".env.production" },
+        { pattern: ".env.prod" },
+        { pattern: ".dev.vars" },
+      ];
+    }
+
+    raw.policies = { rules: [rule] };
+    delete raw.envFiles;
+  }
+
+  raw.version = CURRENT_VERSION;
+  return migrated as GuardrailsConfig;
+}

package/src/shared/config/migration/005-normalize-allowed-paths.ts

@@ -0,0 +1,43 @@
+import { addPendingWarning } from "../../warnings";
+import type { GuardrailsConfig } from "../types";
+import { CURRENT_VERSION } from "./version";
+
+export function shouldRun(config: GuardrailsConfig): boolean {
+  const raw = config as Record<string, unknown>;
+  const pathAccess = raw.pathAccess as Record<string, unknown> | undefined;
+  if (!Array.isArray(pathAccess?.allowedPaths)) return false;
+  return pathAccess.allowedPaths.some((item) => typeof item !== "string");
+}
+
+export function run(config: GuardrailsConfig): GuardrailsConfig {
+  const migrated = structuredClone(config) as Record<string, unknown>;
+  const pathAccess = migrated.pathAccess as Record<string, unknown> | undefined;
+  if (!pathAccess) return migrated as GuardrailsConfig;
+
+  pathAccess.allowedPaths = normalizeAllowedPaths(pathAccess.allowedPaths);
+  migrated.version = CURRENT_VERSION;
+  addPendingWarning(
+    "[guardrails] pathAccess.allowedPaths was migrated from pattern objects to path strings.",
+  );
+  return migrated as GuardrailsConfig;
+}
+
+function normalizeAllowedPaths(items: unknown): string[] {
+  if (!Array.isArray(items)) return [];
+
+  const paths = new Set<string>();
+  for (const item of items) {
+    let path: string | null = null;
+    if (typeof item === "string") {
+      path = item;
+    } else if (typeof item === "object" && item !== null) {
+      const pattern = (item as Record<string, unknown>).pattern;
+      if (typeof pattern === "string") path = pattern;
+    }
+
+    const normalized = path?.trim();
+    if (normalized) paths.add(normalized);
+  }
+
+  return [...paths];
+}

package/src/shared/config/migration/006-apply-builtin-defaults.ts

@@ -0,0 +1,19 @@
+import { addPendingWarning } from "../../warnings";
+import type { GuardrailsConfig } from "../types";
+import { CURRENT_VERSION } from "./version";
+
+export function shouldRun(config: GuardrailsConfig): boolean {
+  return config.applyBuiltinDefaults === undefined;
+}
+
+export function run(config: GuardrailsConfig): GuardrailsConfig {
+  const migrated = structuredClone(config);
+  migrated.applyBuiltinDefaults = true;
+  migrated.version = CURRENT_VERSION;
+
+  addPendingWarning(
+    "Guardrails config was migrated. `applyBuiltinDefaults` was set to `true` to preserve current behavior.",
+  );
+
+  return migrated;
+}

package/src/shared/config/migration/007-mark-onboarding-done.ts

@@ -0,0 +1,25 @@
+import { addPendingWarning } from "../../warnings";
+import type { GuardrailsConfig } from "../types";
+import { CURRENT_VERSION } from "./version";
+
+export function shouldRun(config: GuardrailsConfig): boolean {
+  return (
+    config.onboarding?.completed === undefined &&
+    config.applyBuiltinDefaults !== undefined
+  );
+}
+
+export function run(config: GuardrailsConfig): GuardrailsConfig {
+  const migrated = structuredClone(config);
+  addPendingWarning(
+    "Guardrails config was migrated. Existing setup marked as onboarding-complete.",
+  );
+  migrated.onboarding = {
+    ...(migrated.onboarding ?? {}),
+    completed: true,
+    completedAt: migrated.onboarding?.completedAt ?? new Date().toISOString(),
+    version: migrated.onboarding?.version ?? CURRENT_VERSION,
+  };
+  migrated.version = CURRENT_VERSION;
+  return migrated;
+}

package/src/shared/config/migration/index.ts

@@ -0,0 +1,44 @@
+import type { Migration } from "@aliou/pi-utils-settings";
+import type { GuardrailsConfig } from "../types";
+import * as v0FormatUpgrade from "./001-v0-format-upgrade";
+import * as stripToolchainFields from "./002-strip-toolchain-fields";
+import * as stripCommandExplainerFields from "./003-strip-command-explainer-fields";
+import * as envFilesToPolicies from "./004-env-files-to-policies";
+import * as normalizeAllowedPaths from "./005-normalize-allowed-paths";
+import * as applyBuiltinDefaults from "./006-apply-builtin-defaults";
+import * as markOnboardingDone from "./007-mark-onboarding-done";
+
+export { CURRENT_VERSION } from "./version";
+
+export const migrations: Migration<GuardrailsConfig>[] = [
+  {
+    name: "v0-format-upgrade",
+    shouldRun: v0FormatUpgrade.shouldRun,
+    run: v0FormatUpgrade.run,
+  },
+  {
+    name: "strip-toolchain-fields",
+    shouldRun: stripToolchainFields.shouldRun,
+    run: stripToolchainFields.run,
+  },
+  {
+    name: "strip-command-explainer-fields",
+    shouldRun: stripCommandExplainerFields.shouldRun,
+    run: stripCommandExplainerFields.run,
+  },
+  {
+    name: "envFiles-to-policies",
+    shouldRun: envFilesToPolicies.shouldRun,
+    run: envFilesToPolicies.run,
+  },
+  {
+    name: "normalize-allowed-paths",
+    shouldRun: normalizeAllowedPaths.shouldRun,
+    run: normalizeAllowedPaths.run,
+  },
+];
+
+export const globalConfigMigrations = [
+  applyBuiltinDefaults,
+  markOnboardingDone,
+] as const;

package/src/shared/config/migration/version.ts

@@ -0,0 +1,7 @@
+/**
+ * Config schema version.
+ *
+ * Keep this independent from package.json version.
+ * Bump only when config schema/default migration markers change.
+ */
+export const CURRENT_VERSION = "0.9.0-20260327";

package/src/shared/config/types.ts

@@ -0,0 +1,141 @@
+/**
+ * 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).
+ */
+import type { GuardrailsFeatureId } from "../events";
+
+/**
+ * A pattern with explicit matching mode.
+ * Default: glob for files, substring for commands.
+ * regex: true means full regex matching.
+ */
+export interface PatternConfig {
+  pattern: string;
+  /** Optional description surfaced to the agent when the pattern triggers (e.g. auto-deny reason). */
+  description?: 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;
+}
+
+/**
+ * Protection level for a policy rule.
+ */
+export type Protection = "none" | "readOnly" | "noAccess";
+
+/**
+ * A named policy rule. Matches files by patterns and enforces a protection level.
+ */
+export interface PolicyRule {
+  /** Stable identifier used for deduplication across scopes. */
+  id: string;
+  /** Optional display name for settings/UI. */
+  name?: string;
+  /** Human-readable description. */
+  description?: string;
+  /** File patterns to protect. */
+  patterns: PatternConfig[];
+  /** Optional exceptions. */
+  allowedPatterns?: PatternConfig[];
+  /** Protection level. */
+  protection: Protection;
+  /** Block only when file exists on disk. Default true. */
+  onlyIfExists?: boolean;
+  /** Message shown when blocked; supports {file} placeholder. */
+  blockMessage?: string;
+  /** Per-rule toggle. Default true. */
+  enabled?: boolean;
+}
+
+export type PathAccessMode = "allow" | "ask" | "block";
+
+export interface PathAccessConfig {
+  mode?: PathAccessMode;
+  allowedPaths?: string[];
+}
+
+export interface GuardrailsConfig {
+  /** JSON Schema URL for editor autocomplete and validation. Added automatically when Guardrails writes the file. */
+  $schema?: string;
+  /** Internal config schema marker for migration/debugging. Not tied to the package version. */
+  version?: string;
+  /** Enable or disable all Guardrails checks. */
+  enabled?: boolean;
+  /** When true, include Guardrails built-in policy rules before user rules are merged. */
+  applyBuiltinDefaults?: boolean;
+  /** Tracks whether the setup wizard has been completed. Usually managed by Guardrails. */
+  onboarding?: {
+    /** Whether onboarding is complete. */
+    completed?: boolean;
+    /** ISO timestamp for when onboarding completed. */
+    completedAt?: string;
+    /** Guardrails config schema marker used when onboarding completed. */
+    version?: string;
+  };
+  /** Enable or disable individual Guardrails feature extensions. */
+  features?: Partial<Record<GuardrailsFeatureId, boolean>> & {
+    // Deprecated. Kept only for migration.
+    protectEnvFiles?: boolean;
+  };
+  /** File protection policies. */
+  policies?: {
+    /** Named policy rules. Rules with the same id override earlier rules across scopes. */
+    rules?: PolicyRule[];
+  };
+  /** Outside-workspace path access settings. */
+  pathAccess?: PathAccessConfig;
+  // Deprecated. Kept only for migration.
+  envFiles?: {
+    protectedPatterns?: PatternConfig[];
+    allowedPatterns?: PatternConfig[];
+    protectedDirectories?: PatternConfig[];
+    protectedTools?: string[];
+    onlyBlockIfExists?: boolean;
+    blockMessage?: string;
+  };
+  /** Dangerous bash command detection and confirmation settings. */
+  permissionGate?: {
+    /** Additional dangerous command patterns. */
+    patterns?: DangerousPattern[];
+    /** If set, replaces the default dangerous command patterns entirely. */
+    customPatterns?: DangerousPattern[];
+    /** When true, prompt before running dangerous commands. When false, only warn. */
+    requireConfirmation?: boolean;
+    /** Command patterns that bypass dangerous command prompts. */
+    allowedPatterns?: PatternConfig[];
+    /** Command patterns that are always blocked without prompting. */
+    autoDenyPatterns?: PatternConfig[];
+  };
+}
+
+export interface ResolvedConfig {
+  version: string;
+  enabled: boolean;
+  applyBuiltinDefaults: boolean;
+  features: Record<GuardrailsFeatureId, boolean>;
+  policies: {
+    rules: PolicyRule[];
+  };
+  pathAccess: {
+    mode: PathAccessMode;
+    allowedPaths: string[];
+  };
+  permissionGate: {
+    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: PatternConfig[];
+    autoDenyPatterns: PatternConfig[];
+  };
+}

package/src/shared/events.ts

@@ -0,0 +1,100 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { Action, Safety } from "../core/types";
+
+export const GUARDRAILS_ACTION_BLOCKED_EVENT = "guardrails:action:blocked";
+export const GUARDRAILS_RISK_DETECTED_EVENT = "guardrails:risk:detected";
+export const GUARDRAILS_FEATURE_REQUEST_EVENT = "guardrails:feature:request";
+export const GUARDRAILS_FEATURE_REGISTER_EVENT = "guardrails:feature:register";
+
+export type GuardrailsFeatureId = "policies" | "permissionGate" | "pathAccess";
+
+export interface GuardrailsEventBase {
+  source: "guardrails";
+  feature: GuardrailsFeatureId;
+  timestamp: string;
+}
+
+export interface GuardrailsFeatureRequestPayload {
+  source: "guardrails";
+  timestamp: string;
+}
+
+export interface GuardrailsFeatureRegisterPayload {
+  source: "guardrails";
+  timestamp: string;
+  feature: {
+    id: GuardrailsFeatureId;
+  };
+}
+
+export type GuardrailsBlockSource =
+  | "policy"
+  | "permission"
+  | "user"
+  | "nonInteractive";
+
+export type GuardrailsActionBlockedPayload<TMeta = unknown> =
+  GuardrailsEventBase & {
+    action: Action;
+    reason: string;
+    block: {
+      source: GuardrailsBlockSource;
+      metadata?: TMeta;
+    };
+    context?: {
+      toolName?: string;
+      input?: Record<string, unknown>;
+    };
+  };
+
+export type GuardrailsRiskDetectedPayload<TMeta = unknown> =
+  GuardrailsEventBase & {
+    risk: Safety<TMeta> & { kind: "dangerous" };
+    context?: {
+      toolName?: string;
+      input?: Record<string, unknown>;
+    };
+  };
+
+function timestamp(): string {
+  return new Date().toISOString();
+}
+
+export function createFeatureRequestPayload(): GuardrailsFeatureRequestPayload {
+  return {
+    source: "guardrails",
+    timestamp: timestamp(),
+  };
+}
+
+export function createFeatureRegisterPayload(
+  feature: GuardrailsFeatureId,
+): GuardrailsFeatureRegisterPayload {
+  return {
+    source: "guardrails",
+    timestamp: timestamp(),
+    feature: { id: feature },
+  };
+}
+
+export function emitActionBlocked<TMeta = unknown>(
+  pi: ExtensionAPI,
+  event: Omit<GuardrailsActionBlockedPayload<TMeta>, "source" | "timestamp">,
+): void {
+  pi.events.emit(GUARDRAILS_ACTION_BLOCKED_EVENT, {
+    source: "guardrails",
+    timestamp: timestamp(),
+    ...event,
+  });
+}
+
+export function emitRiskDetected<TMeta = unknown>(
+  pi: ExtensionAPI,
+  event: Omit<GuardrailsRiskDetectedPayload<TMeta>, "source" | "timestamp">,
+): void {
+  pi.events.emit(GUARDRAILS_RISK_DETECTED_EVENT, {
+    source: "guardrails",
+    timestamp: timestamp(),
+    ...event,
+  });
+}

package/src/shared/index.ts

@@ -0,0 +1,6 @@
+export * from "./config";
+export * from "./events";
+export * from "./glob";
+export * from "./matching";
+export * from "./paths";
+export * from "./warnings";

package/src/shared/matching.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import {
+  compileCommandPattern,
+  compileFilePattern,
+  normalizeFilePath,
+} from "./matching";
+import { drainPendingWarnings } from "./warnings";
+
+describe("normalizeFilePath", () => {
+  it.each([
+    ["./src//file.ts", "src/file.ts"],
+    ["src\\file.ts", "src/file.ts"],
+    ["./foo\\bar//baz", "foo/bar/baz"],
+  ])("normalizes %s", (input, expected) => {
+    expect(normalizeFilePath(input)).toBe(expected);
+  });
+});
+
+describe("compileFilePattern", () => {
+  it("matches basename when the pattern has no slash", () => {
+    const pattern = compileFilePattern({ pattern: ".env" });
+
+    expect(pattern.test(".env")).toBe(true);
+    expect(pattern.test("config/.env")).toBe(true);
+    expect(pattern.test("config/.env.local")).toBe(false);
+  });
+
+  it("matches full normalized paths when the pattern has a slash", () => {
+    const pattern = compileFilePattern({ pattern: "config/*.env" });
+
+    expect(pattern.test("config/app.env")).toBe(true);
+    expect(pattern.test("./config//app.env")).toBe(true);
+    expect(pattern.test("nested/config/app.env")).toBe(false);
+  });
+
+  it("uses case-insensitive regex matching for file patterns", () => {
+    const pattern = compileFilePattern({
+      pattern: "SECRET\\.TXT$",
+      regex: true,
+    });
+
+    expect(pattern.test("docs/secret.txt")).toBe(true);
+    expect(pattern.test("docs/public.txt")).toBe(false);
+  });
+
+  it("records a warning and returns a non-matching pattern for invalid regex", () => {
+    drainPendingWarnings();
+
+    const pattern = compileFilePattern({ pattern: "[", regex: true });
+
+    expect(pattern.test("anything")).toBe(false);
+    expect(drainPendingWarnings()).toEqual([
+      "Invalid regex in guardrails config: [",
+    ]);
+  });
+});
+
+describe("compileCommandPattern", () => {
+  it("uses substring matching by default", () => {
+    const pattern = compileCommandPattern({ pattern: "deploy production" });
+
+    expect(pattern.test("please deploy production now")).toBe(true);
+    expect(pattern.test("deploy staging")).toBe(false);
+  });
+
+  it("uses regex matching when requested", () => {
+    const pattern = compileCommandPattern({
+      pattern: "terraform\\s+apply",
+      regex: true,
+    });
+
+    expect(pattern.test("terraform apply -auto-approve")).toBe(true);
+    expect(pattern.test("terraform plan")).toBe(false);
+  });
+
+  it("records a warning and returns a non-matching pattern for invalid regex", () => {
+    drainPendingWarnings();
+
+    const pattern = compileCommandPattern({ pattern: "[", regex: true });
+
+    expect(pattern.test("anything")).toBe(false);
+    expect(drainPendingWarnings()).toEqual([
+      "Invalid regex in guardrails config: [",
+    ]);
+  });
+});

package/src/{utils → shared}/matching.ts

@@ -9,8 +9,8 @@
  */
 
 import { matchesGlob } from "node:path";
-import type { PatternConfig } from "../config";
-import { pendingWarnings } from "./warnings";
+import type { PatternConfig } from "./config";
+import { addPendingWarning } from "./warnings";
 
 export interface CompiledPattern {
   test: (input: string) => boolean;
@@ -47,7 +47,7 @@ export function compileFilePattern(config: PatternConfig): CompiledPattern {
         source: config,
       };
     } catch {
-      pendingWarnings.push(
+      addPendingWarning(
         `Invalid regex in guardrails config: ${config.pattern}`,
       );
       return { test: () => false, source: config };
@@ -80,7 +80,7 @@ export function compileCommandPattern(config: PatternConfig): CompiledPattern {
       const re = new RegExp(config.pattern);
       return { test: (input) => re.test(input), source: config };
     } catch {
-      pendingWarnings.push(
+      addPendingWarning(
         `Invalid regex in guardrails config: ${config.pattern}`,
       );
       return { test: () => false, source: config };

package/src/{utils → shared/paths}/bash-paths.test.ts

@@ -84,8 +84,8 @@ describe("extractBashPathCandidates", () => {
 
     it("detects Windows-style paths", async () => {
       const result = await extractBashPathCandidates("type C:\\foo\\bar", CWD);
-      expect(result.length).toBeGreaterThan(0);
-      // On POSIX, resolve() treats backslash path as a single component under cwd
+
+      expect(result).toHaveLength(1);
       expect(result[0]).toContain("C:\\foo\\bar");
     });
   });
@@ -102,6 +102,15 @@ describe("extractBashPathCandidates", () => {
         await extractBashPathCandidates("echo foo > /tmp/out", CWD),
       ).toEqual(["/tmp/out"]);
     });
+
+    it("extracts paths from multiple commands and redirects", async () => {
+      expect(
+        await extractBashPathCandidates(
+          "cat ./input && grep needle /tmp/log > ./out",
+          CWD,
+        ),
+      ).toEqual(["/work/project/input", "/tmp/log", "/work/project/out"]);
+    });
   });
 
   describe("when command has no path-like tokens", () => {

package/src/{utils → shared/paths}/bash-paths.ts

@@ -1,9 +1,9 @@
 import { resolve } from "node:path";
 import { parse } from "@aliou/sh";
-import { classifyCommandArgs } from "./command-args";
-import { expandGlob, hasGlobChars } from "./glob-expander";
-import { expandHomePath, maybePathLike } from "./path";
-import { walkCommands, wordToString } from "./shell-utils";
+import { expandHomePath, maybePathLike } from "../../core/paths/path";
+import { walkCommands, wordToString } from "../../core/shell/ast";
+import { classifyCommandArgs } from "../../core/shell/command-args";
+import { expandGlob, hasGlobChars } from "../glob";
 
 async function expandCandidate(
   candidate: string,

package/src/shared/paths/index.ts

@@ -0,0 +1 @@
+export { extractBashPathCandidates } from "./bash-paths";