Skip to content

Commit 514de92

Browse files
tsemachhjunie-agent
tsemachh
and
junie-agent
committed
fix(recorder): restore v0.1 flow — fetch body in loadingFinished, flush pending on stop
Co-authored-by: Junie <junie@jetbrains.com>
1 parent c71c110 commit 514de92

13 files changed

Lines changed: 1094 additions & 39 deletions

‎.junie/mcp.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"mcpServers": {
3+
"isdlc": {
4+
"command": "npx",
5+
"args": ["-y", "@isdlc/mcp"],
6+
"env": {
7+
"ISDLC_NO_UPDATE_CHECK": "1"
8+
}
9+
}
10+
}
11+
}

‎.junie/plans/apireplay-production-readiness.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
sessionId: session-260426-084638-op2m
3+
isActive: false
4+
---
5+
6+
# Requirements
7+
8+
### Overview & Goals
9+
Make APIReplay production-ready while improving key user flows (presets, search, replay controls) without breaking existing behavior.
10+
11+
### Current Status
12+
- ✅ Toolchain/bootstrap completed (Vite + CRX + TypeScript + lint/typecheck/build).
13+
- ✅ Background modularization completed (`main.ts`, `recorder.ts`, `replayer.ts`, `messaging.ts`, `state-store.ts`, `logger.ts`).
14+
- 🔄 Next focus is storage schema migration + popup refactor + UX features + tests + CI/docs.
15+
16+
### In Scope
17+
- Migrate storage to namespaced/versioned UUID-keyed recordings.
18+
- Refactor popup monolith into typed components/services.
19+
- Add user-flow improvements: presets, search, per-request enable/disable, latency, replay summary, shortcut.
20+
- Add automated tests and CI/release pipeline.
21+
- Finalize docs and Chrome Web Store readiness artifacts.
22+
23+
### Out of Scope
24+
- Backend/cloud sync.
25+
- Cross-browser ports (Firefox/Edge).
26+
27+
# Technical Design
28+
29+
### Current Implementation (verified)
30+
- `src/manifest.json` now points to `src/background/main.ts` as MV3 module service worker.
31+
- Background logic split across `src/background/{main,recorder,replayer,messaging,state-store,logger}.ts`.
32+
- Reload loop regression in recording flow was fixed by changing `onTabReload` in `src/background/recorder.ts` to observer-only logging.
33+
- Popup remains mostly monolithic in `src/popup/main.ts` and still needs decomposition.
34+
- Storage still uses legacy per-recording-name keys in several flows and needs schema migration.
35+
36+
### Key Decisions
37+
1. Keep MV3 stateless-worker pattern via `StateStore` hydration/patch APIs.
38+
2. Introduce versioned `Recording` contract and migration layer before adding UX features.
39+
3. Implement popup feature slices as components/services (not more monolithic growth).
40+
4. Add tests in parallel with each feature slice (unit-first, plus one extension E2E smoke).
41+
42+
### Proposed Changes
43+
- Add `src/shared/{recording,schema,messages}.ts` for typed contracts and validation.
44+
- Implement one-shot migration to `recordings: Record<uuid, Recording>` with `schemaVersion`.
45+
- Split popup into:
46+
- `components/{Toolbar,RecordingsList,ApiPreview,ResponseEditor,PresetsModal,ReplayStatsPanel}`
47+
- `services/{storage,import-export}`
48+
- UX features:
49+
- Preset CRUD (`settings.presets`) + preset selector
50+
- Request search/filter in recording view
51+
- Per-request enabled flag for replay
52+
- Replay latency options (`latencyMs` / `latencyRange`)
53+
- Replay stats (matched/unmatched/hit count)
54+
- `commands.toggle-recording` keyboard shortcut
55+
- CI/docs/release:
56+
- GitHub Actions CI + release workflows
57+
- changelog, contributing, security/privacy docs, store listing assets
58+
59+
# Testing
60+
61+
### Validation Approach
62+
- Continue running `npm run lint`, `npm run typecheck`, `npm run build` on every slice.
63+
- Add Vitest tests for migration, schema validation, replay matching/controls, presets.
64+
- Add one Playwright smoke test loading built extension from `dist/`.
65+
66+
### Key Scenarios
67+
- Record/replay core flow remains functional after migration.
68+
- Malformed import rejected with no storage mutation.
69+
- Disabled request entries fall through to network.
70+
- Latency options delay mocked responses as configured.
71+
- Replay stats update while replaying.
72+
- Shortcut toggles recording state reliably.
73+
74+
# Delivery Steps
75+
76+
### ✓ Step 1: Complete storage schema migration and shared contracts
77+
Recordings are stored in a versioned UUID-keyed schema with compatibility for legacy data.
78+
- Add typed shared contracts (`Recording`, `RecordedRequest`, `ReplayOptions`, message types) under `src/shared/`.
79+
- Implement migration from legacy per-name keys to `recordings` map with `schemaVersion`.
80+
- Ensure migration is idempotent and wired early in extension startup paths.
81+
- Add schema validation for imports before persisting migrated/new recordings.
82+
83+
### ✓ Step 2: Refactor popup into components and storage services
84+
Popup logic is split into maintainable components/services without changing baseline behavior.
85+
- Extract UI slices from `src/popup/main.ts` into dedicated components.
86+
- Introduce `services/storage.ts` and `services/import-export.ts` for data operations.
87+
- Rewire popup state/update flow to use typed contracts and migrated storage model.
88+
- Keep existing user-visible record/replay/edit flows intact during refactor.
89+
90+
### ✓ Step 3: Implement user-flow improvements (presets, search, replay controls)
91+
Users gain faster, safer replay workflows with presets and granular control.
92+
- Add preset CRUD (`settings.presets`) and last-used preset selection in toolbar.
93+
- Add request search/filter by URL/method/status in recording details.
94+
- Add per-request enable/disable and quick status-edit controls used by replayer.
95+
- Add optional replay latency configuration and session replay stats panel.
96+
- Add manifest command + background handler for keyboard recording toggle.
97+
98+
### ✓ Step 4: Add automated tests for migrated model and replay behavior
99+
Critical flows are covered by unit tests and one extension smoke E2E.
100+
- Add Vitest tests for migration, schema validation, router dispatch, replay matching/fallback, presets.
101+
- Add tests for per-request disable and latency behavior.
102+
- Add Playwright smoke test that loads extension, records one request, and verifies persisted recording.
103+
- Ensure tests are runnable via npm scripts and stable in CI environment.
104+
105+
### ✓ Step 5: Ship CI/CD and release-readiness documentation
106+
Repository is ready for repeatable production builds and Chrome Web Store submission.
107+
- Add GitHub Actions CI pipeline (lint/typecheck/test/build + `dist.zip` artifact).
108+
- Add release workflow for tag-based packaged extension publication.
109+
- Finalize project docs (`CHANGELOG`, `CONTRIBUTING`, `SECURITY`, `PRIVACY`, updated `README`).
110+
- Add `docs/store/` assets/copy and permission rationale checklist.

