@gotgenes/pi-permission-system 4.4.1 → 4.5.0

package/src/rule.ts

@@ -45,3 +45,35 @@ export function evaluate(
   }
   return { surface, pattern, action: defaultAction ?? "ask" };
 }
+
+/**
+ * Evaluate a surface against an ordered list of candidate values, stopping at
+ * the first candidate that matches a non-default rule (last-match-wins within
+ * each candidate, first-non-default-wins across candidates).
+ *
+ * Used by MCP (multi-candidate target list) and, uniformly, by all other
+ * surfaces (single-element candidate list).
+ *
+ * Returns the matched rule and the candidate value that produced it.
+ * When every candidate matches only the synthesized default, falls back to
+ * evaluating the first candidate so the caller always receives a concrete
+ * result.
+ */
+export function evaluateFirst(
+  surface: string,
+  values: string[],
+  rules: Ruleset,
+): { rule: Rule; value: string } {
+  for (const value of values) {
+    const rule = evaluate(surface, value, rules);
+    if (rule.layer !== "default") {
+      return { rule, value };
+    }
+  }
+  // All candidates matched only the synthesized default — use the first.
+  const fallbackValue = values[0] ?? "*";
+  return {
+    rule: evaluate(surface, fallbackValue, rules),
+    value: fallbackValue,
+  };
+}

package/tests/input-normalizer.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, it } from "vitest";
+import { normalizeInput } from "../src/input-normalizer";
+import { createMcpPermissionTargets } from "../src/mcp-targets";
+
+describe("normalizeInput — non-MCP surfaces", () => {
+  describe("special / external_directory", () => {
+    it("uses path from input as the lookup value", () => {
+      const result = normalizeInput(
+        "external_directory",
+        { path: "/other/project" },
+        [],
+      );
+      expect(result.surface).toBe("external_directory");
+      expect(result.values).toEqual(["/other/project"]);
+      expect(result.resultExtras).toEqual({});
+    });
+
+    it("falls back to '*' when path is missing", () => {
+      const result = normalizeInput("external_directory", {}, []);
+      expect(result.values).toEqual(["*"]);
+    });
+
+    it("falls back to '*' when path is not a string", () => {
+      const result = normalizeInput("external_directory", { path: 42 }, []);
+      expect(result.values).toEqual(["*"]);
+    });
+
+    it("handles null input", () => {
+      const result = normalizeInput("external_directory", null, []);
+      expect(result.values).toEqual(["*"]);
+    });
+  });
+
+  describe("skill", () => {
+    it("uses skill name from input.name", () => {
+      const result = normalizeInput("skill", { name: "librarian" }, []);
+      expect(result.surface).toBe("skill");
+      expect(result.values).toEqual(["librarian"]);
+      expect(result.resultExtras).toEqual({});
+    });
+
+    it("falls back to '*' when name is missing", () => {
+      const result = normalizeInput("skill", {}, []);
+      expect(result.values).toEqual(["*"]);
+    });
+
+    it("falls back to '*' when name is not a string", () => {
+      const result = normalizeInput("skill", { name: 99 }, []);
+      expect(result.values).toEqual(["*"]);
+    });
+  });
+
+  describe("bash", () => {
+    it("uses command from input.command", () => {
+      const result = normalizeInput("bash", { command: "git status" }, []);
+      expect(result.surface).toBe("bash");
+      expect(result.values).toEqual(["git status"]);
+      expect(result.resultExtras).toEqual({ command: "git status" });
+    });
+
+    it("uses empty string when command is missing", () => {
+      const result = normalizeInput("bash", {}, []);
+      expect(result.values).toEqual([""]);
+      expect(result.resultExtras).toEqual({ command: "" });
+    });
+
+    it("uses empty string when command is not a string", () => {
+      const result = normalizeInput("bash", { command: 42 }, []);
+      expect(result.values).toEqual([""]);
+      expect(result.resultExtras).toEqual({ command: "" });
+    });
+  });
+
+  describe("tool surfaces (read, write, edit, grep, find, ls, extension tools)", () => {
+    it("uses '*' as the lookup value for built-in tools", () => {
+      for (const tool of ["read", "write", "edit", "grep", "find", "ls"]) {
+        const result = normalizeInput(tool, {}, []);
+        expect(result.surface).toBe(tool);
+        expect(result.values).toEqual(["*"]);
+        expect(result.resultExtras).toEqual({});
+      }
+    });
+
+    it("uses '*' as the lookup value for extension tools", () => {
+      const result = normalizeInput("my_extension_tool", { some: "input" }, []);
+      expect(result.surface).toBe("my_extension_tool");
+      expect(result.values).toEqual(["*"]);
+      expect(result.resultExtras).toEqual({});
+    });
+  });
+});
+
+describe("normalizeInput — MCP surface", () => {
+  it("surface is 'mcp'", () => {
+    const result = normalizeInput("mcp", { tool: "exa:search" }, []);
+    expect(result.surface).toBe("mcp");
+  });
+
+  it("values end with the catch-all 'mcp' target", () => {
+    const result = normalizeInput("mcp", { tool: "exa:search" }, []);
+    expect(result.values.at(-1)).toBe("mcp");
+  });
+
+  it("values include specific targets before the catch-all for a qualified tool call", () => {
+    const result = normalizeInput("mcp", { tool: "exa:search" }, []);
+    expect(result.values).toContain("exa_search");
+    expect(result.values).toContain("exa:search");
+    expect(result.values).toContain("exa");
+    expect(result.values).toContain("mcp_call");
+    // 'mcp' is always last
+    expect(result.values.at(-1)).toBe("mcp");
+  });
+
+  it("matches createMcpPermissionTargets output + 'mcp' appended", () => {
+    const rawTargets = createMcpPermissionTargets({ tool: "exa:search" }, [
+      "exa",
+    ]);
+    const result = normalizeInput("mcp", { tool: "exa:search" }, ["exa"]);
+    expect(result.values).toEqual([...rawTargets, "mcp"]);
+  });
+
+  it("resultExtras.target is the first specific target (most-specific)", () => {
+    const result = normalizeInput("mcp", { tool: "exa:search" }, []);
+    expect(result.resultExtras.target).toBe(result.values[0]);
+  });
+
+  it("resultExtras.target is 'mcp' when no specific targets are derived", () => {
+    // Empty input → only mcp_status then mcp appended
+    const result = normalizeInput("mcp", {}, []);
+    expect(result.resultExtras.target).toBe("mcp_status");
+  });
+
+  it("values contain no duplicates", () => {
+    const result = normalizeInput("mcp", { tool: "exa:search" }, ["exa"]);
+    const unique = [...new Set(result.values)];
+    expect(result.values).toEqual(unique);
+  });
+
+  it("produces mcp_status + mcp for status input", () => {
+    const result = normalizeInput("mcp", {}, []);
+    expect(result.values).toEqual(["mcp_status", "mcp"]);
+  });
+
+  it("produces connect targets + mcp for connect input", () => {
+    const result = normalizeInput("mcp", { connect: "exa" }, []);
+    expect(result.values).toContain("mcp_connect_exa");
+    expect(result.values).toContain("mcp_connect");
+    expect(result.values.at(-1)).toBe("mcp");
+  });
+});

