--- issue: 525 issue_title: "pi-permission-system: extract shared fixtures from permission-manager-unified.test.ts" --- # Extract shared config-harness fixtures from `permission-manager-unified.test.ts` ## Release Recommendation **Release:** ship independently Phase 8 Step 1's roadmap entry is tagged `Release: independent` — it belongs to no release batch. This is test-only work: every commit is `test(pi-permission-system):`, a `hidden: true` changelog type that does not cut a release on its own (per AGENTS.md). So this plan lands on `main` and auto-batches into the next `feat:`/`fix:`/unhidden-`docs:` release; it does not itself trigger one. No mid-batch coordination is required — Step 2 ([#526]) depends on this file's harness existing, not on a release. ## Problem Statement `test/permission-manager-unified.test.ts` (3,745 LOC) carries a cluster of near-identical config-harness scaffolding: six file-local manager factories, several fully-inline temp-dir-plus-config blocks, and eleven hand-rolled `sessionRules` array literals. The roadmap records 24 clone groups / 305 duplicated lines with accelerating churn. Phase 8 Step 2 ([#526]) lands manager-level yolo tests in this same file; extracting the duplication first keeps that step's diff readable instead of copying scaffolding again. This is a Category D (test duplication) tidy-first refactor with no production change. ## Goals - Move the file-local config-harness factories into the shared `test/helpers/manager-harness.ts`, alongside the existing `createManager` / `createManagerWithProject` builders. - Introduce a `sessionRule` builder that replaces the local `sessionAllow` helper and the eleven inline `sessionRules` array literals. - Collapse factories that duplicate the existing shared builders (permission-only and global-plus-project construction) into thin delegators rather than relocating duplicate bodies. - Keep every existing assertion and test case intact — this is a pure setup-scaffolding extraction, not a behavior change. - Leave the file's clone groups at or near zero and make the shared harness reusable by Step 2. Not breaking: no production code, config, schema, or public runtime surface changes. ## Non-Goals - No production source change (`src/` untouched). - Do not extract the repeated test *act/assert* bodies (e.g. the agent-frontmatter blocks at lines ~2494 and ~2523 that construct `createManager` with a `reviewer` agent file and repeat `checkTool` assertions). Per the `testing` skill, the repeated system-under-test call is the test subject, not duplication to remove — wrapping it in a helper would hide the act. - Do not extract the single-instance inline harness blocks that are not clones: the `MCP server names in settings.json` test (~line 2270, which also writes `mcp.json` + `settings.json`) and the `PI_CODING_AGENT_DIR` test (~line 2911, which manages an env var). These appear once, carry test-specific extra setup, and are out of the "repeated config-harness blocks" scope. - Do not touch the file-local action helpers `checkTool` / `checkPathValues` / `checkPath` — they are single-definition wrappers around `manager.check`, not duplicated harness. - Do not rename or re-home the existing `createManager` / `createManagerWithProject` builders (three test files import them); only extend the module. ## Background Relevant modules: - `test/helpers/manager-harness.ts` — the designated shared home. Already exports `createManager(config, agentFiles?, options?)` (filesystem-backed `PermissionManager` from a `ScopeConfig`, returns `{ manager, globalConfigPath, cleanup }`) and `createManagerWithProject(...)` (two-level global + project harness, returns `{ manager, cleanup }`). Establishes the `create*` naming convention this plan follows. - `test/permission-manager-unified.test.ts` — holds the local factories to extract. Local factories and their call-site counts (from `grep -c`): | Local symbol | Uses | What it builds | | ---------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------- | | `sessionAllow(surface, pattern)` | 20 | a `layer: "session"` allow `Rule` | | inline `sessionRules` array literals | 11 | the same `Rule` shape, hand-rolled | | `makeManager(mcpServerNames?)` | 21 | manager over nonexistent paths (universal `ask`), no temp dir / cleanup | | `makeManagerWithConfig(permission, mcp?)` | 62 | temp dir + `{ permission }` config → `{ manager, cleanup }` | | `makeManagerWithScopes(global, project?)` | 10 | global + optional project config → `{ manager, cleanup }` | | `makeInMemoryManager(scopes?, mcp?)` + `createInMemoryPolicyLoader(scopes?, mcp?)` | 28 | manager over an in-memory `PolicyLoader`, no filesystem | | `makeAgentDirSetup({ globalPermission, projectPermission? })` | 7 | agentDir-layout harness via `getGlobalConfigPath` / `getProjectConfigPath` | Two call sites (~lines 1177, 1189) use `createInMemoryPolicyLoader` directly (not via `makeInMemoryManager`) because they pass a `platform: "win32"` option to the `PermissionManager` constructor — so the loader factory must be exported independently, not only wrapped. Applicable constraints from AGENTS.md and skills: - Test-only work uses `test(pi-permission-system):`, a hidden changelog type; it does not cut a release (see Release Recommendation). - `docs/architecture/architecture.md` references this file's metrics (lines 834, 850) and defines Step 1's `Outcome:`; the implementation commit marks Step 1 complete (`package-pi-permission-system` skill: mark the step `✅` on both the step heading and its Mermaid node in the implementation doc-update commit, not at ship time). - `manager-harness.ts` currently imports only `ScopeConfig` from `#src/types`; the moved factories add imports for `PolicyLoader` (`#src/permission-manager`), `ResolvedPolicyPaths` (`#src/policy-loader`), `Rule` + `PermissionState` (`#src/rule` / `#src/types`), and `getGlobalConfigPath` / `getProjectConfigPath` (`#src/config-paths`). ## Design Overview Consolidate all filesystem- and loader-backed manager construction into `manager-harness.ts` under the module's `create*` convention, then migrate call sites and delete the file-local definitions. Two factories that merely re-shape an existing builder's input become thin delegators (no duplicated body); the three genuinely distinct patterns (missing-config, in-memory, agentDir) move as new named builders; the session-rule literal becomes one builder. Final shared API added to `test/helpers/manager-harness.ts`: ```typescript // New — generalizes the local sessionAllow (default action stays "allow"). export function sessionRule( surface: string, pattern: string, action: PermissionState = "allow", ): Rule; // New — manager over nonexistent paths; universal "ask" default. No cleanup. export function createMissingConfigManager( mcpServerNames?: readonly string[], ): PermissionManager; // New — thin delegator to createManager({ permission }, {}, { mcpServerNames }). export function createManagerWithConfig( permission: Record, mcpServerNames?: readonly string[], ): { manager: PermissionManager; cleanup: () => void }; // New — thin delegator to createManagerWithProject. export function createManagerWithScopes( globalPermission: Record, projectPermission?: Record, ): { manager: PermissionManager; cleanup: () => void }; // Moved — in-memory PolicyLoader + its manager wrapper (loader exported for // the two platform-override call sites). export function createInMemoryPolicyLoader( scopes?: { global?: ScopeConfig; project?: ScopeConfig; agent?: Record; projectAgent?: Record; }, mcpServerNames?: readonly string[], ): PolicyLoader; export function createInMemoryManager( scopes?: Parameters[0], mcpServerNames?: readonly string[], ): PermissionManager; // Moved — agentDir-layout harness. export function createAgentDirHarness(opts: { globalPermission: Record; projectPermission?: Record; }): { agentDir: string; cwd: string; globalConfigPath: string; projectConfigPath: string; cleanup: () => void; }; ``` ### Delegation, not relocation, for the two duplicative factories `makeManagerWithConfig(permission, mcp?)` currently re-implements the temp-dir + write + construct sequence that `createManager` already owns; its body just differs by taking a bare `permission` record instead of a full `ScopeConfig`. The extracted `createManagerWithConfig` keeps the ergonomic positional signature (62 terse call sites) but delegates: ```typescript export function createManagerWithConfig(permission, mcpServerNames) { const { manager, cleanup } = createManager({ permission }, {}, { mcpServerNames }); return { manager, cleanup }; } ``` `createManagerWithScopes` likewise delegates to `createManagerWithProject({ permission: global }, {}, { projectConfig: { permission: project } })`. This removes the duplicated harness body rather than moving it — the clone disappears instead of relocating. The one behavioral detail to preserve: `createManager` writes a `pi-permissions.jsonc` file with a trailing newline, whereas the old local `makeManagerWithConfig` wrote `config.json` without one; both are valid inputs to the loader (verified by the suite staying green), so the delegation is behavior-preserving for the assertions. ### Session-rule builder `sessionRule(surface, pattern, action = "allow")` returns the exact `Rule` shape the inline literals build (`{ surface, pattern, action, layer: "session", origin: "session" }`). It subsumes the local `sessionAllow(surface, pattern)` (all 20 uses are `allow`) and the eleven inline `external_directory` session-rule arrays, which become `[sessionRule("external_directory", "/other/project/*")]`. ### Interaction with upstream The moved factories carry no Tell-Don't-Ask or output-argument smell: each constructs a value (`PermissionManager` and/or a `cleanup` closure) and returns it; none mutates a caller-supplied argument. `createInMemoryPolicyLoader` returns a plain object implementing the `PolicyLoader` interface — it reads `#src/permission-manager` and `#src/policy-loader` types the test file already imports, so no upstream API gap needs closing before the move. ## Module-Level Changes - `test/helpers/manager-harness.ts` — add `sessionRule`, `createMissingConfigManager`, `createManagerWithConfig`, `createManagerWithScopes`, `createInMemoryPolicyLoader`, `createInMemoryManager`, `createAgentDirHarness`; add the corresponding imports (`PolicyLoader`, `ResolvedPolicyPaths`, `Rule`, `PermissionState`, `getGlobalConfigPath`, `getProjectConfigPath`). - `test/permission-manager-unified.test.ts` — delete the seven local factory definitions and the inline `sessionRules` literals; import the new builders from `#test/helpers/manager-harness`; migrate all call sites (rename `make*` → `create*`, `sessionAllow` → `sessionRule`). Keep the two `platform: "win32"` call sites using the imported `createInMemoryPolicyLoader` directly. Prune any now-orphaned imports from the file's top block (e.g. `mkdtempSync` / `writeFileSync` if no inline block still uses them; the retained single-instance blocks at ~2270 and ~2911 likely keep them alive — verify before removing). - `docs/architecture/architecture.md` — mark Phase 8 Step 1 complete: `✅` on the Step 1 heading (line ~849) and on the `S1` Mermaid node (line ~909). Update the metric prose (lines 834, 850) only if the post-refactor clone count is being reported as resolved; the `Duplication ≤ 5.5%` target row is a phase-close metric — do not tick it for a single step. This edit lands in the implementation doc-update commit, not at ship time. No `src/`, schema, config, or `README.md` change — this refactor removes no production export and adds no user-facing feature, so the README-command and schema-alignment checks do not apply. ## Test Impact Analysis 1. **New tests enabled:** none directly — this is deduplication of setup, not a new production surface. It does unblock Step 2 ([#526]) to add manager-level yolo tests that import the shared harness instead of copying scaffolding. 2. **Tests made redundant:** none removed. Every existing `it` / `test` case and its assertions are preserved verbatim; only the construction scaffolding is relocated. 3. **Tests that must stay as-is:** all of them. In particular, the agent-frontmatter act/assert clones (~lines 2494, 2523) stay unextracted — the repeated `checkTool` act is the test subject (see Non-Goals). ## Invariants at risk The only invariant is the existing suite: `test/permission-manager-unified.test.ts` must stay fully green after every step, and the other two `manager-harness` consumers (`test/skill-prompt-sanitizer.test.ts`, `test/handlers/external-directory-symlink-acceptance.test.ts`) must stay green since the module gains exports without changing existing signatures. No prior-phase production `Outcome:` invariant is touched — Step 1 changes no `src/` file. Verification is `pnpm --filter @gotgenes/pi-permission-system exec vitest run` (full file) plus `pnpm run check` after any step that moves a type-bearing factory. ## TDD Order This is a behavior-preserving test refactor, so each cycle is a green-suite-verified extraction, not a red→green pair. Per the extraction rule, each step moves a factory (or removes a local symbol) **and** migrates all its call sites in the same commit — a removed local symbol breaks every caller at the type level until they are updated. Run `pnpm --filter @gotgenes/pi-permission-system exec vitest run test/permission-manager-unified.test.ts` after each step; run `pnpm run check` after any step that moves a type-bearing signature. 1. **`sessionRule` builder.** Add `sessionRule` to `manager-harness.ts`; migrate the 20 `sessionAllow` calls and 11 inline `sessionRules` literals; delete the local `sessionAllow`. Verify suite green. Commit: `test(pi-permission-system): extract sessionRule builder into manager-harness`. 2. **`createMissingConfigManager`.** Add it to the harness; migrate the 21 `makeManager()` calls; delete the local `makeManager`. Verify green. Commit: `test(pi-permission-system): extract createMissingConfigManager helper`. 3. **`createManagerWithConfig` (delegator).** Add the delegating builder; migrate the 62 `makeManagerWithConfig` calls; delete the local factory. Verify green + `pnpm run check`. Commit: `test(pi-permission-system): reuse shared createManager via createManagerWithConfig`. 4. **`createManagerWithScopes` (delegator).** Add the delegating builder; migrate the 10 `makeManagerWithScopes` calls; delete the local factory. Verify green. Commit: `test(pi-permission-system): reuse createManagerWithProject via createManagerWithScopes`. 5. **`createInMemoryPolicyLoader` + `createInMemoryManager`.** Move both into the harness (export the loader); migrate the 28 `makeInMemoryManager` calls and the two direct `createInMemoryPolicyLoader` platform-override sites; delete the locals. Verify green + `pnpm run check`. Commit: `test(pi-permission-system): move in-memory policy-loader harness into helpers`. 6. **`createAgentDirHarness`.** Move it into the harness; migrate the 7 `makeAgentDirSetup` calls; delete the local factory. Prune any orphaned top-of-file imports left after all moves. Verify green + `pnpm run check`. Commit: `test(pi-permission-system): move agentDir harness into helpers`. 7. **Roadmap doc update.** Mark Phase 8 Step 1 `✅` (heading + `S1` Mermaid node) in `docs/architecture/architecture.md`; refresh the clone-count prose if reporting it resolved. Verify `rumdl` and `mmdc` (diagram render) pass. Commit: `docs(pi-permission-system): mark Phase 8 Step 1 complete`. ## Risks and Mitigations - **Large mechanical call-site churn (Step 3 touches 62 sites).** Mitigation: each step is a find-and-replace of one symbol, verified by the full file's suite staying green before commit — a missed or wrong rename fails a real assertion, not just a typecheck. - **A moved factory silently changes a default (e.g. config filename / trailing newline).** Mitigation: the delegators reuse the existing green builders; any observable difference surfaces as a suite failure in the same step. - **Orphaned imports after the moves (Biome `noUnusedImports` is warning-level, exit 0).** Mitigation: Step 6 explicitly prunes top-of-file imports; the pre-completion reviewer runs `pnpm fallow dead-code` as a backstop. - **Naming inconsistency if some `make*` names are kept.** Mitigation: rename every extracted factory to the module's `create*` convention (the `sessionRule` builder keeps the plain-`Rule`-builder naming already used by `sessionAllow`). ## Open Questions None. The single-instance inline blocks deliberately left in place (MCP-settings, `PI_CODING_AGENT_DIR`) are recorded in Non-Goals; no follow-up issue is warranted — they are not clones and carry test-specific setup. [#526]: https://github.com/gotgenes/pi-packages/issues/526