‎.junie/plans/github-issues-roadmap-plan.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
sessionId: session-260426-151958-1u9u
3+
isActive: false
4+
---
5+
6+
# Requirements
7+
8+
### Overview & Goals
9+
Prepare and publish **v1.0.1** from the current `main` baseline, ensuring version metadata, release notes, and packaged extension artifacts reflect the latest implemented popup and replay changes.
10+
11+
### Scope
12+
#### In Scope
13+
- Release-only updates required for `1.0.1`.
14+
- Align version identifiers across release-facing files.
15+
- Update changelog with user-visible additions/fixes since `1.0.0`.
16+
- Build and package the extension from latest `main` state.
17+
18+
#### Out of Scope
19+
- New feature development beyond already merged `main` changes.
20+
- Architecture or schema redesign for future roadmap issues.
21+
22+
### Functional Requirements
23+
- Extension version is updated from `1.0.0` to `1.0.1` consistently.
24+
- Changelog contains a new `1.0.1` section summarizing latest shipped behavior.
25+
- Release artifact (`dist.zip`) is regenerated from the updated code/version.
26+
- Release validation confirms the packaged extension loads and popup workflows remain operational.
27+
28+
# Technical Design
29+
30+
### Current Implementation (reviewed)
31+
- Release version is declared in:
32+
- `package.json` (`version`)
33+
- `src/manifest.json` (`version` for Chrome extension)
34+
- User-facing release notes live in:
35+
- `CHANGELOG.md` (currently has `1.0.0` entry only)
36+
- Build/package workflow is already defined in scripts:
37+
- `npm run build`
38+
- `npm run package` (build + create `dist.zip`)
39+
- Core runtime behavior that must remain stable in this release includes popup/background flow:
40+
- `src/popup/main.ts`, `src/popup.html`, `src/styles.css`
41+
- `src/background/index.ts` replay interception path
42+
43+
### Key Decisions
44+
1. **Patch release strategy (`1.0.1`) without functional scope expansion** (recommended)
45+
- Rationale: user asked to release latest `main`; this is a stabilization + packaging release.
46+
2. **Single-source version consistency check before packaging**
47+
- Rationale: prevent mismatched `package.json` vs `manifest.json` values.
48+
3. **Document only already-merged changes in changelog**
49+
- Rationale: keep release notes accurate and auditable.
50+
51+
### Proposed Changes
52+
- **Version alignment**
53+
- Update `package.json` to `1.0.1`.
54+
- Update `src/manifest.json` to `1.0.1`.
55+
- Ensure `package-lock.json` root version reflects the same release when lockfile is updated.
56+
- **Release notes**
57+
- Add `## [1.0.1] - YYYY-MM-DD` section in `CHANGELOG.md`.
58+
- Summarize latest shipped updates from `main` (tab usability refinements, in-progress request preview visibility, replay/popup stability improvements as applicable to merged code).
59+
- **Packaging**
60+
- Generate fresh production bundle via `npm run package` to recreate `dist/` and `dist.zip` for v1.0.1.
61+
62+
### Risks
63+
- **Risk:** version mismatch between extension manifest and npm metadata.
64+
- **Mitigation:** explicit pre-package version cross-check in both files.
65+
- **Risk:** changelog may omit/overstate merged changes.
66+
- **Mitigation:** derive notes strictly from current `main` diff since `1.0.0`.
67+
68+
# Testing
69+
70+
### Validation Approach
71+
Validate release readiness through build/package checks and targeted smoke verification of key extension flows.
72+
73+
### Key Scenarios
74+
- `npm run build` succeeds with no compile errors.
75+
- `npm run package` generates updated `dist.zip`.
76+
- Installed packaged extension reports `1.0.1` in Chrome extension details.
77+
- Popup opens and core actions (record/replay/select/preview) still work on smoke test.
78+
79+
### Regression Focus
80+
- No runtime regression in `replayingListener` interception behavior.
81+
- No regression in popup tab rendering and request preview containers.
82+
- Artifact integrity and version labeling are consistent across all release outputs.
83+
84+
# Delivery Steps
85+
86+
### ✓ Step 1: Align v1.0.1 version metadata across release files
87+
Release metadata is consistently set to `1.0.1`.
88+
- Update `package.json` version.
89+
- Update `src/manifest.json` extension version.
90+
- Reconcile lockfile root version entry if regenerated.
91+
- Verify no remaining `1.0.0` release-version references in version-controlled metadata.
92+
93+
### ✓ Step 2: Draft and apply v1.0.1 changelog entry from latest main changes
94+
`CHANGELOG.md` contains a precise `1.0.1` section describing shipped updates.
95+
- Add a dated `1.0.1` heading above `1.0.0`.
96+
- Summarize user-facing changes already merged into `main`.
97+
- Keep wording concise and release-oriented (features/fixes/stability).
98+
99+
### ✓ Step 3: Build, package, and smoke-validate the 1.0.1 release artifact
100+
A distributable v1.0.1 extension package is generated and sanity-checked.
101+
- Run `npm run package` to rebuild `dist/` and regenerate `dist.zip`.
102+
- Confirm packaged manifest reports `1.0.1`.
103+
- Perform smoke checks for popup open, recording/replay controls, and request preview rendering.

