@aliou/pi-guardrails 0.9.5 → 0.11.0

package/src/utils/bash-paths.test.ts

@@ -0,0 +1,91 @@
+import { homedir } from "node:os";
+import { describe, expect, it } from "vitest";
+import { extractBashPathCandidates } from "./bash-paths";
+
+const CWD = "/work/project";
+const HOME = homedir();
+
+describe("extractBashPathCandidates", () => {
+  describe("when command has path arguments", () => {
+    it("extracts a single absolute path", async () => {
+      expect(await extractBashPathCandidates("cat /etc/hosts", CWD)).toEqual([
+        "/etc/hosts",
+      ]);
+    });
+
+    it("extracts multiple absolute paths", async () => {
+      expect(await extractBashPathCandidates("cp /a /b", CWD)).toEqual([
+        "/a",
+        "/b",
+      ]);
+    });
+
+    it("resolves a relative path with ./ against cwd", async () => {
+      expect(await extractBashPathCandidates("cat ./foo/bar", CWD)).toEqual([
+        "/work/project/foo/bar",
+      ]);
+    });
+
+    it("expands ~ to home", async () => {
+      expect(await extractBashPathCandidates("cat ~/file", CWD)).toEqual([
+        `${HOME}/file`,
+      ]);
+    });
+
+    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[0]).toContain("C:\\foo\\bar");
+    });
+  });
+
+  describe("when command has flags and redirects", () => {
+    it("ignores flag arguments", async () => {
+      expect(await extractBashPathCandidates("ls -la /tmp", CWD)).toEqual([
+        "/tmp",
+      ]);
+    });
+
+    it("extracts redirect targets", async () => {
+      expect(
+        await extractBashPathCandidates("echo foo > /tmp/out", CWD),
+      ).toEqual(["/tmp/out"]);
+    });
+  });
+
+  describe("when command has no path-like tokens", () => {
+    it("returns an empty array for bare filenames (no separators)", async () => {
+      expect(await extractBashPathCandidates("cat README.md", CWD)).toEqual([]);
+    });
+
+    it("returns an empty array for commands with no file arguments", async () => {
+      expect(await extractBashPathCandidates("echo hello", CWD)).toEqual([]);
+    });
+  });
+
+  describe("when command uses quoting", () => {
+    it("handles quoted paths with spaces", async () => {
+      expect(
+        await extractBashPathCandidates('cat "/tmp/hello world"', CWD),
+      ).toEqual(["/tmp/hello world"]);
+    });
+  });
+
+  describe("when command has duplicate paths", () => {
+    it("deduplicates results", async () => {
+      expect(await extractBashPathCandidates("cat /a /a", CWD)).toEqual(["/a"]);
+    });
+  });
+
+  describe("when command is malformed", () => {
+    it("falls back to regex tokenization on parse failure", async () => {
+      // Unbalanced quote triggers parse error; regex fallback still finds paths
+      const result = await extractBashPathCandidates(
+        "cat /tmp/foo 'unterminated",
+        CWD,
+      );
+      expect(result).toContain("/tmp/foo");
+    });
+  });
+});

package/src/utils/bash-paths.ts