package/tests/mcp-targets.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from "vitest";
+import {
+  createMcpPermissionTargets,
+  parseQualifiedMcpToolName,
+} from "../src/mcp-targets";
+
+describe("parseQualifiedMcpToolName", () => {
+  it("returns server and tool for a valid qualified name", () => {
+    expect(parseQualifiedMcpToolName("exa:search")).toEqual({
+      server: "exa",
+      tool: "search",
+    });
+  });
+
+  it("returns server and tool with surrounding whitespace trimmed", () => {
+    expect(parseQualifiedMcpToolName("  exa : search  ")).toEqual({
+      server: "exa",
+      tool: "search",
+    });
+  });
+
+  it("returns null for empty string", () => {
+    expect(parseQualifiedMcpToolName("")).toBeNull();
+  });
+
+  it("returns null for whitespace-only string", () => {
+    expect(parseQualifiedMcpToolName("   ")).toBeNull();
+  });
+
+  it("returns null when colon is the first character", () => {
+    expect(parseQualifiedMcpToolName(":search")).toBeNull();
+  });
+
+  it("returns null when colon is the last character", () => {
+    expect(parseQualifiedMcpToolName("exa:")).toBeNull();
+  });
+
+  it("returns null for a plain tool name with no colon", () => {
+    expect(parseQualifiedMcpToolName("exa_search")).toBeNull();
+  });
+
+  it("returns null when server part is empty after trimming", () => {
+    expect(parseQualifiedMcpToolName(" :search")).toBeNull();
+  });
+
+  it("returns null when tool part is empty after trimming", () => {
+    expect(parseQualifiedMcpToolName("exa: ")).toBeNull();
+  });
+});
+
+describe("createMcpPermissionTargets", () => {
+  describe("tool call (input.tool)", () => {
+    it("produces targets for a bare tool name with no configured servers", () => {
+      const targets = createMcpPermissionTargets({ tool: "exa_search" }, []);
+      expect(targets).toContain("exa_search");
+      expect(targets).toContain("mcp_call");
+    });
+
+    it("produces targets for a qualified tool name (server:tool)", () => {
+      const targets = createMcpPermissionTargets({ tool: "exa:search" }, []);
+      expect(targets).toContain("exa_search");
+      expect(targets).toContain("exa:search");
+      expect(targets).toContain("exa");
+      expect(targets).toContain("mcp_call");
+    });
+
+    it("produces targets for a tool call with explicit server field", () => {
+      const targets = createMcpPermissionTargets(
+        { tool: "search", server: "exa" },
+        [],
+      );
+      expect(targets).toContain("exa_search");
+      expect(targets).toContain("exa:search");
+      expect(targets).toContain("exa");
+      expect(targets).toContain("mcp_call");
+    });
+
+    it("derives server targets from configured server names when tool name ends with _<server>", () => {
+      const targets = createMcpPermissionTargets({ tool: "exa_search" }, [
+        "exa",
+      ]);
+      // exa_search ends with _exa? No — it ends with _search. This tool name
+      // does NOT trigger server derivation because it does not end with _exa.
+      expect(targets).toContain("exa_search");
+    });
+
+    it("does not include duplicate entries", () => {
+      const targets = createMcpPermissionTargets({ tool: "exa:search" }, [
+        "exa",
+      ]);
+      const unique = [...new Set(targets)];
+      expect(targets).toEqual(unique);
+    });
+  });
+
+  describe("connect call (input.connect)", () => {
+    it("produces targets for a connect operation", () => {
+      const targets = createMcpPermissionTargets({ connect: "exa" }, []);
+      expect(targets).toContain("mcp_connect_exa");
+      expect(targets).toContain("exa");
+      expect(targets).toContain("mcp_connect");
+    });
+
+    it("does not include mcp_call for connect operations", () => {
+      const targets = createMcpPermissionTargets({ connect: "exa" }, []);
+      expect(targets).not.toContain("mcp_call");
+    });
+  });
+
+  describe("describe operation (input.describe)", () => {
+    it("produces targets for a describe operation on a qualified tool", () => {
+      const targets = createMcpPermissionTargets(
+        { describe: "exa:search" },
+        [],
+      );
+      expect(targets).toContain("exa_search");
+      expect(targets).toContain("exa:search");
+      expect(targets).toContain("exa");
+      expect(targets).toContain("mcp_describe");
+    });
+  });
+
+  describe("search operation (input.search)", () => {
+    it("produces mcp_search and the search string as targets", () => {
+      const targets = createMcpPermissionTargets({ search: "weather" }, []);
+      expect(targets).toContain("weather");
+      expect(targets).toContain("mcp_search");
+    });
+
+    it("includes server targets when server is provided alongside search", () => {
+      const targets = createMcpPermissionTargets(
+        { search: "weather", server: "exa" },
+        [],
+      );
+      expect(targets).toContain("mcp_server_exa");
+      expect(targets).toContain("exa");
+      expect(targets).toContain("mcp_search");
+    });
+  });
+
+  describe("server listing (input.server only)", () => {
+    it("produces mcp_list and server-specific targets", () => {
+      const targets = createMcpPermissionTargets({ server: "exa" }, []);
+      expect(targets).toContain("mcp_server_exa");
+      expect(targets).toContain("exa");
+      expect(targets).toContain("mcp_list");
+    });
+  });
+
+  describe("status (no meaningful input)", () => {
+    it("produces mcp_status for empty input", () => {
+      const targets = createMcpPermissionTargets({}, []);
+      expect(targets).toContain("mcp_status");
+    });
+
+    it("produces mcp_status for null input", () => {
+      const targets = createMcpPermissionTargets(null, []);
+      expect(targets).toContain("mcp_status");
+    });
+
+    it("produces mcp_status when no server/tool/connect/describe/search present", () => {
+      const targets = createMcpPermissionTargets({ unrelated: "value" }, [
+        "exa",
+      ]);
+      expect(targets).toContain("mcp_status");
+    });
+  });
+
+  describe("priority ordering", () => {
+    it("tool targets appear before mcp_call", () => {
+      const targets = createMcpPermissionTargets({ tool: "exa:search" }, []);
+      const mcpCallIdx = targets.indexOf("mcp_call");
+      const exaSearchIdx = targets.indexOf("exa_search");
+      expect(exaSearchIdx).toBeGreaterThanOrEqual(0);
+      expect(mcpCallIdx).toBeGreaterThan(exaSearchIdx);
+    });
+  });
+});