‎.junie/plans/improve-developer-adoption-docs.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
sessionId: session-260426-221758-1o83
3+
isActive: false
4+
---
5+
6+
# Requirements
7+
8+
### Overview & Goals
9+
Improve APIReplay’s developer adoption by turning the current docs set into a practical onboarding path focused on **real client-fetch mocking workflows** and stronger **zero-boilerplate DX messaging**.
10+
11+
### Scope
12+
#### In Scope
13+
- Restructure `README.md` into a clearer “install → first run → core workflows” path.
14+
- Add/expand documentation for **client-side fetch mocking** (not SSR recording) using existing Playwright integration utilities.
15+
- Add a concrete “record from central environment, replay locally” flow with minimal setup steps.
16+
- Refresh messaging consistency between `README.md`, `COMPARISON.md`, and docs pages.
17+
18+
#### Out of Scope
19+
- Implementing new recorder/replayer runtime features.
20+
- Adding SSR recording claims.
21+
- Building Payload CMS integration unless explicitly prioritized later.
22+
23+
### Functional Requirements
24+
- README must include:
25+
- concise value proposition,
26+
- setup commands from `package.json` scripts,
27+
- quick start for extension usage,
28+
- a practical workflow entry point to Playwright/client fetch mocking docs.
29+
- Documentation must explicitly clarify current capability boundary: client/network request mocking flows are supported; SSR recording is not positioned as a current feature.
30+
- A real-world flow must show:
31+
- recording against a shared/central env,
32+
- exporting fixture JSON,
33+
- replaying locally or in test runs without central-env dependency.
34+
- DX messaging must emphasize reduced infrastructure/tooling overhead and no context switching.
35+
36+
### Non-Functional Requirements
37+
- Keep docs accurate to existing code paths and scripts.
38+
- Keep language concise and developer-oriented (copy/paste commands, concrete examples).
39+
40+
# Technical Design
41+
42+
### Current Implementation
43+
- `README.md` already covers architecture and basic development commands, plus a short Playwright snippet.
44+
- `docs/playwright-integration.md` documents exported recording reuse via `tests/helpers/recording-mock.ts` and its options (`fallbackMatching`, `strictUnmatched`, `debug`).
45+
- `tests/helpers/recording-mock.ts` is the canonical implementation for client fetch replay in tests:
46+
- `applyRecordingMocks(context, recordingPath, options)`
47+
- exact/fallback matching indexes
48+
- unmatched behavior and strict failure mode.
49+
- Background extension behavior is centered in `src/background/main.ts` (record/replay lifecycle via messages and command toggle), which should be reflected in user-facing flow descriptions.
50+
51+
### Key Decisions
52+
1. **Client-fetch-first positioning (recommended by code reality):** Documentation will avoid SSR-recording claims and instead anchor on existing request replay behavior.
53+
2. **Workflow-first docs structure:** README becomes a navigator to specific guides (especially Playwright/client-fetch flow) instead of trying to embed all details inline.
54+
3. **No new feature promises:** Messaging updates will map strictly to shipped capabilities visible in `README.md`, `docs/playwright-integration.md`, and helper APIs.
55+
56+
### Proposed Changes
57+
- Rework `README.md` sections to:
58+
- lead with explicit product identity (Chrome extension for recording/replaying API traffic),
59+
- add “Quick start in ~5 minutes,”
60+
- add “Common workflows” linking to detailed docs.
61+
- Expand `docs/playwright-integration.md` with a stronger end-to-end narrative for client fetch mocking and clearer option trade-offs.
62+
- Add a dedicated workflow doc (e.g., `docs/workflows/central-record-local-replay.md`) describing:
63+
- central env recording,
64+
- fixture curation/versioning,
65+
- local replay/test execution using `applyRecordingMocks`.
66+
- Update `COMPARISON.md` phrasing where needed so market messaging does not conflict with product reality.
67+
68+
### File Structure
69+
- **Modify** `README.md`
70+
- **Modify** `docs/playwright-integration.md`
71+
- **Add** `docs/workflows/central-record-local-replay.md` (or similarly named path under `docs/`)
72+
- **Optionally modify** `COMPARISON.md` for claim alignment
73+
74+
### Risks
75+
- **Risk:** Over-marketing beyond implemented capabilities.
76+
- **Mitigation:** Tie each claim to existing scripts/APIs/files.
77+
- **Risk:** Confusion between extension replay and Playwright helper replay.
78+
- **Mitigation:** Add explicit “when to use which flow” subsection and cross-links.
79+
80+
# Testing
81+
82+
### Validation Approach
83+
- Verify all commands and paths in docs map to real project artifacts (`package.json` scripts, existing helper files, fixture paths).
84+
- Ensure examples remain consistent with `tests/helpers/recording-mock.ts` signatures and option names.
85+
86+
### Key Scenarios
87+
- New developer can follow README to install, build, and load unpacked extension.
88+
- Developer can follow docs to export a recording and replay it in Playwright client-fetch tests.
89+
- Developer can understand the central-record/local-replay workflow without inferring unsupported SSR behavior.
90+
91+
### Edge Cases
92+
- Broken links between README and docs pages.
93+
- Stale file path references (e.g., fixture/helper paths).
94+
- Ambiguous wording that implies new runtime features not present in code.
95+
96+
# Delivery Steps
97+
98+
### ✓ Step 1: Restructure README into a workflow-driven onboarding guide
99+
README provides a clear first-run path and entry points to practical workflows.
100+
101+
- Reorganize `README.md` around: value proposition, quick start commands, extension usage basics, and links to deeper guides.
102+
- Ensure commands and lifecycle steps align with `package.json` scripts and Chrome extension load flow.
103+
- Add a capability boundary note clarifying that the documented integration path is client fetch mocking, not SSR recording.
104+
105+
### ✓ Step 2: Strengthen Playwright/client-fetch documentation with concrete usage patterns
106+
Playwright integration docs clearly describe how to replay recorded responses for client fetch flows.
107+
108+
- Update `docs/playwright-integration.md` to better explain exact vs fallback matching and strict unmatched behavior.
109+
- Align examples with `tests/helpers/recording-mock.ts` API (`applyRecordingMocks`, options, dispose lifecycle).
110+
- Add clearer troubleshooting/debug guidance using the existing `debug` callback behavior.
111+
112+
### ✓ Step 3: Add a real-world central-record → local-replay workflow guide
113+
A new docs page demonstrates recording in a shared environment and replaying locally with minimal boilerplate.
114+
115+
- Create `docs/workflows/central-record-local-replay.md` (path/name can follow existing docs conventions).
116+
- Document step-by-step flow: capture traffic, export JSON, commit fixture, run local replay in tests/dev loops.
117+
- Include best-practice notes on fixture scope/versioning and reducing dependency on central environments.
118+
119+
### ✓ Step 4: Align market-facing comparison messaging with actual capability scope
120+
Comparison copy stays compelling while remaining technically accurate.
121+
122+
- Review `COMPARISON.md` claims against current product behavior and docs wording.
123+
- Adjust phrasing where necessary to avoid implying unsupported SSR recording.
124+
- Keep DX emphasis on no context switching, low infra overhead, and reproducible local flows.

0 commit comments

Comments
 (0)