docs: add cloakbrowser migration plan
This commit is contained in:
Stefano Fiorini
136
docs/plans/2026-03-11-web-automation-cloakbrowser.md
Normal file
136
docs/plans/2026-03-11-web-automation-cloakbrowser.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# 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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user