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,49 @@
+---
+issue: 128
+issue_title: "refactor: extract ForwardingManager class to encapsulate polling lifecycle"
+---
+
+# Retro: #128 — extract ForwardingManager class
+
+## Final Retrospective (2026-05-08T02:00:00Z)
+
+### Session summary
+
+Extracted the forwarding poll lifecycle — 3 mutable fields on `ExtensionRuntime` and 2 free functions in `runtime.ts` — into a `ForwardingManager` class in `src/forwarding-manager.ts`.
+Introduced a `ForwardingController` interface so `HandlerDeps` references a narrow type instead of the concrete class.
+Shipped as v5.9.0 with zero behavioral change. 11 new unit tests, 3 removed; total suite 1260 tests across 57 files.
+
+### Observations
+
+#### What went well
+
+- **Plan-to-code was nearly 1:1 again.**
+  The two-commit structure (new class + tests, then wiring) from the revised plan strategy worked cleanly.
+  Both deviations were small and self-contained.
+- **Mechanical handler test updates were trivially correct.**
+  Replacing `startForwardedPermissionPolling: vi.fn()` / `stopForwardedPermissionPolling: vi.fn()` with `forwarding: { start: vi.fn(), stop: vi.fn() }` across 7 test files was a predictable find-and-replace.
+- **CI stayed green throughout.**
+  No regressions in the 1260-test suite after either commit.
+
+#### What caused friction (agent side)
+
+- `missing-context` — Used `vi.runAllTimersAsync()` in tests for `ForwardingManager`, which uses `setInterval`.
+  This caused an infinite loop ("Aborting after running 10000 timers").
+  Self-identified on the first test run; fixed by switching to `vi.advanceTimersByTimeAsync(250)`.
+  Impact: one test edit cycle (~1 minute), no incorrect commit landed.
+
+- `missing-context` — Plan specified `readonly forwarding: ForwardingManager` in `HandlerDeps`, using the concrete class type.
+  TypeScript's structural checker requires private fields (`timer`, `context`, `processing`, etc.) when the target is a class, so `{ start: vi.fn(), stop: vi.fn() }` in test mocks fails `pnpm run build`.
+  Self-identified when running `pnpm run build` after the wiring step.
+  Fixed by extracting a `ForwardingController` interface that `ForwardingManager` satisfies and `HandlerDeps` references.
+  Impact: one additional interface + two extra edits to `types.ts`, ~2 minutes of rework, no incorrect commit landed.
+
+#### What caused friction (user side)
+
+- None observed.
+
+### Changes made
+
+1. Created `docs/retro/0128-extract-forwarding-manager.md` (this file).
+2. Added fake-timer rule to `.pi/skills/testing/SKILL.md` — warns against `vi.runAllTimersAsync()` with `setInterval`.
+3. Added interface-over-class rule to `.pi/skills/code-style/SKILL.md` — use narrow interfaces in shared dep types, not concrete classes.