suaveplan/openspec/changes/swap-testing-e2e-cloakbrowser/tasks.md

swap-testing-e2e-cloakbrowser — tasks

• 1. Add cloakbrowser: ^0.3.28 as a direct dep in packages/testing/testing-e2e/package.json (skip the root testing catalog for now to avoid entanglement with concurrent root-package.json work).
• 2. Add ./cloakserve and ./presets to the package exports map; update description.
• 3. Add CLOAK_* error codes:
  • Append LAUNCH_FAILED, BINARY_MISSING, PROXY_INVALID to src/errors/codes.ts registry under domain CLOAK.
  • Add CloakLaunchError class to src/errors/testing-e2e-error.ts.
  • Add classifyCloakError(err) + wrapCloakError(err, context?) helpers.
  • Co-located .md + tests covering all three codes + the classifier + the wrapper remediation hints.
• 4. Refactor src/extension-fixture/launch-with-extension.ts:
  • Drop chromium: BrowserType parameter.
  • Accept optional launchPersistentContext injector (default: cloakbrowser's, resolved via dynamic import with cache + _resetDefaultLauncherCache test hook).
  • Forward launchOptions (proxy / humanize / geoip / …) untouched.
  • Wrap launcher errors with wrapCloakError.
  • Update tests + .md; update launch-with-extension.types.ts.
• 5. Override browser worker fixture inside src/fixtures/extended-test.ts:
  • Add cloak: CloakOptions worker option (Playwright option: true) with { headless: true } default.
  • Extract launchBrowserWithCloak(opts, injectedLaunch?) as a unit-testable helper backed by cloakbrowser.launch.
  • Override browser fixture to call the helper; apiContext depends on Playwright's built-in playwright fixture (not browser) so API-only tests never start Chromium.
  • Wrap errors with wrapCloakError.
  • Update tests (source-level pins + runtime classifier tests) + .md.
• 6. Add src/cloakserve/:
  • cloakserve-options.types.ts with CloakServeFingerprint + CloakServeConnectOptions.
  • build-cloakserve-url.ts — pure URL builder with camelCase → kebab-case mapping.
  • cloakserve-connect.ts — connectCloakServe(options, chromium?) wrapping chromium.connectOverCDP; lazy @playwright/test import + _resetCloakServeChromiumCache hook; errors wrapped in CloakLaunchError.
  • index.ts barrel with explicit named exports (rule 10).
  • .md per impl file + tests covering URL building, default base URL, kebab-case mapping, boolean stringification, error classification, lazy import caching.
• 7. Add src/presets/:
  • STEALTH_DEFAULT_CLOAK, STEALTH_HEADED_CLOAK frozen presets.
  • stealthMax(proxy) + stealthMaxHeadless(proxy) factory presets matching the upstream "Recommended config for anti-bot sites" block.
  • .md + tests.
• 8. Extend tests/no-disallowed.test.ts with patterns flagging waitForTimeout and wait_for_timeout calls in src/.
• 9. Add docker/ bundle:
  • Dockerfile.cloakserve extending cloakhq/cloakbrowser, installing the Kasada / Akamai font set, defaulting to cloakserve, healthcheck on /json/version.
  • Dockerfile.manager extending cloakhq/cloakbrowser-manager, /data volume, healthcheck on /api/status.
  • docker-compose.yml — both services bound to 127.0.0.1; manager behind the manager compose profile; cloakprofiles named volume.
  • .env.example for CLOAKBROWSER_TAG, MANAGER_TAG, MANAGER_AUTH_TOKEN.
  • docker/README.md operator playbook.
• 10. Update src/index.ts barrel: re-export new cloakserve symbols, presets, and CLOAK error helpers.
• 11. Update vite externals + vite.config.ts entries for the new subpath modules.
• 12. Rewrite README.md — stealth swap summary, binary download note, humanize/proxy/geoip features, worked examples (extendedTest, cloakserve, presets, Docker, extension fixture).
• 13. Add tests/dep-graph.test.ts assertion that cloakbrowser is a direct dep.
• 14. Pre-publish gate: bunx turbo lint typecheck test --filter=@suaveplan/testing-e2e green; bunx turbo test:coverage --filter=@suaveplan/testing-e2e at 100% on all metrics; bun run docs:check 100%.
• 15. On ship (post-merge): fold delta into openspec/specs/testing-e2e/spec.md; archive change folder under openspec/archive/<date>-swap-testing-e2e-cloakbrowser/.

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.