@@ -0,0 +1,96 @@
+import { resolve } from "node:path";
+import { parse } from "@aliou/sh";
+import { expandGlob, hasGlobChars } from "./glob-expander";
+import { expandHomePath } from "./path";
+import { walkCommands, wordToString } from "./shell-utils";
+
+/**
+ * Heuristic: is this token likely a filesystem path?
+ * Intentionally conservative — only structural signals.
+ * Known false positives: "application/json", URL paths. These cause
+ * spurious prompts in ask mode but are safe (better to over-prompt than miss).
+ * Known false negatives: bare filenames without path separators (e.g. "README.md").
+ * These are usually cwd-relative and would pass the boundary check anyway.
+ */
+function maybePathLike(token: string): boolean {
+  if (token.includes("/")) return true;
+  if (token.includes("\\")) return true;
+  if (/^[A-Za-z]:[\\/]/.test(token)) return true;
+  if (token.startsWith("~")) return true;
+  return false;
+}
+
+async function expandCandidate(
+  candidate: string,
+  cwd: string,
+): Promise<string[]> {
+  if (!hasGlobChars(candidate)) return [candidate];
+  const matches = await expandGlob(candidate, { cwd });
+  return matches.length > 0 ? matches : [candidate];
+}
+
+/**
+ * Extract path-like candidates from a bash command string.
+ * Returns absolute paths. Best-effort: uses AST parsing with regex fallback.
+ * Does NOT filter by any policy — returns all path-like arguments.
+ */
+export async function extractBashPathCandidates(
+  command: string,
+  cwd: string,
+): Promise<string[]> {
+  const seen = new Set<string>();
+  const results: string[] = [];
+
+  const addCandidate = async (
+    token: string,
+    forcePath = false,
+  ): Promise<void> => {
+    if (!token || token.startsWith("-")) return;
+    if (!forcePath && !maybePathLike(token)) return;
+
+    const expanded = await expandCandidate(token, cwd);
+    for (const file of expanded) {
+      const abs = resolve(cwd, expandHomePath(file));
+      if (!seen.has(abs)) {
+        seen.add(abs);
+        results.push(abs);
+      }
+    }
+  };
+
+  try {
+    const { ast } = parse(command);
+    const pending: Promise<void>[] = [];
+
+    walkCommands(ast, (cmd) => {
+      const words = (cmd.words ?? []).map(wordToString);
+      for (let i = 1; i < words.length; i++) {
+        pending.push(addCandidate(words[i] as string));
+      }
+      for (const redir of cmd.redirects ?? []) {
+        pending.push(addCandidate(wordToString(redir.target), true));
+      }
+      return false;
+    });
+
+    await Promise.all(pending);
+    return results;
+  } catch {
+    // Fallback: regex tokenization
+    const tokenRegex = /"([^"]+)"|'([^']+)'|`([^`]+)`|([^\s"'`<>|;&]+)/g;
+    for (const match of command.matchAll(tokenRegex)) {
+      const token = match[1] ?? match[2] ?? match[3] ?? match[4] ?? "";
+      if (token && !token.startsWith("-") && maybePathLike(token)) {
+        const expanded = await expandCandidate(token, cwd);
+        for (const file of expanded) {
+          const abs = resolve(cwd, expandHomePath(file));
+          if (!seen.has(abs)) {
+            seen.add(abs);
+            results.push(abs);
+          }
+        }
+      }
+    }
+    return results;
+  }
+}

package/src/utils/events.ts

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

package/src/utils/migration.ts

@@ -21,7 +21,7 @@ import { pendingWarnings } from "./warnings";
  * Keep this independent from package.json version.
  * Bump only when config schema/default migration markers change.
  */
