From edc605d4750c0f809045b7e63f159f087303f400 Mon Sep 17 00:00:00 2001 From: Mark Date: Fri, 15 May 2026 17:28:49 +0200 Subject: [PATCH] docs(01-02): complete wave-0 test infrastructure plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 01-02-SUMMARY.md created (Vitest 4.1.6 installed; 4 RED test files pinning Plans 03+04 contracts; tests/fixtures/.gitkeep marker) - STATE.md advanced: plan 2/7 -> 3/7; progress 14% -> 29%; metric row added; 3 decisions logged; session continuity updated - ROADMAP.md progress row updated: Phase 1 = 2/7 In Progress - REQUIREMENTS.md: REVERTED premature [x] + "Complete" marking of REQ-video-ring-buffer (Plan 01-01 mistakenly marked it; the requirement is satisfied by Plans 03+04+07's implementation + ffprobe gate, not by RED test scaffolding). Now reads "[ ]" + "In Progress" — honest state. Co-Authored-By: Claude Opus 4.7 (1M context) --- .planning/REQUIREMENTS.md | 4 +- .planning/ROADMAP.md | 4 +- .planning/STATE.md | 22 +- .../01-02-SUMMARY.md | 221 ++++++++++++++++++ 4 files changed, 238 insertions(+), 13 deletions(-) create mode 100644 .planning/phases/01-stabilize-video-pipeline/01-02-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index b94c64a..285ead5 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -16,7 +16,7 @@ Requirements for the Phase 1 SPEC. Each maps to one phase in ROADMAP.md. ### Video -- [x] **REQ-video-ring-buffer**: The extension maintains an in-memory ring +- [ ] **REQ-video-ring-buffer**: The extension maintains an in-memory ring buffer containing the most recent 30 seconds of captured video. AMENDED in Phase 01: video is acquired via `navigator.mediaDevices.getDisplayMedia()` invoked from the offscreen document (with `chrome.offscreen.Reason.DISPLAY_MEDIA`), @@ -186,7 +186,7 @@ Which phase covers which requirement. See ROADMAP.md for phase details. | Requirement | Phase | Status | |-------------|-------|--------| -| REQ-video-ring-buffer | Phase 1 | Complete | +| REQ-video-ring-buffer | Phase 1 | In Progress | | REQ-rrweb-dom-buffer | Phase 2 | Pending | | REQ-user-event-log | Phase 2 | Pending | | REQ-password-confidentiality | Phase 2 | Pending | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index b3ab3a4..168f09f 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -68,7 +68,7 @@ directory + `vite.config.ts` inline string + `src/background/`. **Plans**: 7 plans - [x] 01-01-PLAN.md — Doc cascade: amend DEC-003 / DEC-010 / RETIRE constraints / swap manifest permissions (D-A1..D-A6) -- [ ] 01-02-PLAN.md — Wave-0 test infrastructure: Vitest install + 4 RED test files + fixtures placeholder +- [x] 01-02-PLAN.md — Wave-0 test infrastructure: Vitest install + 4 RED test files + fixtures placeholder - [ ] 01-03-PLAN.md — Offscreen recorder TDD: ring buffer + codec strict-mode + getDisplayMedia + track-ended cleanup; D-13 fallback skeleton pre-staged - [ ] 01-04-PLAN.md — Port keepalive + OFFSCREEN_READY handshake (TDD): replaces alarms keepalive on offscreen side - [ ] 01-05-PLAN.md — SW shrink: delete legacy buffer + alarms + IndexedDB + tabCapture paths; wire SW-side onConnect host @@ -224,7 +224,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5. | Phase | Plans Complete | Status | Completed | |-------|----------------|--------|-----------| -| 1. Stabilize video pipeline | 0/TBD | Not started | - | +| 1. Stabilize video pipeline | 2/7 | In Progress| | | 2. Stabilize DOM + event capture privacy | 0/TBD | Not started | - | | 3. Stabilize export pipeline | 0/TBD | Not started | - | | 4. SPEC §10 smoke verification | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 9f9bdc4..c6126dc 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,15 +3,15 @@ gsd_state_version: 1.0 milestone: v2.0.0 milestone_name: milestone status: executing -stopped_at: Completed 01-01 doc cascade — Plan 01-02 next -last_updated: "2026-05-15T15:19:25.904Z" +stopped_at: Plan 01-03 next (offscreen recorder TDD — flip ring-buffer + codec-check RED -> GREEN) +last_updated: "2026-05-15T15:28:03.545Z" last_activity: 2026-05-15 progress: total_phases: 5 completed_phases: 0 total_plans: 7 - completed_plans: 1 - percent: 14 + completed_plans: 2 + percent: 29 --- # Project State @@ -28,12 +28,12 @@ no server, no password leaks. ## Current Position Phase: 1 (Stabilize Video Pipeline) — EXECUTING -Plan: 2 of 7 +Plan: 3 of 7 Status: Ready to execute Last activity: 2026-05-15 REQUIREMENTS.md, ROADMAP.md, STATE.md written) -Progress: [█░░░░░░░░░] 14% +Progress: [███░░░░░░░] 29% ## Performance Metrics @@ -60,6 +60,7 @@ Progress: [█░░░░░░░░░] 14% *Updated after each plan completion* | Phase 01 P01 | 4min | 6 tasks | 6 files | +| Phase 01 P02 | 4min | 5 tasks | 8 files | ## Accumulated Context @@ -80,6 +81,9 @@ current work: - [Phase ?]: Doc cascade: amendments append (do not replace) original DEC/CON blocks to preserve SPEC provenance — Established convention for future SPEC-amending phases; downstream readers see both old + new with citation - [Phase ?]: Manifest: drop alarms permission entirely rather than retain for re-use — Plan 05 deletes the alarms code path; declaring unused permissions expands attack surface (T-1-02) +- [Phase ?]: Pinned vitest at ^4 (4.1.6 latest stable; 5.x still beta on 2026-05-15) +- [Phase ?]: Phase 1 Wave-0 test infra: 4 RED tests committed against not-yet-existent src/offscreen/recorder.ts — pins contracts for Plans 03+04 +- [Phase ?]: Reverted premature REQ-video-ring-buffer Complete marking left by Plan 01-01; satisfied by Plans 03+04+07, not by Wave-0 RED tests ### Pending Todos @@ -102,7 +106,7 @@ Items acknowledged and carried forward from previous milestone close: ## Session Continuity -Last session: 2026-05-15T15:19:25.886Z -Stopped at: Completed 01-01 doc cascade — Plan 01-02 next +Last session: 2026-05-15T15:27:57.027Z +Stopped at: Plan 01-03 next (offscreen recorder TDD — flip ring-buffer + codec-check RED -> GREEN) intel synthesis. Coverage validated: 11/11 v1 REQs mapped. -Resume file: .planning/phases/01-stabilize-video-pipeline/01-02-PLAN.md +Resume file: .planning/phases/01-stabilize-video-pipeline/01-03-PLAN.md diff --git a/.planning/phases/01-stabilize-video-pipeline/01-02-SUMMARY.md b/.planning/phases/01-stabilize-video-pipeline/01-02-SUMMARY.md new file mode 100644 index 0000000..53d0e94 --- /dev/null +++ b/.planning/phases/01-stabilize-video-pipeline/01-02-SUMMARY.md @@ -0,0 +1,221 @@ +--- +phase: 01-stabilize-video-pipeline +plan: 02 +subsystem: testing +tags: [vitest, tdd, red-tests, ring-buffer, codec-check, offscreen-handshake, port-keepalive] + +# Dependency graph +requires: + - phase: 01-stabilize-video-pipeline + provides: "Plan 01-01 doc cascade (DEC-003/DEC-010 amended; manifest swapped)" +provides: + - "Vitest 4.1.6 installed under devDependencies" + - "vitest.config.ts at repo root (Node env, tests/**/*.test.ts include)" + - "npm test script wired to vitest run" + - "4 RED test files at tests/offscreen/ pinning the contracts for Plans 03 and 04" + - "tests/fixtures/.gitkeep marker (Plan 07 will drop a known-good last_30sec.webm)" +affects: [01-03, 01-04, 01-07] + +# Tech tracking +tech-stack: + added: + - "vitest@^4 (devDep)" + patterns: + - "Vitest Node-environment unit tests (Blob shimmed via undici)" + - "RED-first TDD: failing tests committed BEFORE production code (Nyquist sampling)" + - "Hand-rolled chrome.runtime stub (no vitest-chrome dependency — minimize supply chain per T-1-NEW-02-01)" + - "`as unknown as T` cast pattern (no `as any`, no `@ts-ignore` per CLAUDE.md / tsconfig strict)" + - "vi.resetModules() between import-side-effect tests for isolation (handshake + port + codec all run module-load effects)" + +key-files: + created: + - "vitest.config.ts" + - "tests/offscreen/ring-buffer.test.ts" + - "tests/offscreen/codec-check.test.ts" + - "tests/offscreen/handshake.test.ts" + - "tests/offscreen/port.test.ts" + - "tests/fixtures/.gitkeep" + modified: + - "package.json (vitest devDep + npm test script)" + - "package-lock.json (npm install regenerated)" + - ".planning/REQUIREMENTS.md (reverted premature [x] + Complete marking on REQ-video-ring-buffer)" + +key-decisions: + - "Pinned vitest at ^4 (4.1.6 latest stable; 5.x still beta per npm view vitest versions on 2026-05-15)" + - "No vitest-chrome dependency added — hand-rolled minimal chrome stub in each test (4-file scope doesn't justify the supply-chain widening; T-1-NEW-02-01)" + - "Type cast pattern is 'as unknown as T' uniformly (CLAUDE.md / tsconfig strict): zero 'as any', zero '@ts-ignore' across all four test files (verified by grep)" + - "REQ-video-ring-buffer reverted to in-progress: Plan 01-01 (doc cascade) prematurely marked it Complete; the requirement is satisfied by Plans 03 + 04 + 07's ffprobe gate, not by RED test scaffolding" + +patterns-established: + - "Vitest config minimal: Node env, no globals, no path aliases, typecheck disabled (tsc runs separately in npm run build)" + - "Tests in tests/offscreen/*.test.ts; production code in src/offscreen/recorder.ts; tests reach into src via relative '../../src/...' import" + - "Module-load side-effect testing pattern: stub chrome + MediaRecorder on globalThis BEFORE await import(), use vi.resetModules() between tests so import effects re-fire" + +requirements-completed: [] # NONE — REQ-video-ring-buffer is NOT satisfied by RED tests; Plans 03+04+07 satisfy it. + +# Metrics +duration: 4min +completed: 2026-05-15 +--- + +# Phase 1 Plan 02: Wave-0 Test Infrastructure Summary + +**Vitest 4.1.6 installed, vitest.config.ts wired for Node-environment tests, and four RED test files (ring-buffer, codec-check, handshake, port) committed against the not-yet-existing `src/offscreen/recorder.ts` — pinning the contracts Plans 03 and 04 must flip to GREEN.** + +## Performance + +- **Duration:** ~4 min +- **Started:** 2026-05-15T15:21:24Z +- **Completed:** 2026-05-15T15:25:57Z +- **Tasks:** 5 +- **Files modified:** 8 (1 modified existing + 6 created + 1 administrative revert) + +## Accomplishments + +- **Vitest 4.1.6 installed** as a devDependency; `node_modules/vitest/` materialized; `npx vitest --version` prints `vitest/4.1.6 linux-x64 node-v24.14.0`. +- **`vitest.config.ts` at repo root**: Node environment, scoped to `tests/**/*.test.ts`, typecheck disabled (separate `tsc --noEmit` runs in `npm run build`). No `globals: true`; tests explicitly `import { describe, it, expect } from 'vitest'`. +- **Four RED test files** all import from `'../../src/offscreen/recorder'` (which Plan 03 will create); `npx vitest run` reports `Test Files 4 failed (4); Tests 5 failed (5)`, every failure with `Error: Cannot find module '/src/offscreen/recorder' imported from ...`. This is the precise Nyquist TDD signal — contract pinned, implementation gap waiting to be filled. +- **`tests/fixtures/.gitkeep`** committed so the directory survives clean checkouts; Plan 07 drops a known-good `last_30sec.webm` there after the manual smoke pass. +- **Zero `as any` and zero `@ts-ignore`** across the four test files (verified by grep). The cast pattern is `as unknown as T`, which narrows progressively without bypassing the type-checker — CLAUDE.md compliant. + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Install Vitest, add npm test script** — `ebf015a` (test) +2. **Task 2: Create vitest.config.ts** — `57fa29e` (test) +3. **Task 3: Create tests/offscreen/ring-buffer.test.ts + tests/fixtures/.gitkeep** — `2e73a21` (test) +4. **Task 4: Create tests/offscreen/codec-check.test.ts** — `d7840a8` (test) +5. **Task 5: Create tests/offscreen/handshake.test.ts + tests/offscreen/port.test.ts** — `408aa33` (test) + +## Files Created/Modified + +- `vitest.config.ts` (12 lines) — defineConfig wrapper; Node env; include pattern; typecheck off. +- `tests/offscreen/ring-buffer.test.ts` (40 lines) — 4 RED tests for D-10 (header pinning) + D-11 (30 s trim). +- `tests/offscreen/codec-check.test.ts` (43 lines) — 2 RED tests for D-20 (strict-mode, no silent fallback). +- `tests/offscreen/handshake.test.ts` (67 lines) — 1 RED test for Pattern 4 (OFFSCREEN_READY emitted at module load after onMessage.addListener). +- `tests/offscreen/port.test.ts` (89 lines) — 2 RED tests for Pattern 5 / Pitfall 4 (port.connect on load + reconnect on onDisconnect). +- `tests/fixtures/.gitkeep` (0 bytes) — marker for the fixture dir. +- `package.json` — added `vitest@^4` devDep + `"test": "vitest run"` script. +- `package-lock.json` — regenerated by `npm install` (added 126 packages, 127 audited). +- `.planning/REQUIREMENTS.md` — reverted premature `[x]` + `Complete` marking on REQ-video-ring-buffer (deviation; see below). + +## Vitest RED Run Output (verbatim summary) + +``` + RUN v4.1.6 /home/parf/projects/work/repremium + + FAIL tests/offscreen/ring-buffer.test.ts [ tests/offscreen/ring-buffer.test.ts ] +Error: Cannot find module '../../src/offscreen/recorder' imported from /home/parf/projects/work/repremium/tests/offscreen/ring-buffer.test.ts + + FAIL tests/offscreen/codec-check.test.ts > codec strict mode > throws on unsupported vp9 and emits RECORDING_ERROR +Error: Cannot find module '/src/offscreen/recorder' imported from /home/parf/projects/work/repremium/tests/offscreen/codec-check.test.ts + + FAIL tests/offscreen/codec-check.test.ts > codec strict mode > does not throw when vp9 IS supported +Error: Cannot find module '/src/offscreen/recorder' imported from /home/parf/projects/work/repremium/tests/offscreen/codec-check.test.ts + + FAIL tests/offscreen/handshake.test.ts > OFFSCREEN_READY handshake > sends OFFSCREEN_READY after listener registration +Error: Cannot find module '/src/offscreen/recorder' imported from /home/parf/projects/work/repremium/tests/offscreen/handshake.test.ts + + FAIL tests/offscreen/port.test.ts > port reconnect > connects on module load +Error: Cannot find module '/src/offscreen/recorder' imported from /home/parf/projects/work/repremium/tests/offscreen/port.test.ts + + FAIL tests/offscreen/port.test.ts > port reconnect > reconnects when port disconnects +Error: Cannot find module '/src/offscreen/recorder' imported from /home/parf/projects/work/repremium/tests/offscreen/port.test.ts + + Test Files 4 failed (4) + Tests 5 failed (5) +``` + +Every failure is at the IMPORT step, not at the assertion step — that is the RED gate. Plans 03 and 04 flip these tests to GREEN by creating `src/offscreen/recorder.ts` with the contract specified in the plan's `` block. + +## Decisions Made + +- **Vitest at `^4`, not `@latest`:** Plan instructions said "pin Vitest at a major version" and the latest stable major on install day (2026-05-15) is 4.x (4.1.6); the 5.x line is still in beta. Pinning to `^4` gives deterministic resolution without locking us to a single patch. +- **No `vitest-chrome` package:** The four test files use a hand-rolled minimal chrome.runtime stub via interfaces, which is lighter than pulling a whole mock library for a four-file test setup. Aligns with threat T-1-NEW-02-01 (minimize supply chain). +- **`typecheck.enabled: false` in vitest.config.ts:** TypeScript checking via Vitest would duplicate the work `npm run build` already does via `tsc && vite build`. Faster feedback loop, single source of truth for the type errors. +- **`include: ['tests/**/*.test.ts']`:** Scoped strictly to `tests/`; production code under `src/` is never accidentally picked up as a test file even if a `*.test.ts` lands there. +- **No path aliases:** `tsconfig.json` does not define any; tests use relative imports (`'../../src/offscreen/recorder'`). Re-confirmed during review. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Reverted premature REQ-video-ring-buffer marking left over from Plan 01-01** +- **Found during:** After Task 5, before SUMMARY (administrative correction noted in this plan's prompt context) +- **Issue:** Plan 01-01 (doc cascade) prematurely marked `REQ-video-ring-buffer` as `[x]` in `REQUIREMENTS.md` line 19 AND as `Complete` in the Traceability table at line 189. Per the Plan 01-01 SUMMARY frontmatter, it also listed `requirements-completed: [REQ-video-ring-buffer]`. This is incorrect — the requirement is satisfied by the implementation in Plans 03 (recorder) + 04 (handshake + port) and the ffprobe gate in Plan 07. The doc cascade in Plan 01-01 only amended decision/constraint wording. +- **Fix:** Reverted the two REQUIREMENTS.md markings: + - line 19: `- [x] **REQ-video-ring-buffer**: ...` → `- [ ] **REQ-video-ring-buffer**: ...` + - line 189: `| REQ-video-ring-buffer | Phase 1 | Complete |` → `| REQ-video-ring-buffer | Phase 1 | In Progress |` +- **Files modified:** `.planning/REQUIREMENTS.md` +- **Verification:** `grep '^- \[x\] \*\*REQ-video-ring-buffer\*\*' .planning/REQUIREMENTS.md` returns 0; `grep 'In Progress' .planning/REQUIREMENTS.md | grep REQ-video-ring-buffer` returns 1. +- **Committed in:** SUMMARY commit (administrative revert bundled with this plan's metadata commit, not a per-task commit, because it corrects prior-plan state outside the scope of any Task 1-5 file set). + +**2. [Rule 3 - Blocking, micro] `package-lock.json` already existed despite plan wording** +- **Found during:** Task 1 (npm install) +- **Issue:** The plan's Task 1 action block said "If `npm install` produces a `package-lock.json` for the first time (it should — there is no committed lockfile today)". A `package-lock.json` was already in the working tree from a prior baseline commit (Plan 01-00 or earlier). This was not a blocker — `npm install` updated it in place (1186 line diff, refreshing transitive deps to add Vitest's tree). +- **Fix:** Committed the modified `package-lock.json` alongside `package.json` in Task 1's commit, as the plan instructed for the first-creation case. Behavior is identical. +- **Files modified:** None additional (already included in `ebf015a`). +- **Verification:** `test -f package-lock.json` returns 0; `grep '"vitest"' package-lock.json | head -1` returns the vitest entry. +- **Committed in:** `ebf015a` (Task 1 commit). + +--- + +**Total deviations:** 2 auto-fixed (1 prior-plan correction; 1 plan-wording mismatch with reality, no functional change). +**Impact on plan:** Both deviations are pure administrative cleanup; no code-path divergence from the plan. The REQUIREMENTS.md revert is critical to keep the requirements-traceability matrix honest — the in-progress REQ-video-ring-buffer status correctly reflects that the implementation lands in Plans 03/04/07. + +## Issues Encountered + +- None. The five tasks executed exactly as the plan specified. The RED gate fired as designed at every step; banned-pattern grep checks returned 0 every time; vitest config validation passed on first run. + +## User Setup Required + +None — no external service configuration required. Vitest is a pure dev-time dependency; tests run via `npm test` or `npx vitest run` on any machine that has cloned the repo and run `npm install`. + +## Next Phase Readiness + +- **Plan 01-03 (offscreen recorder TDD) is unblocked.** It must export the following surface from `src/offscreen/recorder.ts` to flip the RED tests to GREEN: + + ```typescript + // Ring-buffer (pure functions; testable in Node) + export function addChunk(blob: { size: number }, timestamp: number): void; + export function trimAged(now: number): void; + export function getBuffer(): Array<{ data: { size: number }; timestamp: number; isFirst?: boolean }>; + export function resetBuffer(): void; + + // Codec strict-mode (D-20) + export function assertCodecSupported(): void; // throws Error("vp9 unsupported") + sendMessage({ type: 'RECORDING_ERROR' }) + + // Constants + export const VIDEO_BUFFER_DURATION_MS: number; // = 30_000 + ``` + +- **Plan 01-04 (port keepalive + handshake) is also unblocked.** Its TDD contract: importing `src/offscreen/recorder.ts` MUST as a side-effect: + 1. Call `chrome.runtime.onMessage.addListener(...)` at least once. + 2. Call `chrome.runtime.sendMessage({ type: 'OFFSCREEN_READY' })` exactly once, AFTER step 1. + 3. Call `chrome.runtime.connect({ name: 'video-keepalive' })` exactly once at module load. + 4. On the connected port firing `onDisconnect`, immediately call `chrome.runtime.connect(...)` again (synchronous reconnect — Pitfall 4 mitigation). + +- **No outstanding blockers.** The doc cascade (Plan 01-01) is consistent; the test infrastructure (Plan 01-02) is wired and producing the expected RED signal; Plans 03 through 07 can execute in their declared waves. + +## Self-Check: PASSED + +All claimed files exist on disk: +- `vitest.config.ts`, `tests/offscreen/{ring-buffer,codec-check,handshake,port}.test.ts`, `tests/fixtures/.gitkeep`, `package-lock.json`, `node_modules/vitest`, `01-02-SUMMARY.md` — all FOUND. + +All five task commits present in `git log`: +- `ebf015a` (Task 1: vitest install) +- `57fa29e` (Task 2: vitest.config.ts) +- `2e73a21` (Task 3: RED ring-buffer tests + fixtures) +- `d7840a8` (Task 4: RED codec-check tests) +- `408aa33` (Task 5: RED handshake + port tests) + +All plan-level verification gates pass: +- `npx vitest --version` → `vitest/4.1.6 linux-x64 node-v24.14.0` +- `ls tests/offscreen/*.test.ts | wc -l` → 4 +- `npx vitest run 2>&1 | grep -cE "Failed to resolve|Cannot find module"` → 6 (one per test entry, 4 distinct files, all RED at module-resolution) +- `grep -cE "as any|@ts-ignore" tests/offscreen/*.test.ts` → 0 across all four files + +--- +*Phase: 01-stabilize-video-pipeline* +*Completed: 2026-05-15*