stef-openclaw-skills/docs/plans/2026-03-11-web-automation-cloakbrowser.md

Web Automation CloakBrowser Migration Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Replace Camoufox and direct Chromium launches in web-automation with CloakBrowser and publish the updated repo/docs.

Architecture: Use a single CloakBrowser-backed launch path in skills/web-automation/scripts/browse.ts, migrate extract.js to the same backend, update dependent scripts and tests, then update docs and publish the repo changes.

Tech Stack: Node.js, TypeScript, JavaScript, Playwright-compatible browser automation, CloakBrowser, git

---

Task 1: Create isolated worktree

Files:

• Modify: repo git metadata only

Step 1: Create worktree

Run:

git -C /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills worktree add /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/web-automation-cloakbrowser -b feature/web-automation-cloakbrowser

Step 2: Verify baseline

Run:

git -C /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/web-automation-cloakbrowser status --short --branch

Expected: clean feature branch

Task 2: Migrate the browser launcher

Files:

• Modify: skills/web-automation/scripts/browse.ts
• Modify: skills/web-automation/scripts/package.json
• Modify: skills/web-automation/scripts/pnpm-lock.yaml
• Optional Modify: test helper scripts under skills/web-automation/scripts/

Step 1: Write the failing verification

Run:

cd /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/web-automation-cloakbrowser/skills/web-automation/scripts && node -e "require.resolve('cloakbrowser/package.json')"

Expected: fail before dependency migration

Step 2: Replace backend dependency

• remove camoufox-js
• add cloakbrowser
• update browse.ts to launch CloakBrowser contexts
• preserve persistent profile support

Step 3: Verify launcher wiring

Run a direct browse smoke test after install/update.

Task 3: Migrate dependent scripts

Files:

• Modify: skills/web-automation/scripts/extract.js
• Modify: skills/web-automation/scripts/auth.ts
• Modify: skills/web-automation/scripts/flow.ts
• Modify: skills/web-automation/scripts/scrape.ts
• Modify: skills/web-automation/scripts/test-minimal.ts
• Modify: skills/web-automation/scripts/test-full.ts
• Modify: skills/web-automation/scripts/test-profile.ts

Step 1: Keep interfaces stable

• preserve CLI usage where possible
• use CloakBrowser through shared launcher code
• keep one-shot extraction JSON output unchanged except for backend wording if needed

Step 2: Add compatibility aliases

• support old CAMOUFOX_* env vars where practical
• document new canonical naming

Task 4: Verify behavior

Files:

• Test: skills/web-automation/scripts/*

Step 1: Extractor error checks

Run:

cd /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/web-automation-cloakbrowser && node skills/web-automation/scripts/extract.js

Expected: JSON error for missing URL

Run:

cd /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/web-automation-cloakbrowser && node skills/web-automation/scripts/extract.js ftp://example.com

Expected: JSON error for invalid scheme

Step 2: Extractor smoke test

Run:

cd /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/web-automation-cloakbrowser && node skills/web-automation/scripts/extract.js https://example.com

Expected: JSON result with title Example Domain and status 200

Step 3: Stateful path verification

• run one direct browse.ts, scrape.ts, or flow.ts command using the CloakBrowser backend
• confirm persistent-context code still initializes successfully

Task 5: Update docs and publish

Files:

• Modify: skills/web-automation/SKILL.md
• Modify: docs/web-automation.md
• Modify: README.md
• Modify: docs/README.md

Step 1: Update docs

• replace Camoufox wording with CloakBrowser wording
• replace old setup/install steps
• document any compatibility env vars and new canonical names

Step 2: Commit and push

Run:

git add skills/web-automation docs README.md
git commit -m "refactor: migrate web-automation to cloakbrowser"
git push -u origin feature/web-automation-cloakbrowser

Step 3: Merge and cleanup

• fast-forward or merge to main
• push main
• remove the worktree
• delete the feature branch