browser-cookie-bridge 1.1.0 → 1.3.0

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "browser-cookie-bridge",
-  "version": "1.1.0",
-  "description": "Private local cookie and session transfer for macOS",
+  "version": "1.3.0",
+  "description": "Local-first cookie and session transfer for macOS with optional Browserless upload",
   "type": "module",
   "bin": {
     "browser-cookie-bridge": "./bin/brave-codex-cookie-sync.js"
   },
   "scripts": {
     "test": "node --test test/*.test.js",
-    "check": "node --check bin/brave-codex-cookie-sync.js && node --check src/app-installer.js && node --check src/broker.js && node --check src/chromium-reader.js && node --check src/cli.js && node --check src/codex-direct-import.js && node --check src/config.js && node --check src/paths.js && node --check src/scheduler.js && node --check src/updater.js && node --check scripts/build-dmg.js && node --check extension-template/background.js && node --check web/server.js && node --check web/script.js",
+    "check": "node --check bin/brave-codex-cookie-sync.js && node --check src/app-installer.js && node --check src/browserless.js && node --check src/browserless-preflight.js && node --check src/browserless-runner.js && node --check src/broker.js && node --check src/chromium-reader.js && node --check src/cli.js && node --check src/codex-direct-import.js && node --check src/config.js && node --check src/paths.js && node --check src/scheduler.js && node --check src/updater.js && node --check scripts/build-dmg.js && node --check extension-template/background.js && node --check web/server.js && node --check web/script.js",
     "release:check": "node scripts/check-release-version.js",
     "build:app": "node bin/brave-codex-cookie-sync.js install-app --no-open",
     "build:dmg": "node scripts/build-dmg.js",
@@ -16,7 +16,7 @@
     "web:deploy": "wrangler deploy --config web/wrangler.jsonc"
   },
   "engines": {
-    "node": ">=22.5"
+    "node": ">=24"
   },
   "license": "MIT",
   "repository": {
@@ -38,6 +38,7 @@
     "macos",
     "chromium",
     "brave",
+    "browserless",
     "codex"
   ],
   "funding": "https://ko-fi.com/apoorvdarshan",
@@ -50,6 +51,10 @@
     "macos-app/Resources",
     "macos-app/Sources",
     "README.md",
-    "LICENSE"
-  ]
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "dependencies": {
+    "@browserless.io/cli": "0.3.0"
+  }
 }

package/src/browserless-preflight.js

