@web-auto/camo 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jason Zhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+# Camo CLI
+
+[![CI](https://github.com/Jasonzhangf/camo/actions/workflows/ci.yml/badge.svg)](https://github.com/Jasonzhangf/camo/actions/workflows/ci.yml)
+[![npm version](https://badge.fury.io/js/@web-auto%2Fcamo.svg)](https://www.npmjs.com/package/@web-auto/camo)
+
+A cross-platform command-line interface for Camoufox browser automation.
+
+## Installation
+
+### npm (Recommended)
+
+```bash
+npm install -g @web-auto/camo
+```
+
+### From Source
+
+```bash
+git clone https://github.com/Jasonzhangf/camo.git
+cd camo
+npm run build:global
+```
+
+## Quick Start
+
+```bash
+# Initialize environment
+camo init
+
+# Create a profile
+camo profile create myprofile
+
+# Set as default
+camo profile default myprofile
+
+# Start browser
+camo start --url https://example.com
+
+# Navigate
+camo goto https://www.xiaohongshu.com
+
+# Interact
+camo click "#search-input"
+camo type "#search-input" "hello world"
+camo scroll --down --amount 500
+```
+
+## Commands
+
+### Profile Management
+
+```bash
+camo profiles                          # List profiles with default profile
+camo profile create <profileId>        # Create a profile
+camo profile delete <profileId>        # Delete a profile
+camo profile default [profileId]       # Get or set default profile
+```
+
+### Initialization
+
+```bash
+camo init                              # Ensure camoufox + browser-service
+camo init geoip                        # Download GeoIP database
+camo init list                         # List available OS and regions
+camo create fingerprint --os <os> --region <region>
+```
+
+### Browser Control
+
+```bash
+camo start [profileId] [--url <url>] [--headless]
+camo stop [profileId]
+camo status [profileId]
+camo shutdown                          # Shutdown browser-service (all sessions)
+```
+
+### Lifecycle & Cleanup
+
+```bash
+camo sessions                          # List active browser sessions
+camo cleanup [profileId]               # Cleanup session (release lock + stop)
+camo cleanup all                       # Cleanup all active sessions
+camo cleanup locks                     # Cleanup stale lock files
+camo force-stop [profileId]            # Force stop session (for stuck sessions)
+camo lock list                         # List active session locks
+camo recover [profileId]               # Recover orphaned session
+```
+
+### Navigation
+
+```bash
+camo goto [profileId] <url>            # Navigate to URL
+camo back [profileId]                  # Navigate back
+camo screenshot [profileId] [--output <file>] [--full]
+```
+
+### Interaction
+
+```bash
+camo scroll [profileId] [--down|--up|--left|--right] [--amount <px>]
+camo click [profileId] <selector>              # Click element by CSS selector
+camo type [profileId] <selector> <text>        # Type text into element
+camo highlight [profileId] <selector>          # Highlight element (red border, 2s)
+camo clear-highlight [profileId]               # Clear all highlights
+camo viewport [profileId] --width <w> --height <h>
+```
+
+### Pages
+
+```bash
+camo new-page [profileId] [--url <url>]
+camo close-page [profileId] [index]
+camo switch-page [profileId] <index>
+camo list-pages [profileId]
+```
+
+### Cookies
+
+```bash
+camo cookies get [profileId]                          Get all cookies for profile
+camo cookies save [profileId] --path <file>           Save cookies to file
+camo cookies load [profileId] --path <file>           Load cookies from file
+camo cookies auto start [profileId] [--interval <ms>] Start auto-saving cookies
+camo cookies auto stop [profileId]                    Stop auto-saving
+camo cookies auto status [profileId]                  Check auto-save status
+```
+
+### Window Control
+
+```bash
+camo window move [profileId] --x <x> --y <y>
+camo window resize [profileId] --width <w> --height <h>
+```
+
+### Mouse Control
+
+```bash
+camo mouse move [profileId] --x <x> --y <y> [--steps <n>]
+camo mouse click [profileId] --x <x> --y <y> [--button left|right|middle] [--clicks <n>] [--delay <ms>]
+camo mouse wheel [profileId] [--deltax <px>] [--deltay <px>]
+```
+
+### System
+
+```bash
+camo system display                    # Show display metrics
+```
+
+## Fingerprint Options
+
+### OS Options
+
+- `mac` (default) - macOS (auto architecture)
+- `mac-m1` - macOS with Apple Silicon
+- `mac-intel` - macOS with Intel
+- `windows` - Windows 11
+- `windows-10` - Windows 10
+- `linux` - Ubuntu 22.04
+
+### Region Options
+
+- `us` (default) - United States (New York)
+- `us-west` - United States (Los Angeles)
+- `uk` - United Kingdom (London)
+- `de` - Germany (Berlin)
+- `fr` - France (Paris)
+- `jp` - Japan (Tokyo)
+- `sg` - Singapore
+- `au` - Australia (Sydney)
+- `hk` - Hong Kong
+- `tw` - Taiwan (Taipei)
+- `br` - Brazil (Sao Paulo)
+- `in` - India (Mumbai)
+
+## Configuration
+
+- Config file: `~/.webauto/camo-cli.json`
+- Profiles directory: `~/.webauto/profiles/`
+- Fingerprints directory: `~/.webauto/fingerprints/`
+- Session registry: `~/.webauto/sessions/`
+- Lock files: `~/.webauto/locks/`
+- GeoIP database: `~/.webauto/geoip/GeoLite2-City.mmdb`
+
+### Environment Variables
+
+- `WEBAUTO_BROWSER_URL` - Browser service URL (default: `http://127.0.0.1:7704`)
+- `WEBAUTO_REPO_ROOT` - WebAuto repository root (optional)
+
+## Session Persistence
+
+Camo CLI persists session information locally:
+
+- Sessions are registered in `~/.webauto/sessions/`
+- On restart, `camo sessions` shows both live and orphaned sessions
+- Use `camo recover <profileId>` to reconnect or cleanup orphaned sessions
+- Stale sessions (>7 days) are automatically cleaned up
+
+## Requirements
+
+- Node.js >= 20.0.0
+- Python 3 with `camoufox` package
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Test
+npm test
+
+# Global install (build + test + install)
+npm run build:global
+
+# Bump version
+npm run version:bump
+```
+
+## Release
+
+```bash
+# Create a release (bumps version, runs tests, creates tag)
+./scripts/release.sh
+
+# Or manually:
+npm run version:bump
+npm test
+git add package.json
+git commit -m "chore: release v$(node -p "require('./package.json').version")"
+git tag "v$(node -p "require('./package.json').version")"
+git push --follow-tags
+```
+
+GitHub Actions will automatically:
+1. Run tests on push to main
+2. Publish to npm when a release is created
+
+## License
+
+MIT

package/bin/camo.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const cliPath = path.join(__dirname, '..', 'src', 'cli.mjs');
+
+// Delegate to the modular CLI
+const child = spawn(process.execPath, [cliPath, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+child.on('error', (err) => {
+  console.error(`Failed to start camo: ${err.message}`);
+  process.exit(1);
+});
+
+child.on('exit', (code) => {
+  process.exit(code || 0);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@web-auto/camo",
+  "version": "0.1.0002",
+  "description": "Camoufox Browser CLI - Cross-platform browser automation",
+  "type": "module",
+  "bin": {
+    "camo": "./bin/camo.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node --test tests/*.test.mjs",
+    "version:bump": "node scripts/bump-version.mjs",
+    "install:global": "npm run build && npm install -g .",
+    "uninstall:global": "npm uninstall -g @web-auto/camo",
+    "build:global": "npm run build && npm test && npm install -g ."
+  },
+  "keywords": [
+    "browser",
+    "automation",
+    "camoufox",
+    "cli",
+    "playwright"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "camoufox": "^0.1.0"
+  }
+}

package/scripts/build.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { copyFileSync, chmodSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, '..');
+
+// Ensure bin directory exists
+const binDir = path.join(root, 'bin');
+try { mkdirSync(binDir, { recursive: true }); } catch {}
+
+// Copy source files to dist (if needed)
+// For now, we're running directly from src/
+
+// Make bin/camo.mjs executable
+const binFile = path.join(binDir, 'camo.mjs');
+chmodSync(binFile, 0o755);
+console.log('Build: bin/camo.mjs ready');

package/scripts/bump-version.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * Version bumper for camo CLI
+ * Increments patch version maintaining 4-digit format (0.1.0001 -> 0.1.0002)
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJsonPath = join(__dirname, '..', 'package.json');
+
+function bumpVersion() {
+  const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+  const currentVersion = pkg.version;
+  
+  // Parse version: 0.1.0001 -> [0, 1, 1]
+  const parts = currentVersion.split('.');
+  const major = parseInt(parts[0], 10);
+  const minor = parseInt(parts[1], 10);
+  let patch = parseInt(parts[2], 10);
+  
+  // Increment patch
+  patch += 1;
+  
+  // Format with 4 digits
+  const newVersion = `${major}.${minor}.${patch.toString().padStart(4, '0')}`;
+  
+  pkg.version = newVersion;
+  writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2) + '\n');
+  
+  console.log(`Version bumped: ${currentVersion} -> ${newVersion}`);
+  return newVersion;
+}
+
+bumpVersion();

package/scripts/install.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * camo CLI Global Installer
+ * Usage: node scripts/install.mjs [--prefix /usr/local]
+ */
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const isWin = os.platform() === 'win32';
+
+function detectPrefix() {
+  const prefixIdx = process.argv.indexOf('--prefix');
+  if (prefixIdx >= 0 && process.argv[prefixIdx + 1]) {
+    return process.argv[prefixIdx + 1];
+  }
+
+  const candidates = [
+    isWin ? path.join(os.homedir(), 'AppData', 'Local', 'camo') : null,
+    '/opt/homebrew',
+    '/usr/local',
+    '/usr',
+    path.join(os.homedir(), '.local'),
+  ].filter(Boolean);
+
+  for (const p of candidates) {
+    try {
+      fs.accessSync(path.dirname(p), fs.constants.W_OK);
+      return p;
+    } catch {}
+  }
+
+  return path.join(os.homedir(), '.local');
+}
+
+function install() {
+  const prefix = detectPrefix();
+  const binDir = path.join(prefix, 'bin');
+  const targetDir = path.join(prefix, 'share', 'camo');
+
+  console.log(`Installing camo CLI...`);
+  console.log(`  Prefix: ${prefix}`);
+  console.log(`  Target: ${targetDir}`);
+  console.log(`  Bin: ${binDir}`);
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  fs.mkdirSync(binDir, { recursive: true });
+
+  const thisDir = path.dirname(new URL(import.meta.url).pathname);
+  const moduleDir = path.resolve(thisDir, '..');
+  const srcFile = path.join(moduleDir, 'bin', 'camoufox.mjs');
+
+  if (!fs.existsSync(srcFile)) {
+    console.error(`Source not found: ${srcFile}`);
+    console.error('Run: cp src/cli.mjs bin/camoufox.mjs');
+    process.exit(1);
+  }
+
+  const targetFile = path.join(targetDir, 'camoufox.mjs');
+  fs.copyFileSync(srcFile, targetFile);
+  fs.chmodSync(targetFile, 0o755);
+
+  const binPath = path.join(binDir, 'camo');
+  const wrapper = `#!/usr/bin/env sh
+exec node "${targetFile}" "$@"`;
+  fs.writeFileSync(binPath, wrapper);
+  fs.chmodSync(binPath, 0o755);
+
+  console.log(`\n✅ camo CLI installed!`);
+  console.log(`\nAdd to PATH if needed:`);
+  console.log(`  export PATH="${binDir}:$PATH"`);
+  console.log(`\nUsage: camo --help`);
+}
+
+install();

package/scripts/release.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# Release script for camo CLI
+# Usage: ./scripts/release.sh [patch|minor|major]
+
+set -e
+
+RELEASE_TYPE="${1:-patch}"
+
+# Ensure we're on main branch
+CURRENT_BRANCH=$(git branch --show-current)
+if [ "$CURRENT_BRANCH" != "main" ] && [ "$CURRENT_BRANCH" != "master" ]; then
+  echo "Error: Must be on main or master branch"
+  exit 1
+fi
+
+# Ensure working tree is clean
+if [ -n "$(git status --porcelain)" ]; then
+  echo "Error: Working tree is not clean. Commit or stash changes first."
+  exit 1
+fi
+
+# Pull latest
+git pull --rebase
+
+# Bump version
+echo "Bumping version..."
+npm run version:bump
+
+# Get new version
+NEW_VERSION=$(node -p "require('./package.json').version")
+echo "New version: $NEW_VERSION"
+
+# Run tests
+echo "Running tests..."
+npm test
+
+# Build
+echo "Building..."
+npm run build
+
+# Commit version bump
+git add package.json
+git commit -m "chore: release v$NEW_VERSION"
+
+# Create tag
+git tag "v$NEW_VERSION"
+
+# Push commit and tag
+echo "Pushing to remote..."
+git push origin HEAD
+git push origin "v$NEW_VERSION"
+
+echo "Release v$NEW_VERSION created successfully!"
+echo "GitHub Actions will automatically publish to npm."