@gotgenes/pi-permission-system 5.6.1 → 5.6.2

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.6.2](https://github.com/gotgenes/pi-permission-system/compare/v5.6.1...v5.6.2) (2026-05-07)
+
+
+### Documentation
+
+* clarify bash arity table usage difference with OpenCode ([b387480](https://github.com/gotgenes/pi-permission-system/commit/b3874801a5084fa762cf521b743c21e3ed328d79))
+* clarify doom_loop is not a Pi surface, not just deprecated ([8c38ab2](https://github.com/gotgenes/pi-permission-system/commit/8c38ab24dbcc4ecb1da8baa1276facfdfa21e785))
+* detail superior bash path extraction vs OpenCode's allowlist approach ([b16767b](https://github.com/gotgenes/pi-permission-system/commit/b16767b5df0d9d8cf960a47f4bfbaa788ee21def))
+* merge doom_loop into OpenCode-only surfaces row ([85756a7](https://github.com/gotgenes/pi-permission-system/commit/85756a72917d43931c9026c0120d6f2731bfae5e))
+* move bash arity/tree-sitter to shared concepts (both at parity) ([6fd7cdc](https://github.com/gotgenes/pi-permission-system/commit/6fd7cdcad2917ab98fb80f80fe2abc8cc5c6bd36))
+* plan deduplicate shared helpers ([#109](https://github.com/gotgenes/pi-permission-system/issues/109)) ([52bff2e](https://github.com/gotgenes/pi-permission-system/commit/52bff2ef7cf0f5d64cf27f90381b558ed8427ac6))
+* plan split external-directory into focused modules ([#110](https://github.com/gotgenes/pi-permission-system/issues/110)) ([b2a4610](https://github.com/gotgenes/pi-permission-system/commit/b2a4610430e27f8ec9456c70e31ce54aa866ac30))
+* **retro:** add retro notes for issue [#106](https://github.com/gotgenes/pi-permission-system/issues/106) ([a945814](https://github.com/gotgenes/pi-permission-system/commit/a945814799264396fa8fc94249791fdbc22b58c1))
+* update target architecture for extracted helpers ([52693d6](https://github.com/gotgenes/pi-permission-system/commit/52693d6c0b0164d38b2746a40df9aab7031b47b2))
+
 ## [5.6.1](https://github.com/gotgenes/pi-permission-system/compare/v5.6.0...v5.6.1) (2026-05-07)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "5.6.1",
+  "version": "5.6.2",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "files": [

package/src/config-loader.ts

@@ -9,6 +9,7 @@ import {
   getLegacyProjectPolicyPath,
   getProjectConfigPath,
 } from "./config-paths";
+import { mergeFlatPermissions } from "./permission-merge";
 import type { FlatPermissionConfig } from "./types";
 
 /**
@@ -151,35 +152,6 @@ function normalizeFlatPermissionValue(
   return hasAny ? normalized : undefined;
 }
 
-/**
- * Deep-shallow merge two flat permission configs.
- * - Both objects for same key → shallow-merge the pattern maps.
- * - Otherwise → override replaces base.
- */
-function mergeFlatPermissions(
-  base: FlatPermissionConfig,
-  override: FlatPermissionConfig,
-): FlatPermissionConfig {
-  const merged: FlatPermissionConfig = { ...base };
-  for (const [key, value] of Object.entries(override)) {
-    const baseVal = merged[key];
-    if (
-      typeof baseVal === "object" &&
-      baseVal !== null &&
-      typeof value === "object" &&
-      value !== null
-    ) {
-      merged[key] = {
-        ...(baseVal as Record<string, import("./types").PermissionState>),
-        ...(value as Record<string, import("./types").PermissionState>),
-      };
-    } else {
-      merged[key] = value;
-    }
-  }
-  return merged;
-}
-
 /**
  * Normalize raw parsed JSON into the unified config shape.
  */

package/src/external-directory.ts

@@ -1,12 +1,21 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
-import { homedir } from "node:os";
 import { basename, dirname, join, normalize, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { getNonEmptyString, toRecord } from "./common";
 
+export {
+  isPathWithinDirectory,
+  normalizePathForComparison,
+} from "./path-utils";
+
+import {
+  isPathWithinDirectory,
+  normalizePathForComparison,
+} from "./path-utils";
+
 /**
  * Walk up the directory tree from the given file URL until a directory
  * literally named `node_modules` is found.
@@ -161,49 +170,6 @@ export const PATH_BEARING_TOOLS = new Set([
   "ls",
 ]);
 
-export function normalizePathForComparison(
-  pathValue: string,
-  cwd: string,
-): string {
-  const trimmed = pathValue.trim().replace(/^['"]|['"]$/g, "");
-  if (!trimmed) {
-    return "";
-  }
-
-  let normalizedPath = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
-
-  if (normalizedPath === "~") {
-    normalizedPath = homedir();
-  } else if (
-    normalizedPath.startsWith("~/") ||
-    normalizedPath.startsWith("~\\")
-  ) {
-    normalizedPath = join(homedir(), normalizedPath.slice(2));
-  }
-
-  const absolutePath = resolve(cwd, normalizedPath);
-  const normalizedAbsolutePath = normalize(absolutePath);
-  return process.platform === "win32"
-    ? normalizedAbsolutePath.toLowerCase()
-    : normalizedAbsolutePath;
-}
-
-export function isPathWithinDirectory(
-  pathValue: string,
-  directory: string,
-): boolean {
-  if (!pathValue || !directory) {
-    return false;
-  }
-
-  if (pathValue === directory) {
-    return true;
-  }
-
-  const prefix = directory.endsWith(sep) ? directory : `${directory}${sep}`;
-  return pathValue.startsWith(prefix);
-}
-
 export function getPathBearingToolPath(
   toolName: string,
   input: unknown,

package/src/handlers/gates/external-directory.ts

@@ -5,8 +5,8 @@ import {
   getPathBearingToolPath,
   isPathOutsideWorkingDirectory,
   isPiInfrastructureRead,
-  normalizePathForComparison,
 } from "../../external-directory";
+import { normalizePathForComparison } from "../../path-utils";
 import { deriveApprovalPattern } from "../../session-rules";
 import type { GateResult } from "./descriptor";
 import type { ToolCallContext } from "./types";

package/src/handlers/gates/skill-read.ts

@@ -1,5 +1,5 @@
 import { toRecord } from "../../common";
-import { normalizePathForComparison } from "../../external-directory";
+import { normalizePathForComparison } from "../../path-utils";
 import {
   formatSkillPathAskPrompt,
   formatSkillPathDenyReason,

package/src/path-utils.ts

@@ -0,0 +1,45 @@
+import { homedir } from "node:os";
+import { join, normalize, resolve, sep } from "node:path";
+
+export function normalizePathForComparison(
+  pathValue: string,
+  cwd: string,
+): string {
+  const trimmed = pathValue.trim().replace(/^['"]|['"]$/g, "");
+  if (!trimmed) {
+    return "";
+  }
+
+  let normalizedPath = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+
+  if (normalizedPath === "~") {
+    normalizedPath = homedir();
+  } else if (
+    normalizedPath.startsWith("~/") ||
+    normalizedPath.startsWith("~\\")
+  ) {
+    normalizedPath = join(homedir(), normalizedPath.slice(2));
+  }
+
+  const absolutePath = resolve(cwd, normalizedPath);
+  const normalizedAbsolutePath = normalize(absolutePath);
+  return process.platform === "win32"
+    ? normalizedAbsolutePath.toLowerCase()
+    : normalizedAbsolutePath;
+}
+
+export function isPathWithinDirectory(
+  pathValue: string,
+  directory: string,
+): boolean {
+  if (!pathValue || !directory) {
+    return false;
+  }
+
+  if (pathValue === directory) {
+    return true;
+  }
+
+  const prefix = directory.endsWith(sep) ? directory : `${directory}${sep}`;
+  return pathValue.startsWith(prefix);
+}

package/src/permission-manager.ts

@@ -1,6 +1,7 @@
 import { isPermissionState } from "./common";
 import { normalizeInput } from "./input-normalizer";
 import { normalizeFlatConfig } from "./normalize";
+import { mergeFlatPermissions } from "./permission-merge";
 import {
   FilePolicyLoader,
   type PolicyLoader,
@@ -34,35 +35,6 @@ const SPECIAL_PERMISSION_KEYS = new Set(["external_directory"]);
 /** Universal fallback when permission["*"] is absent from all scopes. */
 const DEFAULT_UNIVERSAL_FALLBACK: PermissionState = "ask";
 
-/**
- * Deep-shallow merge two flat permission configs.
- * Both objects → shallow-merge the pattern maps.
- * Otherwise → override replaces base.
- */
-function mergeFlatPermissions(
-  base: FlatPermissionConfig,
-  override: FlatPermissionConfig,
-): FlatPermissionConfig {
-  const merged: FlatPermissionConfig = { ...base };
-  for (const [key, value] of Object.entries(override)) {
-    const baseVal = merged[key];
-    if (
-      typeof baseVal === "object" &&
-      baseVal !== null &&
-      typeof value === "object" &&
-      value !== null
-    ) {
-      merged[key] = {
-        ...(baseVal as Record<string, PermissionState>),
-        ...(value as Record<string, PermissionState>),
-      };
-    } else {
-      merged[key] = value;
-    }
-  }
-  return merged;
-}
-
 type FileCacheEntry<TValue> = {
   stamp: string;
   value: TValue;

package/src/permission-merge.ts

@@ -0,0 +1,30 @@
+import type { FlatPermissionConfig, PermissionState } from "./types";
+
+/**
+ * Deep-shallow merge two flat permission configs.
+ * Both objects → shallow-merge the pattern maps.
+ * Otherwise → override replaces base.
+ */
+export function mergeFlatPermissions(
+  base: FlatPermissionConfig,
+  override: FlatPermissionConfig,
+): FlatPermissionConfig {
+  const merged: FlatPermissionConfig = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const baseVal = merged[key];
+    if (
+      typeof baseVal === "object" &&
+      baseVal !== null &&
+      typeof value === "object" &&
+      value !== null
+    ) {
+      merged[key] = {
+        ...(baseVal as Record<string, PermissionState>),
+        ...(value as Record<string, PermissionState>),
+      };
+    } else {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}

package/src/skill-prompt-sanitizer.ts

@@ -1,6 +1,9 @@
-import { homedir } from "node:os";
-import { dirname, join, normalize, resolve, sep } from "node:path";
+import { dirname } from "node:path";
 
+import {
+  isPathWithinDirectory,
+  normalizePathForComparison,
+} from "./path-utils";
 import type { PermissionManager } from "./permission-manager";
 import type { PermissionState } from "./types";
 
@@ -50,43 +53,6 @@ function encodeXml(value: string): string {
     .replace(/'/g, "'");
 }
 
-function normalizePathForComparison(pathValue: string, cwd: string): string {
-  const trimmed = pathValue.trim().replace(/^['"]|['"]$/g, "");
-  if (!trimmed) {
-    return "";
-  }
-
-  let normalizedPath = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
-
-  if (normalizedPath === "~") {
-    normalizedPath = homedir();
-  } else if (
-    normalizedPath.startsWith("~/") ||
-    normalizedPath.startsWith("~\\")
-  ) {
-    normalizedPath = join(homedir(), normalizedPath.slice(2));
-  }
-
-  const absolutePath = resolve(cwd, normalizedPath);
-  const normalizedAbsolutePath = normalize(absolutePath);
-  return process.platform === "win32"
-    ? normalizedAbsolutePath.toLowerCase()
-    : normalizedAbsolutePath;
-}
-
-function isPathWithinDirectory(pathValue: string, directory: string): boolean {
-  if (!pathValue || !directory) {
-    return false;
-  }
-
-  if (pathValue === directory) {
-    return true;
-  }
-
-  const prefix = directory.endsWith(sep) ? directory : `${directory}${sep}`;
-  return pathValue.startsWith(prefix);
-}
-
 function parseSkillEntries(sectionBody: string): ParsedSkillPromptEntry[] {
   const entries: ParsedSkillPromptEntry[] = [];
   const skillBlockRegex = new RegExp(SKILL_BLOCK_PATTERN, "g");

package/tests/external-directory.test.ts

@@ -1,4 +1,3 @@
-import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
 // Hoisted stubs for mocks that reference them in vi.mock factories.
@@ -36,9 +35,7 @@ import {
   formatExternalDirectoryUserDeniedReason,
   getPathBearingToolPath,
   isPathOutsideWorkingDirectory,
-  isPathWithinDirectory,
   isSafeSystemPath,
-  normalizePathForComparison,
   PATH_BEARING_TOOLS,
   SAFE_SYSTEM_PATHS,
 } from "../src/external-directory";
@@ -103,82 +100,6 @@ describe("isSafeSystemPath", () => {
   });
 });
 
-describe("normalizePathForComparison", () => {
-  const cwd = "/projects/my-app";
-
-  test("resolves absolute path unchanged", () => {
-    expect(normalizePathForComparison("/usr/local/bin", cwd)).toBe(
-      "/usr/local/bin",
-    );
-  });
-
-  test("resolves relative path against cwd", () => {
-    expect(normalizePathForComparison("src/foo.ts", cwd)).toBe(
-      "/projects/my-app/src/foo.ts",
-    );
-  });
-
-  test("expands bare ~ to homedir", () => {
-    expect(normalizePathForComparison("~", cwd)).toBe("/mock/home");
-  });
-
-  test("expands ~/... to homedir-relative path", () => {
-    expect(normalizePathForComparison("~/docs/readme.md", cwd)).toBe(
-      join("/mock/home", "docs/readme.md"),
-    );
-  });
-
-  test("strips leading @ before resolving", () => {
-    expect(normalizePathForComparison("@/usr/local/bin", cwd)).toBe(
-      "/usr/local/bin",
-    );
-  });
-
-  test("strips surrounding quotes", () => {
-    expect(normalizePathForComparison("'/usr/local/bin'", cwd)).toBe(
-      "/usr/local/bin",
-    );
-    expect(normalizePathForComparison('"/usr/local/bin"', cwd)).toBe(
-      "/usr/local/bin",
-    );
-  });
-
-  test("returns empty string for blank/whitespace-only path", () => {
-    expect(normalizePathForComparison("", cwd)).toBe("");
-    expect(normalizePathForComparison("   ", cwd)).toBe("");
-  });
-});
-
-describe("isPathWithinDirectory", () => {
-  test("returns true when path equals directory", () => {
-    expect(isPathWithinDirectory("/a/b", "/a/b")).toBe(true);
-  });
-
-  test("returns true when path is a direct child", () => {
-    expect(isPathWithinDirectory("/a/b/c", "/a/b")).toBe(true);
-  });
-
-  test("returns true when path is a deep descendant", () => {
-    expect(isPathWithinDirectory("/a/b/c/d/e", "/a/b")).toBe(true);
-  });
-
-  test("returns false when path is a sibling directory", () => {
-    expect(isPathWithinDirectory("/a/bc", "/a/b")).toBe(false);
-  });
-
-  test("returns false when path is outside the directory", () => {
-    expect(isPathWithinDirectory("/other/path", "/a/b")).toBe(false);
-  });
-
-  test("returns false for empty path", () => {
-    expect(isPathWithinDirectory("", "/a/b")).toBe(false);
-  });
-
-  test("returns false for empty directory", () => {
-    expect(isPathWithinDirectory("/a/b", "")).toBe(false);
-  });
-});
-
 describe("getPathBearingToolPath", () => {
   test("returns path for a path-bearing tool", () => {
     expect(getPathBearingToolPath("read", { path: "/src/foo.ts" })).toBe(

package/tests/path-utils.test.ts

@@ -0,0 +1,92 @@
+import { join } from "node:path";
+import { describe, expect, test, vi } from "vitest";
+
+// Mock node:os so tilde-expansion is deterministic across platforms.
+vi.mock("node:os", () => {
+  const homedir = vi.fn(() => "/mock/home");
+  return {
+    homedir,
+    default: { homedir },
+  };
+});
+
+import {
+  isPathWithinDirectory,
+  normalizePathForComparison,
+} from "../src/path-utils";
+
+describe("normalizePathForComparison", () => {
+  const cwd = "/projects/my-app";
+
+  test("resolves absolute path unchanged", () => {
+    expect(normalizePathForComparison("/usr/local/bin", cwd)).toBe(
+      "/usr/local/bin",
+    );
+  });
+
+  test("resolves relative path against cwd", () => {
+    expect(normalizePathForComparison("src/foo.ts", cwd)).toBe(
+      "/projects/my-app/src/foo.ts",
+    );
+  });
+
+  test("expands bare ~ to homedir", () => {
+    expect(normalizePathForComparison("~", cwd)).toBe("/mock/home");
+  });
+
+  test("expands ~/... to homedir-relative path", () => {
+    expect(normalizePathForComparison("~/docs/readme.md", cwd)).toBe(
+      join("/mock/home", "docs/readme.md"),
+    );
+  });
+
+  test("strips leading @ before resolving", () => {
+    expect(normalizePathForComparison("@/usr/local/bin", cwd)).toBe(
+      "/usr/local/bin",
+    );
+  });
+
+  test("strips surrounding quotes", () => {
+    expect(normalizePathForComparison("'/usr/local/bin'", cwd)).toBe(
+      "/usr/local/bin",
+    );
+    expect(normalizePathForComparison('"/usr/local/bin"', cwd)).toBe(
+      "/usr/local/bin",
+    );
+  });
+
+  test("returns empty string for blank/whitespace-only path", () => {
+    expect(normalizePathForComparison("", cwd)).toBe("");
+    expect(normalizePathForComparison("   ", cwd)).toBe("");
+  });
+});
+
+describe("isPathWithinDirectory", () => {
+  test("returns true when path equals directory", () => {
+    expect(isPathWithinDirectory("/a/b", "/a/b")).toBe(true);
+  });
+
+  test("returns true when path is a direct child", () => {
+    expect(isPathWithinDirectory("/a/b/c", "/a/b")).toBe(true);
+  });
+
+  test("returns true when path is a deep descendant", () => {
+    expect(isPathWithinDirectory("/a/b/c/d/e", "/a/b")).toBe(true);
+  });
+
+  test("returns false when path is a sibling directory", () => {
+    expect(isPathWithinDirectory("/a/bc", "/a/b")).toBe(false);
+  });
+
+  test("returns false when path is outside the directory", () => {
+    expect(isPathWithinDirectory("/other/path", "/a/b")).toBe(false);
+  });
+
+  test("returns false for empty path", () => {
+    expect(isPathWithinDirectory("", "/a/b")).toBe(false);
+  });
+
+  test("returns false for empty directory", () => {
+    expect(isPathWithinDirectory("/a/b", "")).toBe(false);
+  });
+});

package/tests/permission-merge.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "vitest";
+
+import { mergeFlatPermissions } from "../src/permission-merge";
+
+describe("mergeFlatPermissions", () => {
+  test("string replaces string", () => {
+    const result = mergeFlatPermissions({ tools: "ask" }, { tools: "allow" });
+    expect(result).toEqual({ tools: "allow" });
+  });
+
+  test("both objects → shallow-merge pattern maps", () => {
+    const result = mergeFlatPermissions(
+      { bash: { "rm *": "deny", "git *": "ask" } },
+      { bash: { "rm *": "allow", "npm *": "allow" } },
+    );
+    expect(result).toEqual({
+      bash: { "rm *": "allow", "git *": "ask", "npm *": "allow" },
+    });
+  });
+
+  test("object replaces string", () => {
+    const result = mergeFlatPermissions(
+      { tools: "ask" },
+      { tools: { Write: "deny" } },
+    );
+    expect(result).toEqual({ tools: { Write: "deny" } });
+  });
+
+  test("string replaces object", () => {
+    const result = mergeFlatPermissions(
+      { tools: { Write: "deny" } },
+      { tools: "allow" },
+    );
+    expect(result).toEqual({ tools: "allow" });
+  });
+
+  test("empty override returns base unchanged", () => {
+    const base = { tools: "ask" as const, bash: { "rm *": "deny" as const } };
+    const result = mergeFlatPermissions(base, {});
+    expect(result).toEqual(base);
+  });
+
+  test("empty base returns override", () => {
+    const override = { tools: "allow" as const };
+    const result = mergeFlatPermissions({}, override);
+    expect(result).toEqual(override);
+  });
+
+  test("preserves keys only in base", () => {
+    const result = mergeFlatPermissions(
+      { tools: "ask", bash: "deny" },
+      { tools: "allow" },
+    );
+    expect(result).toEqual({ tools: "allow", bash: "deny" });
+  });
+
+  test("adds keys only in override", () => {
+    const result = mergeFlatPermissions({ tools: "ask" }, { bash: "allow" });
+    expect(result).toEqual({ tools: "ask", bash: "allow" });
+  });
+});