@@ -0,0 +1,113 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const BROWSERLESS_SERVER_ARTIFACT_CAP_BYTES = 2 * 1024 * 1024;
+
+const MEBIBYTE = 1024 * 1024;
+const GIBIBYTE = 1024 * MEBIBYTE;
+
+export function inspectBrowserlessProfile({ profilePath } = {}) {
+  if (!profilePath || !fs.existsSync(profilePath)) {
+    throw new Error("The local browser profile could not be inspected.");
+  }
+
+  const profileBytes = directorySize(profilePath);
+  const indexedDBBytes = directorySize(path.join(profilePath, "IndexedDB"));
+  const localStorageBytes = directorySize(path.join(profilePath, "Local Storage"));
+  const freeBytes = availableBytes(profilePath);
+  const severity = sizeSeverity(indexedDBBytes);
+  const temporarySpaceWarning = Number.isFinite(freeBytes) && freeBytes < profileBytes + 256 * MEBIBYTE;
+
+  return {
+    profilePath,
+    profileBytes,
+    indexedDBBytes,
+    localStorageBytes,
+    freeBytes,
+    severity,
+    temporarySpaceWarning,
+    serverArtifactCapBytes: BROWSERLESS_SERVER_ARTIFACT_CAP_BYTES,
+    summary: profileSummary({
+      profileBytes,
+      indexedDBBytes,
+      localStorageBytes,
+      freeBytes,
+      severity,
+      temporarySpaceWarning,
+    }),
+  };
+}
+
+export function sizeSeverity(indexedDBBytes) {
+  if (indexedDBBytes >= GIBIBYTE) return "extreme";
+  if (indexedDBBytes >= 500 * MEBIBYTE) return "high";
+  if (indexedDBBytes >= 100 * MEBIBYTE) return "elevated";
+  return "normal";
+}
+
+export function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) return "unknown";
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let value = bytes;
+  let unit = -1;
+  do {
+    value /= 1024;
+    unit += 1;
+  } while (value >= 1024 && unit < units.length - 1);
+  const digits = value >= 100 ? 0 : value >= 10 ? 1 : 2;
+  return `${value.toFixed(digits)} ${units[unit]}`;
+}
+
+function directorySize(root) {
+  try {
+    if (fs.lstatSync(root).isSymbolicLink()) return 0;
+  } catch {
+    return 0;
+  }
+  let total = 0;
+  const pending = [root];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const candidate = path.join(current, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        pending.push(candidate);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      try {
+        total += fs.statSync(candidate).size;
+      } catch {}
+    }
+  }
+  return total;
+}
+
+function availableBytes(candidate) {
+  try {
+    const statistics = fs.statfsSync(candidate);
+    return Number(statistics.bavail) * Number(statistics.bsize);
+  } catch {
+    return Number.NaN;
+  }
+}
+
+function profileSummary({ profileBytes, indexedDBBytes, localStorageBytes, freeBytes, severity, temporarySpaceWarning }) {
+  const parts = [
+    `${formatBytes(profileBytes)} profile`,
+    `${formatBytes(indexedDBBytes)} IndexedDB`,
+    `${formatBytes(localStorageBytes)} local storage`,
+  ];
+  if (Number.isFinite(freeBytes)) parts.push(`${formatBytes(freeBytes)} free`);
+  if (temporarySpaceWarning) parts.push("low temporary disk space");
+  else if (severity !== "normal") parts.push(`${severity} IndexedDB load`);
+  return parts.join(" · ");
+}

package/src/browserless-runner.js

@@ -0,0 +1,13 @@
+import { pathToFileURL } from "node:url";
+
+const [, , cliPath, ...argumentsWithoutToken] = process.argv;
+const token = process.env.BROWSERLESS_TOKEN?.trim();
+if (!cliPath) throw new Error("Browserless CLI path is missing.");
+if (!token) throw new Error("Browserless API token is missing.");
+
+// Read the Keychain-supplied token once, then remove it before the official CLI
+// launches a temporary browser. Mutating process.argv does not alter the OS
+// command line that started this process, so the token is not exposed by `ps`.
+delete process.env.BROWSERLESS_TOKEN;
+process.argv = [process.execPath, cliPath, ...argumentsWithoutToken, "--token", token];
+await import(pathToFileURL(cliPath).href);

package/src/browserless.js

