camou 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is loosely based on Keep a Changelog and uses semantic versioning.
+
+## [0.2.0] - 2026-03-15
+
+### Added
+
+- Added a public Node API so `camou` can be used from scripts, not just the CLI.
+- Added `launchCamoufox()`, `launchCamoufoxContext()`, and `withCamoufox()` for Playwright-based programmatic control.
+- Exported browser management helpers from the package root for script usage.
+
+### Changed
+
+- Documented the new Node script workflow in `README.md`.
+- Updated the `camou` skill to explain when to use the CLI vs the Node API and how to drive Camou from scripts.
+
+## [0.1.1] - 2026-03-15
+
+### Added
+
+- Added `skills/camou/` with a reusable Camou skill and workflow reference for AI assistants.
+- Added this `CHANGELOG.md` so future releases have a maintained change history.
+
+### Changed
+
+- Reworked `README.md` to be more useful for npm users, first-time visitors, and agent-style workflows.
+- Improved default non-JSON CLI output for common commands so everyday use is easier to scan.
+
+### Fixed
+
+- Fixed `camou session list` and `camou tab list` to print human-readable output instead of raw JSON when `--json` is not enabled.
+- Added a readable non-JSON summary for `camou doctor` while preserving the full structured payload under `--json`.
+- Cleaned up non-JSON output for actions like `open`, `click`, `fill`, `press`, `wait`, `session stop`, `tab new`, and `tab close`.
+
+## [0.1.0] - 2026-03-15
+
+### Added
+
+- Initial public release of the `camou` npm package.
+- Local CLI and daemon for driving Camoufox through Playwright without the Python SDK.
+- Camoufox install, remove, version switching, compatibility probes, and doctor diagnostics.
+- Persistent sessions, named tabs, snapshot refs, JSON output mode, presets, and integration tests.

package/README.md

@@ -1,202 +1,393 @@
 # Camoucli
 
