@gotgenes/pi-permission-system 4.7.0 → 4.8.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [4.8.0](https://github.com/gotgenes/pi-permission-system/compare/v4.7.0...v4.8.0) (2026-05-05)
+
+
+### Features
+
+* add expandHomePath utility for ~ and $HOME expansion ([18264e1](https://github.com/gotgenes/pi-permission-system/commit/18264e104f6aa12ca004a127d0f7b09b9e4fb740))
+* expand ~ and $HOME in wildcard patterns at compile time ([3c7e0c2](https://github.com/gotgenes/pi-permission-system/commit/3c7e0c2ab92c1e6bb58fdab32cfd9ae2c72e100a))
+
+
+### Documentation
+
+* document ~/$HOME pattern expansion in schema, example config, and README ([8ad5190](https://github.com/gotgenes/pi-permission-system/commit/8ad51909512ca294c83876868407866290234882))
+* plan home directory expansion in permission patterns ([#53](https://github.com/gotgenes/pi-permission-system/issues/53)) ([b5b77b6](https://github.com/gotgenes/pi-permission-system/commit/b5b77b640006b67b51420135be8fb78484c9d9a1))
+* **retro:** add retro notes for issue [#52](https://github.com/gotgenes/pi-permission-system/issues/52) ([7fc8113](https://github.com/gotgenes/pi-permission-system/commit/7fc8113390fd1dd9cf09c05e903d597c16d80104))
+* sleep before pulling release commit and tag ([af701b5](https://github.com/gotgenes/pi-permission-system/commit/af701b543b20f274ca9f8aa904af0a39bc232c26))
+
 ## [4.7.0](https://github.com/gotgenes/pi-permission-system/compare/v4.6.0...v4.7.0) (2026-05-05)
 
 

package/README.md

@@ -156,7 +156,7 @@ The `permission` object maps surface names to actions:
 | `bash` | string or object | Bash catch-all or `{ pattern: action }` map |
 | `mcp` | string or object | MCP catch-all or `{ pattern: action }` map |
 | `skill` | string or object | Skill catch-all or `{ pattern: action }` map |
-| `external_directory` | string | Controls access to paths outside `cwd` |
+| `external_directory` | string or object | Controls access to paths outside `cwd`; supports `~/` and `$HOME/` patterns |
 
 > **Note:** Trailing commas are **not** supported. If parsing fails, the extension falls back to `ask` for all categories.
 
@@ -330,14 +330,36 @@ Skill name patterns use `*` wildcards (note: surface is `skill`, not `skills`):
 }
 ```
 
+### Home directory expansion in patterns
+
+Pattern keys in any permission surface can start with `~/` or `$HOME/` (or be exactly `~` / `$HOME`).
+They are expanded to the OS home directory at match time, so configs are portable across machines and users.
+
+```jsonc
+{
+  "permission": {
+    "external_directory": {
+      "*": "ask",
+      "~/development/*": "allow"
+    }
+  }
+}
+```
+
+The pattern is stored and displayed as written (e.g. `~/development/*`) in logs and approval dialogs.
+
 ### `external_directory` surface
 
-Controls access to paths outside the active working directory:
+Controls access to paths outside the active working directory.
+Use a pattern map to allow specific directories without opening all external access:
 
 ```jsonc
 {
   "permission": {
-    "external_directory": "ask"
+    "external_directory": {
+      "*": "ask",
+      "~/development/*": "allow"
+    }
   }
 }
 ```

package/config/config.example.json

@@ -17,6 +17,9 @@
     },
     "mcp": { "*": "ask", "mcp_status": "allow", "mcp_list": "allow" },
     "skill": { "*": "ask" },
-    "external_directory": "ask"
+    "external_directory": {
+      "*": "ask",
+      "~/development/*": "allow"
+    }
   }
 }

package/package.json

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

package/schemas/permissions.schema.json

@@ -88,10 +88,10 @@
     },
     "permissionMap": {
       "description": "A map of wildcard patterns to permission states. Last matching pattern wins.",
-      "markdownDescription": "A map of wildcard patterns to permission states.\n\nUse `*` for wildcard matching. When multiple patterns match, the **last matching rule wins** — put broad catch-alls first and specific overrides after them.",
+      "markdownDescription": "A map of wildcard patterns to permission states.\n\nUse `*` for wildcard matching. When multiple patterns match, the **last matching rule wins** — put broad catch-alls first and specific overrides after them.\n\nPattern keys support home directory expansion:\n- `~/path` or `$HOME/path` — expanded to the OS home directory at match time.\n- `~` or `$HOME` alone — expands to the home directory itself.\n\nThe stored pattern is always shown in logs and approval dialogs as written (e.g. `~/dev/*`).",
       "type": "object",
       "propertyNames": {
-        "description": "A non-empty pattern string. Use * for wildcard matching.",
+        "description": "A non-empty pattern string. Use * for wildcard matching. Prefix with ~/ or $HOME/ for home-relative paths.",
         "type": "string",
         "minLength": 1
       },

package/src/expand-home.ts

@@ -0,0 +1,28 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Expand `~` and `$HOME` prefixes in a pattern to the OS home directory.
+ *
+ * Supported forms:
+ * - `~`          → `homedir()`
+ * - `~/path`     → `homedir()/path`
+ * - `~\path`     → `homedir()\path` (Windows)
+ * - `$HOME`      → `homedir()`
+ * - `$HOME/path` → `homedir()/path`
+ * - `$HOME\path` → `homedir()\path` (Windows)
+ *
+ * All other patterns are returned unchanged.
+ */
+export function expandHomePath(pattern: string): string {
+  if (pattern === "~" || pattern === "$HOME") {
+    return homedir();
+  }
+  if (pattern.startsWith("~/") || pattern.startsWith("~\\")) {
+    return join(homedir(), pattern.slice(2));
+  }
+  if (pattern.startsWith("$HOME/") || pattern.startsWith("$HOME\\")) {
+    return join(homedir(), pattern.slice(6));
+  }
+  return pattern;
+}

package/src/wildcard-matcher.ts

@@ -1,3 +1,5 @@
+import { expandHomePath } from "./expand-home";
+
 export type CompiledWildcardPattern<TState> = {
   pattern: string;
   state: TState;
@@ -18,7 +20,8 @@ export function compileWildcardPattern<TState>(
   pattern: string,
   state: TState,
 ): CompiledWildcardPattern<TState> {
-  const escaped = pattern
+  const expanded = expandHomePath(pattern);
+  const escaped = expanded
     .split("*")
     .map((part) => escapeRegExp(part))
     .join(".*");

package/tests/expand-home.test.ts

@@ -0,0 +1,93 @@
+import { join } from "node:path";
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+const mockHomedir = vi.hoisted(() => vi.fn(() => "/home/testuser"));
+
+vi.mock("node:os", () => ({
+  homedir: mockHomedir,
+  default: { homedir: mockHomedir },
+}));
+
+import { expandHomePath } from "../src/expand-home";
+
+const FAKE_HOME = "/home/testuser";
+
+afterEach(() => {
+  mockHomedir.mockClear();
+});
+
+describe("expandHomePath", () => {
+  describe("~ expansion", () => {
+    test("bare ~ expands to homedir()", () => {
+      expect(expandHomePath("~")).toBe(FAKE_HOME);
+    });
+
+    test("~/path expands to homedir()/path", () => {
+      expect(expandHomePath("~/dev/project")).toBe(
+        join(FAKE_HOME, "dev/project"),
+      );
+    });
+
+    test("~/path/* expands to homedir()/path/*", () => {
+      expect(expandHomePath("~/dev/*")).toBe(join(FAKE_HOME, "dev/*"));
+    });
+
+    test("~\\ (Windows separator) expands to homedir() + rest", () => {
+      expect(expandHomePath("~\\dev\\project")).toBe(
+        join(FAKE_HOME, "dev\\project"),
+      );
+    });
+
+    test("~username (no separator) is not expanded (no-op)", () => {
+      expect(expandHomePath("~username")).toBe("~username");
+    });
+  });
+
+  describe("$HOME expansion", () => {
+    test("bare $HOME expands to homedir()", () => {
+      expect(expandHomePath("$HOME")).toBe(FAKE_HOME);
+    });
+
+    test("$HOME/path expands to homedir()/path", () => {
+      expect(expandHomePath("$HOME/dev/project")).toBe(
+        join(FAKE_HOME, "dev/project"),
+      );
+    });
+
+    test("$HOME/path/* expands to homedir()/path/*", () => {
+      expect(expandHomePath("$HOME/dev/*")).toBe(join(FAKE_HOME, "dev/*"));
+    });
+
+    test("$HOME\\ (Windows separator) expands to homedir() + rest", () => {
+      expect(expandHomePath("$HOME\\dev\\project")).toBe(
+        join(FAKE_HOME, "dev\\project"),
+      );
+    });
+
+    test("$HOMEDIR (no separator) is not expanded (no-op)", () => {
+      expect(expandHomePath("$HOMEDIR")).toBe("$HOMEDIR");
+    });
+  });
+
+  describe("no-op patterns", () => {
+    test("absolute path is unchanged", () => {
+      expect(expandHomePath("/usr/local/bin")).toBe("/usr/local/bin");
+    });
+
+    test("relative path is unchanged", () => {
+      expect(expandHomePath("dev/project")).toBe("dev/project");
+    });
+
+    test("glob-only pattern is unchanged", () => {
+      expect(expandHomePath("*")).toBe("*");
+    });
+
+    test("empty string is unchanged", () => {
+      expect(expandHomePath("")).toBe("");
+    });
+
+    test("bash command pattern starting with a word is unchanged", () => {
+      expect(expandHomePath("git push *")).toBe("git push *");
+    });
+  });
+});

package/tests/permission-manager-unified.test.ts

@@ -5,7 +5,7 @@
  * Step 6: all five surfaces produce identical decisions to the old branching code.
  */
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { PermissionManager } from "../src/permission-manager";
@@ -373,3 +373,76 @@ describe("checkPermission — source derivation and matchedPattern", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Home directory expansion in external_directory patterns
+// ---------------------------------------------------------------------------
+
+describe("checkPermission — home path expansion in external_directory rules", () => {
+  it("~/glob pattern allows a path under the real home directory", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      "*": "ask",
+      external_directory: { "~/trusted/*": "allow" },
+    });
+    try {
+      const result = manager.checkPermission("external_directory", {
+        path: join(homedir(), "trusted/repo"),
+      });
+      expect(result.state).toBe("allow");
+      expect(result.source).toBe("special");
+      expect(result.matchedPattern).toBe("~/trusted/*");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("$HOME/glob pattern allows a path under the real home directory", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      "*": "ask",
+      external_directory: { "$HOME/trusted/*": "allow" },
+    });
+    try {
+      const result = manager.checkPermission("external_directory", {
+        path: join(homedir(), "trusted/repo"),
+      });
+      expect(result.state).toBe("allow");
+      expect(result.source).toBe("special");
+      expect(result.matchedPattern).toBe("$HOME/trusted/*");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("~/glob deny rule blocks a path under home", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      "*": "allow",
+      external_directory: { "~/private/*": "deny" },
+    });
+    try {
+      const result = manager.checkPermission("external_directory", {
+        path: join(homedir(), "private/secrets.txt"),
+      });
+      expect(result.state).toBe("deny");
+      expect(result.matchedPattern).toBe("~/private/*");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("~/glob pattern does not match a path outside home", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      "*": "ask",
+      external_directory: { "~/trusted/*": "allow" },
+    });
+    try {
+      const result = manager.checkPermission("external_directory", {
+        path: "/tmp/not-home/file",
+      });
+      // Falls back to the "*": "ask" default — no allow from the ~/trusted/* rule.
+      expect(result.state).toBe("ask");
+      expect(result.matchedPattern).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+});

package/tests/wildcard-matcher.test.ts

@@ -1,5 +1,15 @@
+import { join } from "node:path";
 import { afterEach, describe, expect, test, vi } from "vitest";
 
+const mockHomedir = vi.hoisted(() => vi.fn(() => "/home/testuser"));
+
+vi.mock("node:os", () => ({
+  homedir: mockHomedir,
+  default: { homedir: mockHomedir },
+}));
+
+const FAKE_HOME = "/home/testuser";
+
 import {
   compileWildcardPattern,
   compileWildcardPatternEntries,
@@ -9,6 +19,7 @@ import {
 } from "../src/wildcard-matcher";
 
 afterEach(() => {
+  mockHomedir.mockClear();
   vi.restoreAllMocks();
 });
 
@@ -233,3 +244,50 @@ describe("wildcardMatch", () => {
     expect(wildcardMatch("tool.name", "toolXname")).toBe(false);
   });
 });
+
+describe("home path expansion in patterns", () => {
+  test("wildcardMatch expands ~ prefix in pattern before matching", () => {
+    const expandedPath = join(FAKE_HOME, "dev/project");
+    expect(wildcardMatch("~/dev/project", expandedPath)).toBe(true);
+  });
+
+  test("wildcardMatch expands ~/glob in pattern", () => {
+    const expandedFile = join(FAKE_HOME, "dev/project/file.ts");
+    expect(wildcardMatch("~/dev/*", expandedFile)).toBe(true);
+  });
+
+  test("wildcardMatch ~/glob does not match a different home directory", () => {
+    expect(wildcardMatch("~/dev/*", "/other/user/dev/file.ts")).toBe(false);
+  });
+
+  test("wildcardMatch expands $HOME prefix in pattern before matching", () => {
+    const expandedPath = join(FAKE_HOME, "dev/project");
+    expect(wildcardMatch("$HOME/dev/project", expandedPath)).toBe(true);
+  });
+
+  test("wildcardMatch expands $HOME/glob in pattern", () => {
+    const expandedFile = join(FAKE_HOME, "work/file.ts");
+    expect(wildcardMatch("$HOME/work/*", expandedFile)).toBe(true);
+  });
+
+  test("compileWildcardPattern retains original ~ pattern in .pattern field", () => {
+    const compiled = compileWildcardPattern("~/dev/*", "allow");
+    expect(compiled.pattern).toBe("~/dev/*");
+  });
+
+  test("compileWildcardPattern retains original $HOME pattern in .pattern field", () => {
+    const compiled = compileWildcardPattern("$HOME/dev/*", "allow");
+    expect(compiled.pattern).toBe("$HOME/dev/*");
+  });
+
+  test("compileWildcardPattern expanded regex matches the expanded path", () => {
+    const compiled = compileWildcardPattern("~/dev/*", "allow");
+    const expandedFile = join(FAKE_HOME, "dev/file.ts");
+    expect(compiled.regex.test(expandedFile)).toBe(true);
+  });
+
+  test("non-home pattern is unaffected", () => {
+    expect(wildcardMatch("/absolute/path/*", "/absolute/path/file")).toBe(true);
+    expect(wildcardMatch("/absolute/path/*", "/other/file")).toBe(false);
+  });
+});