@@ -0,0 +1,281 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { projectRoot } from "./paths.js";
+
+const SUPPORTED_SOURCES = new Set(["brave", "chrome", "edge", "arc", "vivaldi", "opera"]);
+const REGIONS = new Set(["sfo", "lon", "ams"]);
+
+export async function uploadBrowserlessProfile({
+  browser,
+  localProfile,
+  profileName,
+  region = "sfo",
+  onlyDomains = [],
+  token = process.env.BROWSERLESS_TOKEN,
+  root = projectRoot(),
+  runner = runBrowserlessCLI,
+  signal,
+  timeoutMs = 15 * 60 * 1000,
+  onProgress = () => {},
+} = {}) {
+  if (!SUPPORTED_SOURCES.has(browser)) {
+    throw new Error(`${browser === "comet" ? "Comet" : browser} is not supported by Browserless profile capture yet.`);
+  }
+  if (!localProfile) throw new Error("The local browser profile could not be determined.");
+  if (!profileName?.trim()) throw new Error("Choose a Browserless cloud profile name.");
+  if (!REGIONS.has(region)) throw new Error("Browserless region must be sfo, lon, or ams.");
+  if (!token?.trim()) throw new Error("Connect Browserless first. The API token is missing from macOS Keychain.");
+
+  const cliPath = path.join(root, "node_modules", "@browserless.io", "cli", "build", "cli.js");
+  const runnerPath = path.join(root, "src", "browserless-runner.js");
+  const environment = {
+    ...process.env,
+    BROWSERLESS_TOKEN: token.trim(),
+    BROWSERLESS_ACCEPT_TERMS: "1",
+    BROWSERLESS_TELEMETRY_DISABLED: "1",
+    BROWSERLESS_DISABLE_KEYCHAIN: "1",
+    DO_NOT_TRACK: "1",
+  };
+  const client = ["--region", region, "--json"];
+  onProgress({ phase: "validating", fraction: 0.10, detail: "Checking the destination profile…" });
+  const shown = await runner(
+    cliPath,
+    ["profile", "show", profileName.trim(), ...client],
+    environment,
+    runnerPath,
+    { signal, timeoutMs: Math.min(timeoutMs, 60_000) },
+  );
+  throwForInterruptedRun(shown, timeoutMs);
+  const operation = shown.status === 0 ? "refresh" : isMissingProfile(shown.output) ? "upload" : null;
+  if (!operation) throw new Error(lastLine(shown.output) || "Browserless could not validate the cloud profile.");
+
+  const capture = [
+    "profile", operation,
+    "--browser", browser,
+    "--profile", localProfile,
+    "--name", profileName.trim(),
+    ...client,
+    "--accept-terms",
+    "--auto-fit",
+  ];
+  for (const domain of onlyDomains) capture.push("--only-domain", domain);
+  const parseProgress = progressParser(onProgress);
+  const result = await runner(cliPath, capture, environment, runnerPath, {
+    signal,
+    timeoutMs,
+    onOutput: parseProgress,
+  });
+  parseProgress("\n");
+  throwForInterruptedRun(result, timeoutMs);
+  if (result.status !== 0) throw new Error(actionableFailure(result.output));
+
+  onProgress({ phase: "verifying", fraction: 0.97, detail: "Verifying the cloud profile…" });
+  const verified = await runner(
+    cliPath,
+    ["profile", "show", profileName.trim(), ...client],
+    environment,
+    runnerPath,
+    { signal, timeoutMs: Math.min(timeoutMs, 60_000) },
+  );
+  throwForInterruptedRun(verified, timeoutMs);
+  if (verified.status !== 0) {
+    throw new Error(`The upload finished, but Browserless could not verify the cloud profile: ${lastLine(verified.output) || "profile lookup failed"}`);
+  }
+
+  const details = parseJSON(result.output);
+  const cookies = details?.cookieCount;
+  const origins = details?.originCount;
+  const counts = Number.isInteger(cookies) && Number.isInteger(origins)
+    ? ` (${cookies} cookies, ${origins} origins)`
+    : "";
+  return {
+    operation,
+    verified: true,
+    profileName: details?.name || profileName.trim(),
+    cookieCount: cookies,
+    originCount: origins,
+    droppedOriginCount: droppedOrigins(result.output),
+    failedOriginCount: failedOrigins(result.output),
+    summary: uploadSummary({ operation, details, fallbackName: profileName.trim(), counts, output: result.output }),
+  };
+}
+
+export function runBrowserlessCLI(cliPath, args, environment, runnerPath, {
+  signal,
+  timeoutMs = 15 * 60 * 1000,
+  onOutput = () => {},
+} = {}) {
+  return new Promise((resolve, reject) => {
+    const temporaryRoot = fs.mkdtempSync(path.join(os.tmpdir(), "browser-cookie-bridge-browserless-"));
+    fs.chmodSync(temporaryRoot, 0o700);
+    const child = spawn(process.execPath, [runnerPath, cliPath, ...args], {
+      env: { ...environment, TMPDIR: temporaryRoot },
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: process.platform !== "win32",
+    });
+    let stdout = "";
+    let stderr = "";
+    let interruption = null;
+    let settled = false;
+    const append = (target, chunk) => {
+      const text = String(chunk);
+      if (target === "stdout") stdout += text;
+      else stderr += text;
+      onOutput(text);
+    };
+    const terminate = (reason) => {
+      if (settled || interruption) return;
+      interruption = reason;
+      try {
+        if (process.platform !== "win32" && child.pid) process.kill(-child.pid, "SIGTERM");
+        else child.kill("SIGTERM");
+      } catch {}
+      setTimeout(() => {
+        if (child.exitCode !== null || child.signalCode !== null) return;
+        try {
+          if (process.platform !== "win32" && child.pid) process.kill(-child.pid, "SIGKILL");
+          else child.kill("SIGKILL");
+        } catch {}
+      }, 2_000).unref();
+    };
+    const abort = () => terminate("canceled");
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+    const timer = setTimeout(() => terminate("timedOut"), timeoutMs);
+    timer.unref();
+    child.stdout.on("data", (chunk) => append("stdout", chunk));
+    child.stderr.on("data", (chunk) => append("stderr", chunk));
+    child.on("error", (error) => {
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      fs.rmSync(temporaryRoot, { recursive: true, force: true });
+      reject(error);
+    });
+    child.on("close", (status) => {
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      fs.rmSync(temporaryRoot, { recursive: true, force: true });
+      resolve({
+        status: interruption === "canceled" ? 130 : interruption === "timedOut" ? 124 : (status ?? 1),
+        output: `${stderr}${stdout}`,
+        canceled: interruption === "canceled",
+        timedOut: interruption === "timedOut",
+      });
+    });
+  });
+}
+
+export function progressParser(onProgress) {
+  let pending = "";
+  let lastPhase = "";
+  return (chunk) => {
+    pending += chunk;
+    const lines = pending.split(/\r\n|\n|\r/);
+    pending = lines.pop() ?? "";
+    for (const raw of lines) {
+      const line = raw.trim();
+      let progress = null;
+      if (/copying profile data/i.test(line)) {
+        progress = { phase: "copying", fraction: 0.18, detail: "Copying profile data into an isolated workspace…" };
+      } else if (/launching headless browser/i.test(line)) {
+        progress = { phase: "launching", fraction: 0.30, detail: "Launching the temporary browser…" };
+      } else if (/waiting for browser to be ready/i.test(line)) {
+        progress = { phase: "waiting", fraction: 0.38, detail: "Waiting for the temporary browser…" };
+      } else if (/capturing per-origin storage/i.test(line)) {
+        progress = { phase: "capturing", fraction: 0.42, detail: "Capturing cookies, local storage, and IndexedDB…" };
+      } else if (/^\d+\/\d+\s+/.test(line)) {
+        const match = line.match(/^(\d+)\/(\d+)\s+(.+)$/);
+        if (match) {
+          const current = Number(match[1]);
+          const total = Number(match[2]);
+          progress = {
+            phase: "capturing",
+            fraction: total > 0 ? 0.42 + 0.42 * Math.min(current / total, 1) : 0.42,
+            current,
+            total,
+            detail: `Capturing ${match[3]}`,
+          };
+        }
+      } else if (/uploading to browserless/i.test(line)) {
+        progress = { phase: "uploading", fraction: 0.90, detail: "Uploading the fitted authenticated profile…" };
+      }
+      if (!progress) continue;
+      const identity = `${progress.phase}:${progress.current ?? ""}:${progress.total ?? ""}:${progress.detail}`;
+      if (identity === lastPhase) continue;
+      lastPhase = identity;
+      onProgress(progress);
+    }
+  };
+}
+
+function isMissingProfile(output) {
+  return /(?:not found|does not exist|404)/i.test(output);
+}
+
+function parseJSON(output) {
+  const start = output.indexOf("{");
+  const end = output.lastIndexOf("}");
+  if (start !== -1 && end > start) {
+    try {
+      const parsed = JSON.parse(output.slice(start, end + 1));
+      if (parsed && typeof parsed === "object") return parsed;
+    } catch {}
+  }
+  for (const line of output.split("\n").reverse()) {
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed && typeof parsed === "object") return parsed;
+    } catch {}
+  }
+  return null;
+}
+
+function lastLine(output) {
+  return output.split("\n").map((line) => line.trim()).filter(Boolean).at(-1)?.replace(/^Error:\s*/, "");
+}
+
+function throwForInterruptedRun(result, timeoutMs) {
+  if (result?.canceled || result?.status === 130) {
+    throw new Error("Browserless upload canceled. Temporary profile data was removed.");
+  }
+  if (result?.timedOut || result?.status === 124) {
+    const minutes = Math.max(1, Math.round(timeoutMs / 60_000));
+    throw new Error(`Browserless upload timed out after ${minutes} minute${minutes === 1 ? "" : "s"}. Check the connection, close the source browser, and try again with a smaller domain allowlist.`);
+  }
+}
+
+function droppedOrigins(output) {
+  return Number(output.match(/--auto-fit:\s*dropped\s+(\d+)\s+origin/i)?.[1] || 0);
+}
+
+function failedOrigins(output) {
+  return Number(output.match(/!\s+(\d+)\s+origin\(s\) failed to capture/i)?.[1] || 0);
+}
+
+function uploadSummary({ operation, details, fallbackName, counts, output }) {
+  const dropped = droppedOrigins(output);
+  const failed = failedOrigins(output);
+  const warnings = [];
+  if (dropped > 0) warnings.push(`${dropped} heavy origin${dropped === 1 ? "" : "s"} omitted to fit Browserless's 2 MB cap`);
+  if (failed > 0) warnings.push(`${failed} origin${failed === 1 ? "" : "s"} could not be captured`);
+  const warning = warnings.length > 0 ? `; ${warnings.join("; ")}` : "";
+  return `Browserless profile ${operation === "refresh" ? "updated" : "created"} and verified: ${details?.name || fallbackName}${counts}${warning}`;
+}
+
+function actionableFailure(output) {
+  const detail = lastLine(output) || "Browserless profile upload failed.";
+  if (/(?:failed to reach|enotfound|econnreset|econnrefused|network|socket hang up|fetch failed)/i.test(output)) {
+    return `Browserless could not be reached. Check your internet connection and region, then try again. ${detail}`;
+  }
+  if (/(?:profile busy|singletonlock|browser.*running|source browser must be closed)/i.test(output)) {
+    return `The source browser is still using this profile. Quit it completely, wait a few seconds, and try again. ${detail}`;
+  }
+  if (/(?:2 MB|too large|artifact.*cap|payload.*large)/i.test(output)) {
+    return `The captured state could not fit Browserless's 2 MB profile cap. Add a domain allowlist for the sites you need, then try again. ${detail}`;
+  }
+  return detail;
+}

