@gotgenes/pi-permission-system 8.1.0 → 8.2.1

package/test/handlers/tool-call-events.test.ts

@@ -2,125 +2,15 @@
  * Tests that handleToolCall emits permissions:decision events at every
  * gate resolution and fast-path site.
  */
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { describe, expect, it, vi } from "vitest";
-import { DEFAULT_EXTENSION_CONFIG } from "#src/extension-config";
-import { PermissionGateHandler } from "#src/handlers/permission-gate-handler";
-import type { PermissionDecisionEvent } from "#src/permission-events";
-import { PERMISSIONS_DECISION_CHANNEL } from "#src/permission-events";
-import type { PermissionSession } from "#src/permission-session";
-import type { ToolRegistry } from "#src/tool-registry";
-import type { PermissionCheckResult } from "#src/types";
-
-// ── helpers ────────────────────────────────────────────────────────────────
-
-function makeEvents() {
-  return {
-    emit: vi.fn(),
-    on: vi.fn().mockReturnValue(() => undefined),
-  };
-}
-
-function makeCtx(overrides: Partial<ExtensionContext> = {}): ExtensionContext {
-  return {
-    cwd: "/test/project",
-    hasUI: true,
-    ui: {
-      setStatus: vi.fn(),
-      notify: vi.fn(),
-      select: vi.fn(),
-      input: vi.fn(),
-    },
-    sessionManager: {
-      getEntries: vi.fn().mockReturnValue([]),
-      getSessionDir: vi.fn().mockReturnValue("/sessions/test"),
-      addEntry: vi.fn(),
-    },
-    ...overrides,
-  } as unknown as ExtensionContext;
-}
-
-function makeToolCallEvent(
-  toolName: string,
-  extraFields: Record<string, unknown> = {},
-) {
-  return {
-    type: "tool_call",
-    toolCallId: "tc-1",
-    name: toolName,
-    input: {},
-    ...extraFields,
-  };
-}
-
-function makeCheckResult(
-  state: "allow" | "deny" | "ask",
-  overrides: Partial<PermissionCheckResult> = {},
-): PermissionCheckResult {
-  return {
-    state,
-    toolName: "read",
-    source: "tool",
-    origin: "builtin",
-    matchedPattern: "*",
-    ...overrides,
-  };
-}
-
-function makeSession(
-  overrides: Partial<Record<keyof PermissionSession, unknown>> = {},
-): PermissionSession {
-  return {
-    logger: { debug: vi.fn(), review: vi.fn(), warn: vi.fn() },
-    activate: vi.fn(),
-    resolveAgentName: vi.fn().mockReturnValue(null),
-    checkPermission: vi.fn().mockReturnValue(makeCheckResult("allow")),
-    getToolPermission: vi.fn().mockReturnValue("allow"),
-    getSessionRuleset: vi.fn().mockReturnValue([]),
-    approveSessionRule: vi.fn(),
-    getActiveSkillEntries: vi.fn().mockReturnValue([]),
-    getInfrastructureDirs: vi
-      .fn()
-      .mockReturnValue(["/test/agent", "/test/agent/git"]),
-    getInfrastructureReadPaths: vi.fn().mockReturnValue([]),
-    config: DEFAULT_EXTENSION_CONFIG,
-    canPrompt: vi.fn().mockReturnValue(true),
-    prompt: vi.fn().mockResolvedValue({ approved: true, state: "approved" }),
-    ...overrides,
-  } as unknown as PermissionSession;
-}
-
-function makeToolRegistry(overrides: Partial<ToolRegistry> = {}): ToolRegistry {
-  return {
-    getAll: vi.fn().mockReturnValue([{ name: "read" }, { name: "bash" }]),
-    setActive: vi.fn(),
-    ...overrides,
-  };
-}
-
-function makeHandler(overrides?: {
-  session?: Partial<Record<keyof PermissionSession, unknown>>;
-  toolRegistry?: Partial<ToolRegistry>;
-}): {
-  handler: PermissionGateHandler;
-  events: ReturnType<typeof makeEvents>;
-  session: PermissionSession;
-} {
-  const session = makeSession(overrides?.session);
-  const events = makeEvents();
-  const toolRegistry = makeToolRegistry(overrides?.toolRegistry);
-  const handler = new PermissionGateHandler(session, events, toolRegistry);
-  return { handler, events, session };
-}
-
-/** Extract all permissions:decision payloads from the events.emit mock. */
-function getDecisionEvents(
-  events: ReturnType<typeof makeEvents>,
-): PermissionDecisionEvent[] {
-  return events.emit.mock.calls
-    .filter(([channel]) => channel === PERMISSIONS_DECISION_CHANNEL)
-    .map(([, payload]) => payload as PermissionDecisionEvent);
-}
+
+import {
+  getDecisionEvents,
+  makeCheckResult,
+  makeCtx,
+  makeHandler,
+  makeToolCallEvent,
+} from "#test/helpers/handler-fixtures";
 
 // ── policy_allow path ──────────────────────────────────────────────────────
 
