137 lines
4.5 KiB
Markdown
137 lines
4.5 KiB
Markdown
# 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
|