package/src/cli.js

@@ -9,6 +9,8 @@ import {
   isCodexRunning,
 } from "./codex-direct-import.js";
 import { readChromiumProfile } from "./chromium-reader.js";
+import { uploadBrowserlessProfile } from "./browserless.js";
+import { inspectBrowserlessProfile } from "./browserless-preflight.js";
 import { installConfig, installRuntime, readConfig, updatePreferences } from "./config.js";
 import {
   braveCookiePaths,
@@ -44,7 +46,8 @@ Commands:
   install-app [--no-open]
   bootstrap-bundled --app-path /Applications/Browser Cookie Bridge.app
   preferences --source brave --target codex --cookies on --history off --menu-bar on --auto-check-updates on
-  sync [--timeout 300]
+  sync [--timeout 300] [--allow-cloud-upload]
+  browserless-preflight
   doctor
   enable-login-sync
   disable-login-sync
@@ -54,13 +57,15 @@ Commands:
   help
 `;
 
-export async function main(argv) {
+export async function main(argv, { signal } = {}) {
   const [command = "help", ...args] = argv;
   switch (command) {
     case "setup":
       return setup(args);
     case "sync":
-      return sync(args);
+      return sync(args, { signal });
+    case "browserless-preflight":
+      return browserlessPreflight();
     case "install-app":
       return installDesktopApp(args);
     case "bootstrap-bundled":
@@ -123,6 +128,9 @@ function preferences(args) {
     menuBar: booleanFlag(args, "--menu-bar", existing.ui?.menuBar === true),
     openAtLogin: booleanFlag(args, "--open-at-login", existing.ui?.openAtLogin !== false),
     autoCheckUpdates: booleanFlag(args, "--auto-check-updates", existing.ui?.autoCheckUpdates !== false),
+    browserlessProfileName: stringFlag(args, "--browserless-profile", existing.browserless?.profileName || "browser-cookie-bridge"),
+    browserlessRegion: stringFlag(args, "--browserless-region", existing.browserless?.region || "sfo"),
+    browserlessOnlyDomains: optionalStringFlag(args, "--browserless-domains", (existing.browserless?.onlyDomains || []).join(",")),
   });
   console.log(
     `Saved: source=${config.sourceBrowser}, target=${config.targetBrowser}, cookies=${config.imports.cookies ? "on" : "off"}, history=${config.imports.history ? "on" : "off"}, menu-bar=${config.ui.menuBar ? "on" : "off"}, open-at-login=${config.ui.openAtLogin ? "on" : "off"}, auto-check-updates=${config.ui.autoCheckUpdates ? "on" : "off"}`,
@@ -239,6 +247,10 @@ function setup(args) {
   if (config.targetBrowser === "codex") {
     console.log(`Source browser: ${config.sourceBrowser} (read locally; no extension required)`);
     console.log("Target integration: direct local Codex merge (Codex must be closed)");
+  } else if (config.targetBrowser === "browserless") {
+    console.log(`Source browser: ${config.sourceBrowser} (captured locally by the Browserless CLI)`);
+    console.log(`Cloud destination: Browserless ${config.browserless?.region || "sfo"} / ${config.browserless?.profileName || "browser-cookie-bridge"}`);
+    console.log("Browserless uploads are manual-only and require --allow-cloud-upload.");
   } else {
     console.log(`Source extension (${config.sourceBrowser}): ${installedExtensionDir(undefined, config.sourceBrowser)}`);
     console.log(`Target extension (${config.targetBrowser}): ${installedExtensionDir(undefined, config.targetBrowser)}`);
@@ -251,11 +263,42 @@ function setup(args) {
     : "Cookie values are transferred in memory and are not written to logs or disk.");
 }
 
-async function sync(args) {
+async function sync(args, { signal } = {}) {
   assertMacOS();
-  const seconds = integerFlag(args, "--timeout", 300, 5, 3600);
   const config = readConfig();
-  const isCodexTarget = (config.targetBrowser || "codex") === "codex";
+  const target = config.targetBrowser || "codex";
+  const seconds = integerFlag(args, "--timeout", target === "browserless" ? 900 : 300, 5, 3600);
+  const isCodexTarget = target === "codex";
+  if (target === "browserless") {
+    if (!args.includes("--allow-cloud-upload")) {
+      throw new Error("Browserless cloud uploads are manual-only. Start one from the app or pass --allow-cloud-upload explicitly.");
+    }
+    const source = config.sourceBrowser || "brave";
+    const local = readChromiumProfile({ browser: source, imports: { cookies: false, history: false } });
+    emitBrowserlessProgress({ phase: "preflight", fraction: 0.03, detail: "Inspecting the local profile…" });
+    const assessment = inspectBrowserlessProfile({ profilePath: local.profilePath });
+    emitBrowserlessProgress({
+      phase: "preflight-complete",
+      fraction: 0.06,
+      detail: assessment.summary,
+      assessment,
+    });
+    console.log(`Profile preflight: ${assessment.summary}`);
+    console.log(`Preparing ${source} profile ${local.profileName} for an explicit Browserless cloud upload…`);
+    const result = await uploadBrowserlessProfile({
+      browser: source,
+      localProfile: local.profileName,
+      profileName: config.browserless?.profileName || "browser-cookie-bridge",
+      region: config.browserless?.region || "sfo",
+      onlyDomains: config.browserless?.onlyDomains || [],
+      timeoutMs: seconds * 1000,
+      signal,
+      onProgress: emitBrowserlessProgress,
+    });
+    emitBrowserlessProgress({ phase: "complete", fraction: 1, detail: result.summary });
+    console.log(result.summary);
+    return result;
+  }
   if (isCodexTarget) {
     if (isCodexRunning()) throw new Error(CODEX_RUNNING_ERROR);
     const payload = readChromiumProfile({
@@ -296,6 +339,21 @@ async function sync(args) {
   return result;
 }
 
+function browserlessPreflight() {
+  assertMacOS();
+  const config = readConfig();
+  const source = config.sourceBrowser || "brave";
+  if (source === "comet") throw new Error("Comet is not supported by Browserless profile capture yet.");
+  const local = readChromiumProfile({ browser: source, imports: { cookies: false, history: false } });
+  const assessment = inspectBrowserlessProfile({ profilePath: local.profilePath });
+  console.log(JSON.stringify({ browser: source, profileName: local.profileName, ...assessment }));
+  return assessment;
+}
+
+function emitBrowserlessProgress(event) {
+  console.log(`BCB_PROGRESS ${JSON.stringify(event)}`);
+}
+
 export function directCodexSummary(result) {
   const imported = result.imported + result.historyImported;
   const skipped = result.skipped + result.historySkipped;
@@ -331,6 +389,8 @@ function doctor() {
   console.log(
     target === "codex"
       ? "Target integration: direct local Codex merge (Codex must be closed)"
+      : target === "browserless"
+        ? `Target integration: optional Browserless cloud upload (${config?.browserless?.region || "sfo"}); manual only`
       : `Target extension: ${status(installedExtensionDir(home, target))}`,
   );
   console.log(`Daily schedule: ${status(launchAgentPath(home))}`);
@@ -355,6 +415,8 @@ function enableLoginSync() {
   const config = readConfig();
   console.log(config.targetBrowser === "codex"
     ? "A sync starts when you sign in and updates Codex only when Codex is closed."
+    : config.targetBrowser === "browserless"
+      ? "Browserless uploads remain manual-only; login sync will not send data to the cloud."
     : "A sync starts when you sign in and waits up to five minutes for both browser extensions.");
 }
 
@@ -373,6 +435,9 @@ function setAppLogin(enabled) {
     menuBar: existing.ui?.menuBar === true,
     openAtLogin: enabled,
     autoCheckUpdates: existing.ui?.autoCheckUpdates !== false,
+    browserlessProfileName: existing.browserless?.profileName,
+    browserlessRegion: existing.browserless?.region,
+    browserlessOnlyDomains: existing.browserless?.onlyDomains,
   });
   if (enabled) {
     const appPath = installedAppPath();
@@ -422,6 +487,11 @@ function stringFlag(args, name, fallback) {
   return value;
 }
 
+function optionalStringFlag(args, name, fallback) {
+  const index = args.indexOf(name);
+  return index === -1 ? fallback : (args[index + 1] ?? "");
+}
+
 function existing(paths) {
   return paths.filter((candidate) => fs.existsSync(candidate));
 }