@gotgenes/pi-permission-system 16.2.0 → 17.0.0

package/test/handlers/gates/path.test.ts

@@ -1,5 +1,16 @@
-import { describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
+// Mock node:fs so realpathSync (used by canonicalizePath) is controllable.
+// Default implementation is identity — lexical tests are unaffected.
+const realpathSync = vi.hoisted(() =>
+  vi.fn<(path: string) => string>((p) => p),
+);
+vi.mock("node:fs", () => ({
+  realpathSync,
+  default: { realpathSync },
+}));
+
+import { AccessPath } from "#src/access-intent/access-path";
 import type { GateDescriptor } from "#src/handlers/gates/descriptor";
 import { isGateDescriptor } from "#src/handlers/gates/descriptor";
 import { describePathGate } from "#src/handlers/gates/path";
@@ -27,6 +38,11 @@ function makeTcc(overrides: Partial<ToolCallContext> = {}): ToolCallContext {
 // ── tests ──────────────────────────────────────────────────────────────────
 
 describe("describePathGate", () => {
+  beforeEach(() => {
+    realpathSync.mockReset();
+    realpathSync.mockImplementation((p: string) => p);
+  });
+
   it("returns null for non-path-bearing tools", () => {
     const resolver = makeResolver();
     const result = describePathGate(
@@ -152,16 +168,31 @@ describe("describePathGate", () => {
     expect(result.decision.value).toBe(".env");
   });
 
-  it("resolves the path surface with the file path and agent name", () => {
+  it("resolves the path surface with an access-path intent and agent name", () => {
     const resolver = makeResolver(makeCheckResult({ state: "allow" }));
     describePathGate(makeTcc({ agentName: "my-agent" }), resolver);
     expect(resolver.resolve).toHaveBeenCalledWith({
-      kind: "tool",
+      kind: "access-path",
       surface: "path",
-      input: { path: ".env" },
+      path: AccessPath.forPath(".env", { cwd: "/test/project" }),
       agentName: "my-agent",
     });
   });
+
+  it("emits an access-path whose matchValues include the symlink-resolved form (#486)", () => {
+    // /test/project/.env is a symlink to /vault/secret.env.
+    realpathSync.mockImplementation((p: string) =>
+      p === "/test/project/.env" ? "/vault/secret.env" : p,
+    );
+    const resolver = makeResolver(makeCheckResult({ state: "allow" }));
+    describePathGate(makeTcc(), resolver);
+
+    const intent = resolver.resolve.mock.lastCall?.[0];
+    expect(intent?.kind).toBe("access-path");
+    expect(intent?.kind === "access-path" && intent.path.matchValues()).toEqual(
+      ["/test/project/.env", ".env", "/vault/secret.env"],
+    );
+  });
 });
 
 // Home-relative path characterization (#350) ──────────────────────────────
@@ -189,9 +220,9 @@ describe("describePathGate — home-relative paths", () => {
       pathValue: "~/.ssh/config",
     });
     expect(resolver.resolve).toHaveBeenCalledWith({
-      kind: "tool",
+      kind: "access-path",
       surface: "path",
-      input: { path: "~/.ssh/config" },
+      path: AccessPath.forPath("~/.ssh/config", { cwd: "/test/project" }),
       agentName: undefined,
     });
   });
@@ -246,9 +277,9 @@ describe("describePathGate — extension and MCP tools (#352)", () => {
     );
     expect(isGateDescriptor(result)).toBe(true);
     expect(resolver.resolve).toHaveBeenCalledWith({
-      kind: "tool",
+      kind: "access-path",
       surface: "path",
-      input: { path: ".env" },
+      path: AccessPath.forPath(".env", { cwd: "/test/project" }),
       agentName: undefined,
     });
   });
@@ -263,9 +294,9 @@ describe("describePathGate — extension and MCP tools (#352)", () => {
     );
     expect(isGateDescriptor(result)).toBe(true);
     expect(resolver.resolve).toHaveBeenCalledWith({
-      kind: "tool",
+      kind: "access-path",
       surface: "path",
-      input: { path: ".env" },
+      path: AccessPath.forPath(".env", { cwd: "/test/project" }),
       agentName: undefined,
     });
   });
@@ -280,9 +311,9 @@ describe("describePathGate — extension and MCP tools (#352)", () => {
       extractorLookup("ffgrep", "target"),
     );
     expect(resolver.resolve).toHaveBeenCalledWith({
-      kind: "tool",
+      kind: "access-path",
       surface: "path",
-      input: { path: "/etc/passwd" },
+      path: AccessPath.forPath("/etc/passwd", { cwd: "/test/project" }),
       agentName: undefined,
     });
   });

package/test/helpers/external-directory-fixtures.ts

@@ -0,0 +1,269 @@
+/**
+ * Shared fixtures for the external-directory handler-pipeline tests.
+ *
+ * Targets the collapsed external-directory gate (Phase 6 Step 5, #477).
+ * Consumed by external-directory-integration.test.ts and
+ * external-directory-session-dedup.test.ts.
+ */
+import { vi } from "vitest";
+
+import { GateDecisionReporter } from "#src/decision-reporter";
+import type { GatePrompter } from "#src/gate-prompter";
+import { GateRunner } from "#src/handlers/gates/runner";
+import { SkillInputGatePipeline } from "#src/handlers/gates/skill-input-gate-pipeline";
+import { ToolCallGatePipeline } from "#src/handlers/gates/tool-call-gate-pipeline";
+import { PermissionGateHandler } from "#src/handlers/permission-gate-handler";
+import type { ScopedPermissionManager } from "#src/permission-manager";
+import type { SessionLogger } from "#src/session-logger";
+import type { PermissionCheckResult, PermissionState } from "#src/types";
+import { wildcardMatch } from "#src/wildcard-matcher";
+
+import {
+  getDecisionEvents,
+  makeEvents,
+  makeSurfaceCheck,
+  makeToolRegistry,
+} from "#test/helpers/handler-fixtures";
+import {
+  makeRealResolver,
+  makeRealSession,
+} from "#test/helpers/session-fixtures";
+
+// ── Shared constants ───────────────────────────────────────────────────────
+
+/** Working-directory used by the external-directory handler-pipeline tests. */
+export const EXT_DIR_CWD = "/test/project";
+
+/** An external path (outside {@link EXT_DIR_CWD}) used across the test suite. */
+export const EXTERNAL_PATH = "/outside/project/file.ts";
+
+/** All path-bearing tools subject to the external-directory gate. */
+export const ALL_PATH_BEARING_TOOLS = [
+  "read",
+  "write",
+  "edit",
+  "find",
+  "grep",
+  "ls",
+];
+
+/** Path-bearing tools where the path is optional (no input → gate is skipped). */
+export const OPTIONAL_PATH_TOOLS = ["find", "grep", "ls"];
+
+/** Full tool set used as the default registry in external-directory tests. */
+export const ALL_TOOLS = [...ALL_PATH_BEARING_TOOLS, "bash"];
+
+// ── Setup builders ─────────────────────────────────────────────────────────
+
+/**
+ * Builds a `checkPermission` mock for external-directory tests.
+ *
+ * Routes `external_directory` to `externalDirectoryState`, `path` to allow
+ * with `source: "special"` (so the cross-cutting path gate is transparent),
+ * and every other surface to `toolState` (default: allow).
+ */
+export function makeExtDirCheck(
+  externalDirectoryState: PermissionState,
+  toolState: PermissionState = "allow",
+) {
+  return makeSurfaceCheck(
+    {
+      external_directory: { state: externalDirectoryState },
+      path: { state: "allow", source: "special" },
+    },
+    { state: toolState },
+  );
+}
+
+/** GatePrompter stub that approves with `state: "approved"`. */
+export function makeApprovingPrompter(): GatePrompter {
+  return {
+    canConfirm: vi.fn().mockReturnValue(true),
+    prompt: vi
+      .fn<GatePrompter["prompt"]>()
+      .mockResolvedValue({ approved: true, state: "approved" }),
+  };
+}
+
+/**
+ * GatePrompter stub that denies.
+ *
+ * Pass `denialReason` to simulate a user who explains the refusal.
+ */
+export function makeDenyingPrompter(denialReason?: string): GatePrompter {
+  return {
+    canConfirm: vi.fn().mockReturnValue(true),
+    prompt: vi
+      .fn<GatePrompter["prompt"]>()
+      .mockResolvedValue(
+        denialReason !== undefined
+          ? { approved: false, state: "denied", denialReason }
+          : { approved: false, state: "denied" },
+      ),
+  };
+}
+
+/** GatePrompter stub that reports no UI is available (`canConfirm: false`). */
+export function makeUnavailablePrompter(): GatePrompter {
+  return {
+    canConfirm: vi.fn().mockReturnValue(false),
+    prompt: vi.fn<GatePrompter["prompt"]>(),
+  };
+}
+
+// ── Query helpers ──────────────────────────────────────────────────────────
+
+/** Find the `external_directory` decision event from the events mock. */
+export function findExtDirDecision(events: ReturnType<typeof makeEvents>) {
+  return getDecisionEvents(events).find(
+    (d) => d.surface === "external_directory",
+  );
+}
+
+/** Return the `permission_request.blocked` review-log entries from the logger mock. */
+export function blockReviewEntries(logger: SessionLogger) {
+  return (logger.review as ReturnType<typeof vi.fn>).mock.calls.filter(
+    ([eventName]: string[]) => eventName === "permission_request.blocked",
+  );
+}
+
+// ── Session-dedup wiring ──────────────────────────────────────────────────
+
+/**
+ * Installs the session-aware `check(intent)` mock on the permission manager.
+ *
+ * Returns `ask` for `external_directory` on first access; re-checks recorded
+ * session rules on subsequent calls and returns `allow` (source: "session")
+ * when a `wildcardMatch` covers the path.
+ */
+export function makeExtDirDedupCheck(
+  permissionManager: ScopedPermissionManager,
+): void {
+  vi.mocked(permissionManager.check).mockImplementation(
+    (intent, rules): PermissionCheckResult => {
+      const { surface } = intent;
+      const pathValue =
+        intent.kind === "path-values" ? (intent.values[0] ?? null) : null;
+
+      if (surface === "external_directory") {
+        if (pathValue && rules && rules.length > 0) {
+          const match = rules.findLast(
+            (r) =>
+              r.surface === "external_directory" &&
+              wildcardMatch(r.pattern, pathValue),
+          );
+          if (match) {
+            return {
+              state: "allow",
+              toolName: surface,
+              source: "session",
+              origin: "session",
+              matchedPattern: match.pattern,
+            };
+          }
+        }
+        return {
+          state: "ask",
+          toolName: surface,
+          source: "special",
+          origin: "global",
+        };
+      }
+
+      return {
+        state: "allow",
+        toolName: surface,
+        source: "tool",
+        origin: "builtin",
+      };
+    },
+  );
+}
+
+/** GatePrompter stub that approves for the session (`state: "approved_for_session"`). */
+function makeSessionApprovingPrompter(): GatePrompter {
+  return {
+    canConfirm: vi.fn().mockReturnValue(true),
+    prompt: vi
+      .fn<GatePrompter["prompt"]>()
+      .mockResolvedValue({ approved: true, state: "approved_for_session" }),
+  };
+}
+
+/**
+ * Builds the fully-wired session-dedup handler with real collaborators.
+ *
+ * Unlike `makeHandler`, this wires `makeRealSession` + `makeRealResolver`
+ * manually so the caller can access the raw `session` for shutdown tests.
+ *
+ * Returns `{ handler, prompter, session }`.
+ */
+export function makeDedupWiring(prompter?: GatePrompter) {
+  const { session, permissionManager, sessionRules, logger } =
+    makeRealSession();
+  const { resolver } = makeRealResolver(permissionManager, sessionRules);
+  makeExtDirDedupCheck(permissionManager);
+  const events = makeEvents();
+  const reporter = new GateDecisionReporter(logger, events);
+  const resolvedPrompter: GatePrompter =
+    prompter ?? makeSessionApprovingPrompter();
+  const runner = new GateRunner(
+    resolver,
+    sessionRules,
+    resolvedPrompter,
+    reporter,
+  );
+  const handler = new PermissionGateHandler(
+    session,
+    makeToolRegistry({
+      getAll: vi
+        .fn()
+        .mockReturnValue([
+          { name: "read" },
+          { name: "write" },
+          { name: "edit" },
+          { name: "bash" },
+        ]),
+    }),
+    new ToolCallGatePipeline(resolver, session),
+    new SkillInputGatePipeline(resolver),
+    runner,
+  );
+  return { handler, prompter: resolvedPrompter, session };
+}
+
+/**
+ * Builds the session-dedup handler without exposing the raw session.
+ *
+ * Wraps `makeDedupWiring`; returns `{ handler, prompter }`.
+ * Use `makeDedupWiring` when the test also needs `session.shutdown()`.
+ */
+export function makeDeduplicatingHandler(prompter?: GatePrompter) {
+  const { handler, prompter: resolvedPrompter } = makeDedupWiring(prompter);
+  return { handler, prompter: resolvedPrompter };
+}
+
+// ── Event builders ─────────────────────────────────────────────────────────
+
+/**
+ * Builds a tool-call event in the shape that external-directory-session-dedup
+ * tests use — `toolName` field (not `name`); both are accepted by
+ * `getToolNameFromValue`.
+ */
+export function makeExtDirToolEvent(
+  toolName: string,
+  path: string,
+  toolCallId = "tc-1",
+) {
+  return { type: "tool_call" as const, toolCallId, toolName, input: { path } };
+}
+
+/** Builds a bash tool-call event for external-directory session-dedup tests. */
+export function makeExtDirBashEvent(command: string, toolCallId = "tc-1") {
+  return {
+    type: "tool_call" as const,
+    toolCallId,
+    toolName: "bash",
+    input: { command },
+  };
+}

package/test/helpers/gate-fixtures.ts

@@ -213,8 +213,7 @@ export function makePathDispatchResolver(
       }
       return defaultResult;
     }
-    const values =
-      intent.kind === "access-path" ? intent.path.matchValues() : intent.values;
+    const values = intent.path.matchValues();
     for (const value of values) {
       if (value in byPath) return byPath[value];
     }

package/test/permission-resolver.test.ts

@@ -120,28 +120,7 @@ describe("PermissionResolver", () => {
     });
   });
 
