@gotgenes/pi-permission-system 5.6.3 → 5.7.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.7.0](https://github.com/gotgenes/pi-permission-system/compare/v5.6.3...v5.7.0) (2026-05-08)
+
+
+### Features
+
+* extract ExtensionPaths value object ([#126](https://github.com/gotgenes/pi-permission-system/issues/126)) ([85bc347](https://github.com/gotgenes/pi-permission-system/commit/85bc347d3ed487210ffbed4c1c53616b5cf0d978))
+
+
+### Documentation
+
+* add handler decomposition plan ([#126](https://github.com/gotgenes/pi-permission-system/issues/126), [#127](https://github.com/gotgenes/pi-permission-system/issues/127), [#128](https://github.com/gotgenes/pi-permission-system/issues/128), [#129](https://github.com/gotgenes/pi-permission-system/issues/129), [#130](https://github.com/gotgenes/pi-permission-system/issues/130)) ([5a116a6](https://github.com/gotgenes/pi-permission-system/commit/5a116a6cf2f6ef29f5e6550821bb26b6e1c3a90f))
+* add structural design heuristics, design-review skill, and plan-issue hook ([d8e3233](https://github.com/gotgenes/pi-permission-system/commit/d8e32330baa25fa5a5abaf75f8e442ce650fe5a9))
+* extract code-style, testing, and markdown-conventions skills from AGENTS.md ([9d5ba7a](https://github.com/gotgenes/pi-permission-system/commit/9d5ba7a4a4a7a9e9fbdfe869fb42840238351b81))
+* plan ExtensionPaths value object extraction ([#126](https://github.com/gotgenes/pi-permission-system/issues/126)) ([d76e6cc](https://github.com/gotgenes/pi-permission-system/commit/d76e6cc255dc124a7a914e8d178113e5b7c8bddd))
+* rename target-architecture to architecture, strip progress indicators ([9776550](https://github.com/gotgenes/pi-permission-system/commit/9776550351f3b59f96bdad614cc5129a7be52a51))
+* **retro:** add retro notes for issue [#110](https://github.com/gotgenes/pi-permission-system/issues/110) ([5597de3](https://github.com/gotgenes/pi-permission-system/commit/5597de3c9c64c3d672a1fc77ba7910e952545824))
+
 ## [5.6.3](https://github.com/gotgenes/pi-permission-system/compare/v5.6.2...v5.6.3) (2026-05-07)
 
 

package/package.json

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

package/src/extension-paths.ts

@@ -0,0 +1,55 @@
+import { join } from "node:path";
+import { getGlobalLogsDir } from "./config-paths";
+import { discoverGlobalNodeModulesRoot } from "./node-modules-discovery";
+
+/**
+ * Immutable path constants derived from `agentDir` at construction time.
+ *
+ * Computed once at startup in `computeExtensionPaths()` and embedded into
+ * `ExtensionRuntime`. Later refactorings (#129 PermissionSession, #130
+ * handler classes) consume this as a single dep instead of individual fields.
+ */
+export interface ExtensionPaths {
+  readonly agentDir: string;
+  readonly sessionsDir: string;
+  readonly subagentSessionsDir: string;
+  readonly forwardingDir: string;
+  readonly globalLogsDir: string;
+  /**
+   * Static Pi infrastructure directories used for external-directory
+   * read auto-allow. Computed once from `agentDir` and
+   * `discoverGlobalNodeModulesRoot()`. Config-based extras
+   * (`piInfrastructureReadPaths`) are read from `runtime.config` at
+   * call time in the handler so they pick up config reloads.
+   */
+  readonly piInfrastructureDirs: readonly string[];
+}
+
+/**
+ * Compute all immutable path constants from `agentDir`.
+ *
+ * Calls `discoverGlobalNodeModulesRoot()` internally so the result is
+ * self-contained. Call this once at extension startup, not at module scope.
+ */
+export function computeExtensionPaths(agentDir: string): ExtensionPaths {
+  const sessionsDir = join(agentDir, "sessions");
+  const subagentSessionsDir = join(agentDir, "subagent-sessions");
+  const forwardingDir = join(sessionsDir, "permission-forwarding");
+  const globalLogsDir = getGlobalLogsDir(agentDir);
+
+  const globalNodeModulesRoot = discoverGlobalNodeModulesRoot();
+  const piInfrastructureDirs: string[] = [
+    agentDir,
+    join(agentDir, "git"),
+    ...(globalNodeModulesRoot ? [globalNodeModulesRoot] : []),
+  ];
+
+  return {
+    agentDir,
+    sessionsDir,
+    subagentSessionsDir,
+    forwardingDir,
+    globalLogsDir,
+    piInfrastructureDirs,
+  };
+}

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

@@ -1,14 +1,14 @@
 import { getNonEmptyString, toRecord } from "../../common";
-import {
-  extractExternalPathsFromBashCommand,
-  formatBashExternalDirectoryAskPrompt,
-  formatBashExternalDirectoryDenyReason,
-  formatExternalDirectoryHardStopHint,
-} from "../../external-directory";
 import type { Rule } from "../../rule";
 import { deriveApprovalPattern } from "../../session-rules";
 import type { PermissionCheckResult } from "../../types";
+import { extractExternalPathsFromBashCommand } from "./bash-path-extractor";
 import type { GateResult } from "./descriptor";
+import {
+  formatBashExternalDirectoryAskPrompt,
+  formatBashExternalDirectoryDenyReason,
+  formatExternalDirectoryHardStopHint,
+} from "./external-directory-messages";
 import type { ToolCallContext } from "./types";
 
 /** Function type for checkPermission used by the descriptor factory. */

package/src/{bash-path-extractor.ts → handlers/gates/bash-path-extractor.ts}

@@ -4,7 +4,7 @@ import { basename } from "node:path";
 import {
   isPathOutsideWorkingDirectory,
   normalizePathForComparison,
-} from "./path-utils";
+} from "../../path-utils";
 
 // ── tree-sitter-bash lazy parser ───────────────────────────────────────────
 

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

@@ -1,14 +1,16 @@
 import {
-  formatExternalDirectoryAskPrompt,
-  formatExternalDirectoryDenyReason,
-  formatExternalDirectoryUserDeniedReason,
   getPathBearingToolPath,
   isPathOutsideWorkingDirectory,
   isPiInfrastructureRead,
-} from "../../external-directory";
-import { normalizePathForComparison } from "../../path-utils";
+  normalizePathForComparison,
+} from "../../path-utils";
 import { deriveApprovalPattern } from "../../session-rules";
 import type { GateResult } from "./descriptor";
+import {
+  formatExternalDirectoryAskPrompt,
+  formatExternalDirectoryDenyReason,
+  formatExternalDirectoryUserDeniedReason,
+} from "./external-directory-messages";
 import type { ToolCallContext } from "./types";
 
 /**

package/src/handlers/gates/tool.ts

@@ -1,4 +1,4 @@
-import { PATH_BEARING_TOOLS } from "../../external-directory";
+import { PATH_BEARING_TOOLS } from "../../path-utils";
 import { suggestSessionPattern } from "../../pattern-suggest";
 import {
   formatAskPrompt,

package/src/handlers/types.ts

@@ -42,7 +42,7 @@ export interface HandlerDeps {
   writeReviewLog(event: string, details?: Record<string, unknown>): void;
 
   // ── Immutable infrastructure paths ───────────────────────────────────
-  readonly piInfrastructureDirs: string[];
+  readonly piInfrastructureDirs: readonly string[];
   /** Returns config-derived infrastructure read paths (current at call time). */
   getPiInfrastructureReadPaths(): string[];
 

package/src/runtime.ts

@@ -11,6 +11,7 @@ import {
   type ExtensionContext,
   getAgentDir,
 } from "@mariozechner/pi-coding-agent";
+
 import {
   getActiveAgentName,
   getActiveAgentNameFromSystemPrompt,
@@ -19,7 +20,6 @@ import { loadAndMergeConfigs, loadUnifiedConfig } from "./config-loader";
 import {
   DEBUG_LOG_FILENAME,
   getGlobalConfigPath,
-  getGlobalLogsDir,
   getLegacyExtensionConfigPath,
   getLegacyGlobalPolicyPath,
   getLegacyProjectPolicyPath,
@@ -34,7 +34,10 @@ import {
   normalizePermissionSystemConfig,
   type PermissionSystemExtensionConfig,
 } from "./extension-config";
-import { discoverGlobalNodeModulesRoot } from "./external-directory";
+import { computeExtensionPaths, type ExtensionPaths } from "./extension-paths";
+
+export type { ExtensionPaths } from "./extension-paths";
+
 import {
   type PermissionForwardingDeps,
   processForwardedPermissionRequests,
@@ -73,22 +76,7 @@ export interface SessionState {
  * Tests construct this via `createExtensionRuntime({ agentDir: tmpDir })`
  * without timing issues around `PI_CODING_AGENT_DIR`.
  */
-export interface ExtensionRuntime extends SessionState {
-  // ── Immutable paths (derived from agentDir at construction) ───────────
-  readonly agentDir: string;
-  readonly sessionsDir: string;
-  readonly subagentSessionsDir: string;
-  readonly forwardingDir: string;
-  readonly globalLogsDir: string;
-  /**
-   * Static Pi infrastructure directories used for external-directory
-   * read auto-allow. Computed once at construction from `agentDir` and
-   * `discoverGlobalNodeModulesRoot()`. Config-based extras
-   * (`piInfrastructureReadPaths`) are read from `runtime.config` at
-   * call time in the handler so they pick up config reloads.
-   */
-  readonly piInfrastructureDirs: string[];
-
+export interface ExtensionRuntime extends ExtensionPaths, SessionState {
   // ── Mutable state (beyond SessionState) ───────────────────────────────────
   config: PermissionSystemExtensionConfig;
   lastConfigWarning: string | null;
@@ -353,27 +341,12 @@ export function createExtensionRuntime(options?: {
   agentDir?: string;
 }): ExtensionRuntime {
   const agentDir = options?.agentDir ?? getAgentDir();
-  const sessionsDir = join(agentDir, "sessions");
-  const subagentSessionsDir = join(agentDir, "subagent-sessions");
-  const forwardingDir = join(sessionsDir, "permission-forwarding");
-  const globalLogsDir = getGlobalLogsDir(agentDir);
-
-  const globalNodeModulesRoot = discoverGlobalNodeModulesRoot();
-  const piInfrastructureDirs: string[] = [
-    agentDir,
-    join(agentDir, "git"),
-    ...(globalNodeModulesRoot ? [globalNodeModulesRoot] : []),
-  ];
+  const paths = computeExtensionPaths(agentDir);
 
   // Build a plain-object runtime first so the logger's `getConfig` closure
   // can reference `runtime.config` directly (always reads current value).
   const runtime: ExtensionRuntime = {
-    agentDir,
-    sessionsDir,
-    subagentSessionsDir,
-    forwardingDir,
-    globalLogsDir,
-    piInfrastructureDirs,
+    ...paths,
     config: { ...DEFAULT_EXTENSION_CONFIG },
     runtimeContext: null,
     permissionManager: createPermissionManagerForCwd(agentDir, undefined),
@@ -395,10 +368,10 @@ export function createExtensionRuntime(options?: {
   const logger = createPermissionSystemLogger({
     // Reads runtime.config at call time — always current.
     getConfig: () => runtime.config,
-    debugLogPath: join(globalLogsDir, DEBUG_LOG_FILENAME),
-    reviewLogPath: join(globalLogsDir, REVIEW_LOG_FILENAME),
+    debugLogPath: join(paths.globalLogsDir, DEBUG_LOG_FILENAME),
+    reviewLogPath: join(paths.globalLogsDir, REVIEW_LOG_FILENAME),
     ensureLogsDirectory: () =>
-      ensurePermissionSystemLogsDirectory(globalLogsDir),
+      ensurePermissionSystemLogsDirectory(paths.globalLogsDir),
   });
 
   const reportLoggingWarning = (message: string): void => {

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

@@ -9,11 +9,11 @@ vi.mock("node:os", () => {
   };
 });
 
+import { extractExternalPathsFromBashCommand } from "../src/handlers/gates/bash-path-extractor";
 import {
-  extractExternalPathsFromBashCommand,
   formatBashExternalDirectoryAskPrompt,
   formatBashExternalDirectoryDenyReason,
-} from "../src/external-directory";
+} from "../src/handlers/gates/external-directory-messages";
 
 afterEach(() => {
   vi.restoreAllMocks();

package/tests/extension-paths.test.ts

@@ -0,0 +1,89 @@
+import { join } from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { mockDiscoverGlobalNodeModulesRoot } = vi.hoisted(() => ({
+  mockDiscoverGlobalNodeModulesRoot: vi.fn<() => string | null>(),
+}));
+
+vi.mock("../src/node-modules-discovery", () => ({
+  discoverGlobalNodeModulesRoot: mockDiscoverGlobalNodeModulesRoot,
+}));
+
+import { getGlobalLogsDir } from "../src/config-paths";
+import { computeExtensionPaths } from "../src/extension-paths";
+
+describe("computeExtensionPaths", () => {
+  beforeEach(() => {
+    mockDiscoverGlobalNodeModulesRoot.mockReset();
+    mockDiscoverGlobalNodeModulesRoot.mockReturnValue(
+      "/mock/global/node_modules",
+    );
+  });
+
+  it("sets agentDir from argument", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.agentDir).toBe("/test/agent");
+  });
+
+  it("derives sessionsDir as agentDir/sessions", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.sessionsDir).toBe("/test/agent/sessions");
+  });
+
+  it("derives subagentSessionsDir as agentDir/subagent-sessions", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.subagentSessionsDir).toBe("/test/agent/subagent-sessions");
+  });
+
+  it("derives forwardingDir as sessionsDir/permission-forwarding", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.forwardingDir).toBe(
+      join("/test/agent/sessions", "permission-forwarding"),
+    );
+  });
+
+  it("derives globalLogsDir via getGlobalLogsDir(agentDir)", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.globalLogsDir).toBe(getGlobalLogsDir("/test/agent"));
+  });
+
+  it("includes agentDir in piInfrastructureDirs", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.piInfrastructureDirs).toContain("/test/agent");
+  });
+
+  it("includes agentDir/git in piInfrastructureDirs", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.piInfrastructureDirs).toContain("/test/agent/git");
+  });
+
+  it("includes discovered global node_modules root in piInfrastructureDirs", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.piInfrastructureDirs).toContain("/mock/global/node_modules");
+  });
+
+  it("omits global node_modules from piInfrastructureDirs when discovery returns null", () => {
+    mockDiscoverGlobalNodeModulesRoot.mockReturnValue(null);
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.piInfrastructureDirs).toHaveLength(2);
+    expect(paths.piInfrastructureDirs).toContain("/test/agent");
+    expect(paths.piInfrastructureDirs).toContain("/test/agent/git");
+  });
+
+  it("all entries in piInfrastructureDirs are strings (no null)", () => {
+    mockDiscoverGlobalNodeModulesRoot.mockReturnValue(null);
+    const paths = computeExtensionPaths("/test/agent");
+    for (const dir of paths.piInfrastructureDirs) {
+      expect(typeof dir).toBe("string");
+    }
+  });
+
+  it("two calls with different agentDirs produce independent results", () => {
+    const a = computeExtensionPaths("/agent/a");
+    const b = computeExtensionPaths("/agent/b");
+    expect(a.agentDir).toBe("/agent/a");
+    expect(b.agentDir).toBe("/agent/b");
+    expect(a.sessionsDir).toBe("/agent/a/sessions");
+    expect(b.sessionsDir).toBe("/agent/b/sessions");
+  });
+});

package/tests/{external-directory-messages.test.ts → handlers/gates/external-directory-messages.test.ts}

@@ -7,7 +7,7 @@ import {
   formatExternalDirectoryDenyReason,
   formatExternalDirectoryHardStopHint,
   formatExternalDirectoryUserDeniedReason,
-} from "../src/external-directory-messages";
+} from "../../../src/handlers/gates/external-directory-messages";
 
 describe("formatExternalDirectoryHardStopHint", () => {
   test("returns the hard stop instruction string", () => {

package/tests/pi-infrastructure-read.test.ts

@@ -14,10 +14,8 @@ vi.mock("node:child_process", () => ({
   default: { spawnSync: mockSpawnSync },
 }));
 
-import {
-  discoverGlobalNodeModulesRoot,
-  isPiInfrastructureRead,
-} from "../src/external-directory";
+import { discoverGlobalNodeModulesRoot } from "../src/node-modules-discovery";
+import { isPiInfrastructureRead } from "../src/path-utils";
 
 // ── discoverGlobalNodeModulesRoot ──────────────────────────────────────────
 

package/tests/runtime.test.ts

@@ -67,7 +67,7 @@ vi.mock("../src/subagent-context", () => ({
   isSubagentExecutionContext: vi.fn().mockReturnValue(false),
 }));
 
-vi.mock("../src/external-directory", () => ({
+vi.mock("../src/node-modules-discovery", () => ({
   discoverGlobalNodeModulesRoot: mockDiscoverGlobalNodeModulesRoot,
 }));
 

package/src/external-directory.ts

@@ -1,24 +0,0 @@
-export {
-  extractExternalPathsFromBashCommand,
-  resetParserForTesting,
-} from "./bash-path-extractor";
-export {
-  formatBashExternalDirectoryAskPrompt,
-  formatBashExternalDirectoryDenyReason,
-  formatExternalDirectoryAskPrompt,
-  formatExternalDirectoryDenyReason,
-  formatExternalDirectoryHardStopHint,
-  formatExternalDirectoryUserDeniedReason,
-} from "./external-directory-messages";
-export { discoverGlobalNodeModulesRoot } from "./node-modules-discovery";
-export {
-  getPathBearingToolPath,
-  isPathOutsideWorkingDirectory,
-  isPathWithinDirectory,
-  isPiInfrastructureRead,
-  isSafeSystemPath,
-  normalizePathForComparison,
-  PATH_BEARING_TOOLS,
-  READ_ONLY_PATH_BEARING_TOOLS,
-  SAFE_SYSTEM_PATHS,
-} from "./path-utils";