# WEB-AUTOMATION

## Purpose

Automate rendered browsing, scraping, authentication, and multi-step browser flows with Playwright-compatible CloakBrowser.

## What Ships In Every Variant

- `browse.ts` for direct navigation and screenshots
- `auth.ts` for form and Microsoft SSO login flows
- `scrape.ts` for markdown extraction
- `flow.ts` for natural-language or JSON browser steps
- `extract.js` for one-shot rendered JSON extraction
- `check-install.js` for install and wiring validation
- `scan-local-app.ts` for configurable local-app smoke scans

## Requirements

- Node.js 20+
- pnpm
- `cloakbrowser`
- `playwright-core`
- Network access to download the CloakBrowser binary on first use

## Install

### Codex

```bash
mkdir -p ~/.codex/skills/web-automation
cp -R skills/web-automation/codex/* ~/.codex/skills/web-automation/
cd ~/.codex/skills/web-automation/scripts
pnpm install
npx cloakbrowser install
pnpm approve-builds
pnpm rebuild better-sqlite3 esbuild
```

### Claude Code

```bash
mkdir -p ~/.claude/skills/web-automation
cp -R skills/web-automation/claude-code/* ~/.claude/skills/web-automation/
cd ~/.claude/skills/web-automation/scripts
pnpm install
npx cloakbrowser install
pnpm approve-builds
pnpm rebuild better-sqlite3 esbuild
```

### OpenCode

```bash
mkdir -p ~/.config/opencode/skills/web-automation
cp -R skills/web-automation/opencode/* ~/.config/opencode/skills/web-automation/
cd ~/.config/opencode/skills/web-automation/scripts
pnpm install
npx cloakbrowser install
pnpm approve-builds
pnpm rebuild better-sqlite3 esbuild
```

## Update To The Latest CloakBrowser

Run inside the installed `scripts/` directory for the variant you are using:

```bash
pnpm up cloakbrowser playwright-core
npx cloakbrowser install
pnpm approve-builds
pnpm rebuild better-sqlite3 esbuild
```

This repo intentionally treats `cloakbrowser` as a refreshable dependency: update to the latest available compatible release, then regenerate the lockfile from that resolved set.

## Verify Installation & Wiring

Run in the installed `scripts/` folder:

```bash
node check-install.js
```

Expected checks:

- `cloakbrowser` and `playwright-core` resolve correctly
- `browse.ts` is wired to CloakBrowser
- the frozen reference repo + commit recorded in `reference-source.json` are visible to the operator

If the check fails, stop and return:

"Missing dependency/config: web-automation requires `cloakbrowser` and `playwright-core` with CloakBrowser-based scripts. Run setup in this skill, then retry."

If runtime later fails with native-binding issues, run:

```bash
pnpm approve-builds
pnpm rebuild better-sqlite3 esbuild
```

## Environment Variables

- `CLOAKBROWSER_PROFILE_PATH`
- `CLOAKBROWSER_HEADLESS`
- `CLOAKBROWSER_USERNAME`
- `CLOAKBROWSER_PASSWORD`

There are no `CAMOUFOX_*` compatibility aliases in this migration.

## Usage Examples

- Browse: `npx tsx browse.ts --url "https://example.com"`
- Scrape markdown: `npx tsx scrape.ts --url "https://example.com" --mode main --output page.md`
- Authenticate: `npx tsx auth.ts --url "https://example.com/login"`
- Natural-language flow: `npx tsx flow.ts --instruction 'go to https://example.com then click on "Login"'`
- JSON extract: `node extract.js "https://example.com"`
- Local smoke scan: `SCAN_BASE_URL=http://localhost:3000 SCAN_ROUTES=/,/dashboard npx tsx scan-local-app.ts`

## Local App Smoke Scan

`scan-local-app.ts` is generic. Configure it with:

- `SCAN_BASE_URL`
- `SCAN_LOGIN_PATH`
- `SCAN_USERNAME`
- `SCAN_PASSWORD`
- `SCAN_USERNAME_SELECTOR`
- `SCAN_PASSWORD_SELECTOR`
- `SCAN_SUBMIT_SELECTOR`
- `SCAN_ROUTES`
- `SCAN_REPORT_PATH`
- `SCAN_HEADLESS`

If `SCAN_USERNAME` or `SCAN_PASSWORD` are omitted, the script falls back to `CLOAKBROWSER_USERNAME` and `CLOAKBROWSER_PASSWORD`.