-  describe("resolve — path-values intent", () => {
-    it("forwards a path-values intent with the current session ruleset", () => {
-      const { resolver, permissionManager } = makeResolver();
-
-      resolver.resolve({
-        kind: "path-values",
-        surface: "path",
-        values: ["/proj/src/a.ts", "src/a.ts"],
-        agentName: "agent-x",
-      });
-
-      expect(permissionManager.check).toHaveBeenCalledWith(
-        {
-          kind: "path-values",
-          surface: "path",
-          values: ["/proj/src/a.ts", "src/a.ts"],
-          agentName: "agent-x",
-        },
-        [],
-      );
-    });
-
+  describe("resolve — session ruleset threading", () => {
     it("applies a recorded session approval on the next call", () => {
       const pm = makePermissionManager();
       const sessionRules = new SessionRules();
@@ -151,9 +130,9 @@ describe("PermissionResolver", () => {
         SessionApproval.single("path", "src/*"),
       );
       resolver.resolve({
-        kind: "path-values",
+        kind: "access-path",
         surface: "path",
-        values: ["src/a.ts"],
+        path: AccessPath.forPath("src/a.ts", { cwd: "/proj" }),
       });
 
       const passedRules = vi.mocked(pm.check).mock.calls[0][1];
@@ -169,10 +148,7 @@ describe("PermissionResolver", () => {
   describe("resolve — access-path intent", () => {
     it("unwraps the AccessPath via matchValues() into a path-values intent", () => {
       const { resolver, permissionManager } = makeResolver();
-      const accessPath = AccessPath.forExternalDirectory(
-        "/tmp/x",
-        "/workspace",
-      );
+      const accessPath = AccessPath.forPath("/tmp/x", { cwd: "/workspace" });
 
       resolver.resolve({
         kind: "access-path",
@@ -202,10 +178,7 @@ describe("PermissionResolver", () => {
         matchedPattern: "/tmp/*",
       });
       const { resolver } = makeResolver(pm);
-      const accessPath = AccessPath.forExternalDirectory(
-        "/tmp/x",
-        "/workspace",
-      );
+      const accessPath = AccessPath.forPath("/tmp/x", { cwd: "/workspace" });
 
       const result = resolver.resolve({
         kind: "access-path",

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

@@ -1,19 +1,13 @@
-import { afterEach, describe, expect, it, test, vi } from "vitest";
+import { describe, expect, it, test } from "vitest";
 
 import {
-  extractFrontmatter,
   getNonEmptyString,
   isDenyWithReason,
   isPermissionState,
   normalizeOptionalPositiveInt,
   normalizeOptionalStringArray,
-  parseSimpleYamlMap,
   toRecord,
-} from "#src/common";
-
-afterEach(() => {
-  vi.restoreAllMocks();
-});
+} from "#src/value-guards";
 
 describe("toRecord", () => {
   test("returns empty object for null", () => {
@@ -130,94 +124,6 @@ describe("isDenyWithReason", () => {
   });
 });
 
-describe("extractFrontmatter", () => {
-  test("returns empty string when no frontmatter delimiter", () => {
-    expect(extractFrontmatter("# Hello\nSome content")).toBe("");
-  });
-
-  test("returns empty string when only opening delimiter with no closing", () => {
-    expect(extractFrontmatter("---\nkey: value")).toBe("");
-  });
-
-  test("returns frontmatter body between delimiters", () => {
-    const markdown = "---\nissue: 1\ntitle: Test\n---\n# Content";
-    expect(extractFrontmatter(markdown)).toBe("issue: 1\ntitle: Test");
-  });
-
-  test("returns empty string when file does not start with ---", () => {
-    expect(extractFrontmatter("content\n---\nkey: val\n---")).toBe("");
-  });
-
-  test("handles CRLF line endings", () => {
-    const markdown = "---\r\nissue: 5\r\n---\r\n# Content";
-    expect(extractFrontmatter(markdown)).toBe("issue: 5");
-  });
-
-  test("returns empty string for empty string input", () => {
-    expect(extractFrontmatter("")).toBe("");
-  });
-
-  test("returns empty frontmatter for --- \\n--- with nothing between", () => {
-    const markdown = "---\n---\n# Content";
-    expect(extractFrontmatter(markdown)).toBe("");
-  });
-});
-
-describe("parseSimpleYamlMap", () => {
-  test("returns empty object for empty string", () => {
-    expect(parseSimpleYamlMap("")).toEqual({});
-  });
-
-  test("parses simple key-value pairs", () => {
-    const yaml = "issue: 21\ntitle: Test";
-    expect(parseSimpleYamlMap(yaml)).toEqual({ issue: "21", title: "Test" });
-  });
-
-  test("strips surrounding quotes from values", () => {
-    const yaml = 'title: "My Title"';
-    expect(parseSimpleYamlMap(yaml)).toEqual({ title: "My Title" });
-
-    const yaml2 = "title: 'My Title'";
-    expect(parseSimpleYamlMap(yaml2)).toEqual({ title: "My Title" });
-  });
-
-  test("skips lines without colon or with colon at position 0", () => {
-    const yaml = "no separator here\n:starts-with-colon: val\nkey: val";
-    const result = parseSimpleYamlMap(yaml);
-    expect(result.key).toBe("val");
-    expect(result["no separator here"]).toBeUndefined();
-  });
-
-  test("skips comment lines", () => {
-    const yaml = "# This is a comment\nkey: value";
-    expect(parseSimpleYamlMap(yaml)).toEqual({ key: "value" });
-  });
-
-  test("skips blank lines", () => {
-    const yaml = "\n\nkey: value\n\n";
-    expect(parseSimpleYamlMap(yaml)).toEqual({ key: "value" });
-  });
-
-  test("parses nested map (child indented under parent)", () => {
-    const yaml = "parent:\n  child: nested_value";
-    const result = parseSimpleYamlMap(yaml);
-    expect(result.parent).toEqual({ child: "nested_value" });
-  });
-
-  test("handles multi-line values correctly (second line is new key)", () => {
-    const yaml = "key1: val1\nkey2: val2";
-    const result = parseSimpleYamlMap(yaml);
-    expect(result.key1).toBe("val1");
-    expect(result.key2).toBe("val2");
-  });
-
-  test("strips quotes from keys", () => {
-    const yaml = '"quoted-key": value';
-    const result = parseSimpleYamlMap(yaml);
-    expect(result["quoted-key"]).toBe("value");
-  });
-});
-
 describe("normalizeOptionalStringArray", () => {
   it("returns the array for a valid string array", () => {
     expect(normalizeOptionalStringArray(["a", "b", "c"])).toEqual([

package/test/yaml-frontmatter.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from "vitest";
+
+import { extractFrontmatter, parseSimpleYamlMap } from "#src/yaml-frontmatter";
+
+describe("extractFrontmatter", () => {
+  test("returns empty string when no frontmatter delimiter", () => {
+    expect(extractFrontmatter("# Hello\nSome content")).toBe("");
+  });
+
+  test("returns empty string when only opening delimiter with no closing", () => {
+    expect(extractFrontmatter("---\nkey: value")).toBe("");
+  });
+
+  test("returns frontmatter body between delimiters", () => {
+    const markdown = "---\nissue: 1\ntitle: Test\n---\n# Content";
+    expect(extractFrontmatter(markdown)).toBe("issue: 1\ntitle: Test");
+  });
+
+  test("returns empty string when file does not start with ---", () => {
+    expect(extractFrontmatter("content\n---\nkey: val\n---")).toBe("");
+  });
+
+  test("handles CRLF line endings", () => {
+    const markdown = "---\r\nissue: 5\r\n---\r\n# Content";
+    expect(extractFrontmatter(markdown)).toBe("issue: 5");
+  });
+
+  test("returns empty string for empty string input", () => {
+    expect(extractFrontmatter("")).toBe("");
+  });
+
+  test("returns empty frontmatter for --- \\n--- with nothing between", () => {
+    const markdown = "---\n---\n# Content";
+    expect(extractFrontmatter(markdown)).toBe("");
+  });
+});
+
+describe("parseSimpleYamlMap", () => {
+  test("returns empty object for empty string", () => {
+    expect(parseSimpleYamlMap("")).toEqual({});
+  });
+
+  test("parses simple key-value pairs", () => {
+    const yaml = "issue: 21\ntitle: Test";
+    expect(parseSimpleYamlMap(yaml)).toEqual({ issue: "21", title: "Test" });
+  });
+
+  test("strips surrounding quotes from values", () => {
+    const yaml = 'title: "My Title"';
+    expect(parseSimpleYamlMap(yaml)).toEqual({ title: "My Title" });
+
+    const yaml2 = "title: 'My Title'";
+    expect(parseSimpleYamlMap(yaml2)).toEqual({ title: "My Title" });
+  });
+
+  test("skips lines without colon or with colon at position 0", () => {
+    const yaml = "no separator here\n:starts-with-colon: val\nkey: val";
+    const result = parseSimpleYamlMap(yaml);
+    expect(result.key).toBe("val");
+    expect(result["no separator here"]).toBeUndefined();
+  });
+
+  test("skips comment lines", () => {
+    const yaml = "# This is a comment\nkey: value";
+    expect(parseSimpleYamlMap(yaml)).toEqual({ key: "value" });
+  });
+
+  test("skips blank lines", () => {
+    const yaml = "\n\nkey: value\n\n";
+    expect(parseSimpleYamlMap(yaml)).toEqual({ key: "value" });
+  });
+
+  test("parses nested map (child indented under parent)", () => {
+    const yaml = "parent:\n  child: nested_value";
+    const result = parseSimpleYamlMap(yaml);
+    expect(result.parent).toEqual({ child: "nested_value" });
+  });
+
+  test("handles multi-line values correctly (second line is new key)", () => {
+    const yaml = "key1: val1\nkey2: val2";
+    const result = parseSimpleYamlMap(yaml);
+    expect(result.key1).toBe("val1");
+    expect(result.key2).toBe("val2");
+  });
+
+  test("strips quotes from keys", () => {
+    const yaml = '"quoted-key": value';
+    const result = parseSimpleYamlMap(yaml);
+    expect(result["quoted-key"]).toBe("value");
+  });
+});