@gotgenes/pi-permission-system 16.2.0 → 17.0.0

package/src/handlers/permission-gate-handler.ts

@@ -2,8 +2,6 @@ import type {
   ExtensionContext,
   InputEventResult,
 } from "@earendil-works/pi-coding-agent";
-
-import { toRecord } from "#src/common";
 import {
   formatMissingToolNameReason,
   formatUnknownToolReason,
@@ -14,6 +12,7 @@ import {
   getToolNameFromValue,
   type ToolRegistry,
 } from "#src/tool-registry";
+import { toRecord } from "#src/value-guards";
 import type { GateRunner } from "./gates/runner";
 import type {
   GateNotifier,

package/src/handlers/tool-call-boundary.ts

@@ -1,8 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-
-import { toRecord } from "#src/common";
 import type { DecisionRecorder } from "#src/decision-audit";
 import type { DecisionReporter } from "#src/decision-reporter";
+import { toRecord } from "#src/value-guards";
 import type { GateOutcome } from "./gates/types";
 
 /** The SDK-facing result shape for a `tool_call` handler. */

package/src/input-normalizer.ts

@@ -1,7 +1,7 @@
 import { stripBashCommentLines } from "./bash-arity";
-import { getNonEmptyString, toRecord } from "./common";
 import { createMcpPermissionTargets } from "./mcp-targets";
 import { getPathPolicyValues, PATH_BEARING_TOOLS } from "./path-utils";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 /**
  * Construct a surface-appropriate input object from a raw value string.

package/src/mcp-targets.ts

@@ -1,4 +1,4 @@
-import { getNonEmptyString, toRecord } from "./common";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 /**
  * An ordered accumulator that owns the uniqueness invariant.

package/src/normalize.ts

@@ -1,6 +1,6 @@
-import { isDenyWithReason, isPermissionState } from "./common";
 import type { Rule, Ruleset } from "./rule";
 import type { FlatPermissionConfig } from "./types";
+import { isDenyWithReason, isPermissionState } from "./value-guards";
 
 /**
  * Convert a flat permission config into a Ruleset.

package/src/path-utils.ts

@@ -8,9 +8,9 @@ import {
 } from "node:path";
 
 import { canonicalizePath } from "./canonicalize-path";
-import { getNonEmptyString, toRecord } from "./common";
 import { expandHomePath } from "./expand-home";
 import type { ToolAccessExtractorLookup } from "./tool-access-extractor-registry";
+import { getNonEmptyString, toRecord } from "./value-guards";
 import { wildcardMatch } from "./wildcard-matcher";
 
 export function normalizePathForComparison(

package/src/permission-manager.ts

@@ -1,6 +1,5 @@
 import { join } from "node:path";
 import type { ResolvedAccessIntent } from "./access-intent/access-intent";
-import { isPermissionState } from "./common";
 import {
   getGlobalConfigPath,
   getProjectAgentsDir,
@@ -28,6 +27,7 @@ import type {
   PermissionCheckResult,
   PermissionState,
 } from "./types";
+import { isPermissionState } from "./value-guards";
 
 const BUILT_IN_TOOL_PERMISSION_NAMES = new Set([
   "bash",

package/src/permission-prompts.ts

@@ -1,8 +1,8 @@
-import { getNonEmptyString, toRecord } from "./common";
 import { matchQualifier } from "./denial-messages";
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
 import type { ToolPreviewFormatter } from "./tool-preview-formatter";
 import type { PermissionCheckResult } from "./types";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 // NOTE: formatDenyReason, formatUserDeniedReason, and
 // formatPermissionHardStopHint have been moved to denial-messages.ts.

package/src/policy-loader.ts

@@ -1,8 +1,6 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-
-import { extractFrontmatter, parseSimpleYamlMap, toRecord } from "./common";
 import {
   loadUnifiedConfig,
   normalizeUnifiedConfig,
@@ -10,6 +8,8 @@ import {
 } from "./config-loader";
 import { getGlobalConfigPath } from "./config-paths";
 import type { ScopeConfig } from "./types";
+import { toRecord } from "./value-guards";
+import { extractFrontmatter, parseSimpleYamlMap } from "./yaml-frontmatter";
 
 // ---------------------------------------------------------------------------
 // File-stamp helper

package/src/tool-input-prompt-formatters.ts

@@ -1,5 +1,5 @@
-import { getNonEmptyString, toRecord } from "./common";
 import { countTextLines, formatCount } from "./tool-input-preview";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 export function getPromptPath(input: Record<string, unknown>): string | null {
   return getNonEmptyString(input.path) ?? getNonEmptyString(input.file_path);

package/src/tool-preview-formatter.ts

@@ -1,4 +1,3 @@
-import { getNonEmptyString, toRecord } from "./common";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ToolInputFormatterLookup } from "./tool-input-formatter-registry";
 import {
@@ -15,6 +14,7 @@ import {
   getPromptPath,
 } from "./tool-input-prompt-formatters";
 import type { PermissionCheckResult } from "./types";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 export interface ToolPreviewFormatterOptions {
   toolInputPreviewMaxLength: number;

package/src/tool-registry.ts

@@ -1,4 +1,4 @@
-import { getNonEmptyString, toRecord } from "./common";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 /** Narrow interface for the Pi tool API subset used by handler classes. */
 export interface ToolRegistry {

package/src/{common.ts → value-guards.ts}

@@ -53,69 +53,3 @@ export function isDenyWithReason(value: unknown): value is DenyWithReason {
     (record.reason === undefined || typeof record.reason === "string")
   );
 }
-
-type StackNode = { indent: number; target: Record<string, unknown> };
-
-export function parseSimpleYamlMap(input: string): Record<string, unknown> {
-  const root: Record<string, unknown> = {};
-  const stack: StackNode[] = [{ indent: -1, target: root }];
-
-  const lines = input.split(/\r?\n/);
-  for (const rawLine of lines) {
-    if (!rawLine.trim() || rawLine.trimStart().startsWith("#")) {
-      continue;
-    }
-
-    const indent = rawLine.length - rawLine.trimStart().length;
-    const line = rawLine.trim();
-    const separatorIndex = line.indexOf(":");
-    if (separatorIndex <= 0) {
-      continue;
-    }
-
-    const key = line
-      .slice(0, separatorIndex)
-      .trim()
-      .replace(/^['"]|['"]$/g, "");
-    const rawValue = line.slice(separatorIndex + 1).trim();
-
-    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
-      stack.pop();
-    }
-
-    const current = stack[stack.length - 1].target;
-
-    if (!rawValue) {
-      const child: Record<string, unknown> = {};
-      current[key] = child;
-      stack.push({ indent, target: child });
-      continue;
-    }
-
-    let scalar = rawValue;
-    if (
-      (scalar.startsWith('"') && scalar.endsWith('"')) ||
-      (scalar.startsWith("'") && scalar.endsWith("'"))
-    ) {
-      scalar = scalar.slice(1, -1);
-    }
-
-    current[key] = scalar;
-  }
-
-  return root;
-}
-
-export function extractFrontmatter(markdown: string): string {
-  const normalized = markdown.replace(/\r\n/g, "\n");
-  if (!normalized.startsWith("---\n")) {
-    return "";
-  }
-
-  const end = normalized.indexOf("\n---", 4);
-  if (end === -1) {
-    return "";
-  }
-
-  return normalized.slice(4, end);
-}

package/src/yaml-frontmatter.ts

@@ -0,0 +1,65 @@
+type StackNode = { indent: number; target: Record<string, unknown> };
+
+export function parseSimpleYamlMap(input: string): Record<string, unknown> {
+  const root: Record<string, unknown> = {};
+  const stack: StackNode[] = [{ indent: -1, target: root }];
+
+  const lines = input.split(/\r?\n/);
+  for (const rawLine of lines) {
+    if (!rawLine.trim() || rawLine.trimStart().startsWith("#")) {
+      continue;
+    }
+
+    const indent = rawLine.length - rawLine.trimStart().length;
+    const line = rawLine.trim();
+    const separatorIndex = line.indexOf(":");
+    if (separatorIndex <= 0) {
+      continue;
+    }
+
+    const key = line
+      .slice(0, separatorIndex)
+      .trim()
+      .replace(/^['"]|['"]$/g, "");
+    const rawValue = line.slice(separatorIndex + 1).trim();
+
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+
+    const current = stack[stack.length - 1].target;
+
+    if (!rawValue) {
+      const child: Record<string, unknown> = {};
+      current[key] = child;
+      stack.push({ indent, target: child });
+      continue;
+    }
+
+    let scalar = rawValue;
+    if (
+      (scalar.startsWith('"') && scalar.endsWith('"')) ||
+      (scalar.startsWith("'") && scalar.endsWith("'"))
+    ) {
+      scalar = scalar.slice(1, -1);
+    }
+
+    current[key] = scalar;
+  }
+
+  return root;
+}
+
+export function extractFrontmatter(markdown: string): string {
+  const normalized = markdown.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return "";
+  }
+
+  const end = normalized.indexOf("\n---", 4);
+  if (end === -1) {
+    return "";
+  }
+
+  return normalized.slice(4, end);
+}

package/test/access-intent/access-path.test.ts

@@ -21,7 +21,7 @@ vi.mock("node:fs", () => ({
 
 import { AccessPath } from "#src/access-intent/access-path";
 
-describe("AccessPath.forExternalDirectory", () => {
+describe("AccessPath.forPath", () => {
   const cwd = "/projects/my-app";
 
   beforeEach(() => {
@@ -35,30 +35,59 @@ describe("AccessPath.forExternalDirectory", () => {
       realpathSync.mockImplementation((p: string) =>
         p.startsWith("/tmp") ? `/private${p}` : p,
       );
-      expect(
-        AccessPath.forExternalDirectory("/tmp/x", cwd).matchValues(),
-      ).toEqual(["/tmp/x", "/private/tmp/x"]);
+      expect(AccessPath.forPath("/tmp/x", { cwd }).matchValues()).toEqual([
+        "/tmp/x",
+        "/private/tmp/x",
+      ]);
     });
 
     test("deduplicates when the canonical form equals the lexical form", () => {
-      expect(
-        AccessPath.forExternalDirectory("/etc/hosts", cwd).matchValues(),
-      ).toEqual(["/etc/hosts"]);
+      expect(AccessPath.forPath("/etc/hosts", { cwd }).matchValues()).toEqual([
+        "/etc/hosts",
+      ]);
     });
 
     test("keeps the relative aliases for an in-cwd token without duplicating", () => {
-      expect(
-        AccessPath.forExternalDirectory("src/foo.ts", cwd).matchValues(),
-      ).toEqual(["/projects/my-app/src/foo.ts", "src/foo.ts"]);
+      expect(AccessPath.forPath("src/foo.ts", { cwd }).matchValues()).toEqual([
+        "/projects/my-app/src/foo.ts",
+        "src/foo.ts",
+      ]);
     });
 
     test("includes only the lexical aliases when canonical is empty", () => {
       // Force canonicalizePath to return the original (no-op symlink resolution
       // effectively means canonical === lexical, handled by dedup).
       expect(
-        AccessPath.forExternalDirectory("/etc/hosts", cwd).matchValues(),
+        AccessPath.forPath("/etc/hosts", { cwd }).matchValues(),
       ).not.toHaveLength(0);
     });
+
+    test("resolves a relative token against an explicit resolveBase", () => {
+      // The cd-folded effective base differs from cwd (the bash-path case).
+      expect(
+        AccessPath.forPath("foo.ts", {
+          cwd,
+          resolveBase: "/projects/my-app/sub",
+        }).matchValues(),
+      ).toEqual(["/projects/my-app/sub/foo.ts", "sub/foo.ts", "foo.ts"]);
+    });
+
+    test("adds the canonical alias resolved against resolveBase", () => {
+      realpathSync.mockImplementation((p: string) =>
+        p === "/projects/my-app/sub/foo.ts" ? "/real/foo.ts" : p,
+      );
+      expect(
+        AccessPath.forPath("foo.ts", {
+          cwd,
+          resolveBase: "/projects/my-app/sub",
+        }).matchValues(),
+      ).toEqual([
+        "/projects/my-app/sub/foo.ts",
+        "sub/foo.ts",
+        "foo.ts",
+        "/real/foo.ts",
+      ]);
+    });
   });
 
   describe("boundaryValue()", () => {
@@ -66,19 +95,19 @@ describe("AccessPath.forExternalDirectory", () => {
       realpathSync.mockImplementation((p: string) =>
         p.startsWith("/tmp") ? `/private${p}` : p,
       );
-      expect(
-        AccessPath.forExternalDirectory("/tmp/x", cwd).boundaryValue(),
-      ).toBe("/private/tmp/x");
+      expect(AccessPath.forPath("/tmp/x", { cwd }).boundaryValue()).toBe(
+        "/private/tmp/x",
+      );
     });
 
     test("returns the lexical form when path has no symlinks", () => {
-      expect(
-        AccessPath.forExternalDirectory("/etc/hosts", cwd).boundaryValue(),
-      ).toBe("/etc/hosts");
+      expect(AccessPath.forPath("/etc/hosts", { cwd }).boundaryValue()).toBe(
+        "/etc/hosts",
+      );
     });
 
     test("returns empty string for empty input", () => {
-      expect(AccessPath.forExternalDirectory("", cwd).boundaryValue()).toBe("");
+      expect(AccessPath.forPath("", { cwd }).boundaryValue()).toBe("");
     });
   });
 
@@ -88,20 +117,51 @@ describe("AccessPath.forExternalDirectory", () => {
         p.startsWith("/tmp") ? `/private${p}` : p,
       );
       // Even when the path resolves to a different canonical, value() stays lexical.
-      expect(AccessPath.forExternalDirectory("/tmp/x", cwd).value()).toBe(
-        "/tmp/x",
-      );
+      expect(AccessPath.forPath("/tmp/x", { cwd }).value()).toBe("/tmp/x");
     });
 
     test("normalizes the path against cwd", () => {
       // A relative path becomes an absolute lexical value.
-      expect(AccessPath.forExternalDirectory("src/foo.ts", cwd).value()).toBe(
+      expect(AccessPath.forPath("src/foo.ts", { cwd }).value()).toBe(
         "/projects/my-app/src/foo.ts",
       );
     });
 
+    test("normalizes a relative path against an explicit resolveBase", () => {
+      expect(
+        AccessPath.forPath("foo.ts", {
+          cwd,
+          resolveBase: "/projects/my-app/sub",
+        }).value(),
+      ).toBe("/projects/my-app/sub/foo.ts");
+    });
+
     test("returns empty string for empty input", () => {
-      expect(AccessPath.forExternalDirectory("", cwd).value()).toBe("");
+      expect(AccessPath.forPath("", { cwd }).value()).toBe("");
     });
   });
 });
+
+describe("AccessPath.forLiteral", () => {
+  beforeEach(() => {
+    realpathSync.mockReset();
+    realpathSync.mockImplementation((p: string) => p);
+  });
+
+  test("matchValues() carries only the literal — no canonical, no absolute", () => {
+    expect(AccessPath.forLiteral("foo.ts").matchValues()).toEqual(["foo.ts"]);
+  });
+
+  test("boundaryValue() is empty (no outside-cwd notion for an unknown base)", () => {
+    expect(AccessPath.forLiteral("foo.ts").boundaryValue()).toBe("");
+  });
+
+  test("value() returns the literal", () => {
+    expect(AccessPath.forLiteral("foo.ts").value()).toBe("foo.ts");
+  });
+
+  test("an empty literal yields no match values", () => {
+    expect(AccessPath.forLiteral("").matchValues()).toEqual([]);
+    expect(AccessPath.forLiteral("").value()).toBe("");
+  });
+});

package/test/access-intent/bash/node-text.test.ts

@@ -10,6 +10,7 @@ function makeNode(type: string, text: string, children: TSNode[] = []): TSNode {
   return {
     type,
     text,
+    startIndex: 0,
     childCount: children.length,
     isNamed: true,
     child: (i) => children[i] ?? null,

package/test/access-intent/bash/program.test.ts

@@ -16,14 +16,20 @@ describe("BashProgram", () => {
   describe("pathRuleCandidates", () => {
     const cwd = "/projects/my-app";
 
+    beforeEach(() => {
+      realpathSync.mockReset();
+      realpathSync.mockImplementation((p: string) => p);
+    });
+
     it("adds absolute and relative policy values for relative tokens", async () => {
       const program = await BashProgram.parse("cat src/foo.ts", cwd);
-      expect(program.pathRuleCandidates()).toEqual([
-        {
-          token: "src/foo.ts",
-          policyValues: ["/projects/my-app/src/foo.ts", "src/foo.ts"],
-        },
+      const candidates = program.pathRuleCandidates();
+      expect(candidates.map(({ token }) => token)).toEqual(["src/foo.ts"]);
+      expect(candidates[0].path.matchValues()).toEqual([
+        "/projects/my-app/src/foo.ts",
+        "src/foo.ts",
       ]);
+      expect(candidates[0].path.value()).toBe("/projects/my-app/src/foo.ts");
     });
 
     it("resolves tokens after literal cd against the effective directory", async () => {
@@ -34,14 +40,28 @@ describe("BashProgram", () => {
       const fileCandidate = program
         .pathRuleCandidates()
         .find((candidate) => candidate.token === "src/file.txt");
-      expect(fileCandidate).toEqual({
-        token: "src/file.txt",
-        policyValues: [
-          "/projects/my-app/nested/src/file.txt",
-          "nested/src/file.txt",
-          "src/file.txt",
-        ],
-      });
+      expect(fileCandidate?.path.matchValues()).toEqual([
+        "/projects/my-app/nested/src/file.txt",
+        "nested/src/file.txt",
+        "src/file.txt",
+      ]);
+      expect(fileCandidate?.path.value()).toBe(
+        "/projects/my-app/nested/src/file.txt",
+      );
+    });
+
+    it("adds the canonical alias for a symlinked token (#486)", async () => {
+      // /projects/my-app/src/foo.ts is a symlink to /vault/foo.ts.
+      realpathSync.mockImplementation((p: string) =>
+        p === "/projects/my-app/src/foo.ts" ? "/vault/foo.ts" : p,
+      );
+      const program = await BashProgram.parse("cat src/foo.ts", cwd);
+      const candidate = program.pathRuleCandidates()[0];
+      expect(candidate.path.matchValues()).toEqual([
+        "/projects/my-app/src/foo.ts",
+        "src/foo.ts",
+        "/vault/foo.ts",
+      ]);
     });
 
     it("does not absolute-allow relative tokens after unknown cd", async () => {
@@ -52,10 +72,22 @@ describe("BashProgram", () => {
       const fileCandidate = program
         .pathRuleCandidates()
         .find((candidate) => candidate.token === "src/foo.ts");
-      expect(fileCandidate).toEqual({
-        token: "src/foo.ts",
-        policyValues: ["src/foo.ts"],
-      });
+      expect(fileCandidate?.path.matchValues()).toEqual(["src/foo.ts"]);
+      expect(fileCandidate?.path.value()).toBe("src/foo.ts");
+    });
+
+    it("keeps an unknown-cd token literal-only even when it would resolve a symlink (#393)", async () => {
+      // A canonical alias here would resolve against the wrong (unknown) base.
+      realpathSync.mockImplementation(() => "/somewhere/else");
+      const program = await BashProgram.parse(
+        'cd "$DIR" && cat src/foo.ts',
+        cwd,
+      );
+      const fileCandidate = program
+        .pathRuleCandidates()
+        .find((candidate) => candidate.token === "src/foo.ts");
+      expect(fileCandidate?.path.matchValues()).toEqual(["src/foo.ts"]);
+      expect(fileCandidate?.path.boundaryValue()).toBe("");
     });
   });
 
@@ -435,6 +467,73 @@ describe("BashProgram", () => {
       expect((await BashProgram.parse("", cwd)).commands()).toEqual([]);
       expect((await BashProgram.parse("   ", cwd)).commands()).toEqual([]);
     });
+
+    it("strips a leading env-var assignment prefix", async () => {
+      const program = await BashProgram.parse(
+        "AWS_PROFILE=prod aws ec2 terminate-instances --instance-ids i-1",
+        cwd,
+      );
+      expect(program.commands()).toEqual([
+        { text: "aws ec2 terminate-instances --instance-ids i-1" },
+      ]);
+    });
+
+    it("strips multiple leading env-var assignments", async () => {
+      const program = await BashProgram.parse("A=1 B=2 aws s3 ls", cwd);
+      expect(program.commands()).toEqual([{ text: "aws s3 ls" }]);
+    });
+
+    it("strips the env-var prefix of each command in a chain", async () => {
+      const program = await BashProgram.parse(
+        "X=1 aws sts get-caller-identity && ls",
+        cwd,
+      );
+      expect(program.commands()).toEqual([
+        { text: "aws sts get-caller-identity" },
+        { text: "ls" },
+      ]);
+    });
+
+    it("keeps a pure assignment with no command unchanged", async () => {
+      const program = await BashProgram.parse("FOO=bar", cwd);
+      expect(program.commands()).toEqual([{ text: "FOO=bar" }]);
+    });
+
+    describe("opaque-payload wrappers", () => {
+      it.each([
+        ['bash -c "rm -rf /"', 'bash -c "rm -rf /"'],
+        ['sh -c "rm -rf /"', 'sh -c "rm -rf /"'],
+        ['dash -c "rm -rf /"', 'dash -c "rm -rf /"'],
+        ['zsh -c "rm -rf /"', 'zsh -c "rm -rf /"'],
+        ['ksh -c "rm -rf /"', 'ksh -c "rm -rf /"'],
+        ['eval "rm -rf /"', 'eval "rm -rf /"'],
+        ['/bin/bash -c "rm -rf /"', '/bin/bash -c "rm -rf /"'],
+        ['bash -ec "rm -rf /"', 'bash -ec "rm -rf /"'],
+      ])("flags %s as opaque", async (command, text) => {
+        const program = await BashProgram.parse(command, cwd);
+        expect(program.commands()).toEqual([{ text, opaque: true }]);
+      });
+
+      it("flags an env-prefixed wrapper as opaque after stripping the prefix", async () => {
+        const program = await BashProgram.parse(
+          'AWS_PROFILE=prod bash -c "rm -rf /"',
+          cwd,
+        );
+        expect(program.commands()).toEqual([
+          { text: 'bash -c "rm -rf /"', opaque: true },
+        ]);
+      });
+
+      it.each([
+        "bash script.sh",
+        "bash",
+        "ls -la",
+        "grep -c foo file",
+      ])("does not flag %s as opaque", async (command) => {
+        const program = await BashProgram.parse(command, cwd);
+        expect(program.commands()).toEqual([{ text: command }]);
+      });
+    });
   });
 
   it("derives both slices from a single parse", async () => {