-export const CURRENT_VERSION = "0.8.0-20260228";
+export const CURRENT_VERSION = "0.9.0-20260327";
 
 /**
  * Check if a config needs migration (no version field = v0).
@@ -97,6 +97,60 @@ export function needsEnvFilesToPoliciesMigration(
   return features?.protectEnvFiles !== undefined;
 }
 
+/**
+ * Check if config needs applyBuiltinDefaults bridge migration.
+ * This runs only for existing config files loaded by ConfigLoader.
+ */
+export function needsApplyBuiltinDefaultsMigration(
+  config: GuardrailsConfig,
+): boolean {
+  return config.applyBuiltinDefaults === undefined;
+}
+
+/**
+ * Bridge migration for defaults deprecation.
+ * Existing config files get applyBuiltinDefaults=true to preserve behavior.
+ */
+export function migrateApplyBuiltinDefaults(
+  config: GuardrailsConfig,
+): GuardrailsConfig {
+  const migrated = structuredClone(config);
+  migrated.applyBuiltinDefaults = true;
+  migrated.version = CURRENT_VERSION;
+
+  pendingWarnings.push(
+    "Guardrails config was migrated. `applyBuiltinDefaults` was set to `true` to preserve current behavior.",
+  );
+
+  return migrated;
+}
+
+export function needsOnboardingDoneMigration(
+  config: GuardrailsConfig,
+): boolean {
+  return (
+    config.onboarding?.completed === undefined &&
+    config.applyBuiltinDefaults !== undefined
+  );
+}
+
+export function migrateMarkOnboardingDone(
+  config: GuardrailsConfig,
+): GuardrailsConfig {
+  const migrated = structuredClone(config);
+  pendingWarnings.push(
+    "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;
+}
+
 /**
  * Migrate deprecated envFiles/protectEnvFiles fields to policies.
  */

package/src/utils/path-access.test.ts

@@ -0,0 +1,154 @@
+import { assert, describe, expect, it } from "vitest";
+import {
+  checkPathAccess,
+  isPathAllowed,
+  type PathAccessState,
+} from "./path-access";
+
+describe("isPathAllowed", () => {
+  describe("when allowedPaths is empty", () => {
+    it("returns false", () => {
+      expect(isPathAllowed("/foo/bar", [])).toBe(false);
+    });
+  });
+
+  describe("when entry is an exact file grant", () => {
+    it.each([
+      { desc: "matches the exact file", path: "/foo/bar", expected: true },
+      {
+        desc: "does not match a sibling file",
+        path: "/foo/other",
+        expected: false,
+      },
+      {
+        desc: "does not match the containing directory",
+        path: "/foo",
+        expected: false,
+      },
+    ])("$desc", ({ path, expected }) => {
+      expect(isPathAllowed(path, ["/foo/bar"])).toBe(expected);
+    });
+  });
+
+  describe("when entry is a directory grant (trailing /)", () => {
+    it.each([
+      {
+        desc: "matches the directory itself",
+        path: "/foo/bar",
+        expected: true,
+      },
+      { desc: "matches a direct child", path: "/foo/bar/baz", expected: true },
+      {
+        desc: "matches a grandchild",
+        path: "/foo/bar/baz/qux",
+        expected: true,
+      },
+      {
+        desc: "does not match a prefix-collision path like /foo/barbaz",
+        path: "/foo/barbaz",
+        expected: false,
+      },
+    ])("$desc", ({ path, expected }) => {
+      expect(isPathAllowed(path, ["/foo/bar/"])).toBe(expected);
+    });
+  });
+
+  describe("when allowedPaths has multiple entries", () => {
+    it("returns true if any entry matches", () => {
+      expect(isPathAllowed("/b", ["/a", "/b"])).toBe(true);
+    });
+
+    it.each([
+      { path: "/foo/file.ts", expected: true },
+      { path: "/bar/anything", expected: true },
+      { path: "/foo/other.ts", expected: false },
+      { path: "/baz", expected: false },
+    ])("with mixed file + directory grants, returns $expected for $path", ({
+      path,
+      expected,
+    }) => {
+      expect(isPathAllowed(path, ["/foo/file.ts", "/bar/"])).toBe(expected);
+    });
+  });
+});
+
+describe("checkPathAccess", () => {
+  const cwd = "/work/project";
+  const base = (overrides: Partial<PathAccessState> = {}): PathAccessState => ({
+    cwd,
+    mode: "ask",
+    allowedPaths: [],
+    hasUI: true,
+    ...overrides,
+  });
+
+  describe("when mode is allow", () => {
+    it("always returns allow, even for paths outside cwd and without UI", () => {
+      const state = base({ mode: "allow", hasUI: false, allowedPaths: [] });
+      expect(checkPathAccess("/etc/hosts", "/etc/hosts", state).kind).toBe(
+        "allow",
+      );
+      expect(checkPathAccess("/work/project/src", "src", state).kind).toBe(
+        "allow",
+      );
+    });
+  });
+
+  describe("when path is inside cwd", () => {
+    it.each([
+      { mode: "block" as const },
+      { mode: "ask" as const },
+    ])("returns allow in $mode mode", ({ mode }) => {
+      const state = base({ mode });
+      expect(
+        checkPathAccess("/work/project/src/file", "src/file", state).kind,
+      ).toBe("allow");
+    });
+
+    it("returns allow when path equals cwd", () => {
+      expect(checkPathAccess(cwd, ".", base({ mode: "ask" })).kind).toBe(
+        "allow",
+      );
+    });
+  });
+
+  describe("when path is outside cwd and mode is block", () => {
+    it("returns deny with the displayPath in the reason", () => {
+      const state = base({ mode: "block" });
+      const decision = checkPathAccess("/etc/hosts", "/etc/hosts", state);
+      assert(decision.kind === "deny", "expected deny decision");
+      expect(decision.reason).toContain("/etc/hosts");
+    });
+
+    it("returns allow when the path is in allowedPaths", () => {
+      const state = base({ mode: "block", allowedPaths: ["/etc/hosts"] });
+      expect(checkPathAccess("/etc/hosts", "/etc/hosts", state).kind).toBe(
+        "allow",
+      );
+    });
+  });
+
+  describe("when path is outside cwd and mode is ask", () => {
+    it("returns ask with displayPath when UI is available", () => {
+      const state = base({ mode: "ask", hasUI: true });
+      const decision = checkPathAccess("/etc/hosts", "/etc/hosts", state);
+      assert(decision.kind === "ask", "expected ask decision");
+      expect(decision.displayPath).toBe("/etc/hosts");
+      expect(decision.absolutePath).toBe("/etc/hosts");
+    });
+
+    it("returns deny with a 'no UI' reason when UI is unavailable", () => {
+      const state = base({ mode: "ask", hasUI: false });
+      const decision = checkPathAccess("/etc/hosts", "/etc/hosts", state);
+      assert(decision.kind === "deny", "expected deny decision");
+      expect(decision.reason).toContain("no UI");
+    });
+
+    it("returns allow when the path is in allowedPaths (no prompt)", () => {
+      const state = base({ mode: "ask", allowedPaths: ["/etc/hosts"] });
+      expect(checkPathAccess("/etc/hosts", "/etc/hosts", state).kind).toBe(
+        "allow",
+      );
+    });
+  });
+});

package/src/utils/path-access.ts

@@ -0,0 +1,62 @@
+import { isWithinBoundary } from "./path";
+
+export type PathDecision =
+  | { kind: "allow" }
+  | { kind: "deny"; reason: string }
+  | { kind: "ask"; absolutePath: string; displayPath: string };
+
+export interface PathAccessState {
+  cwd: string;
+  mode: "allow" | "ask" | "block";
+  allowedPaths: string[]; // already resolved to absolute, with trailing / convention
+  hasUI: boolean;
+}
+
+/**
+ * Check if an absolute path is covered by the allowedPaths list.
+ * - Entries ending in "/" are directory grants (boundary/prefix match).
+ * - Entries without trailing "/" are exact file grants.
+ */
+export function isPathAllowed(
+  absPath: string,
+  allowedPaths: string[],
+): boolean {
+  for (const entry of allowedPaths) {
+    if (entry.endsWith("/")) {
+      const dirPath = entry.slice(0, -1);
+      if (isWithinBoundary(absPath, dirPath)) return true;
+    } else {
+      if (absPath === entry) return true;
+    }
+  }
+  return false;
+}
+
+export function checkPathAccess(
+  absolutePath: string,
+  displayPath: string,
+  state: PathAccessState,
+): PathDecision {
+  if (state.mode === "allow") return { kind: "allow" };
+
+  if (isWithinBoundary(absolutePath, state.cwd)) return { kind: "allow" };
+
+  if (isPathAllowed(absolutePath, state.allowedPaths)) return { kind: "allow" };
+
+  if (state.mode === "block") {
+    return {
+      kind: "deny",
+      reason: `Access to ${displayPath} is blocked (outside working directory).`,
+    };
+  }
+
+  // mode === "ask"
+  if (!state.hasUI) {
+    return {
+      kind: "deny",
+      reason: `Access to ${displayPath} is blocked (outside working directory, no UI to confirm).`,
+    };
+  }
+
+  return { kind: "ask", absolutePath, displayPath };
+}

package/src/utils/path.test.ts

@@ -0,0 +1,177 @@
+import { homedir } from "node:os";
+import { describe, expect, it } from "vitest";
+import {
+  expandHomePath,
+  isWithinBoundary,
+  normalizeForDisplay,
+  resolveFromCwd,
+  toStorageForm,
+} from "./path";
+
+const HOME = homedir();
+
+describe("expandHomePath", () => {
+  it.each([
+    { desc: "bare ~", input: "~", expected: HOME },
+    { desc: "~/foo", input: "~/foo", expected: `${HOME}/foo` },
+    {
+      desc: "~\\foo (Windows tilde)",
+      input: "~\\foo",
+      expected: `${HOME}/foo`,
+    },
+    {
+      desc: "an absolute path",
+      input: "/absolute/path",
+      expected: "/absolute/path",
+    },
+    {
+      desc: "a relative path",
+      input: "relative/path",
+      expected: "relative/path",
+    },
+    { desc: "an empty string", input: "", expected: "" },
+  ])("given $desc, returns the expanded path", ({ input, expected }) => {
+    expect(expandHomePath(input)).toBe(expected);
+  });
+});
+
+describe("resolveFromCwd", () => {
+  const cwd = "/some/cwd";
+
+  it.each([
+    {
+      desc: "a relative path",
+      input: "sub/file",
+      expected: "/some/cwd/sub/file",
+    },
+    { desc: "an absolute path", input: "/etc/hosts", expected: "/etc/hosts" },
+    { desc: "a ~ path", input: "~/foo", expected: `${HOME}/foo` },
+    { desc: "'.'", input: ".", expected: "/some/cwd" },
+  ])("given $desc, resolves against cwd", ({ input, expected }) => {
+    expect(resolveFromCwd(input, cwd)).toBe(expected);
+  });
+});
+
+describe("isWithinBoundary", () => {
+  it.each([
+    {
+      desc: "paths are identical",
+      target: "/foo/bar",
+      root: "/foo/bar",
+      expected: true,
+    },
+    {
+      desc: "target is a direct child",
+      target: "/foo/bar/baz",
+      root: "/foo/bar",
+      expected: true,
+    },
+    {
+      desc: "target is a grandchild",
+      target: "/foo/bar/baz/qux",
+      root: "/foo/bar",
+      expected: true,
+    },
+    {
+      desc: "target is a parent",
+      target: "/foo",
+      root: "/foo/bar",
+      expected: false,
+    },
+    {
+      desc: "target is a sibling",
+      target: "/foo/other",
+      root: "/foo/bar",
+      expected: false,
+    },
+    {
+      desc: "target shares a string prefix but is not a child (critical case)",
+      target: "/foo/barbaz",
+      root: "/foo/bar",
+      expected: false,
+    },
+    {
+      desc: "paths are completely unrelated",
+      target: "/tmp",
+      root: "/home/user",
+      expected: false,
+    },
+  ])("when $desc, returns $expected", ({ target, root, expected }) => {
+    expect(isWithinBoundary(target, root)).toBe(expected);
+  });
+});
+
+describe("normalizeForDisplay", () => {
+  const cwd = "/work/project";
+
+  it.each([
+    { desc: "path equals cwd", input: cwd, expected: "." },
+    {
+      desc: "path is a child of cwd",
+      input: "/work/project/src/file.ts",
+      expected: "src/file.ts",
+    },
+    {
+      desc: "path is under home but not cwd",
+      input: `${HOME}/config/file`,
+      expected: "~/config/file",
+    },
+    {
+      desc: "path is outside both cwd and home",
+      input: "/etc/hosts",
+      expected: "/etc/hosts",
+    },
+    { desc: "path is home itself", input: HOME, expected: "~" },
+  ])("when $desc, returns $expected", ({ input, expected }) => {
+    expect(normalizeForDisplay(input, cwd)).toBe(expected);
+  });
+});
+
+describe("toStorageForm", () => {
+  it.each([
+    {
+      desc: "file under home",
+      absPath: `${HOME}/code/file.ts`,
+      isDirectory: false,
+      expected: "~/code/file.ts",
+    },
+    {
+      desc: "directory under home",
+      absPath: `${HOME}/code`,
+      isDirectory: true,
+      expected: "~/code/",
+    },
+    {
+      desc: "absolute file outside home",
+      absPath: "/etc/hosts",
+      isDirectory: false,
+      expected: "/etc/hosts",
+    },
+    {
+      desc: "absolute directory outside home",
+      absPath: "/etc",
+      isDirectory: true,
+      expected: "/etc/",
+    },
+    {
+      desc: "input has trailing slash but isDirectory=false",
+      absPath: "/etc/hosts/",
+      isDirectory: false,
+      expected: "/etc/hosts",
+    },
+    {
+      desc: "input uses Windows backslashes",
+      absPath: "C:\\Users\\foo",
+      isDirectory: false,
+      expected: "C:/Users/foo",
+    },
+    {
+      desc: "input is home itself with isDirectory=true",
+      absPath: HOME,
+      isDirectory: true,
+      expected: "~/",
+    },
+  ])("when $desc, returns $expected", ({ absPath, isDirectory, expected }) => {
+    expect(toStorageForm(absPath, isDirectory)).toBe(expected);
+  });
+});