@gotgenes/pi-permission-system 5.6.2 → 5.6.3

package/src/node-modules-discovery.ts

@@ -0,0 +1,76 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Walk up the directory tree from the given file URL until a directory
+ * literally named `node_modules` is found.
+ *
+ * Returns the `node_modules` path, or `null` if the URL cannot be parsed or
+ * no `node_modules` ancestor exists.
+ */
+function walkUpToNodeModules(fromUrl: string): string | null {
+  try {
+    const thisFile = fileURLToPath(fromUrl);
+    let dir = dirname(thisFile);
+    while (dir !== dirname(dir)) {
+      if (basename(dir) === "node_modules") {
+        return dir;
+      }
+      dir = dirname(dir);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run `npm root -g` synchronously and return the trimmed output, or `null` on
+ * any failure (non-zero exit, ENOENT, timeout, non-existent path).
+ *
+ * Only called when the walk-up-from-self strategy fails (i.e. the extension is
+ * running from a local development checkout, not a global install).
+ */
+function discoverGlobalNodeModulesViaSubprocess(): string | null {
+  try {
+    const result = spawnSync("npm", ["root", "-g"], {
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const root = result.stdout?.trim();
+    if (result.status === 0 && root && existsSync(root)) {
+      return root;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Discover the global node_modules root.
+ *
+ * Strategy 1 (zero-cost, covers all global installs): walk up from
+ * `fromUrl` (defaults to this module's own `import.meta.url`) looking for a
+ * directory named `node_modules`. This works whenever the extension is
+ * installed inside a `node_modules` tree.
+ *
+ * Strategy 2 (subprocess fallback, dev checkout only): when Strategy 1 fails
+ * because the extension is running from a local development checkout with no
+ * `node_modules` ancestor, run `npm root -g` to discover the global root.
+ * Pi installs skills and extensions via `npm` by default, so `npm root -g`
+ * returns the correct root regardless of the user's own project package
+ * manager.
+ *
+ * Returns `null` when both strategies fail — callers must degrade gracefully.
+ */
+export function discoverGlobalNodeModulesRoot(
+  fromUrl = import.meta.url,
+): string | null {
+  const fromSelf = walkUpToNodeModules(fromUrl);
+  if (fromSelf) return fromSelf;
+  return discoverGlobalNodeModulesViaSubprocess();
+}

package/src/path-utils.ts

@@ -1,6 +1,8 @@
 import { homedir } from "node:os";
 import { join, normalize, resolve, sep } from "node:path";
 
+import { getNonEmptyString, toRecord } from "./common";
+
 export function normalizePathForComparison(
   pathValue: string,
   cwd: string,
@@ -43,3 +45,111 @@ export function isPathWithinDirectory(
   const prefix = directory.endsWith(sep) ? directory : `${directory}${sep}`;
   return pathValue.startsWith(prefix);
 }
+
+/**
+ * Paths that are universally safe and should never trigger external-directory checks.
+ * These are OS device files: read returns EOF or process streams, write discards or goes to process streams.
+ */
+export const SAFE_SYSTEM_PATHS: ReadonlySet<string> = new Set([
+  "/dev/null",
+  "/dev/stdin",
+  "/dev/stdout",
+  "/dev/stderr",
+]);
+
+/**
+ * Returns true if the given normalized path is a safe OS device file
+ * that should never trigger external-directory checks.
+ */
+export function isSafeSystemPath(normalizedPath: string): boolean {
+  return SAFE_SYSTEM_PATHS.has(normalizedPath);
+}
+
+/**
+ * File tools that only read — never write — the filesystem.
+ * Only these tools are eligible for the Pi infrastructure auto-allow.
+ */
+export const READ_ONLY_PATH_BEARING_TOOLS: ReadonlySet<string> = new Set([
+  "read",
+  "find",
+  "grep",
+  "ls",
+]);
+
+export const PATH_BEARING_TOOLS = new Set([
+  "read",
+  "write",
+  "edit",
+  "find",
+  "grep",
+  "ls",
+]);
+
+export function getPathBearingToolPath(
+  toolName: string,
+  input: unknown,
+): string | null {
+  if (!PATH_BEARING_TOOLS.has(toolName)) {
+    return null;
+  }
+
+  return getNonEmptyString(toRecord(input).path);
+}
+
+export function isPathOutsideWorkingDirectory(
+  pathValue: string,
+  cwd: string,
+): boolean {
+  const normalizedCwd = normalizePathForComparison(cwd, cwd);
+  const normalizedPath = normalizePathForComparison(pathValue, cwd);
+  if (!normalizedCwd || !normalizedPath) {
+    return false;
+  }
+  if (isSafeSystemPath(normalizedPath)) {
+    return false;
+  }
+  return !isPathWithinDirectory(normalizedPath, normalizedCwd);
+}
+
+/**
+ * Returns true if the given tool + normalized path combination qualifies for
+ * automatic allow as a Pi infrastructure read.
+ *
+ * A path qualifies when:
+ * 1. The tool is read-only (in READ_ONLY_PATH_BEARING_TOOLS).
+ * 2. The normalized path is within one of the provided `infrastructureDirs`
+ *    OR within the project-local Pi package directories
+ *    (`<cwd>/.pi/npm/` or `<cwd>/.pi/git/`).
+ *
+ * `infrastructureDirs` should contain pre-expanded absolute paths (no `~`).
+ * Project-local paths are computed fresh from `cwd` on each call so they
+ * follow working-directory changes without a runtime rebuild.
+ */
+export function isPiInfrastructureRead(
+  toolName: string,
+  normalizedPath: string,
+  infrastructureDirs: readonly string[],
+  cwd: string,
+): boolean {
+  if (!READ_ONLY_PATH_BEARING_TOOLS.has(toolName)) {
+    return false;
+  }
+
+  for (const dir of infrastructureDirs) {
+    if (isPathWithinDirectory(normalizedPath, dir)) {
+      return true;
+    }
+  }
+
+  // Project-local Pi packages — checked fresh every call so CWD changes work.
+  const projectNpmDir = join(cwd, ".pi", "npm");
+  const projectGitDir = join(cwd, ".pi", "git");
+  if (isPathWithinDirectory(normalizedPath, projectNpmDir)) {
+    return true;
+  }
+  if (isPathWithinDirectory(normalizedPath, projectGitDir)) {
+    return true;
+  }
+
+  return false;
+}

package/tests/external-directory-messages.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  formatBashExternalDirectoryAskPrompt,
+  formatBashExternalDirectoryDenyReason,
+  formatExternalDirectoryAskPrompt,
+  formatExternalDirectoryDenyReason,
+  formatExternalDirectoryHardStopHint,
+  formatExternalDirectoryUserDeniedReason,
+} from "../src/external-directory-messages";
+
+describe("formatExternalDirectoryHardStopHint", () => {
+  test("returns the hard stop instruction string", () => {
+    const hint = formatExternalDirectoryHardStopHint();
+    expect(hint).toContain("Hard stop");
+    expect(hint).toContain("external directory");
+  });
+});
+
+describe("formatExternalDirectoryAskPrompt", () => {
+  test("uses 'Current agent' when no agent name provided", () => {
+    const result = formatExternalDirectoryAskPrompt(
+      "read",
+      "/etc/passwd",
+      "/projects/my-app",
+    );
+    expect(result).toContain("Current agent");
+    expect(result).toContain("read");
+    expect(result).toContain("/etc/passwd");
+    expect(result).toContain("/projects/my-app");
+  });
+
+  test("uses agent name when provided", () => {
+    const result = formatExternalDirectoryAskPrompt(
+      "write",
+      "/tmp/out.txt",
+      "/projects/my-app",
+      "my-agent",
+    );
+    expect(result).toContain("Agent 'my-agent'");
+    expect(result).toContain("write");
+    expect(result).toContain("/tmp/out.txt");
+  });
+});
+
+describe("formatExternalDirectoryDenyReason", () => {
+  test("includes tool name, path, cwd, agent name, and hard stop hint", () => {
+    const result = formatExternalDirectoryDenyReason(
+      "read",
+      "/etc/passwd",
+      "/projects/my-app",
+      "sec-agent",
+    );
+    expect(result).toContain("Agent 'sec-agent'");
+    expect(result).toContain("read");
+    expect(result).toContain("/etc/passwd");
+    expect(result).toContain("/projects/my-app");
+    expect(result).toContain("Hard stop");
+  });
+
+  test("uses 'Current agent' without agent name", () => {
+    const result = formatExternalDirectoryDenyReason(
+      "read",
+      "/etc",
+      "/projects",
+    );
+    expect(result).toContain("Current agent");
+  });
+});
+
+describe("formatExternalDirectoryUserDeniedReason", () => {
+  test("includes tool name and path", () => {
+    const result = formatExternalDirectoryUserDeniedReason(
+      "edit",
+      "/etc/hosts",
+    );
+    expect(result).toContain("edit");
+    expect(result).toContain("/etc/hosts");
+    expect(result).toContain("Hard stop");
+  });
+
+  test("appends denial reason when provided", () => {
+    const result = formatExternalDirectoryUserDeniedReason(
+      "edit",
+      "/etc/hosts",
+      "too risky",
+    );
+    expect(result).toContain("Reason: too risky");
+  });
+
+  test("omits reason suffix when not provided", () => {
+    const result = formatExternalDirectoryUserDeniedReason(
+      "edit",
+      "/etc/hosts",
+    );
+    expect(result).not.toContain("Reason:");
+  });
+});
+
+describe("formatBashExternalDirectoryAskPrompt", () => {
+  test("includes command, paths, cwd, and agent name", () => {
+    const result = formatBashExternalDirectoryAskPrompt(
+      "cat /etc/passwd",
+      ["/etc/passwd"],
+      "/projects/my-app",
+      "my-agent",
+    );
+    expect(result).toContain("Agent 'my-agent'");
+    expect(result).toContain("cat /etc/passwd");
+    expect(result).toContain("/etc/passwd");
+    expect(result).toContain("/projects/my-app");
+  });
+
+  test("uses 'Current agent' when no agent name provided", () => {
+    const result = formatBashExternalDirectoryAskPrompt(
+      "ls /tmp",
+      ["/tmp"],
+      "/projects/my-app",
+    );
+    expect(result).toContain("Current agent");
+  });
+});
+
+describe("formatBashExternalDirectoryDenyReason", () => {
+  test("includes command, paths, cwd, agent name, and hard stop hint", () => {
+    const result = formatBashExternalDirectoryDenyReason(
+      "rm /etc/hosts",
+      ["/etc/hosts"],
+      "/projects/my-app",
+      "sec-agent",
+    );
+    expect(result).toContain("Agent 'sec-agent'");
+    expect(result).toContain("rm /etc/hosts");
+    expect(result).toContain("/etc/hosts");
+    expect(result).toContain("Hard stop");
+  });
+});

package/tests/node-modules-discovery.test.ts

@@ -0,0 +1,97 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+// Hoisted stubs for mocks that reference them in vi.mock factories.
+const { mockSpawnSync, mockExistsSync } = vi.hoisted(() => ({
+  mockSpawnSync: vi.fn(),
+  mockExistsSync: vi.fn(),
+}));
+
+// Mock node:child_process so tests don't spawn real subprocesses.
+vi.mock("node:child_process", () => ({
+  spawnSync: mockSpawnSync,
+  default: { spawnSync: mockSpawnSync },
+}));
+
+// Mock node:fs so existsSync is controllable.
+vi.mock("node:fs", () => ({
+  existsSync: mockExistsSync,
+  default: { existsSync: mockExistsSync },
+}));
+
+import { discoverGlobalNodeModulesRoot } from "../src/node-modules-discovery";
+
+describe("discoverGlobalNodeModulesRoot", () => {
+  beforeEach(() => {
+    mockSpawnSync.mockReset();
+    mockExistsSync.mockReset();
+  });
+
+  test("returns node_modules root when URL is inside a node_modules tree", () => {
+    const fakeUrl =
+      "file:///opt/homebrew/lib/node_modules/@gotgenes/pi-permission-system/dist/external-directory.js";
+    const result = discoverGlobalNodeModulesRoot(fakeUrl);
+    expect(result).toBe("/opt/homebrew/lib/node_modules");
+    expect(mockSpawnSync).not.toHaveBeenCalled();
+  });
+
+  test("calls npm root -g as fallback when walk-up finds no node_modules ancestor", () => {
+    const npmRootPath = "/opt/homebrew/lib/node_modules";
+    mockSpawnSync.mockReturnValue({
+      status: 0,
+      stdout: `${npmRootPath}\n`,
+    });
+    mockExistsSync.mockReturnValue(true);
+
+    const fakeUrl = "file:///Users/dev/my-project/src/external-directory.ts";
+    const result = discoverGlobalNodeModulesRoot(fakeUrl);
+
+    expect(mockSpawnSync).toHaveBeenCalledWith(
+      "npm",
+      ["root", "-g"],
+      expect.objectContaining({ encoding: "utf-8" }),
+    );
+    expect(result).toBe(npmRootPath);
+  });
+
+  test("returns null when walk-up fails and npm root -g returns non-zero exit", () => {
+    mockSpawnSync.mockReturnValue({ status: 1, stdout: "" });
+
+    const fakeUrl = "file:///Users/dev/my-project/src/external-directory.ts";
+    const result = discoverGlobalNodeModulesRoot(fakeUrl);
+
+    expect(result).toBeNull();
+  });
+
+  test("returns null when walk-up fails and spawnSync throws", () => {
+    mockSpawnSync.mockImplementation(() => {
+      throw new Error("ENOENT");
+    });
+
+    const fakeUrl = "file:///Users/dev/my-project/src/external-directory.ts";
+    const result = discoverGlobalNodeModulesRoot(fakeUrl);
+
+    expect(result).toBeNull();
+  });
+
+  test("returns null when walk-up fails and npm root -g returns non-existent path", () => {
+    mockSpawnSync.mockReturnValue({
+      status: 0,
+      stdout: "/some/nonexistent/node_modules\n",
+    });
+    mockExistsSync.mockReturnValue(false);
+
+    const fakeUrl = "file:///Users/dev/my-project/src/external-directory.ts";
+    const result = discoverGlobalNodeModulesRoot(fakeUrl);
+
+    expect(result).toBeNull();
+  });
+
+  test("returns null when walk-up fails and npm root -g returns empty stdout", () => {
+    mockSpawnSync.mockReturnValue({ status: 0, stdout: "   " });
+
+    const fakeUrl = "file:///Users/dev/my-project/src/external-directory.ts";
+    const result = discoverGlobalNodeModulesRoot(fakeUrl);
+
+    expect(result).toBeNull();
+  });
+});

package/tests/path-utils.test.ts

@@ -11,8 +11,15 @@ vi.mock("node:os", () => {
 });
 
 import {
+  getPathBearingToolPath,
+  isPathOutsideWorkingDirectory,
   isPathWithinDirectory,
+  isPiInfrastructureRead,
+  isSafeSystemPath,
   normalizePathForComparison,
+  PATH_BEARING_TOOLS,
+  READ_ONLY_PATH_BEARING_TOOLS,
+  SAFE_SYSTEM_PATHS,
 } from "../src/path-utils";
 
 describe("normalizePathForComparison", () => {
@@ -90,3 +97,197 @@ describe("isPathWithinDirectory", () => {
     expect(isPathWithinDirectory("/a/b", "")).toBe(false);
   });
 });
+
+describe("PATH_BEARING_TOOLS", () => {
+  test("contains the expected tool names", () => {
+    for (const tool of ["read", "write", "edit", "find", "grep", "ls"]) {
+      expect(PATH_BEARING_TOOLS.has(tool)).toBe(true);
+    }
+  });
+
+  test("does not contain bash or mcp", () => {
+    expect(PATH_BEARING_TOOLS.has("bash")).toBe(false);
+    expect(PATH_BEARING_TOOLS.has("mcp")).toBe(false);
+  });
+});
+
+describe("READ_ONLY_PATH_BEARING_TOOLS", () => {
+  test("contains read, find, grep, ls", () => {
+    for (const tool of ["read", "find", "grep", "ls"]) {
+      expect(READ_ONLY_PATH_BEARING_TOOLS.has(tool)).toBe(true);
+    }
+  });
+
+  test("does not contain write or edit", () => {
+    expect(READ_ONLY_PATH_BEARING_TOOLS.has("write")).toBe(false);
+    expect(READ_ONLY_PATH_BEARING_TOOLS.has("edit")).toBe(false);
+  });
+});
+
+describe("SAFE_SYSTEM_PATHS", () => {
+  test("contains /dev/null, /dev/stdin, /dev/stdout, /dev/stderr", () => {
+    expect(SAFE_SYSTEM_PATHS.has("/dev/null")).toBe(true);
+    expect(SAFE_SYSTEM_PATHS.has("/dev/stdin")).toBe(true);
+    expect(SAFE_SYSTEM_PATHS.has("/dev/stdout")).toBe(true);
+    expect(SAFE_SYSTEM_PATHS.has("/dev/stderr")).toBe(true);
+  });
+});
+
+describe("isSafeSystemPath", () => {
+  test("returns true for /dev/null", () => {
+    expect(isSafeSystemPath("/dev/null")).toBe(true);
+  });
+
+  test("returns true for /dev/stdin", () => {
+    expect(isSafeSystemPath("/dev/stdin")).toBe(true);
+  });
+
+  test("returns true for /dev/stdout", () => {
+    expect(isSafeSystemPath("/dev/stdout")).toBe(true);
+  });
+
+  test("returns true for /dev/stderr", () => {
+    expect(isSafeSystemPath("/dev/stderr")).toBe(true);
+  });
+
+  test("returns false for an arbitrary absolute path", () => {
+    expect(isSafeSystemPath("/etc/passwd")).toBe(false);
+  });
+
+  test("returns false for a path prefixed with a safe system path", () => {
+    expect(isSafeSystemPath("/dev/null/subdir")).toBe(false);
+  });
+
+  test("returns false for an empty string", () => {
+    expect(isSafeSystemPath("")).toBe(false);
+  });
+
+  test("returns false for a relative path", () => {
+    expect(isSafeSystemPath("dev/null")).toBe(false);
+  });
+});
+
+describe("getPathBearingToolPath", () => {
+  test("returns path for a path-bearing tool", () => {
+    expect(getPathBearingToolPath("read", { path: "/src/foo.ts" })).toBe(
+      "/src/foo.ts",
+    );
+  });
+
+  test("returns null for a non-path-bearing tool", () => {
+    expect(getPathBearingToolPath("bash", { path: "/src/foo.ts" })).toBeNull();
+    expect(getPathBearingToolPath("mcp", { path: "/src/foo.ts" })).toBeNull();
+    expect(getPathBearingToolPath("task", { path: "/src/foo.ts" })).toBeNull();
+  });
+
+  test("returns null when input has no path", () => {
+    expect(getPathBearingToolPath("read", {})).toBeNull();
+    expect(getPathBearingToolPath("read", { path: "" })).toBeNull();
+    expect(getPathBearingToolPath("read", null)).toBeNull();
+  });
+});
+
+describe("isPathOutsideWorkingDirectory", () => {
+  const cwd = "/projects/my-app";
+
+  test("returns false when path is inside cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/projects/my-app/src", cwd)).toBe(
+      false,
+    );
+  });
+
+  test("returns false when path equals cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/projects/my-app", cwd)).toBe(false);
+  });
+
+  test("returns true when path is outside cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/etc/passwd", cwd)).toBe(true);
+  });
+
+  test("returns true for home directory when outside cwd", () => {
+    expect(isPathOutsideWorkingDirectory("~/secrets", cwd)).toBe(true);
+  });
+
+  test("returns false for relative path resolving inside cwd", () => {
+    expect(isPathOutsideWorkingDirectory("src/index.ts", cwd)).toBe(false);
+  });
+
+  test("returns false for empty path (normalizes to empty string)", () => {
+    expect(isPathOutsideWorkingDirectory("", cwd)).toBe(false);
+  });
+
+  test("returns false for /dev/null regardless of cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/null", cwd)).toBe(false);
+  });
+
+  test("returns false for /dev/stdin regardless of cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/stdin", cwd)).toBe(false);
+  });
+
+  test("returns false for /dev/stdout regardless of cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/stdout", cwd)).toBe(false);
+  });
+
+  test("returns false for /dev/stderr regardless of cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/stderr", cwd)).toBe(false);
+  });
+
+  test("returns true for /dev/null/subdir (not a safe path)", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/null/subdir", cwd)).toBe(true);
+  });
+});
+
+describe("isPiInfrastructureRead", () => {
+  const cwd = "/projects/my-app";
+  const infraDirs = ["/mock/home/.pi/agent"];
+
+  test("returns true for read-only tool reading from infra dir", () => {
+    expect(
+      isPiInfrastructureRead(
+        "read",
+        "/mock/home/.pi/agent/config.json",
+        infraDirs,
+        cwd,
+      ),
+    ).toBe(true);
+  });
+
+  test("returns false for write tool even in infra dir", () => {
+    expect(
+      isPiInfrastructureRead(
+        "write",
+        "/mock/home/.pi/agent/config.json",
+        infraDirs,
+        cwd,
+      ),
+    ).toBe(false);
+  });
+
+  test("returns true for read-only tool reading from project .pi/npm", () => {
+    expect(
+      isPiInfrastructureRead(
+        "read",
+        "/projects/my-app/.pi/npm/package.json",
+        [],
+        cwd,
+      ),
+    ).toBe(true);
+  });
+
+  test("returns true for read-only tool reading from project .pi/git", () => {
+    expect(
+      isPiInfrastructureRead(
+        "grep",
+        "/projects/my-app/.pi/git/some-file",
+        [],
+        cwd,
+      ),
+    ).toBe(true);
+  });
+
+  test("returns false for path outside all infra dirs and project dirs", () => {
+    expect(isPiInfrastructureRead("read", "/etc/passwd", infraDirs, cwd)).toBe(
+      false,
+    );
+  });
+});