-Camoucli is a Node.js-first CLI and local daemon for driving Camoufox through Playwright.
+Camoucli is a local-first CLI and background daemon for driving [Camoufox](https://github.com/daijro/camoufox) through Playwright, without depending on the Camoufox Python SDK.
 
-The published npm package is `camou`, and the installed command is `camou`.
+- npm package: `camou`
+- installed command: `camou`
+- project/repo name: Camoucli
 
-It is built for local agent-style workflows:
+Camou is built for agent-style browser workflows:
 
-- keep a browser session alive across CLI invocations
+- keep a browser session alive across separate CLI invocations
 - preserve login state with persistent profiles
-- target named tabs and sessions
-- work with stable `@eN` refs from text snapshots
-- install and switch Camoufox versions without the Python SDK
+- operate named tabs in parallel without ref collisions
+- interact through stable `@eN` refs from text snapshots
+- install, switch, and diagnose Camoufox browser versions from the CLI
 
-## Requirements
+Camou takes strong inspiration from [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) and [BUNotesAI/agent-browser-session](https://github.com/BUNotesAI/agent-browser-session), but is built for the Camoufox + Playwright Firefox path and persistent local daemon workflows.
 
-- Node.js `>=20`
-- a supported OS for Camoufox releases
+## Why Camou
+
+| Feature | Why it matters |
+| --- | --- |
+| Persistent profiles | Login once and reuse the same authenticated browser state later |
+| Named sessions | Keep separate workspaces like `work`, `shopping`, or `github` isolated |
+| Named tabs | Run multiple agents against the same browser session without fighting over one active page |
+| Snapshot refs | Use `@e1`, `@e2`, ... from `snapshot` instead of brittle selectors when driving pages |
+| Version manager | Install and switch Camoufox builds without bundling the browser into the npm package |
+| Doctor diagnostics | Check launch compatibility, bundle health, and Linux shared-library issues quickly |
 
 ## Install
 
-End users:
+Requirements:
+
+- Node.js `>=20`
+- a supported Camoufox release for your OS
+
+Global install (recommended):
 
 ```bash
 npm install -g camou
+camou install
 ```
 
-Contributors / local development:
+One-off usage with `npx`:
 
 ```bash
-npm install
-npm run build
+npx camou install
+npx camou open https://example.com
 ```
 
-For local development:
+From this repo:
 
 ```bash
+npm install
+npm run build
 npm run dev -- --help
-npm run dev:daemon
 ```
 
-## Quick Start
+Notes:
+
+- Browser download is explicit. Installing the npm package does not download Camoufox.
+- `camou install` runs a quick headless launch probe after download.
+- `camou use <version>` runs the same compatibility check when you switch versions.
+
+## Install The Skill
+
+Camou also ships an agent skill that can be installed through the open skills ecosystem at [skills.sh](https://skills.sh).
 
-Install a browser build:
+Install it from this repo:
 
 ```bash
-camou install
+npx skills add txchen/camoucli --skill camou
 ```
 
-`install` runs a quick launch probe after download so it can warn if the installed browser does not work with the current `playwright-core` version.
-`use` runs the same check when you switch versions.
+Useful variants:
+
+```bash
+# Preview available skills in the repo
+npx skills add txchen/camoucli --list
 
-Open a page and capture refs:
+# Install globally for a specific agent
+npx skills add txchen/camoucli --skill camou -g -a opencode
+```
+
+The skill teaches agents the recommended Camou workflow: `open -> snapshot -i -> interact with @refs -> re-snapshot`, plus session/tab/version troubleshooting guidance.
+
+## Quick Start
 
 ```bash
+camou install
 camou open https://example.com
 camou snapshot -i
+# @e1 a "Learn more"
+camou click @e1
+camou get title
+```
+
+What happens behind the scenes:
+
+1. `camou open` auto-starts the local daemon if needed.
+2. Camoufox launches with a persistent profile for the default session.
+3. `snapshot -i` returns interactive elements with refs like `@e1`.
+4. Later commands reuse the same browser session and profile.
+
+Important ref rule:
+
+- Re-run `snapshot` after navigation or major page changes. Refs are per tab and are invalidated on navigation or a new snapshot.
+
+## Use From Node Scripts
+
+Camou can also be used as a Node library, not just a CLI.
+
+The programmatic API is Playwright-based: it launches Camoufox for you and gives you a real Playwright `BrowserContext`, similar in spirit to the Camoufox Python wrapper.
+
+```ts
+import { launchCamoufox } from 'camou';
+
+const camou = await launchCamoufox({
+  session: 'script',
+  headless: false,
+});
+
+const page = await camou.context.newPage();
+await page.goto('https://example.com');
+console.log(await page.title());
+
+await camou.close();
 ```
 
-Use refs in later commands:
+If you prefer a scoped helper:
+
+```ts
+import { withCamoufox } from 'camou';
+
+await withCamoufox({ session: 'script' }, async ({ context }) => {
+  const page = await context.newPage();
+  await page.goto('https://example.com');
+  console.log(await page.title());
+});
+```
+
+Useful exported helpers include:
+
+- `launchCamoufox()`
+- `launchCamoufoxContext()`
+- `withCamoufox()`
+- `installCamoufox()`
+- `listInstalledBrowsers()`
+- `setCurrentBrowser()`
+- `doctorCamoufox()`
+
+Notes:
+
+- install a browser first with `camou install` or `installCamoufox()`
+- use a dedicated `session` name in scripts if you do not want to share the default CLI profile
+- the returned context is a normal Playwright context, so you can use standard Playwright APIs from there
+
+## Recommended Agent Workflow
+
+For agents and automation loops, this is the happy path:
 
 ```bash
-camou click @e1
-camou fill @e2 "hello"
-camou get title
+camou open https://target.site
+camou snapshot -i --json
+camou click @e3
+camou fill @e5 "hello"
+camou snapshot -i --json
 ```
 
-When working from this repo without a global install, prefix commands with `npm run dev --`.
+Why this works well:
 
-The daemon auto-starts on demand, so later commands reuse the same session and profile.
+- `snapshot` gives a stable text representation of the page
+- refs are deterministic within the current tab snapshot
+- `--json` gives machine-readable success and error payloads
+- the daemon keeps browser state alive between commands
 
-## What Works Today
+## Core Concepts
 
-### Browser management
+### Session
 
-- `camou install [version]`
-- `camou remove [version]`
-- `camou use <version>`
-- `camou versions`
-- `camou presets`
-- `camou version`
-- `camou path`
-- `camou doctor`
+A session is a named browser workspace selected with `--session <name>`.
 
-### Page automation
+- sessions have separate persistent profile directories
+- different sessions isolate cookies, storage, downloads, and artifacts
+- reuse the same session name to keep login state across runs
 
-- `camou open <url>`
-- `camou snapshot [-i]`
-- `camou click <selectorOrRef>`
-- `camou fill <selectorOrRef> <text>`
-- `camou press <key>`
-- `camou wait <selectorOrRef>`
-- `camou screenshot [path]`
-- `camou get url`
-- `camou get title`
-- `camou get text <selectorOrRef>`
-
-### Session and tab management
-
-- `camou session list`
-- `camou session stop [name]`
-- `camou tab list`
-- `camou tab new [url]`
-- `camou tab close [nameOrIndex]`
+Example:
 
-## Common Flags
+```bash
+camou open https://github.com --session work
+camou open https://mail.google.com --session personal
+```
 
-Most browser commands support:
+### Tab
 
-- `--session <name>`
-- `--tabname <name>`
-- `--headless`
-- `--browser <version>`
-- `--config <path>`
-- `--config-json <json>`
-- `--prefs <path>`
-- `--prefs-json <json>`
-- `--preset <name>`
-- `--proxy <url>`
-- `--locale <locale>`
-- `--timezone <timezone>`
-- `--width <px>` / `--height <px>`
-- `--json`
-- `--verbose`
+A tab is a named page binding inside a session selected with `--tabname <name>`.
 
-## Example Flows
+- tabs in the same session share browser profile state
+- tabs keep separate page bindings and separate ref maps
+- named tabs make concurrent agent workflows much safer
 
-Use a named session and tab:
+Example:
 
 ```bash
-camou open https://github.com --session work --tabname github
-camou snapshot -i --session work --tabname github
+camou open https://reddit.com --session work --tabname reddit
+camou open https://news.ycombinator.com --session work --tabname hn
 ```
 
-Install and switch versions:
+### Ref
+
+A ref is a snapshot-generated handle like `@e1` or `@e2`.
+
+- refs come from `camou snapshot` or `camou snapshot -i`
+- refs are only valid for the tab that created them
+- refs are cleared when the page navigates or you take a new snapshot
+
+### Browser version
+
+Camou keeps an active Camoufox version, but you can also pick a version per command.
+
+- `camou use <version>` changes the active default version
+- `camou <command> ... --browser <version>` runs a command against a specific installed version without changing the default
+
+## Common Workflows
+
+### Persistent login session
 
 ```bash
-camou install 135.0.1-beta.24
-camou install 134.0.0-beta.20
-camou versions
-camou use 134.0.0-beta.20
-camou version
+camou open https://github.com/login --session work --tabname github
+# log in once in the browser
+camou open https://github.com/settings/profile --session work --tabname github
+```
+
+Use the same `--session` name later and the login state is still there.
+
+### Multi-tab parallel-safe browsing
+
+```bash
+camou open https://reddit.com --session research --tabname reddit
+camou open https://news.ycombinator.com --session research --tabname hn
+
+camou snapshot -i --session research --tabname reddit
+camou snapshot -i --session research --tabname hn
 ```
 
-Check the current install inventory and launch compatibility:
+Both tabs share the same browser profile, but each tab has its own page and ref map.
+
+### Install and switch versions
 
 ```bash
+camou install 135.0.1-beta.24
+camou install 135.0.1-beta.23
+camou versions
+camou use 135.0.1-beta.24
 camou doctor --json
 ```
 
-Launch a session with an explicit installed browser version without changing the global default:
+### Use a specific browser version for one session
 
 ```bash
 camou open https://example.com --session canary --browser 135.0.1-beta.24
 ```
 
-Save a screenshot to the session artifacts directory:
+### JSON output for automation
 
 ```bash
-camou screenshot --session work --tabname github
+camou snapshot -i --json
+camou get title --json
+camou doctor --json
 ```
 
-## Storage Layout
+Errors are also structured when `--json` is enabled.
+
+## Command Reference
+
+### Browser management
+
+```bash
+camou install [version]
+camou remove [version]
+camou use <version>
+camou versions
+camou presets
+camou version
+camou path
+camou doctor
+```
+
+### Page automation
 
-Camoucli uses platform-specific app directories for its own state and profiles.
+```bash
+camou open <url>
+camou snapshot [-i]
+camou click <selectorOrRef>
+camou fill <selectorOrRef> <text>
+camou press <key>
+camou wait <selectorOrRef>
+camou screenshot [path]
+camou get url
+camou get title
+camou get text <selectorOrRef>
+```
 
-- session profiles live under `profiles/<session>/{user-data,downloads,artifacts}`
-- daemon state and logs live under the platform state/runtime dirs
+### Sessions and tabs
 
-Camoufox binaries are stored in the shared cache layout used by the Python library when possible:
+```bash
+camou session list
+camou session stop [name]
+camou tab list
+camou tab new [url]
+camou tab close [nameOrIndex]
+```
 
-- Linux: `~/.cache/camoufox/browsers/official/<version>/`
-- macOS: `~/Library/Caches/camoufox/browsers/official/<version>/`
-- Windows: `%LOCALAPPDATA%\camoufox\Cache\browsers\official\<version>\`
+## Common Flags
+
+Most browser commands support:
 
-This lets Camoucli reuse compatible Camoufox installs from the Python ecosystem and vice versa.
+- `--session <name>`
+- `--tabname <name>`
+- `--headless`
+- `--browser <version>`
+- `--config <path>`
+- `--config-json <json>`
+- `--prefs <path>`
+- `--prefs-json <json>`
+- `--preset <name>`
+- `--proxy <url>`
+- `--locale <locale>`
+- `--timezone <timezone>`
+- `--width <px>`
+- `--height <px>`
+- `--json`
+- `--verbose`
 
 ## Presets
 
-Built-in presets give you a small layer of tested ergonomics on top of raw config and prefs JSON:
+Built-in presets give you a small layer of tested ergonomics on top of raw config and prefs JSON.
 
-- `default` - baseline launch with no additional overrides
-- `cache` - enables the Firefox cache/session prefs used by the Python library
-- `low-bandwidth` - blocks images and speculative requests for lighter automation sessions
-- `disable-coop` - relaxes Cross-Origin-Opener-Policy isolation for troublesome embedded flows
+| Preset | What it does |
+| --- | --- |
+| `default` | Baseline launch with no extra overrides |
+| `cache` | Enables the Firefox cache/session prefs used by the Python library |
+| `low-bandwidth` | Blocks images and speculative requests for lighter automation sessions |
+| `disable-coop` | Relaxes Cross-Origin-Opener-Policy isolation for troublesome embedded flows |
 
-List them from the CLI:
+List them:
 
 ```bash
 camou presets
 ```
 
-Apply one or more presets to a browser command:
+Apply one or more:
 
 ```bash
 camou open https://example.com --preset cache --preset low-bandwidth
 ```
 
-## Compatibility Matrix
+## Doctor And Troubleshooting
+
+`camou doctor --json` reports:
+
+- installed Camoufox versions
+- which version is active
+- whether each version can launch with the current `playwright-core`
+- bundle file checks
+- Linux shared-library diagnostics
+- remediation hints
+
+Useful commands:
+
+```bash
+camou versions
+camou use 135.0.1-beta.24
+camou doctor --json
+```
+
+Common fixes:
+
+- `Browser.setContrast is not supported`
+  - the selected Camoufox build is older than the bundled Playwright runtime
+  - switch to a newer browser version with `camou use <version>`
+- profile/session locked
+  - another browser process is using that session profile
+  - stop the other browser or use a different `--session`
+- executable missing or damaged
+  - reinstall with `camou install --force`
+- Linux launch failures
+  - run `camou doctor --json` and install the missing shared libraries it reports
+
+## Current Compatibility
 
 Current local verification with `playwright-core` `1.51.1`:
 
@@ -205,14 +396,18 @@ Current local verification with `playwright-core` `1.51.1`:
 | `135.0.1-beta.24` | launches | smoke-tested successfully |
 | `135.0.1-beta.23` | incompatible | `Browser.setContrast` is not supported |
 
-## Notes
+## Storage Layout
+
+Camou keeps its own runtime state and profiles, but stores browser binaries in the shared Camoufox cache layout when possible.
+
+- session data lives under `profiles/<session>/{user-data,downloads,artifacts}`
+- daemon state and logs live under platform runtime/state directories
+- Camoufox binaries live in the shared cache used by the Python library:
+  - Linux: `~/.cache/camoufox/browsers/official/<version>/`
+  - macOS: `~/Library/Caches/camoufox/browsers/official/<version>/`
+  - Windows: `%LOCALAPPDATA%\camoufox\Cache\browsers\official\<version>\`
 
-- The CLI is intentionally thin; the daemon owns browser lifecycle and persistent state.
-- `snapshot` creates per-tab `@eN` refs, and refs are cleared after navigation or a new snapshot.
-- Browser installation is explicit; the package does not download Camoufox during `npm install`.
-- `install` and `use` include a quick compatibility hint based on a real headless launch probe of the selected version.
-- `doctor` reports installed versions, a per-version launch compatibility matrix, shared-library diagnostics, and remediation hints.
-- Passing `--json` returns structured machine-readable errors for both top-level CLI failures and daemon responses.
+This lets Camou reuse compatible Camoufox installs from the Python ecosystem and vice versa.
 
 ## Development
 
@@ -227,3 +422,17 @@ Optional targeted integration suite:
 ```bash
 npm run test:integration
 ```
+
+Local development commands:
+
+```bash
+npm run dev -- --help
+npm run dev:daemon
+```
+
+## Acknowledgements
+
+Camoucli learned a lot from these projects:
+
+- [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) for the agent-oriented command workflow and skill ecosystem patterns
+- [BUNotesAI/agent-browser-session](https://github.com/BUNotesAI/agent-browser-session) for persistent-session and named-tab ergonomics

package/dist/api.d.ts

@@ -0,0 +1,34 @@
+import type { BrowserContext, Page } from 'playwright-core';
+import type { LaunchInput, ResolvedLaunchConfig } from './camoufox/config.js';
+import { type CamoucliPaths } from './state/paths.js';
+export interface LaunchCamoufoxOptions extends LaunchInput {
+    session?: string | undefined;
+    paths?: CamoucliPaths | undefined;
+    verbose?: boolean | undefined;
+}
+export declare class CamoufoxSession {
+    readonly context: BrowserContext;
+    readonly sessionName: string;
+    readonly browserVersion: string;
+    readonly executablePath: string;
+    readonly profileDir: string;
+    readonly downloadsDir: string;
+    readonly artifactsDir: string;
+    readonly resolvedConfig: ResolvedLaunchConfig;
+    constructor(input: {
+        context: BrowserContext;
+        sessionName: string;
+        browserVersion: string;
+        executablePath: string;
+        profileDir: string;
+        downloadsDir: string;
+        artifactsDir: string;
+        resolvedConfig: ResolvedLaunchConfig;
+    });
+    newPage(): Promise<Page>;
+    pages(): Page[];
+    close(): Promise<void>;
+}
+export declare function launchCamoufox(options?: LaunchCamoufoxOptions): Promise<CamoufoxSession>;
+export declare function launchCamoufoxContext(options?: LaunchCamoufoxOptions): Promise<BrowserContext>;
+export declare function withCamoufox<T>(options: LaunchCamoufoxOptions, callback: (session: CamoufoxSession) => Promise<T> | T): Promise<T>;