my-pi/pi-permission-system/docs/plans/0525-extract-manager-unified-fixtures.md

issue, issue_title

issue	issue_title
525	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:

// 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<string, unknown>,
  mcpServerNames?: readonly string[],
): { manager: PermissionManager; cleanup: () => void };

// New — thin delegator to createManagerWithProject.
export function createManagerWithScopes(
  globalPermission: Record<string, unknown>,
  projectPermission?: Record<string, unknown>,
): { 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<string, ScopeConfig>;
    projectAgent?: Record<string, ScopeConfig>;
  },
  mcpServerNames?: readonly string[],
): PolicyLoader;
export function createInMemoryManager(
  scopes?: Parameters<typeof createInMemoryPolicyLoader>[0],
  mcpServerNames?: readonly string[],
): PermissionManager;

// Moved — agentDir-layout harness.
export function createAgentDirHarness(opts: {
  globalPermission: Record<string, unknown>;
  projectPermission?: Record<string, unknown>;
}): {
  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:

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.