@phi-code-admin/camofox-browser 1.0.0 → 1.0.2

package/plugins/persistence/AGENTS.md

@@ -1,37 +1,37 @@
-# Persistence Plugin — Agent Guide
-
-Saves and restores per-user browser storage state (cookies + localStorage) across session restarts using Playwright's `storageState` API. Enabled by default — profiles persist to `~/.camofox/profiles/`.
-
-## How It Works
-
-- `session:creating` hook → loads saved `storage_state.json` into `contextOptions.storageState`
-- `session:created` hook → imports bootstrap cookies if no persisted state exists
-- `session:cookies:import` / `session:destroyed` / `server:shutdown` → checkpoints state to disk
-
-All hooks are async and awaited via `emitAsync()` — storage state is guaranteed loaded before the context is created.
-
-## Key Files
-
-- `index.js` — lifecycle hooks (no routes, no `child_process`)
-- `persistence.test.js` — unit tests for `lib/persistence.js` helpers
-- `plugin.test.js` — integration tests for plugin lifecycle hooks
-
-## Storage Layout
-
-```
-~/.camofox/profiles/
-└── <sha256(userId)>/
-    └── storage_state.json
-```
-
-## Configuration
-
-Enabled by default. Override profile directory with `CAMOFOX_PROFILE_DIR` env var or `"profileDir"` in plugin config. To disable: `"persistence": { "enabled": false }` in `camofox.config.json`.
-
-## Original Contributors
-
-- [@company8](https://github.com/company8) — original persistence concept ([PR #62](https://github.com/jo-inc/camofox-browser/pull/62))
-- [@eddieoz](https://github.com/eddieoz) — cookie auto-load on startup ([PR #55](https://github.com/jo-inc/camofox-browser/pull/55))
-- [@pradeepe](https://github.com/pradeepe) — plugin system integration, atomic writes, inflight coalescing
-
-For PRs touching this plugin, tag the contributors above for review.
+# Persistence Plugin — Agent Guide
+
+Saves and restores per-user browser storage state (cookies + localStorage) across session restarts using Playwright's `storageState` API. Enabled by default — profiles persist to `~/.camofox/profiles/`.
+
+## How It Works
+
+- `session:creating` hook → loads saved `storage_state.json` into `contextOptions.storageState`
+- `session:created` hook → imports bootstrap cookies if no persisted state exists
+- `session:cookies:import` / `session:destroyed` / `server:shutdown` → checkpoints state to disk
+
+All hooks are async and awaited via `emitAsync()` — storage state is guaranteed loaded before the context is created.
+
+## Key Files
+
+- `index.js` — lifecycle hooks (no routes, no `child_process`)
+- `persistence.test.js` — unit tests for `lib/persistence.js` helpers
+- `plugin.test.js` — integration tests for plugin lifecycle hooks
+
+## Storage Layout
+
+```
+~/.camofox/profiles/
+└── <sha256(userId)>/
+    └── storage_state.json
+```
+
+## Configuration
+
+Enabled by default. Override profile directory with `CAMOFOX_PROFILE_DIR` env var or `"profileDir"` in plugin config. To disable: `"persistence": { "enabled": false }` in `camofox.config.json`.
+
+## Original Contributors
+
+- [@company8](https://github.com/company8) — original persistence concept ([PR #62](https://github.com/jo-inc/camofox-browser/pull/62))
+- [@eddieoz](https://github.com/eddieoz) — cookie auto-load on startup ([PR #55](https://github.com/jo-inc/camofox-browser/pull/55))
+- [@pradeepe](https://github.com/pradeepe) — plugin system integration, atomic writes, inflight coalescing
+
+For PRs touching this plugin, tag the contributors above for review.

package/plugins/persistence/README.md

@@ -1,48 +1,48 @@
-# persistence
-
-Optional per-user browser storage state persistence for camofox-browser.
-
-Saves and restores cookies + localStorage across session restarts, container deploys, and idle timeouts using Playwright's `storageState` API.
-
-## Configuration
-
-In `camofox.config.json`:
-
-```json
-{
-  "plugins": {
-    "persistence": {
-      "enabled": true,
-      "profileDir": "/data/profiles"
-    }
-  }
-}
-```
-
-Or override via environment variable:
-
-```
-CAMOFOX_PROFILE_DIR=/data/profiles
-```
-
-## How it works
-
-- **Session create**: If a persisted `storageState` exists for the `userId`, it's restored into the new Playwright context.
-- **First run**: If no persisted state exists, bootstrap cookies from `CAMOFOX_COOKIES_DIR/cookies.txt` are imported (if present).
-- **Cookie import / session close / shutdown**: Storage state is checkpointed to disk via atomic tmp-write + rename.
-- **User isolation**: Each `userId` maps to a deterministic SHA256-hashed subdirectory under `profileDir`, so arbitrary userIds are path-safe.
-
-## Docker
-
-When running with Docker, mount the profile directory as a volume:
-
-```bash
-docker run -d \
-  -p 9377:9377 \
-  -v /host/profiles:/data/profiles \
-  camofox-browser
-```
-
-## Credits
-
-Based on PR #62 by [company8](https://github.com/company8).
+# persistence
+
+Optional per-user browser storage state persistence for camofox-browser.
+
+Saves and restores cookies + localStorage across session restarts, container deploys, and idle timeouts using Playwright's `storageState` API.
+
+## Configuration
+
+In `camofox.config.json`:
+
+```json
+{
+  "plugins": {
+    "persistence": {
+      "enabled": true,
+      "profileDir": "/data/profiles"
+    }
+  }
+}
+```
+
+Or override via environment variable:
+
+```
+CAMOFOX_PROFILE_DIR=/data/profiles
+```
+
+## How it works
+
+- **Session create**: If a persisted `storageState` exists for the `userId`, it's restored into the new Playwright context.
+- **First run**: If no persisted state exists, bootstrap cookies from `CAMOFOX_COOKIES_DIR/cookies.txt` are imported (if present).
+- **Cookie import / session close / shutdown**: Storage state is checkpointed to disk via atomic tmp-write + rename.
+- **User isolation**: Each `userId` maps to a deterministic SHA256-hashed subdirectory under `profileDir`, so arbitrary userIds are path-safe.
+
+## Docker
+
+When running with Docker, mount the profile directory as a volume:
+
+```bash
+docker run -d \
+  -p 9377:9377 \
+  -v /host/profiles:/data/profiles \
+  camofox-browser
+```
+
+## Credits
+
+Based on PR #62 by [company8](https://github.com/company8).

package/plugins/persistence/index.js

@@ -1,124 +1,124 @@
-/**
- * Persistence plugin for camofox-browser.
- *
- * Saves and restores per-user browser storage state (cookies + localStorage)
- * across session restarts using Playwright's storageState API.
- *
- * Configuration (camofox.config.json):
- *   {
- *     "plugins": {
- *       "persistence": {
- *         "enabled": true,
- *         "profileDir": "/data/profiles"
- *       }
- *     }
- *   }
- *
- * Or via environment variables (overrides config file):
- *   CAMOFOX_PROFILE_DIR=/data/profiles
- *
- * Each userId gets a deterministic SHA256-hashed subdirectory under profileDir.
- * Storage state is checkpointed on cookie import, session close, and shutdown.
- * On session creation, saved state is restored into the new Playwright context
- * via the session:creating hook (mutates contextOptions.storageState).
- */
-
-import {
-  getUserPersistencePaths,
-  loadPersistedStorageState,
-  persistStorageState,
-} from '../../lib/persistence.js';
-import { importBootstrapCookies } from '../../lib/cookies.js';
-
-export async function register(app, ctx, pluginConfig = {}) {
-  const { events, config, log } = ctx;
-
-  // Resolve profileDir: env var > plugin config > global config default (~/.camofox/profiles)
-  const profileDir = process.env.CAMOFOX_PROFILE_DIR || pluginConfig.profileDir || config.profileDir;
-  if (!profileDir) {
-    log('warn', 'persistence plugin: no profileDir configured, plugin disabled');
-    return;
-  }
-
-  const logger = {
-    warn: (msg, fields = {}) => log('warn', msg, fields),
-  };
-
-  log('info', 'persistence plugin enabled', { profileDir });
-
-  // Track active sessions for checkpoint on close
-  const activeSessions = new Map(); // userId -> context
-
-  /**
-   * Checkpoint storage state to disk for a userId.
-   */
-  async function checkpoint(userId, context, reason) {
-    if (!context) return;
-    const result = await persistStorageState({ profileDir, userId, context, logger });
-    if (result.persisted) {
-      log('info', 'storage state persisted', { userId, reason, path: result.storageStatePath });
-    }
-    return result;
-  }
-
-  // --- Lifecycle hooks ---
-
-  // Before session context is created: inject storageState if we have one saved
-  events.on('session:creating', async ({ userId, contextOptions }) => {
-    const storageStatePath = await loadPersistedStorageState(profileDir, userId, logger);
-    if (storageStatePath) {
-      contextOptions.storageState = storageStatePath;
-      log('info', 'restoring persisted storage state', { userId, storageStatePath });
-    }
-  });
-
-  // After session is created: import bootstrap cookies if no persisted state,
-  // and track the context for later checkpointing
-  events.on('session:created', async ({ userId, context }) => {
-    activeSessions.set(userId, context);
-
-    // If no persisted state was restored, try bootstrap cookies
-    const existingState = await loadPersistedStorageState(profileDir, userId, logger);
-    if (!existingState) {
-      const result = await importBootstrapCookies({
-        cookiesDir: config.cookiesDir,
-        context,
-        logger,
-      });
-      if (result.imported > 0) {
-        log('info', 'bootstrap cookies imported', { userId, count: result.imported, source: result.source });
-        await checkpoint(userId, context, 'bootstrap_cookies');
-      }
-    }
-  });
-
-  // On cookie import: checkpoint
-  events.on('session:cookies:import', async ({ userId }) => {
-    const context = activeSessions.get(userId);
-    if (context) {
-      await checkpoint(userId, context, 'cookie_import');
-    }
-  });
-
-  // On session destroying (pre-close): checkpoint while context is still alive
-  events.on('session:destroying', async ({ userId, reason }) => {
-    const context = activeSessions.get(userId);
-    if (context) {
-      await checkpoint(userId, context, reason).catch(() => {});
-      activeSessions.delete(userId);
-    }
-  });
-
-  // On session destroyed (post-close): cleanup tracking if not already done
-  events.on('session:destroyed', async ({ userId }) => {
-    activeSessions.delete(userId);
-  });
-
-  // On shutdown: checkpoint all remaining sessions
-  events.on('server:shutdown', async () => {
-    for (const [userId, context] of activeSessions) {
-      await checkpoint(userId, context, 'shutdown').catch(() => {});
-    }
-    activeSessions.clear();
-  });
-}
+/**
+ * Persistence plugin for camofox-browser.
+ *
+ * Saves and restores per-user browser storage state (cookies + localStorage)
+ * across session restarts using Playwright's storageState API.
+ *
+ * Configuration (camofox.config.json):
+ *   {
+ *     "plugins": {
+ *       "persistence": {
+ *         "enabled": true,
+ *         "profileDir": "/data/profiles"
+ *       }
+ *     }
+ *   }
+ *
+ * Or via environment variables (overrides config file):
+ *   CAMOFOX_PROFILE_DIR=/data/profiles
+ *
+ * Each userId gets a deterministic SHA256-hashed subdirectory under profileDir.
+ * Storage state is checkpointed on cookie import, session close, and shutdown.
+ * On session creation, saved state is restored into the new Playwright context
+ * via the session:creating hook (mutates contextOptions.storageState).
+ */
+
+import {
+  getUserPersistencePaths,
+  loadPersistedStorageState,
+  persistStorageState,
+} from '../../lib/persistence.js';
+import { importBootstrapCookies } from '../../lib/cookies.js';
+
+export async function register(app, ctx, pluginConfig = {}) {
+  const { events, config, log } = ctx;
+
+  // Resolve profileDir: env var > plugin config > global config default (~/.camofox/profiles)
+  const profileDir = process.env.CAMOFOX_PROFILE_DIR || pluginConfig.profileDir || config.profileDir;
+  if (!profileDir) {
+    log('warn', 'persistence plugin: no profileDir configured, plugin disabled');
+    return;
+  }
+
+  const logger = {
+    warn: (msg, fields = {}) => log('warn', msg, fields),
+  };
+
+  log('info', 'persistence plugin enabled', { profileDir });
+
+  // Track active sessions for checkpoint on close
+  const activeSessions = new Map(); // userId -> context
+
+  /**
+   * Checkpoint storage state to disk for a userId.
+   */
+  async function checkpoint(userId, context, reason) {
+    if (!context) return;
+    const result = await persistStorageState({ profileDir, userId, context, logger });
+    if (result.persisted) {
+      log('info', 'storage state persisted', { userId, reason, path: result.storageStatePath });
+    }
+    return result;
+  }
+
+  // --- Lifecycle hooks ---
+
+  // Before session context is created: inject storageState if we have one saved
+  events.on('session:creating', async ({ userId, contextOptions }) => {
+    const storageStatePath = await loadPersistedStorageState(profileDir, userId, logger);
+    if (storageStatePath) {
+      contextOptions.storageState = storageStatePath;
+      log('info', 'restoring persisted storage state', { userId, storageStatePath });
+    }
+  });
+
+  // After session is created: import bootstrap cookies if no persisted state,
+  // and track the context for later checkpointing
+  events.on('session:created', async ({ userId, context }) => {
+    activeSessions.set(userId, context);
+
+    // If no persisted state was restored, try bootstrap cookies
+    const existingState = await loadPersistedStorageState(profileDir, userId, logger);
+    if (!existingState) {
+      const result = await importBootstrapCookies({
+        cookiesDir: config.cookiesDir,
+        context,
+        logger,
+      });
+      if (result.imported > 0) {
+        log('info', 'bootstrap cookies imported', { userId, count: result.imported, source: result.source });
+        await checkpoint(userId, context, 'bootstrap_cookies');
+      }
+    }
+  });
+
+  // On cookie import: checkpoint
+  events.on('session:cookies:import', async ({ userId }) => {
+    const context = activeSessions.get(userId);
+    if (context) {
+      await checkpoint(userId, context, 'cookie_import');
+    }
+  });
+
+  // On session destroying (pre-close): checkpoint while context is still alive
+  events.on('session:destroying', async ({ userId, reason }) => {
+    const context = activeSessions.get(userId);
+    if (context) {
+      await checkpoint(userId, context, reason).catch(() => {});
+      activeSessions.delete(userId);
+    }
+  });
+
+  // On session destroyed (post-close): cleanup tracking if not already done
+  events.on('session:destroyed', async ({ userId }) => {
+    activeSessions.delete(userId);
+  });
+
+  // On shutdown: checkpoint all remaining sessions
+  events.on('server:shutdown', async () => {
+    for (const [userId, context] of activeSessions) {
+      await checkpoint(userId, context, 'shutdown').catch(() => {});
+    }
+    activeSessions.clear();
+  });
+}

package/plugins/vnc/AGENTS.md

@@ -1,42 +1,42 @@
-# VNC Plugin — Agent Guide
-
-Interactive browser access via noVNC. Log into sites visually, solve CAPTCHAs, approve OAuth prompts — then export the authenticated storage state for agent reuse.
-
-## Endpoints
-
-- `GET /vnc/status` — check if VNC is running (no auth)
-- `GET /sessions/:userId/storage_state` — export cookies + localStorage as JSON (requires auth)
-
-## Activation
-
-Disabled by default. Enable with `ENABLE_VNC=1` env var or `"vnc": { "enabled": true }` in `camofox.config.json`.
-
-## Key Files
-
-- `index.js` — route handlers only (no `child_process`, no `process.env` reads)
-- `vnc-launcher.js` — process management, config resolution from env vars (`child_process` isolated here)
-- `vnc-watcher.sh` — shell script that detects Xvfb, attaches x11vnc, starts noVNC
-- `vnc.test.js` — unit tests
-- `apt.txt` — system deps (x11vnc, novnc, websockify, etc.)
-
-## Code Separation
-
-`child_process` is in `vnc-launcher.js`, route handlers are in `index.js`, env var reads are in `vnc-launcher.js` — separate files per project conventions.
-
-## Security
-
-- noVNC binds to `127.0.0.1` by default — set `VNC_BIND=0.0.0.0` to expose externally
-- Set `VNC_PASSWORD` for password-protected access
-- `VIEW_ONLY=1` disables keyboard/mouse input (observation only)
-- Storage state export endpoint requires auth (API key or loopback)
-
-## Architecture
-
-The plugin overrides `ctx.createVirtualDisplay` to use a higher-resolution display (default 1920x1080 instead of 1x1). `vnc-watcher.sh` polls for the Xvfb process, then attaches x11vnc + noVNC on top.
-
-## Original Contributors
-
-- [@leoneparise](https://github.com/leoneparise) — original VNC implementation + keyboard mode ([PR #65](https://github.com/jo-inc/camofox-browser/pull/65), [PR #66](https://github.com/jo-inc/camofox-browser/pull/66))
-- [@pradeepe](https://github.com/pradeepe) — plugin system integration, code separation refactor, security hardening
-
-For PRs touching this plugin, tag the contributors above for review.
+# VNC Plugin — Agent Guide
+
+Interactive browser access via noVNC. Log into sites visually, solve CAPTCHAs, approve OAuth prompts — then export the authenticated storage state for agent reuse.
+
+## Endpoints
+
+- `GET /vnc/status` — check if VNC is running (no auth)
+- `GET /sessions/:userId/storage_state` — export cookies + localStorage as JSON (requires auth)
+
+## Activation
+
+Disabled by default. Enable with `ENABLE_VNC=1` env var or `"vnc": { "enabled": true }` in `camofox.config.json`.
+
+## Key Files
+
+- `index.js` — route handlers only (no `child_process`, no `process.env` reads)
+- `vnc-launcher.js` — process management, config resolution from env vars (`child_process` isolated here)
+- `vnc-watcher.sh` — shell script that detects Xvfb, attaches x11vnc, starts noVNC
+- `vnc.test.js` — unit tests
+- `apt.txt` — system deps (x11vnc, novnc, websockify, etc.)
+
+## Code Separation
+
+`child_process` is in `vnc-launcher.js`, route handlers are in `index.js`, env var reads are in `vnc-launcher.js` — separate files per project conventions.
+
+## Security
+
+- noVNC binds to `127.0.0.1` by default — set `VNC_BIND=0.0.0.0` to expose externally
+- Set `VNC_PASSWORD` for password-protected access
+- `VIEW_ONLY=1` disables keyboard/mouse input (observation only)
+- Storage state export endpoint requires auth (API key or loopback)
+
+## Architecture
+
+The plugin overrides `ctx.createVirtualDisplay` to use a higher-resolution display (default 1920x1080 instead of 1x1). `vnc-watcher.sh` polls for the Xvfb process, then attaches x11vnc + noVNC on top.
+
+## Original Contributors
+
+- [@leoneparise](https://github.com/leoneparise) — original VNC implementation + keyboard mode ([PR #65](https://github.com/jo-inc/camofox-browser/pull/65), [PR #66](https://github.com/jo-inc/camofox-browser/pull/66))
+- [@pradeepe](https://github.com/pradeepe) — plugin system integration, code separation refactor, security hardening
+
+For PRs touching this plugin, tag the contributors above for review.