@@ -129,7 +19,8 @@ describe("handleToolCall decision events — policy_allow", () => {
     const { handler, events } = makeHandler({
       session: {
         checkPermission: vi.fn().mockReturnValue(
-          makeCheckResult("allow", {
+          makeCheckResult({
+            state: "allow",
             origin: "global",
             matchedPattern: "*",
           }),
@@ -158,7 +49,8 @@ describe("handleToolCall decision events — policy_deny", () => {
     const { handler, events } = makeHandler({
       session: {
         checkPermission: vi.fn().mockReturnValue(
-          makeCheckResult("deny", {
+          makeCheckResult({
+            state: "deny",
             origin: "project",
             matchedPattern: "read",
           }),
@@ -185,7 +77,8 @@ describe("handleToolCall decision events — session_approved", () => {
     const { handler, events } = makeHandler({
       session: {
         checkPermission: vi.fn().mockReturnValue(
-          makeCheckResult("allow", {
+          makeCheckResult({
+            state: "allow",
             source: "session",
             matchedPattern: "git *",
           }),
@@ -214,7 +107,9 @@ describe("handleToolCall decision events — user_approved", () => {
   it("emits allow with user_approved when state=ask and user approves once", async () => {
     const { handler, events } = makeHandler({
       session: {
-        checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(makeCheckResult({ state: "ask" })),
         prompt: vi
           .fn()
           .mockResolvedValue({ approved: true, state: "approved" }),
@@ -234,7 +129,9 @@ describe("handleToolCall decision events — user_approved", () => {
   it("emits allow with user_approved_for_session when user approves for session", async () => {
     const { handler, events } = makeHandler({
       session: {
-        checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(makeCheckResult({ state: "ask" })),
         prompt: vi.fn().mockResolvedValue({
           approved: true,
           state: "approved_for_session",
@@ -259,7 +156,9 @@ describe("handleToolCall decision events — user_denied", () => {
   it("emits deny with user_denied when state=ask and user denies", async () => {
     const { handler, events } = makeHandler({
       session: {
-        checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(makeCheckResult({ state: "ask" })),
         prompt: vi.fn().mockResolvedValue({ approved: false, state: "denied" }),
       },
     });
@@ -281,7 +180,9 @@ describe("handleToolCall decision events — confirmation_unavailable", () => {
   it("emits deny with confirmation_unavailable when state=ask but no UI", async () => {
     const { handler, events } = makeHandler({
       session: {
-        checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(makeCheckResult({ state: "ask" })),
         canPrompt: vi.fn().mockReturnValue(false),
       },
     });
@@ -307,7 +208,7 @@ describe("handleToolCall decision events — infrastructure_auto_allowed", () =>
     const infraDir = "/test/agent";
     const { handler, events } = makeHandler({
       session: {
-        checkPermission: vi.fn().mockReturnValue(makeCheckResult("allow")),
+        checkPermission: vi.fn().mockReturnValue(makeCheckResult()),
         getInfrastructureDirs: vi.fn().mockReturnValue([infraDir]),
       },
     });
@@ -335,7 +236,9 @@ describe("handleToolCall decision events — auto_approved", () => {
   it("emits allow with auto_approved when prompt returns autoApproved:true", async () => {
     const { handler, events } = makeHandler({
       session: {
-        checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(makeCheckResult({ state: "ask" })),
         prompt: vi.fn().mockResolvedValue({
           approved: true,
           state: "approved",

package/test/handlers/tool-call.test.ts

@@ -1,13 +1,13 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { describe, expect, it, vi } from "vitest";
-import { DEFAULT_EXTENSION_CONFIG } from "#src/extension-config";
+
+import { getEventInput } from "#src/handlers/permission-gate-handler";
+
 import {
-  getEventInput,
-  PermissionGateHandler,
-} from "#src/handlers/permission-gate-handler";
-import type { PermissionSession } from "#src/permission-session";
-import type { ToolRegistry } from "#src/tool-registry";
-import type { PermissionCheckResult } from "#src/types";
+  makeCheckResult,
+  makeCtx,
+  makeHandler,
+  makeToolCallEvent,
+} from "#test/helpers/handler-fixtures";
 
 // ── SDK stubs ──────────────────────────────────────────────────────────────
 vi.mock("@earendil-works/pi-coding-agent", async (importOriginal) => {
@@ -16,101 +16,6 @@ vi.mock("@earendil-works/pi-coding-agent", async (importOriginal) => {
   return { ...original };
 });
 
-// ── helpers ────────────────────────────────────────────────────────────────
-
-function makeCtx(
-  overrides: Partial<ExtensionContext> & { cwd?: string } = {},
-): ExtensionContext {
-  return {
-    cwd: "/test/project",
-    hasUI: true,
-    ui: {
-      setStatus: vi.fn(),
-      notify: vi.fn(),
-      select: vi.fn(),
-      input: vi.fn(),
-    },
-    sessionManager: {
-      getEntries: vi.fn().mockReturnValue([]),
-      getSessionDir: vi.fn().mockReturnValue("/sessions/test"),
-      addEntry: vi.fn(),
-    },
-    ...overrides,
-  } as unknown as ExtensionContext;
-}
-
-function makeToolCallEvent(
-  toolName: string,
-  extraFields: Record<string, unknown> = {},
-) {
-  return {
-    type: "tool_call",
-    toolCallId: "tc-1",
-    name: toolName,
-    input: {},
-    ...extraFields,
-  };
-}
-
-function makePermissionResult(
-  state: "allow" | "deny" | "ask",
-): PermissionCheckResult {
-  return { state, toolName: "read", source: "tool", origin: "builtin" };
-}
-
-function makeSession(
-  overrides: Partial<Record<keyof PermissionSession, unknown>> = {},
-): PermissionSession {
-  return {
-    logger: { debug: vi.fn(), review: vi.fn(), warn: vi.fn() },
-    activate: vi.fn(),
-    resolveAgentName: vi.fn().mockReturnValue(null),
-    checkPermission: vi.fn().mockReturnValue(makePermissionResult("allow")),
-    getToolPermission: vi.fn().mockReturnValue("allow"),
-    getSessionRuleset: vi.fn().mockReturnValue([]),
-    approveSessionRule: vi.fn(),
-    getActiveSkillEntries: vi.fn().mockReturnValue([]),
-    getInfrastructureDirs: vi
-      .fn()
-      .mockReturnValue(["/test/agent", "/test/agent/git"]),
-    getInfrastructureReadPaths: vi.fn().mockReturnValue([]),
-    config: DEFAULT_EXTENSION_CONFIG,
-    canPrompt: vi.fn().mockReturnValue(true),
-    prompt: vi.fn().mockResolvedValue({ approved: true, state: "approved" }),
-    ...overrides,
-  } as unknown as PermissionSession;
-}
-
-function makeEvents() {
-  return {
-    emit: vi.fn(),
-    on: vi.fn().mockReturnValue(() => undefined),
-  };
-}
-
-function makeToolRegistry(overrides: Partial<ToolRegistry> = {}): ToolRegistry {
-  return {
-    getAll: vi.fn().mockReturnValue([{ name: "read" }, { name: "bash" }]),
-    setActive: vi.fn(),
-    ...overrides,
-  };
-}
-
-function makeHandler(overrides?: {
-  session?: Partial<Record<keyof PermissionSession, unknown>>;
-  toolRegistry?: Partial<ToolRegistry>;
-}): {
-  handler: PermissionGateHandler;
-  session: PermissionSession;
-  toolRegistry: ToolRegistry;
-} {
-  const session = makeSession(overrides?.session);
-  const events = makeEvents();
-  const toolRegistry = makeToolRegistry(overrides?.toolRegistry);
-  const handler = new PermissionGateHandler(session, events, toolRegistry);
-  return { handler, session, toolRegistry };
-}
-
 // ── getEventInput ──────────────────────────────────────────────────────────
 
 describe("getEventInput", () => {
@@ -184,7 +89,9 @@ describe("handleToolCall", () => {
   it("blocks when tool is denied by policy", async () => {
     const { handler } = makeHandler({
       session: {
-        checkPermission: vi.fn().mockReturnValue(makePermissionResult("deny")),
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(makeCheckResult({ state: "deny" })),
       },
     });
     const result = await handler.handleToolCall(
@@ -259,7 +166,9 @@ describe("handleToolCall — external-directory gate", () => {
   it("blocks a read of a path outside cwd when policy is deny", async () => {
     const { handler } = makeHandler({
       session: {
-        checkPermission: vi.fn().mockReturnValue(makePermissionResult("deny")),
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(makeCheckResult({ state: "deny" })),
       },
       toolRegistry: {
         getAll: vi.fn().mockReturnValue([{ name: "read" }]),
@@ -282,7 +191,9 @@ describe("handleToolCall — bash external-directory gate", () => {
   it("blocks a bash command referencing an external path when policy is deny", async () => {
     const { handler } = makeHandler({
       session: {
-        checkPermission: vi.fn().mockReturnValue(makePermissionResult("deny")),
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(makeCheckResult({ state: "deny" })),
       },
       toolRegistry: {
         getAll: vi.fn().mockReturnValue([{ name: "bash" }]),
@@ -308,9 +219,9 @@ describe("handleToolCall — path gate (tools)", () => {
       .mockImplementation(
         (surface: string, _input: unknown, _agentName?: string) => {
           if (surface === "path") {
-            return { ...makePermissionResult("deny"), matchedPattern: "*.env" };
+            return makeCheckResult({ state: "deny", matchedPattern: "*.env" });
           }
-          return makePermissionResult("allow");
+          return makeCheckResult();
         },
       );
     const { handler } = makeHandler({
@@ -355,9 +266,9 @@ describe("handleToolCall — bash path gate", () => {
       .mockImplementation(
         (surface: string, _input: unknown, _agentName?: string) => {
           if (surface === "path") {
-            return { ...makePermissionResult("deny"), matchedPattern: "*.env" };
+            return makeCheckResult({ state: "deny", matchedPattern: "*.env" });
           }
-          return makePermissionResult("allow");
+          return makeCheckResult();
         },
       );
     const { handler } = makeHandler({

package/test/helpers/gate-fixtures.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared gate-level test fixtures for gate descriptor and runner tests.
+ */
+import { vi } from "vitest";
+
+import type {
+  GateDescriptor,
+  GateRunnerDeps,
+} from "#src/handlers/gates/descriptor";
+import type { ToolCallContext } from "#src/handlers/gates/types";
+import type { PermissionCheckResult } from "#src/types";
+
+import { makeCheckResult } from "#test/helpers/handler-fixtures";
+
+/**
+ * Gate descriptor factory with runner-test defaults.
+ *
+ * Uses deny as the default `denialContext` check result so tests that
+ * verify block paths don't need to override the surface check.
+ */
+export function makeDescriptor(
+  overrides: Partial<GateDescriptor> = {},
+): GateDescriptor {
+  return {
+    surface: "read",
+    input: {},
+    denialContext: {
+      kind: "tool",
+      check: makeCheckResult({ state: "deny", matchedPattern: "*" }),
+    },
+    promptDetails: {
+      source: "tool_call",
+      agentName: null,
+      message: "Allow tool 'read'?",
+      toolCallId: "tc-1",
+      toolName: "read",
+    },
+    logContext: {
+      source: "tool_call",
+      toolCallId: "tc-1",
+      toolName: "read",
+    },
+    decision: {
+      surface: "read",
+      value: "read",
+    },
+    ...overrides,
+  };
+}
+
+export function makeRunnerDeps(
+  overrides: Partial<GateRunnerDeps> = {},
+): GateRunnerDeps {
+  return {
+    checkPermission: vi
+      .fn()
+      .mockReturnValue(makeCheckResult({ matchedPattern: "*" })),
+    getSessionRuleset: vi.fn().mockReturnValue([]),
+    recordSessionApproval: vi.fn(),
+    writeReviewLog: vi.fn(),
+    emitDecision: vi.fn(),
+    canConfirm: vi.fn().mockReturnValue(true),
+    promptPermission: vi
+      .fn()
+      .mockResolvedValue({ approved: true, state: "approved" }),
+    ...overrides,
+  };
+}
+
+/**
+ * Tool-call context factory with bash defaults.
+ *
+ * path.test.ts uses different defaults (toolName "read", path input) and
+ * keeps a local wrapper; bash-path.test.ts uses this factory directly.
+ */
+export function makeTcc(
+  overrides: Partial<ToolCallContext> = {},
+): ToolCallContext {
+  return {
+    toolName: "bash",
+    agentName: null,
+    input: { command: "cat .env" },
+    toolCallId: "tc-1",
+    cwd: "/test/project",
+    ...overrides,
+  };
+}
+
+/**
+ * Path-surface check result factory.
+ *
+ * Shared between bash-path.test.ts and path.test.ts; both use
+ * toolName "path", source "special", origin "global" as defaults.
+ */
+export function makeGateCheckResult(
+  overrides: Partial<PermissionCheckResult> = {},
+): PermissionCheckResult {
+  return {
+    toolName: "path",
+    state: "allow",
+    source: "special",
+    origin: "global",
+    ...overrides,
+  };
+}

package/test/helpers/handler-fixtures.ts

@@ -0,0 +1,141 @@
+/**
+ * Shared handler-level test fixtures for PermissionGateHandler tests.
+ *
+ * All factories use override bags so callers can specialize any field
+ * without constructing the full object from scratch.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { vi } from "vitest";
+
+import { DEFAULT_EXTENSION_CONFIG } from "#src/extension-config";
+import { PermissionGateHandler } from "#src/handlers/permission-gate-handler";
+import type { PermissionDecisionEvent } from "#src/permission-events";
+import { PERMISSIONS_DECISION_CHANNEL } from "#src/permission-events";
+import type { PermissionSession } from "#src/permission-session";
+import type { ToolRegistry } from "#src/tool-registry";
+import type { PermissionCheckResult } from "#src/types";
+
+export function makeEvents() {
+  return {
+    emit: vi.fn(),
+    on: vi.fn().mockReturnValue(() => undefined),
+  };
+}
+
+export function makeCtx(
+  overrides: Partial<ExtensionContext> = {},
+): ExtensionContext {
+  return {
+    cwd: "/test/project",
+    hasUI: true,
+    ui: {
+      setStatus: vi.fn(),
+      notify: vi.fn(),
+      select: vi.fn(),
+      input: vi.fn(),
+    },
+    sessionManager: {
+      getEntries: vi.fn().mockReturnValue([]),
+      getSessionDir: vi.fn().mockReturnValue("/sessions/test"),
+      addEntry: vi.fn(),
+    },
+    ...overrides,
+  } as unknown as ExtensionContext;
+}
+
+export function makeToolCallEvent(
+  toolName: string,
+  extraFields: Record<string, unknown> = {},
+) {
+  return {
+    type: "tool_call",
+    toolCallId: "tc-1",
+    name: toolName,
+    input: {},
+    ...extraFields,
+  };
+}
+
+/**
+ * Neutral-default check-result builder.
+ *
+ * Pass exactly the fields the original fixture hard-coded so divergent
+ * defaults across test files are preserved at their call sites.
+ */
+export function makeCheckResult(
+  overrides: Partial<PermissionCheckResult> = {},
+): PermissionCheckResult {
+  return {
+    state: "allow",
+    toolName: "read",
+    source: "tool",
+    origin: "builtin",
+    ...overrides,
+  };
+}
+
+/**
+ * Full-union session stub.
+ *
+ * Includes every method mocked across handler test files so each file
+ * only needs to override the fields that differ from the defaults.
+ */
+export function makeSession(
+  overrides: Partial<Record<keyof PermissionSession, unknown>> = {},
+): PermissionSession {
+  return {
+    logger: { debug: vi.fn(), review: vi.fn(), warn: vi.fn() },
+    activate: vi.fn(),
+    resolveAgentName: vi.fn().mockReturnValue(null),
+    checkPermission: vi.fn().mockReturnValue(makeCheckResult()),
+    getToolPermission: vi.fn().mockReturnValue("allow"),
+    getSessionRuleset: vi.fn().mockReturnValue([]),
+    recordSessionApproval: vi.fn(),
+    getActiveSkillEntries: vi.fn().mockReturnValue([]),
+    getInfrastructureDirs: vi
+      .fn()
+      .mockReturnValue(["/test/agent", "/test/agent/git"]),
+    getInfrastructureReadPaths: vi.fn().mockReturnValue([]),
+    config: DEFAULT_EXTENSION_CONFIG,
+    canPrompt: vi.fn().mockReturnValue(true),
+    prompt: vi.fn().mockResolvedValue({ approved: true, state: "approved" }),
+    createPermissionRequestId: vi.fn().mockReturnValue("req-id"),
+    ...overrides,
+  } as unknown as PermissionSession;
+}
+
+export function makeToolRegistry(
+  overrides: Partial<ToolRegistry> = {},
+): ToolRegistry {
+  return {
+    getAll: vi.fn().mockReturnValue([{ name: "read" }, { name: "bash" }]),
+    setActive: vi.fn(),
+    ...overrides,
+  };
+}
+
+/**
+ * Constructs a PermissionGateHandler with mocked collaborators.
+ *
+ * Returns all collaborators so each test file can destructure only what
+ * it needs — handler, events, session, and toolRegistry are all available.
+ */
+export function makeHandler(overrides?: {
+  session?: Partial<Record<keyof PermissionSession, unknown>>;
+  toolRegistry?: Partial<ToolRegistry>;
+}) {
+  const session = makeSession(overrides?.session);
+  const events = makeEvents();
+  const toolRegistry = makeToolRegistry(overrides?.toolRegistry);
+  const handler = new PermissionGateHandler(session, events, toolRegistry);
+  return { handler, events, session, toolRegistry };
+}
+
+/** Extract all permissions:decision payloads from the events.emit mock. */
+export function getDecisionEvents(
+  events: ReturnType<typeof makeEvents>,
+): PermissionDecisionEvent[] {
+  return events.emit.mock.calls
+    .filter(([channel]) => channel === PERMISSIONS_DECISION_CHANNEL)
+    .map(([, payload]) => payload as PermissionDecisionEvent);
+}