feat: vendor permission system source

2026-08-28 08:35:57 +00:00 · 2026-08-19 14:35:19 +08:00
parent 198584daf8
commit 410c50a3e5
809 changed files with 157793 additions and 139 deletions
@@ -0,0 +1,281 @@
+---
+issue: 335
+issue_title: "Extract a ConfigStore from the runtime free-functions"
+---
+
+# Extract a ConfigStore from the runtime free-functions
+
+## Problem Statement
+
+The extension's mutable config lives as a reassigned field (`config`) on the `ExtensionRuntime` god object, and its operations are free functions that take that god object as their first argument: `refreshExtensionConfig(runtime, ctx)`, `saveExtensionConfig(runtime, next, ctx)`, and `logResolvedConfigPaths(runtime)`.
+Because the value is reassigned on every refresh/save and the operations are free functions, every consumer captures a `() => runtime.config` closure to read the live value — four such closures across `index.ts` and the runtime factory.
+Config has no owner.
+
+This is Phase 4 Step 2 (Track B: De-god the runtime) from `docs/architecture/architecture.md` — the first link in the chain `ConfigStore → injectable logger → dissolve runtime → collapse index.ts closures`.
+It is behavior-preserving.
+
+## Goals
+
+- Introduce `src/config-store.ts` — a `ConfigStore` class that privately owns `config` + `lastConfigWarning` and exposes `current()` / `refresh(ctx?)` / `save(next, ctx)` / `logResolvedPaths()`.
+- Convert the three `(runtime, …)` config free functions into `ConfigStore` methods; the runtime no longer carries `config` / `lastConfigWarning`.
+- Give the config consumers (`PermissionSession`, `PermissionPrompter`, the `/permission-system` command controller) a `ConfigStore` / `ConfigReader` reference so they call `store.current()` instead of capturing `() => runtime.config`.
+- Behavior-preserving: no observable change to config loading, saving, warnings, status sync, or resolved-path logging.
+
+## Non-Goals
+
+- Moving the runtime context (`runtimeContext`) ownership into the store.
+  The roadmap deliberately scopes this store to `config` + `lastConfigWarning`; context unification onto `PermissionSession` is Step 4 (#337).
+  Until then the store reads/writes the still-runtime-owned context through a narrow transitional seam.
+- Making the logger injectable / removing `createSessionLogger(runtime)` — Step 3 (#336).
+- Dissolving `ExtensionRuntime` or fixing the `permissionManager` / `sessionRules` split-brain — Step 4 (#337).
+- Collapsing the remaining `index.ts` closure bags and `.bind` logging adapters into object references, and shrinking the `PermissionPrompter` / command / RPC deps bags beyond the config fields — Step 5 (#338).
+- Any `PermissionSession` god-object decomposition (Steps 6-8).
+
+## Background
+
+Relevant modules:
+
+- `src/runtime.ts` — defines `ExtensionRuntime` (extends `ExtensionPaths` + `SessionState`, adds `config`, `lastConfigWarning`, `writeDebugLog`, `writeReviewLog`), the three config free functions, and the `createExtensionRuntime()` factory.
+  `refreshExtensionConfig` reads/writes `runtime.runtimeContext`, reads `runtime.agentDir`, mutates `runtime.config` + `runtime.lastConfigWarning`, syncs status, notifies, and writes the debug log.
+  `saveExtensionConfig` is self-contained on its passed `ExtensionCommandContext` (no `runtime.runtimeContext` read), mutates `runtime.config` + `runtime.lastConfigWarning`, and writes the debug log.
+  `logResolvedConfigPaths` reads `runtime.permissionManager.getResolvedPolicyPaths()` and `runtime.runtimeContext?.cwd`, then writes the review + debug logs.
+- `src/index.ts` — the composition root.
+  Four `() => runtime.config` closures (`prompter`, `session` runtimeDeps, the command controller, and the logger `getConfig` inside the factory), plus the `(ctx) => refreshExtensionConfig(runtime, ctx)` / `() => logResolvedConfigPaths(runtime)` session wrappers, the `(next, ctx) => saveExtensionConfig(runtime, next, ctx)` command wrapper, the `shouldAutoApprove: () => shouldAutoApprovePermissionState("ask", runtime.config)` forwarding dep, and `refreshExtensionConfig(runtime)` (the initial pre-session refresh).
+- `src/permission-session.ts` — `PermissionSessionRuntimeDeps` carries `refreshExtensionConfig(ctx?)`, `logResolvedConfigPaths()`, `getConfig()` (plus `canRequestPermissionConfirmation` + `promptPermission`).
+  The session's `config` getter, `refreshConfig`, and `logResolvedConfigPaths` delegate to those three members; `getInfrastructureReadDirs` and `getToolPreviewLimits` read `this.config`.
+- `src/permission-prompter.ts` — `PermissionPrompterDeps.getConfig()` feeds the yolo-mode auto-approve check.
+- `src/config-modal.ts` — `PermissionSystemConfigController.getConfig()` + `setConfig(next, ctx)` (plus `getConfigPath`, `getComposedRules`).
+- `src/session-logger.ts` — `createSessionLogger(runtime)` reads `runtime.writeDebugLog` / `writeReviewLog` / `runtimeContext`; it does **not** read `runtime.config`, so moving config out does not affect it.
+- `src/permission-manager.ts` — `getResolvedPolicyPaths(): ResolvedPolicyPaths`.
+
+Constraints from AGENTS.md / the package skill:
+
+- Keep schema, example config, `docs/configuration.md`, `README.md`, and the loader aligned — not triggered here; this is a pure internal restructure with no config-format change.
+- Inject the new collaborator with a narrow interface type, not the concrete class, so test mocks need no `as unknown as` cast (concrete class types leak private fields to the structural checker).
+- Do not read `process.env` / `getAgentDir()` inside the store — `agentDir` is passed in.
+- Business logic at the edges: the store still calls the existing `loadAndMergeConfigs` / `loadUnifiedConfig` / `normalizePermissionSystemConfig` / `syncPermissionSystemStatus` / `buildResolvedConfigLogEntry` free functions (full IO injection is out of scope; the constructibility win here is config *ownership* and a substitutable store, not IO injection).
+
+### Why the context seam stays transitional
+
+`runtime.runtimeContext` is written **only** by `refreshExtensionConfig` today and read by `refreshExtensionConfig`, `logResolvedConfigPaths`, the deprecated RPC handler (`getRuntimeContext`), and the runtime/session loggers' `warn`.
+The store's `refresh(ctx?)` must keep setting it (so the RPC + loggers see the current context), and `logResolvedPaths()` must keep reading its `cwd`.
+Because Step 4 unifies the context onto `PermissionSession` (not onto the store), this Step does **not** move context ownership into `ConfigStore`.
+Instead the store takes a narrow `RuntimeContextRef` (get/set) backed by the still-runtime-owned `runtimeContext` field.
+This get/set pair is the runtime-context seam — not one of the four `() => runtime.config` closures this Step removes — and it dissolves in Step 4.
+
+## Design Overview
+
+### `ConfigStore` and its collaborators
+
+`ConfigStore` privately owns `config` and `lastConfigWarning` and holds four narrow collaborators — none of them the whole runtime:
+
+```typescript
+/** Read-only view of the current config — for consumers that only read. */
+export interface ConfigReader {
+  current(): PermissionSystemExtensionConfig;
+}
+
+/** Transitional get/set seam over the runtime-owned context (retired in Step 4 / #337). */
+export interface RuntimeContextRef {
+  get(): ExtensionContext | null;
+  set(ctx: ExtensionContext): void;
+}
+
+/** Narrow logging sink — replaced by an injected logger in Step 3 (#336). */
+export interface ConfigStoreLogger {
+  writeDebugLog(event: string, details?: Record<string, unknown>): void;
+  writeReviewLog(event: string, details?: Record<string, unknown>): void;
+}
+
+/** Narrow view of the manager's resolved policy paths (for logResolvedPaths). */
+export interface ResolvedPolicyPathProvider {
+  getResolvedPolicyPaths(): ResolvedPolicyPaths;
+}
+
+export interface ConfigStoreDeps {
+  agentDir: string;
+  context: RuntimeContextRef;
+  policyPaths: ResolvedPolicyPathProvider;
+  logger: ConfigStoreLogger;
+}
+
+export class ConfigStore implements ConfigReader {
+  private config: PermissionSystemExtensionConfig;
+  private lastConfigWarning: string | null = null;
+
+  constructor(private readonly deps: ConfigStoreDeps) {
+    this.config = { ...DEFAULT_EXTENSION_CONFIG };
+  }
+
+  current(): PermissionSystemExtensionConfig { return this.config; }
+  refresh(ctx?: ExtensionContext): void { /* refreshExtensionConfig body */ }
+  save(next: PermissionSystemExtensionConfig, ctx: ExtensionCommandContext): void { /* saveExtensionConfig body */ }
+  logResolvedPaths(): void { /* logResolvedConfigPaths body */ }
+}
+```
+
+Each method body is the corresponding free-function body with `runtime.config` / `runtime.lastConfigWarning` → `this.config` / `this.lastConfigWarning`, `runtime.runtimeContext` → `this.deps.context.get()` (and the one assignment → `this.deps.context.set(ctx)`), `runtime.agentDir` → `this.deps.agentDir`, `runtime.permissionManager.getResolvedPolicyPaths()` → `this.deps.policyPaths.getResolvedPolicyPaths()`, and `runtime.writeDebugLog` / `writeReviewLog` → `this.deps.logger.*`.
+`save` is unchanged apart from the field/logging redirection — it uses its own `ExtensionCommandContext`, not the context seam.
+
+### Construction in the factory (this Step)
+
+The store is constructed inside `createExtensionRuntime()`, where the runtime's context field, manager, and logger sink are in scope without index-level closures, and exposed as `runtime.configStore`.
+The existing logger ↔ config temporal coupling is preserved (Step 3 fixes it):
+
+```typescript
+const runtime = { ...paths, runtimeContext: null, permissionManager, /* … */,
+  writeDebugLog: () => {}, writeReviewLog: () => {} } as ExtensionRuntime;
+
+const configStore = new ConfigStore({
+  agentDir,
+  context: {
+    get: () => runtime.runtimeContext,
+    set: (ctx) => { runtime.runtimeContext = ctx; },
+  },
+  policyPaths: runtime.permissionManager,
+  logger: {
+    writeDebugLog: (e, d) => runtime.writeDebugLog(e, d),
+    writeReviewLog: (e, d) => runtime.writeReviewLog(e, d),
+  },
+});
+runtime.configStore = configStore;
+
+const logger = createPermissionSystemLogger({
+  getConfig: () => configStore.current(), // was () => runtime.config
+  /* … */
+});
+runtime.writeDebugLog = /* … */; runtime.writeReviewLog = /* … */;
+```
+
+The store's `logger` sink defers to `runtime.writeDebugLog` (assigned after the logger is built but before any store method runs at session time) — the same deferred-binding pattern the factory already uses.
+
+### Consumer call sites (Tell-Don't-Ask)
+
+`PermissionSession` holds the store directly; its config members leave `PermissionSessionRuntimeDeps`:
+
+```typescript
+// permission-session.ts
+get config() { return this.configStore.current(); }
+refreshConfig(ctx?) { this.configStore.refresh(ctx); }
+logResolvedConfigPaths() { this.configStore.logResolvedPaths(); }
+```
+
+`PermissionPrompter` and the forwarding `shouldAutoApprove` read through `ConfigReader`; the command controller holds the store for `current()` + `save()`.
+None re-capture `runtime.config`.
+
+### Edge cases
+
+- `refresh()` with no `ctx` → context seam unchanged; `cwd`/`hasUI` read whatever the seam currently holds (matches today's `runtime.runtimeContext` read).
+- `refresh(ctx)` before any context exists → `context.set(ctx)` then read back — identical to the current first-assignment path.
+- `logResolvedPaths()` reads `context.get()?.cwd` — null before the first `refresh(ctx)`, exactly as today.
+- Warning dedup (`lastConfigWarning`) and the `!warning` reset move verbatim into the store's private field.
+
+### Extracted-module upstream check
+
+`config-store.ts` imports only the existing config IO/reporting free functions, `node:fs` / `node:path` helpers, `DEFAULT_EXTENSION_CONFIG` + `normalizePermissionSystemConfig` (`extension-config.ts`), the config-paths helpers, and SDK context types — the same imports `runtime.ts` already has for these bodies.
+It does **not** import `runtime.ts` (no cycle): the runtime imports the store, not vice versa.
+No output-argument mutation is carried over — the store mutates only its own private fields; the one external write (`runtimeContext`) goes through the explicit `RuntimeContextRef.set` seam rather than reaching into a passed bag.
+
+## Module-Level Changes
+
+- `src/config-store.ts` (new) — `ConfigStore` class + `ConfigReader`, `RuntimeContextRef`, `ConfigStoreLogger`, `ResolvedPolicyPathProvider`, `ConfigStoreDeps` interfaces.
+  Holds the three former free-function bodies as methods plus `current()`.
+- `src/runtime.ts`
+  - Construct `ConfigStore` in `createExtensionRuntime()`; add `configStore: ConfigStore` to `ExtensionRuntime`.
+  - Remove `config` and `lastConfigWarning` from `ExtensionRuntime` (and `SessionState` if declared there); the logger `getConfig` reads `configStore.current()`.
+  - Convert `refreshExtensionConfig` / `saveExtensionConfig` / `logResolvedConfigPaths` into thin delegators to `runtime.configStore` during migration, then delete them in the final step.
+  - Drop config-IO imports that move solely into `config-store.ts` once the free functions are deleted.
+- `src/permission-session.ts`
+  - Add constructor param `configStore: ConfigStore` (or a session-narrow interface); store it.
+  - Remove `refreshExtensionConfig`, `logResolvedConfigPaths`, `getConfig` from `PermissionSessionRuntimeDeps` (leaving `canRequestPermissionConfirmation` + `promptPermission`).
+  - `config` getter / `refreshConfig` / `logResolvedConfigPaths` delegate to `this.configStore`.
+- `src/permission-prompter.ts`
+  - Replace `PermissionPrompterDeps.getConfig(): Config` with `config: ConfigReader`; `prompt` reads `this.deps.config.current()`.
+- `src/config-modal.ts`
+  - Point `PermissionSystemConfigController` at the store: `current()` + `save()` (replacing `getConfig` / `setConfig`); keep `getConfigPath` / `getComposedRules`.
+- `src/index.ts`
+  - Pass `runtime.configStore` into `PermissionSession`, `PermissionPrompter` (as `config`), and the command controller; remove the four `() => runtime.config` closures, the two session free-function wrappers, and the command `setConfig` wrapper.
+  - `shouldAutoApprove` reads `runtime.configStore.current()`.
+  - The initial `refreshExtensionConfig(runtime)` becomes `runtime.configStore.refresh()`.
+- `test/config-store.test.ts` (new) — unit tests for the store with injected fakes.
+- `test/runtime.test.ts` — delete the `refreshExtensionConfig` describe block (behavior now owned by `config-store.test.ts`); adjust any `createExtensionRuntime` assertion that read `runtime.config` / `runtime.lastConfigWarning`.
+- `test/permission-session.test.ts` — inject a fake `ConfigStore`; drop the three config members from the runtimeDeps fixture; re-point the `refreshConfig` / `logResolvedConfigPaths` delegation assertions at the store fake.
+- `test/permission-prompter.test.ts` — replace the `getConfig` stub with a `config: ConfigReader` fake.
+- `test/config-modal.test.ts` — replace the `getConfig` / `setConfig` controller stubs with a `ConfigStore` fake (`current` / `save`).
+
+Grep confirms `runtime.config` is read only in `src/index.ts` (5 lines) and `src/runtime.ts`; `lastConfigWarning` only in `src/runtime.ts`; the three free functions only in `src/index.ts`, `src/runtime.ts`, `src/permission-session.ts`, and their tests.
+`session-logger.test.ts`'s `as unknown as ExtensionRuntime` mock does not set `config`, so removing the field does not break it.
+The package skill (`.pi/skills/package-pi-permission-system/SKILL.md`) does not name `refreshExtensionConfig` / `saveExtensionConfig` / `logResolvedConfigPaths`.
+
+Doc updates: `docs/architecture/architecture.md` already names `config-store.ts` and the `ConfigStore` outcome in the Step 2 narrative and the module-structure list; the constructibility metrics table is a phase-start snapshot, not a live count, so no edit is required by this Step (the `/retro` for the phase will refresh it).
+
+## Test Impact Analysis
+
+1. New unit tests enabled: `config-store.test.ts` constructs `ConfigStore` directly with plain fakes for the context seam, policy-path provider, and logger sink — no `as unknown as ExtensionRuntime`, no `vi.mock("../src/runtime")`.
+   It exercises `current()`, `refresh(ctx?)` (config update, warning set/clear/dedup, status sync gated on `hasUI`, debug log), `save(next, ctx)` (success write, error notify + early return, debug log), and `logResolvedPaths()` (review + debug entries from the injected policy-path provider).
+2. Redundant tests: the `runtime.test.ts` `refreshExtensionConfig` describe block — the function under test becomes a delegator and is then deleted; its behavior is covered at the layer that now owns it.
+   Removed in the step that turns the free functions into delegators.
+3. Tests that must stay: the `permission-session.test.ts` config-delegation tests (now assert delegation to the injected `ConfigStore` fake rather than the runtimeDeps stub — same contract, different collaborator); the `permission-prompter.test.ts` yolo auto-approve tests (now via the `ConfigReader` fake); the `config-modal.test.ts` get/set tests (now via the `ConfigStore` fake); the `createExtensionRuntime` path-derivation tests (unaffected).
+
+## TDD Order
+
+1. **Add `ConfigStore` + interfaces with `config-store.test.ts`** — `feat:`
+   - Red: `test/config-store.test.ts` — construct `new ConfigStore({ agentDir, context: fakeRef, policyPaths: fakeProvider, logger: fakeSink })`; assert `current()`, `refresh` (load/normalize, warning set/clear/dedup, status sync on `hasUI`, debug log, `context.set` on `ctx`), `save` (write path, error-notify + early return, debug log), `logResolvedPaths` (review + debug entries).
+     Mock the config-IO/status/reporter modules as `runtime.test.ts` does today.
+   - Green: implement the class and interfaces by lifting the three free-function bodies and redirecting field/context/logger access.
+   - Additive: no production consumer yet (gains consumers in steps 2-5 of this plan — not a speculative export; `pnpm fallow dead-code` runs clean at plan completion).
+   - Run `pnpm run check` + `config-store.test.ts`.
+   - Commit: `feat: add ConfigStore owning extension config state`.
+
+2. **Construct `ConfigStore` in the factory; back runtime config with it** — `refactor:`
+   - Build the store in `createExtensionRuntime()`; add `runtime.configStore`; remove `config` (replace its readers in `runtime.ts` with `configStore.current()`; expose a temporary `get config()` getter on the runtime object so the still-unmigrated `index.ts` consumers compile) and remove the `lastConfigWarning` field (no external reader).
+   - Logger `getConfig` → `() => configStore.current()`; the three free functions become one-line delegators to `runtime.configStore`.
+   - Delete the redundant `refreshExtensionConfig` block from `runtime.test.ts`.
+   - Internal to `runtime.ts`; `index.ts` and the other consumers are untouched this step.
+   - Run `pnpm run check` + the full suite.
+   - Commit: `refactor: back ExtensionRuntime config with ConfigStore`.
+
+3. **Inject `ConfigStore` into `PermissionSession`** — `refactor:`
+   - Coupled step (constructor-signature change; single production call site `index.ts` + the `createSession` test helper).
+   - Red: `permission-session.test.ts` — inject a `ConfigStore` fake; drop `refreshExtensionConfig` / `logResolvedConfigPaths` / `getConfig` from the runtimeDeps fixture; re-point the delegation assertions at the store fake.
+   - Green: add the `configStore` constructor param; delegate the `config` getter / `refreshConfig` / `logResolvedConfigPaths` to it; remove the three members from `PermissionSessionRuntimeDeps`; update `index.ts` to pass `runtime.configStore` and drop the two session config wrappers.
+   - Run `pnpm run check` (shared-interface change) + the full suite.
+   - Commit: `refactor: inject ConfigStore into PermissionSession`.
+
+4. **Point `PermissionPrompter` (and forwarding) at `ConfigReader`** — `refactor:`
+   - Coupled step (deps-interface change; single call site `index.ts` + `permission-prompter.test.ts`).
+   - Red: `permission-prompter.test.ts` — replace the `getConfig` stub with a `config: ConfigReader` fake.
+   - Green: `PermissionPrompterDeps.getConfig()` → `config: ConfigReader`; `prompt` reads `this.deps.config.current()`; `index.ts` passes `config: runtime.configStore` and rewrites `shouldAutoApprove` to read `runtime.configStore.current()`.
+   - Run `pnpm run check` + the full suite.
+   - Commit: `refactor: read config from ConfigReader in PermissionPrompter`.
+
+5. **Point the `/permission-system` command at the `ConfigStore`** — `refactor:`
+   - Coupled step (controller-interface change; single call site `index.ts` + `config-modal.test.ts`).
+   - Red: `config-modal.test.ts` — replace the `getConfig` / `setConfig` controller stubs with a `ConfigStore` fake (`current` / `save`).
+   - Green: `PermissionSystemConfigController` reads `current()` + `save()`; `index.ts` passes `runtime.configStore`; drop the `getConfig` closure and the `setConfig` wrapper.
+   - Run `pnpm run check` + the full suite.
+   - Commit: `refactor: drive the permission-system command from ConfigStore`.
+
+6. **Remove the runtime config free functions and the transitional getter** — `refactor:`
+   - All consumers now read the store; delete `refreshExtensionConfig` / `saveExtensionConfig` / `logResolvedConfigPaths` and the temporary `get config()` getter from `runtime.ts`; change the initial `refreshExtensionConfig(runtime)` in `index.ts` to `runtime.configStore.refresh()`; drop now-unused imports.
+   - Run `pnpm run check`, the full suite, and `pnpm fallow dead-code` to confirm no orphaned exports.
+   - Commit: `refactor: remove runtime config free-functions`.
+
+## Risks and Mitigations
+
+- Risk: the transitional `RuntimeContextRef` get/set seam changes when/where `runtime.runtimeContext` is written.
+  Mitigation: `set` is called exactly where `refreshExtensionConfig` assigned today (and only there); `get` reads the same field; the RPC + loggers read the unchanged field.
+  Covered by the `config-store.test.ts` `context.set` assertion and the surviving composition-root test.
+- Risk: removing `config` / `lastConfigWarning` from `ExtensionRuntime` breaks an importer not found by grep.
+  Mitigation: grep across `src/` + `test/` is clean (config in `index.ts` + `runtime.ts`; warning in `runtime.ts` only); step 6 runs `pnpm fallow dead-code` as a backstop; the temporary getter keeps `index.ts` compiling across steps 2-5.
+- Risk: dropping the `getConfig` callbacks surfaces incomplete mock returns the call shape previously hid.
+  Mitigation: the consumer-test fakes return full `PermissionSystemExtensionConfig` shapes via the existing `DEFAULT_EXTENSION_CONFIG` clone; the narrow `ConfigReader` only requires `current()`.
+- Risk: the logger ↔ config temporal coupling (store built before the logger that the store's sink defers to) misfires.
+  Mitigation: identical deferred-binding pattern to today's `writeDebugLog`/`writeReviewLog` reassignment; store methods only run at session time, after the reassignment; Step 3 removes the coupling entirely.
+
+## Open Questions
+
+- Should `runtimeContext` ownership move onto the store rather than staying a transitional seam?
+  Deferred to Step 4 (#337), which unifies context onto `PermissionSession`; owning it in the store now would pre-empt and then re-do that work.
+- Should the remaining `() => configStore.current()` adapters (the logger `getConfig`, the forwarding `shouldAutoApprove`) collapse to bare references?
+  The logger one is retired in Step 3 (#336); the index-level deps-bag collapse is Step 5 (#338).