@aliou/pi-guardrails 0.11.2 → 0.12.1

package/{src → extensions/guardrails}/components/pattern-editor.ts

@@ -1,11 +1,12 @@
-import type { Component, SettingsListTheme } from "@mariozechner/pi-tui";
+import type { Component, SettingsListTheme } from "@earendil-works/pi-tui";
 import {
   Input,
   Key,
   matchesKey,
   truncateToWidth,
   visibleWidth,
-} from "@mariozechner/pi-tui";
+} from "@earendil-works/pi-tui";
+import type { Action } from "../../../src/core";
 
 /**
  * A submenu component for editing an array of {pattern, description, regex?} objects.
@@ -16,7 +17,7 @@ import {
  *            Escape to cancel.
  */
 
-export interface PatternItem {
+export interface EditorPatternItem {
   pattern: string;
   description: string;
   regex?: boolean;
@@ -24,24 +25,24 @@ export interface PatternItem {
 
 export interface PatternEditorOptions {
   label: string;
-  items: PatternItem[];
+  items: EditorPatternItem[];
   theme: SettingsListTheme;
-  onSave: (items: PatternItem[]) => void;
+  onSave: (items: EditorPatternItem[]) => void;
   onDone: () => void;
   /** Context hint for the pattern field label. */
-  context?: "file" | "command";
+  context?: Action["kind"];
   maxVisible?: number;
 }
 
 type Field = "pattern" | "description" | "regex";
 
 export class PatternEditor implements Component {
-  private items: PatternItem[];
+  private items: EditorPatternItem[];
   private label: string;
   private theme: SettingsListTheme;
-  private onSave: (items: PatternItem[]) => void;
+  private onSave: (items: EditorPatternItem[]) => void;
   private onDone: () => void;
-  private context: "file" | "command";
+  private context: Action["kind"];
   private selectedIndex = 0;
   private maxVisible: number;
   private mode: "list" | "add" | "edit" = "list";
@@ -98,7 +99,7 @@ export class PatternEditor implements Component {
       return;
     }
 
-    const item: PatternItem = {
+    const item: EditorPatternItem = {
       pattern,
       description: description || pattern,
     };

package/extensions/guardrails/index.ts

@@ -0,0 +1,106 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { checkAction } from "../../src/core";
+import { configLoader } from "../../src/shared/config";
+import {
+  createFeatureRequestPayload,
+  emitActionBlocked,
+  GUARDRAILS_FEATURE_REGISTER_EVENT,
+  GUARDRAILS_FEATURE_REQUEST_EVENT,
+  type GuardrailsFeatureId,
+  type GuardrailsFeatureRegisterPayload,
+} from "../../src/shared/events";
+import { drainPendingWarnings } from "../../src/shared/warnings";
+import { registerGuardrailsExamplesCommand } from "./commands/examples";
+import { registerGuardrailsOnboardingCommand } from "./commands/onboarding";
+import { isOnboardingPending } from "./commands/onboarding/config";
+import { registerGuardrailsSettings } from "./commands/settings";
+import {
+  BLOCKED_TOOLS,
+  compilePolicies,
+  createPolicyRules,
+  protectionRank,
+} from "./rules";
+import { extractTargets } from "./targets";
+
+function setupPolicyHook(pi: ExtensionAPI): void {
+  pi.on("tool_call", async (event, ctx) => {
+    const config = configLoader.getConfig();
+    if (!config.enabled || !config.features.policies) return;
+
+    const policies = compilePolicies(config.policies.rules)
+      .filter((policy) => BLOCKED_TOOLS[policy.protection].has(event.toolName))
+      .sort(
+        (a, b) => protectionRank(b.protection) - protectionRank(a.protection),
+      );
+    if (policies.length === 0) return;
+
+    const input = event.input as Record<string, unknown>;
+    const targets = await extractTargets(
+      { toolName: event.toolName, input },
+      ctx.cwd,
+      policies,
+    );
+    const rules = createPolicyRules(policies, ctx.cwd);
+
+    for (const target of targets) {
+      const safety = await checkAction(
+        { kind: "file", path: target, origin: event.toolName },
+        rules,
+      );
+      if (safety.kind === "safe") continue;
+
+      emitActionBlocked(pi, {
+        feature: "policies",
+        action: safety.action,
+        reason: safety.reason,
+        block: { source: "policy", metadata: safety.metadata },
+        context: { toolName: event.toolName, input },
+      });
+      return { block: true, reason: safety.reason };
+    }
+  });
+}
+
+export default async function guardrails(pi: ExtensionAPI) {
+  await configLoader.load();
+
+  const loadedFeatures = new Set<GuardrailsFeatureId>(["policies"]);
+
+  pi.events.on(GUARDRAILS_FEATURE_REGISTER_EVENT, (data: unknown) => {
+    const payload = data as GuardrailsFeatureRegisterPayload;
+    loadedFeatures.add(payload.feature.id);
+  });
+
+  registerGuardrailsSettings(pi, {
+    getLoadedFeatures: () => loadedFeatures,
+  });
+
+  registerGuardrailsExamplesCommand(pi);
+  if (isOnboardingPending(configLoader.getRawConfig("global"))) {
+    registerGuardrailsOnboardingCommand(pi);
+  }
+  setupPolicyHook(pi);
+
+  pi.on("session_start", (_event, ctx) => {
+    loadedFeatures.clear();
+    loadedFeatures.add("policies");
+
+    pi.events.emit(
+      GUARDRAILS_FEATURE_REQUEST_EVENT,
+      createFeatureRequestPayload(),
+    );
+
+    const warnings = drainPendingWarnings();
+    if (warnings.length === 1) {
+      ctx.ui.notify(warnings[0], "warning");
+    } else if (warnings.length > 1) {
+      ctx.ui.notify(
+        [
+          "Guardrails warnings:",
+          ...warnings.map((warning) => `- ${warning}`),
+        ].join("\n"),
+        "warning",
+      );
+    }
+  });
+}

package/extensions/guardrails/rules.test.ts

@@ -0,0 +1,107 @@
+import { join } from "node:path";
+import { vol } from "memfs";
+import { describe, expect, it } from "vitest";
+import { compilePolicies, createPolicyRules, normalizeTarget } from "./rules";
+
+function singleRule(
+  cwd: string,
+  policy: Parameters<typeof compilePolicies>[0][number],
+) {
+  const [rule] = createPolicyRules(compilePolicies([policy]), cwd);
+  return rule;
+}
+
+describe("normalizeTarget", () => {
+  it("prefers cwd-relative paths for targets inside cwd", () => {
+    const cwd = "/repo";
+    expect(normalizeTarget("/repo/config/locked.json", cwd)).toBe(
+      "config/locked.json",
+    );
+  });
+});
+
+describe("compilePolicies", () => {
+  it("skips disabled and empty rules", () => {
+    const policies = compilePolicies([
+      {
+        id: "disabled",
+        name: "Disabled",
+        enabled: false,
+        patterns: [{ pattern: "*.env" }],
+        protection: "noAccess",
+      },
+      { id: "empty", name: "Empty", patterns: [], protection: "noAccess" },
+      {
+        id: "active",
+        name: "Active",
+        patterns: [{ pattern: "*.env" }],
+        protection: "readOnly",
+      },
+    ]);
+
+    expect(policies.map((policy) => policy.id)).toEqual(["active"]);
+  });
+});
+
+describe("createPolicyRules", () => {
+  const cwd = "/repo";
+
+  it("matches protected files and returns policy metadata", async () => {
+    vol.fromJSON({ "/repo/.env": "SECRET=1" });
+    const rule = singleRule(cwd, {
+      id: "secrets",
+      name: "Secrets",
+      patterns: [{ pattern: ".env" }],
+      protection: "noAccess",
+    });
+
+    await expect(
+      rule.check({ kind: "file", path: join(cwd, ".env") }),
+    ).resolves.toMatchObject({
+      kind: "match",
+      metadata: { ruleId: "secrets", protection: "noAccess", path: ".env" },
+    });
+  });
+
+  it("passes allowed patterns", async () => {
+    vol.fromJSON({ "/repo/.env.example": "SECRET=" });
+    const rule = singleRule(cwd, {
+      id: "secrets",
+      name: "Secrets",
+      patterns: [{ pattern: ".env*" }],
+      allowedPatterns: [{ pattern: ".env.example" }],
+      protection: "noAccess",
+    });
+
+    await expect(
+      rule.check({ kind: "file", path: join(cwd, ".env.example") }),
+    ).resolves.toEqual({ kind: "pass" });
+  });
+
+  it("passes missing files when onlyIfExists is true", async () => {
+    const rule = singleRule(cwd, {
+      id: "secrets",
+      name: "Secrets",
+      patterns: [{ pattern: ".env" }],
+      protection: "noAccess",
+    });
+
+    await expect(
+      rule.check({ kind: "file", path: join(cwd, ".env") }),
+    ).resolves.toEqual({ kind: "pass" });
+  });
+
+  it("matches missing files when onlyIfExists is false", async () => {
+    const rule = singleRule(cwd, {
+      id: "secrets",
+      name: "Secrets",
+      patterns: [{ pattern: ".env" }],
+      protection: "noAccess",
+      onlyIfExists: false,
+    });
+
+    await expect(
+      rule.check({ kind: "file", path: join(cwd, ".env") }),
+    ).resolves.toMatchObject({ kind: "match" });
+  });
+});

package/extensions/guardrails/rules.ts

@@ -0,0 +1,119 @@
+import { stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import type { Action, Rule } from "../../src/core";
+import { expandHomePath } from "../../src/core/paths";
+import type { PolicyRule, Protection } from "../../src/shared/config";
+import {
+  type CompiledPattern,
+  compileFilePatterns,
+  normalizeFilePath,
+} from "../../src/shared/matching";
+
+export type PolicyMeta = {
+  ruleId: string;
+  protection: Protection;
+  path: string;
+};
+
+export type CompiledPolicy = {
+  id: string;
+  protection: Protection;
+  patterns: CompiledPattern[];
+  allowedPatterns: CompiledPattern[];
+  onlyIfExists: boolean;
+  blockMessage: string;
+};
+
+const DEFAULT_BLOCK_MESSAGES: Record<Protection, string> = {
+  noAccess:
+    "Accessing {file} is not allowed. This file is protected. Ask the user if changes are needed.",
+  readOnly:
+    "Writing to {file} is not allowed. This file is read-only. Use the read tool to inspect it instead.",
+  none: "",
+};
+
+export const BLOCKED_TOOLS: Record<Protection, Set<string>> = {
+  noAccess: new Set(["read", "write", "edit", "bash", "grep", "find", "ls"]),
+  readOnly: new Set(["write", "edit", "bash"]),
+  none: new Set(),
+};
+
+export function compilePolicies(rules: PolicyRule[]): CompiledPolicy[] {
+  return rules
+    .filter((rule) => rule.enabled ?? true)
+    .filter((rule) => rule.id.trim() && rule.patterns.length > 0)
+    .map((rule) => ({
+      id: rule.id,
+      protection: rule.protection,
+      patterns: compileFilePatterns(rule.patterns),
+      allowedPatterns: compileFilePatterns(rule.allowedPatterns ?? []),
+      onlyIfExists: rule.onlyIfExists ?? true,
+      blockMessage:
+        rule.blockMessage ?? DEFAULT_BLOCK_MESSAGES[rule.protection],
+    }));
+}
+
+export function protectionRank(protection: Protection): number {
+  if (protection === "noAccess") return 2;
+  if (protection === "readOnly") return 1;
+  return 0;
+}
+
+export function normalizeTarget(filePath: string, cwd: string): string {
+  if (filePath === "~" || filePath.startsWith("~/")) {
+    return normalizeFilePath(filePath);
+  }
+
+  const expanded = expandHomePath(filePath);
+  const absolute = resolve(cwd, expanded);
+  const rel = relative(cwd, absolute);
+  if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel))) {
+    return normalizeFilePath(rel || ".");
+  }
+
+  const normalizedHome = normalizeFilePath(expandHomePath("~"));
+  const normalizedAbsolute = normalizeFilePath(absolute);
+
+  if (normalizedAbsolute.startsWith(`${normalizedHome}/`)) {
+    return normalizeFilePath(`~/${relative(expandHomePath("~"), absolute)}`);
+  }
+
+  return normalizeFilePath(absolute);
+}
+
+async function fileExists(filePath: string, cwd: string): Promise<boolean> {
+  try {
+    await stat(resolve(cwd, expandHomePath(filePath)));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function createPolicyRules(
+  policies: CompiledPolicy[],
+  cwd: string,
+): Rule<PolicyMeta>[] {
+  return policies.map((policy) => ({
+    key: `policies.${policy.id}`,
+    async check(action: Action) {
+      if (action.kind !== "file") return { kind: "pass" };
+      const path = normalizeTarget(action.path, cwd);
+      if (!policy.patterns.some((pattern) => pattern.test(path))) {
+        return { kind: "pass" };
+      }
+      if (policy.allowedPatterns.some((pattern) => pattern.test(path))) {
+        return { kind: "pass" };
+      }
+      if (policy.onlyIfExists && !(await fileExists(path, cwd))) {
+        return { kind: "pass" };
+      }
+      if (policy.protection === "none") return { kind: "pass" };
+      return {
+        kind: "match",
+        reason: policy.blockMessage.replace("{file}", path),
+        metadata: { ruleId: policy.id, protection: policy.protection, path },
+      };
+    },
+  }));
+}

package/extensions/guardrails/targets.test.ts

@@ -0,0 +1,44 @@
+import { join } from "node:path";
+import { vol } from "memfs";
+import { describe, expect, it } from "vitest";
+import { compilePolicies } from "./rules";
+import { extractTargets } from "./targets";
+
+describe("extractTargets", () => {
+  it("returns direct file tool targets", async () => {
+    await expect(
+      extractTargets(
+        { toolName: "read", input: { path: "config/locked.json" } },
+        "/repo",
+        [],
+      ),
+    ).resolves.toEqual(["config/locked.json"]);
+  });
+
+  it("extracts only bash targets matching configured policies", async () => {
+    const cwd = "/repo";
+    vol.fromJSON({
+      "/repo/config/locked.json": "{}",
+      "/repo/README.md": "hello",
+    });
+    const policies = compilePolicies([
+      {
+        id: "locked",
+        name: "Locked",
+        patterns: [{ pattern: "config/locked.json" }],
+        protection: "readOnly",
+      },
+    ]);
+
+    await expect(
+      extractTargets(
+        {
+          toolName: "bash",
+          input: { command: "cat README.md config/locked.json" },
+        },
+        cwd,
+        policies,
+      ),
+    ).resolves.toEqual([join("config", "locked.json")]);
+  });
+});

package/extensions/guardrails/targets.ts

@@ -0,0 +1,66 @@
+import { parse } from "@aliou/sh";
+import { maybePathLike } from "../../src/core/paths";
+import { walkCommands, wordToString } from "../../src/core/shell";
+import { expandGlob, hasGlobChars } from "../../src/shared/glob";
+import type { CompiledPolicy } from "./rules";
+import { normalizeTarget } from "./rules";
+
+async function expandCandidate(candidate: string): Promise<string[]> {
+  if (!hasGlobChars(candidate)) return [candidate];
+  const matches = await expandGlob(candidate);
+  return matches.length > 0 ? matches : [candidate];
+}
+
+export async function extractTargets(
+  event: { toolName: string; input: Record<string, unknown> },
+  cwd: string,
+  policies: CompiledPolicy[],
+): Promise<string[]> {
+  if (
+    ["read", "write", "edit", "grep", "find", "ls"].includes(event.toolName)
+  ) {
+    const target = String(
+      event.input.file_path ?? event.input.path ?? "",
+    ).trim();
+    return target ? [target] : [];
+  }
+
+  if (event.toolName !== "bash") return [];
+  const command = String(event.input.command ?? "");
+  const targets = new Set<string>();
+  const maybeAdd = async (candidate: string) => {
+    if (!candidate || candidate.startsWith("-")) return;
+    for (const file of await expandCandidate(candidate)) {
+      const normalized = normalizeTarget(file, cwd);
+      if (
+        policies.some((policy) =>
+          policy.patterns.some((pattern) => pattern.test(normalized)),
+        )
+      ) {
+        targets.add(file);
+      }
+    }
+  };
+
+  try {
+    const { ast } = parse(command);
+    const pending: Promise<void>[] = [];
+    walkCommands(ast, (cmd) => {
+      const words = (cmd.words ?? []).map(wordToString);
+      for (const word of words.slice(1)) pending.push(maybeAdd(word));
+      for (const redir of cmd.redirects ?? []) {
+        pending.push(maybeAdd(wordToString(redir.target)));
+      }
+      return false;
+    });
+    await Promise.all(pending);
+  } catch {
+    const tokenRegex = /"([^"]+)"|'([^']+)'|`([^`]+)`|([^\s"'`<>|;&]+)/g;
+    for (const match of command.matchAll(tokenRegex)) {
+      const token = match[1] ?? match[2] ?? match[3] ?? match[4] ?? "";
+      if (maybePathLike(token)) await maybeAdd(token);
+    }
+  }
+
+  return [...targets];
+}

package/extensions/path-access/grants.test.ts

@@ -0,0 +1,47 @@
+import { homedir } from "node:os";
+import { describe, expect, it } from "vitest";
+import {
+  createPendingGrant,
+  isGrantTooBroad,
+  pendingAllowedPaths,
+  resolveAllowedPaths,
+} from "./grants";
+
+describe("path access grants", () => {
+  it("resolves allowed paths relative to cwd", () => {
+    expect(resolveAllowedPaths(["../shared", "logs/"], "/repo/app")).toEqual([
+      "/repo/shared",
+      "/repo/app/logs/",
+    ]);
+  });
+
+  it("converts pending grants to absolute allowed paths", () => {
+    expect(
+      pendingAllowedPaths([
+        {
+          storagePath: "/tmp/file.txt",
+          absolutePath: "/tmp/file.txt",
+          scope: "memory",
+        },
+        {
+          storagePath: "/tmp/logs/",
+          absolutePath: "/tmp/logs",
+          scope: "local",
+        },
+      ]),
+    ).toEqual(["/tmp/file.txt", "/tmp/logs/"]);
+  });
+
+  it("rejects home grants as too broad", () => {
+    expect(isGrantTooBroad(`${homedir()}/`)).toBe(true);
+    expect(isGrantTooBroad(`${homedir()}/project`)).toBe(false);
+  });
+
+  it("creates pending grants with storage form", () => {
+    expect(createPendingGrant("/tmp/logs", true, "local")).toEqual({
+      absolutePath: "/tmp/logs",
+      scope: "local",
+      storagePath: "/tmp/logs/",
+    });
+  });
+});

package/extensions/path-access/grants.ts

@@ -0,0 +1,68 @@
+import { homedir } from "node:os";
+import { resolveFromCwd, toStorageForm } from "../../src/core/paths";
+import { configLoader } from "../../src/shared/config";
+
+export type PendingPathGrant = {
+  storagePath: string;
+  scope: "memory" | "local";
+  absolutePath: string;
+};
+
+export function resolveAllowedPaths(
+  allowedPaths: string[],
+  cwd: string,
+): string[] {
+  return allowedPaths.map((path) => {
+    const isDir = path.endsWith("/");
+    const resolved = resolveFromCwd(isDir ? path.slice(0, -1) : path, cwd);
+    return isDir ? `${resolved}/` : resolved;
+  });
+}
+
+export function pendingAllowedPaths(grants: PendingPathGrant[]): string[] {
+  return grants.map((grant) =>
+    grant.storagePath.endsWith("/")
+      ? `${grant.absolutePath}/`
+      : grant.absolutePath,
+  );
+}
+
+export function isGrantTooBroad(absPath: string): boolean {
+  const normalized = absPath.replace(/[\\/]+$/, "");
+  return normalized === "/" || normalized === homedir();
+}
+
+export function createPendingGrant(
+  absolutePath: string,
+  isDirectory: boolean,
+  scope: "memory" | "local",
+): PendingPathGrant {
+  return {
+    absolutePath,
+    scope,
+    storagePath: toStorageForm(absolutePath, isDirectory),
+  };
+}
+
+export async function persistGrant(grant: PendingPathGrant): Promise<void> {
+  const raw = (configLoader.getRawConfig(grant.scope) ?? {}) as Record<
+    string,
+    unknown
+  >;
+  const pathAccess = (raw.pathAccess ?? {}) as Record<string, unknown>;
+  const existing = Array.isArray(pathAccess.allowedPaths)
+    ? pathAccess.allowedPaths.filter(
+        (path): path is string => typeof path === "string",
+      )
+    : [];
+
+  if (existing.includes(grant.storagePath)) return;
+
+  await configLoader.save(grant.scope, {
+    ...raw,
+    pathAccess: {
+      ...pathAccess,
+      allowedPaths: [...existing, grant.storagePath],
+    },
+  });
+}