chrome-bridge-mcp 1.11.0 → 1.13.0

package/README.md

@@ -1,10 +1,10 @@
 # Chrome Bridge
 
-![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![Chrome 135+](https://img.shields.io/badge/chrome-%E2%89%A5135-blue) ![Tests](https://img.shields.io/badge/tests-147%20unit%20%2B%20e2e-brightgreen) [![Chrome Web Store](https://img.shields.io/badge/web%20store-published-blue)](https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb)
+![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![Chrome 135+](https://img.shields.io/badge/chrome-%E2%89%A5135-blue) ![Tests](https://img.shields.io/badge/tests-169%20unit%20%2B%20e2e-brightgreen) [![Chrome Web Store](https://img.shields.io/badge/web%20store-published-blue)](https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb)
 
 **Chrome Bridge is an MCP server that connects Claude Code to your real, logged-in Chrome browser — measured 2.75× fewer turns and 2.28× lower cost than the official "Claude in Chrome" extension on a form-filling task, with ~3× the toolset and no paid plan.**
 
-By using a local WebSocket bridge and a specialized Chrome extension, Chrome Bridge provides 60 web-development tools (navigation, DOM inspection, visual regression, audits, network mocking) and a dedicated headless instance for CI. It is self-hosted, local-only, and requires no paid plan.
+By using a local WebSocket bridge and a specialized Chrome extension, Chrome Bridge provides 62 web-development tools (navigation, DOM inspection, visual regression, audits, network mocking) and a dedicated headless instance for CI. It is self-hosted, local-only, and requires no paid plan.
 
 ## Why Chrome Bridge?
 
@@ -31,12 +31,12 @@ unfavourable ones) and the harness limits are in
 - **Honest caveat:** per *turn*, Chrome Bridge costs slightly more than Claude in Chrome (41,985 vs 36,613 cache-read tokens; $0.0373 vs $0.0337). The win is in the number of turns.
 
 ### 2. Feature Comparison
-Chrome Bridge ships 60 specialized tools (31 core by default) compared to ~20 in Claude in Chrome. It is also the only automation that drives the real host Chrome on ChromeOS/Crostini.
+Chrome Bridge ships 62 specialized tools (33 core by default) compared to ~20 in Claude in Chrome. It is also the only automation that drives the real host Chrome on ChromeOS/Crostini.
 
 | | Chrome Bridge | Claude in Chrome | Chrome DevTools MCP | Playwright MCP |
 |---|---|---|---|---|
 | **ChromeOS / Crostini** | **Yes** (real host) | No | Container only | Container only |
-| **Tools** | **60** (31 core) | ~20 | ~50 | 23 core (71 total) |
+| **Tools** | **62** (33 core) | ~20 | ~50 | 23 core (71 total) |
 | **Requires Paid Plan** | **No** | Yes (Pro+) | No | No |
 | **Network Mocking** | **Yes** (stub/headers) | No | No | Yes |
 | **Visual Regression** | **Yes** (`screenshot_diff`) | No | No | No |
@@ -63,7 +63,7 @@ Claude Code calls `navigate` (returning clickable element refs), `accessibility_
 
 ## Token-Efficient Design
 
-- **Opt-in Surface**: 31 core tools cost ≈7.9k tokens of `tools/list`, all 60 cost ≈14.9k; specialized groups (audits, visual, network, storage, dom, files) are opt-in via `--caps`. That core figure was ≈3.8k in 1.8.0 and roughly doubled in 1.10.0: MCP annotations on every tool, rewritten descriptions, and a documented `.describe()` on all 254 parameters (coverage went from 35% to 100%). The trade is deliberate and it is not free — on the form benchmark it adds ≈8% to the cache-read tokens per turn — but the measured advantage was never prefix size, it was round trips: 2.75× fewer turns. Playwright MCP's 23 core tools measured ≈4.6k in July 2026, so on prefix size alone it is the leaner one. Measure ours with `npm run measure`.
+- **Opt-in Surface**: 33 core tools cost ≈8.5k tokens of `tools/list`, all 62 cost ≈15.5k; specialized groups (audits, visual, network, storage, dom, files) are opt-in via `--caps`. That core figure was ≈3.8k in 1.8.0 and roughly doubled in 1.10.0: MCP annotations on every tool, rewritten descriptions, and a documented `.describe()` on all 254 parameters (coverage went from 35% to 100%). The trade is deliberate and it is not free — on the form benchmark it adds ≈8% to the cache-read tokens per turn — but the measured advantage was never prefix size, it was round trips: 2.75× fewer turns. Playwright MCP's 23 core tools measured ≈4.6k in July 2026, so on prefix size alone it is the leaner one. Measure ours with `npm run measure`.
 - **Act-from-Result**: Tools attach a capped preview of interactive elements with short refs. Actions only report a `page_changed` delta when the URL or title actually changes.
 - **Optimized Media**: Screenshots are downscaled to ≤1568px. Full-page captures are sliced into readable segments.
 - **Payload Escape Hatches**: `save_to` on `read_page`, `extract`, `screenshot` and `http_request` writes the result to a file and returns the path — the bytes never enter the context unless the agent decides to read them. `read_page(mode="markdown")` keeps headings, links and tables at a fraction of the HTML cost. The [CLI](#cli) skips MCP schemas entirely, and recorded flows [replay](#launch-mode-headless--ci) without any model in the loop.
@@ -84,10 +84,10 @@ Claude Code  <--stdio-->  MCP Server  <--WebSocket :8765-->  Chrome Extension
 
 The **MCP Server** (Node.js) handles the protocol and tool logic. The **Chrome Extension** (MV3) executes commands via Chrome APIs. User scripts (`execute_js`) run via `chrome.userScripts.execute()`, requiring the "Allow user scripts" toggle in extension settings.
 
-## Tools (60 total)
+## Tools (62 total)
 
-### Core & Navigation (7)
-`get_status`, `get_tabs`, `create_tab`, `navigate`, `tab_action`, `get_frames`, `screenshot`.
+### Core & Navigation (9)
+`get_status`, `get_tabs`, `create_tab`, `navigate`, `tab_action`, `move_tab` (between windows), `tile_windows` (split one monitor evenly), `get_frames`, `screenshot`.
 
 ### Interaction (11)
 `click`, `type_text`, `fill_form`, `hover`, `press_key`, `scroll`, `drag_and_drop`, `upload_file`, `dismiss_overlays`, `handle_dialogs`, `clipboard`.
@@ -132,7 +132,7 @@ Configure the server via environment variables (or the matching CLI flags):
 - `CHROME_BRIDGE_PORT`: Default `8765`.
 - `CHROME_BRIDGE_HOST` / `--host`: Bind address, default `127.0.0.1`. Set to `0.0.0.0` **only** where the browser lives outside the container (ChromeOS/Crostini port-forward) — and pair it with a token.
 - `CHROME_BRIDGE_TOKEN`: Shared secret required on both `ext_init` and `relay_init`. Strongly recommended whenever the bind is not loopback.
-- `CHROME_BRIDGE_CAPS` / `--caps`: Tool groups to load (`core`, `audits`, `visual`, `network`, `storage`, `dom`, `files`, or `all`). `install.sh` registers with `all`; the bare server defaults to `core` (31 tools). `get_status` reports `caps_active` and `caps_available`.
+- `CHROME_BRIDGE_CAPS` / `--caps`: Tool groups to load (`core`, `audits`, `visual`, `network`, `storage`, `dom`, `files`, or `all`). `install.sh` registers with `all`; the bare server defaults to `core` (33 tools). `get_status` reports `caps_active` and `caps_available`.
 
 Run `node tools/measure-schema.mjs` to see the exact schema cost of the active set.
 

package/extension/lib/tile-layout.js

@@ -0,0 +1,75 @@
+/**
+ * Divide un'area rettangolare in `count` tessere che la riempiono per intero.
+ *
+ * Funzione pura, tenuta fuori dal service worker perché è l'unica parte con una
+ * geometria da sbagliare: il resto del tool è una sequenza di
+ * chrome.windows.update.
+ *
+ * Sul resto della divisione intera: 3 finestre su 1000px fanno 333 e avanza 1.
+ * Buttarlo lascia una striscia di scrivania scoperta, che è esattamente ciò che
+ * l'affiancamento dovrebbe eliminare. Qui il resto viene distribuito un pixel
+ * per volta sulle prime tessere: le larghezze differiscono al massimo di 1px e
+ * lo spazio resta pieno.
+ */
+
+// Ripartisce `total` in `parts` interi che sommano esattamente a `total`.
+function split(total, parts) {
+  const base = Math.floor(total / parts);
+  const remainder = total - base * parts;
+  return Array.from({ length: parts }, (_, i) => base + (i < remainder ? 1 : 0));
+}
+
+// Righe e colonne per una griglia il più quadrata possibile: con 5 finestre
+// preferisce 3×2 a 5×1, che su uno schermo largo lascerebbe strisce inutilizzabili.
+function gridShape(count) {
+  const cols = Math.ceil(Math.sqrt(count));
+  const rows = Math.ceil(count / cols);
+  return { cols, rows };
+}
+
+export function computeTiles({ count, area, layout = 'grid', padding = 0 }) {
+  if (!count || count < 1) return [];
+
+  const box = {
+    left: area.left + padding,
+    top: area.top + padding,
+    width: area.width - padding * 2,
+    height: area.height - padding * 2,
+  };
+
+  let rows;
+  let colsPerRow;
+  if (layout === 'columns') {
+    rows = 1;
+    colsPerRow = [count];
+  } else if (layout === 'rows') {
+    rows = count;
+    colsPerRow = Array.from({ length: count }, () => 1);
+  } else {
+    const shape = gridShape(count);
+    rows = shape.rows;
+    // L'ultima riga può essere incompleta: le sue tessere si allargano a
+    // riempirla invece di lasciare un buco a destra.
+    colsPerRow = Array.from({ length: rows }, (_, r) => {
+      const remaining = count - r * shape.cols;
+      return Math.min(shape.cols, remaining);
+    });
+  }
+
+  const rowHeights = split(box.height, rows);
+  const tiles = [];
+  let top = box.top;
+
+  for (let r = 0; r < rows; r++) {
+    const cols = colsPerRow[r];
+    const colWidths = split(box.width, cols);
+    let left = box.left;
+    for (let c = 0; c < cols; c++) {
+      tiles.push({ left, top, width: colWidths[c], height: rowHeights[r] });
+      left += colWidths[c];
+    }
+    top += rowHeights[r];
+  }
+
+  return tiles;
+}

package/extension/manifest.json

@@ -1,8 +1,8 @@
 {
   "manifest_version": 3,
   "name": "Chrome Bridge for Claude Code",
-  "version": "1.11.0",
-  "description": "Bridge your browser to Claude Code: 60 token-efficient web-dev automation tools over a local WebSocket. ChromeOS included.",
+  "version": "1.13.0",
+  "description": "Bridge your browser to Claude Code: 62 token-efficient web-dev automation tools over a local WebSocket. ChromeOS included.",
   "homepage_url": "https://github.com/frsorrentino/chrome-bridge",
   "minimum_chrome_version": "135",
   "permissions": [

package/extension/service-worker.js

@@ -7,6 +7,7 @@
 
 import './telemetry.js';
 import { buildMarkdown } from './lib/page-markdown.js';
+import { computeTiles } from './lib/tile-layout.js';
 const { pushError } = globalThis.__cbTelemetry;
 
 const DEFAULT_PORT = 8765;
@@ -386,6 +387,10 @@ async function executeCommand(msg) {
       return await cmdGetFrames(params);
     case 'tab_action':
       return await cmdTabAction(params);
+    case 'move_tab':
+      return await cmdMoveTab(params);
+    case 'tile_windows':
+      return await cmdTileWindows(params);
     case 'upload_file':
       return await cmdUploadFile(params);
     case 'wait_for_navigation':
@@ -930,6 +935,142 @@ async function cmdCreateTab({ url, active = true }) {
 
 // --- tab_action ---
 
+// --- move_tab ---
+
+/**
+ * Sposta una scheda in un'altra finestra senza ricrearla: la scheda conserva id,
+ * cronologia e stato della pagina.
+ *
+ * Motivo per cui esiste: sul Terminale ChromeOS garcon apre ogni sessione in una
+ * finestra separata, e consolidarle richiede di spostare schede
+ * `chrome-untrusted://terminal`. Su quello schema `chrome.tabs.create` è vietato;
+ * `move` non ricrea nulla, quindi potrebbe essere permesso. Se Chrome rifiuta, il
+ * messaggio viene propagato **testuale**: è il dato che si sta cercando, e
+ * riscriverlo lo distruggerebbe.
+ */
+// --- tile_windows ---
+
+/**
+ * Affianca le finestre di Chrome su un monitor, dividendone l'area utile in
+ * parti uguali che non lasciano spazi.
+ *
+ * L'area del monitor si legge da `screen.availLeft/availTop/availWidth/
+ * availHeight` eseguito in una scheda di una finestra che ci sta sopra. La via
+ * "giusta" sarebbe chrome.system.display, ma richiede un permesso install-time:
+ * su un'estensione già pubblicata significa una nuova revisione e il possibile
+ * ri-consenso degli utenti, per un dato che il DOM offre gratis.
+ *
+ * Il prezzo di questa scelta: serve almeno una scheda scriptabile fra le
+ * finestre bersaglio. Una finestra con sole schede chrome:// o
+ * chrome-untrusted:// non può fornire l'area, e il tool lo dice invece di
+ * ripiegare su misure inventate.
+ */
+async function cmdTileWindows({ window_ids, reference_window_id, layout = 'grid', padding = 0, include_types }) {
+  const types = include_types?.length ? include_types : ['normal'];
+  const all = await chrome.windows.getAll({ populate: true });
+
+  let targets = all.filter((w) => types.includes(w.type));
+  if (window_ids?.length) targets = all.filter((w) => window_ids.includes(w.id));
+  if (!targets.length) throw new Error(`Nessuna finestra da affiancare (tipi: ${types.join(', ')})`);
+
+  // Il monitor è quello della finestra di riferimento: su più schermi non
+  // esiste "lo schermo" senza dire quale.
+  const reference = reference_window_id
+    ? targets.find((w) => w.id === reference_window_id) ?? all.find((w) => w.id === reference_window_id)
+    : targets.find((w) => w.focused) ?? targets[0];
+  if (!reference) throw new Error(`Finestra di riferimento ${reference_window_id} non trovata`);
+
+  // Prima scheda scriptabile fra le finestre bersaglio, partendo dalla
+  // riferimento: le pagine interne di Chrome non accettano injection.
+  const candidates = [reference, ...targets.filter((w) => w.id !== reference.id)]
+    .flatMap((w) => (w.tabs || []).map((t) => ({ windowId: w.id, tabId: t.id, url: t.url || '' })))
+    .filter((t) => /^(https?|file):/i.test(t.url));
+
+  let area = null;
+  const failures = [];
+  for (const cand of candidates) {
+    try {
+      const [res] = await chrome.scripting.executeScript({
+        target: { tabId: cand.tabId },
+        func: () => ({
+          left: screen.availLeft ?? 0,
+          top: screen.availTop ?? 0,
+          width: screen.availWidth,
+          height: screen.availHeight,
+        }),
+        world: 'MAIN',
+      });
+      if (res?.result?.width) { area = res.result; break; }
+    } catch (e) {
+      failures.push(`${cand.url.slice(0, 40)}: ${e.message}`);
+    }
+  }
+  if (!area) {
+    throw new Error(
+      'Impossibile leggere l\'area del monitor: nessuna scheda scriptabile fra le finestre bersaglio '
+      + '(le pagine chrome:// e chrome-untrusted:// non lo permettono). '
+      + `Apri una pagina http(s) in una di esse e riprova.${failures.length ? ' Tentativi: ' + failures.join(' | ') : ''}`,
+    );
+  }
+
+  const tiles = computeTiles({ count: targets.length, area, layout, padding });
+  const results = [];
+
+  for (let i = 0; i < targets.length; i++) {
+    const w = targets[i];
+    const tile = tiles[i];
+    try {
+      // Una finestra massimizzata accetta i bounds e li ignora: va riportata a
+      // 'normal' prima, o la chiamata riesce senza che nulla si muova.
+      if (w.state !== 'normal') {
+        await chrome.windows.update(w.id, { state: 'normal' });
+      }
+      const updated = await chrome.windows.update(w.id, tile);
+      const actual = { left: updated.left, top: updated.top, width: updated.width, height: updated.height };
+      results.push({
+        window_id: w.id,
+        type: w.type,
+        requested: tile,
+        actual,
+        // Il window manager può rifiutare in silenzio: senza il confronto, una
+        // finestra rimasta ferma passerebbe per affiancata.
+        applied: actual.left === tile.left && actual.top === tile.top
+          && actual.width === tile.width && actual.height === tile.height,
+      });
+    } catch (e) {
+      results.push({ window_id: w.id, type: w.type, requested: tile, error: e.message });
+    }
+  }
+
+  return {
+    monitor: area,
+    layout,
+    windows: results.length,
+    applied: results.filter((r) => r.applied).length,
+    results,
+  };
+}
+
+async function cmdMoveTab({ tab_id, window_id, index = -1 }) {
+  if (typeof tab_id !== 'number') throw new Error('Missing required parameter: tab_id');
+  if (typeof window_id !== 'number') throw new Error('Missing required parameter: window_id');
+
+  const before = await chrome.tabs.get(tab_id);
+  const moved = await chrome.tabs.move(tab_id, { windowId: window_id, index });
+  const tab = Array.isArray(moved) ? moved[0] : moved;
+
+  return {
+    moved: tab_id,
+    url: before.url,
+    from_window: before.windowId,
+    to_window: tab?.windowId ?? window_id,
+    index: tab?.index ?? index,
+    // Chrome può accettare la chiamata e lasciare la scheda dov'era: senza questo
+    // il chiamante vedrebbe un successo per un'operazione non avvenuta.
+    same_window: before.windowId === (tab?.windowId ?? window_id),
+  };
+}
+
 async function cmdTabAction({ action, tab_id, bypass_cache = false }) {
   if (!action) throw new Error('Missing required parameter: action');
   const tabId = await resolveTabId(tab_id);

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "chrome-bridge-mcp",
   "mcpName": "io.github.frsorrentino/chrome-bridge",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "type": "module",
-  "description": "MCP server with 60 tools for browser automation via Chrome extension. Works on ChromeOS/Crostini.",
+  "description": "MCP server with 62 tools for browser automation via Chrome extension. Works on ChromeOS/Crostini.",
   "main": "server/index.js",
   "bin": {
     "chrome-bridge-mcp": "server/index.js",

package/server/protocol.js

@@ -40,6 +40,8 @@ export const MessageType = Object.freeze({
   PRESS_KEY:            'press_key',
   GET_FRAMES:           'get_frames',
   TAB_ACTION:           'tab_action',
+  MOVE_TAB:             'move_tab',
+  TILE_WINDOWS:         'tile_windows',
   UPLOAD_FILE:           'upload_file',
   WAIT_FOR_NAVIGATION:   'wait_for_navigation',
   WAIT_FOR_NETWORK_IDLE: 'wait_for_network_idle',
@@ -82,7 +84,7 @@ export const MessageType = Object.freeze({
 });
 
 // Versione
-export const VERSION               = '1.11.0';
+export const VERSION               = '1.13.0';
 
 // Configurazione
 export const DEFAULT_PORT          = 8765;
@@ -133,6 +135,7 @@ export function getTimeout(type) {
     || type === MessageType.MANAGE_DOWNLOADS
     || type === MessageType.SAVE_PAGE
     || type === MessageType.HTTP_REQUEST
+    || type === MessageType.TILE_WINDOWS
     || type === MessageType.WAIT_FOR_FUNCTION
     || type === MessageType.SCROLL_UNTIL) return 60000;
   return COMMAND_TIMEOUT_MS;

package/server/tools.js

@@ -188,8 +188,9 @@ export const TOOL_CAPS = {
 // Parametri ubiqui: un solo testo, così `tab_id` non significa una cosa in un
 // tool e un'altra nel gemello. test/unit/tool-parameters.test.js lo verifica.
 // save_to: il payload va su disco e nel contesto resta solo il percorso più un
-// sommario. L'idea è di superpowers-chrome, che scrive automaticamente a ogni
-// azione; qui è opt-in, perché scrivere file per chi non li leggerà è una tassa.
+// sommario. Deliberatamente opt-in per chiamata e non automatico dopo ogni
+// azione: scrivere file per chi non li leggerà è una tassa, e il server non
+// controlla la directory di lavoro del client.
 const saveToField = (what) => z.string().optional()
   .describe(`Absolute path: write ${what} there and return the path instead of the content`);
 
@@ -288,6 +289,8 @@ export const TOOL_ANNOTATIONS = {
   set_zoom: rw({ idempotent: true }),
   viewport_resize: rw({ idempotent: true }),
   create_tab: rw({ open: true }),
+  move_tab: rw({ idempotent: true }),   // rispostare dove è già = stesso esito
+  tile_windows: rw({ idempotent: true }),
   navigate: rw({ idempotent: true, open: true }),
   tab_action: rw({ destructive: true, open: true }),  // close chiude una tab dell'utente
 
@@ -1730,6 +1733,47 @@ export function registerTools(server, wsManager, caps = 'all') {
     }
   );
 
+  // --- move_tab ---
+  server.tool(
+    'move_tab',
+    'Move an existing tab into another window (chrome.tabs.move), e.g. to consolidate windows that were '
+      + 'each opened separately. Does not create or close anything: the tab keeps its id, its history and its '
+      + 'page state. Both windows must be normal browser windows — Chrome refuses to move a tab into a popup or '
+      + 'an app window, and the refusal is reported verbatim rather than retried.',
+    {
+      tab_id: z.number().describe('Tab to move; get it from get_tabs'),
+      window_id: z.number().describe('Destination window; get_tabs reports windowId for every tab'),
+      index: z.number().optional().default(-1).describe('Position in the destination window; -1 appends at the end'),
+    },
+    async ({ tab_id, window_id, index }) => {
+      const data = await send(MessageType.MOVE_TAB, { tab_id, window_id, index: index ?? -1 });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- tile_windows ---
+  server.tool(
+    'tile_windows',
+    'Tile Chrome windows over one monitor, splitting its usable area into equal parts that leave no gap. '
+      + 'Only Chrome windows: an extension cannot touch other applications. The monitor is chosen by pointing at '
+      + 'a window already on it, since the work area is read from a page there — so at least one target window '
+      + 'needs a scriptable tab (a chrome:// or chrome-untrusted:// tab cannot provide it). Maximized windows are '
+      + 'restored first, because a maximized window accepts bounds and ignores them.',
+    {
+      window_ids: z.array(z.number()).optional().describe('Windows to tile; omitted = every normal window on the reference monitor'),
+      reference_window_id: z.number().optional().describe('Window whose monitor is used; omitted = the focused one'),
+      layout: z.enum(['grid', 'columns', 'rows']).optional().default('grid').describe('columns splits left to right, rows top to bottom, grid keeps tiles as square as it can'),
+      padding: z.number().optional().default(0).describe('Px of empty margin kept inside the work area'),
+      include_types: z.array(z.enum(['normal', 'popup', 'app'])).optional().describe('Window types to include; omitted = normal only'),
+    },
+    async ({ window_ids, reference_window_id, layout, padding, include_types }) => {
+      const data = await send(MessageType.TILE_WINDOWS, {
+        window_ids, reference_window_id, layout: layout ?? 'grid', padding: padding ?? 0, include_types,
+      });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
   // --- set_zoom ---
   server.tool(
     'set_zoom',

package/tools/cws-upload.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * Carica e pubblica lo zip dell'estensione sul Chrome Web Store via API.
+ *
+ * Esiste per togliere di mezzo il TOTP: la dev console non è automatizzabile
+ * (la gallery non è scriptabile da un'estensione, e via CDP serve comunque il
+ * login Google completo), mentre l'API vuole solo un refresh token revocabile.
+ *
+ * Credenziali in ~/.config/chrome-bridge/cws.json (chmod 600), MAI nel repo:
+ *   { "client_id": "...", "client_secret": "...", "refresh_token": "...", "item_id": "..." }
+ * Sovrascrivibili da CWS_CLIENT_ID / CWS_CLIENT_SECRET / CWS_REFRESH_TOKEN / CWS_ITEM_ID.
+ *
+ * Uso:
+ *   node tools/cws-upload.mjs dist/chrome-bridge-extension-1.11.0.zip           # carica come bozza
+ *   node tools/cws-upload.mjs dist/....zip --publish                            # carica e pubblica
+ *   node tools/cws-upload.mjs --status                                         # stato della bozza sullo store
+ *   node tools/cws-upload.mjs --auth [porta]                                    # URL di consenso + cattura del codice sul loopback
+ *   node tools/cws-upload.mjs --exchange <code> [--redirect <uri>]              # code → refresh token
+ */
+import { createServer } from 'node:http';
+import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+const CONFIG = join(homedir(), '.config', 'chrome-bridge', 'cws.json');
+const SCOPE = 'https://www.googleapis.com/auth/chromewebstore';
+// Google ha dismesso il redirect fuori banda (urn:ietf:wg:oauth:2.0:oob): un
+// client nuovo che lo usa riceve "Errore 400: invalid_request". Per i client
+// desktop la strada supportata è il loopback su una porta qualsiasi, che qui
+// viene aperta al volo e chiusa appena arriva il codice.
+function buildAuthUrl(clientId, redirectUri) {
+  return 'https://accounts.google.com/o/oauth2/auth?' + new URLSearchParams({
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    response_type: 'code',
+    scope: SCOPE,
+    access_type: 'offline',
+    prompt: 'consent',
+  });
+}
+
+// Attende un solo codice sul loopback e poi chiude: nessun server che resta su.
+function waitForCode(port) {
+  return new Promise((resolve, reject) => {
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, `http://127.0.0.1:${port}`);
+      const code = url.searchParams.get('code');
+      const err = url.searchParams.get('error');
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(`<h2>${code ? 'Autorizzato. Puoi chiudere questa scheda.' : 'Errore: ' + (err || 'nessun codice')}</h2>`);
+      server.close();
+      if (code) resolve(code); else reject(new Error(err || 'nessun codice nella risposta'));
+    });
+    server.on('error', reject);
+    server.listen(port, '127.0.0.1');
+    setTimeout(() => { server.close(); reject(new Error('nessuna autorizzazione entro 5 minuti')); }, 300000);
+  });
+}
+
+export async function loadConfig(env = process.env) {
+  let file = {};
+  try { file = JSON.parse(await readFile(CONFIG, 'utf8')); } catch { /* prima esecuzione */ }
+  return {
+    client_id: env.CWS_CLIENT_ID || file.client_id,
+    client_secret: env.CWS_CLIENT_SECRET || file.client_secret,
+    refresh_token: env.CWS_REFRESH_TOKEN || file.refresh_token,
+    item_id: env.CWS_ITEM_ID || file.item_id,
+  };
+}
+
+export function requireFields(cfg, fields) {
+  const missing = fields.filter((f) => !cfg[f]);
+  if (missing.length) {
+    throw new Error(`Manca ${missing.join(', ')} — mettili in ${CONFIG} o nelle variabili CWS_*`);
+  }
+}
+
+/**
+ * Il Web Store risponde 200 anche quando il caricamento è fallito: l'esito vero
+ * è in uploadState, e itemError porta il motivo. Trattare 200 come successo è
+ * il modo di credere di aver pubblicato senza averlo fatto.
+ */
+export function interpretUpload(body) {
+  const state = body?.uploadState;
+  if (state === 'SUCCESS') return { ok: true, state };
+  const reasons = (body?.itemError || []).map((e) => e.error_detail || e.errorDetail || JSON.stringify(e));
+  return { ok: false, state: state ?? 'UNKNOWN', reasons };
+}
+
+/**
+ * Distingue un'attesa da un guasto.
+ *
+ * Se un ritentativo periodico tratta "c'è una versione in revisione" come
+ * errore, ogni giro produce una notifica rossa per una situazione normale — e in
+ * due giorni nessuno guarda più le notifiche, incluse quelle vere.
+ */
+export function classifyFailure(reasons = []) {
+  const text = reasons.join(' ').toLowerCase();
+  const waiting = [
+    'in pending review',
+    'is in review',
+    'ready to publish',
+    'version number is the same as the published one',
+  ];
+  return waiting.some((w) => text.includes(w)) ? 'locked' : 'error';
+}
+
+export function interpretPublish(body) {
+  const status = body?.status || [];
+  const ok = status.includes('OK') || status.includes('PUBLISHED_WITH_FRICTION_WARNING');
+  return { ok, status, detail: body?.statusDetail || [] };
+}
+
+async function exchange(cfg, code, redirectUri) {
+  const res = await fetch('https://oauth2.googleapis.com/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      client_id: cfg.client_id, client_secret: cfg.client_secret,
+      code, grant_type: 'authorization_code', redirect_uri: redirectUri,
+    }),
+  });
+  const body = await res.json();
+  if (!body.refresh_token) throw new Error(`Nessun refresh_token: ${JSON.stringify(body)}`);
+  return body.refresh_token;
+}
+
+async function saveRefreshToken(cfg, refresh_token) {
+  await mkdir(dirname(CONFIG), { recursive: true });
+  await writeFile(CONFIG, JSON.stringify({ ...cfg, refresh_token }, null, 2), { mode: 0o600 });
+  console.log(`refresh_token salvato in ${CONFIG} (chmod 600)`);
+}
+
+async function accessToken(cfg) {
+  const res = await fetch('https://oauth2.googleapis.com/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      client_id: cfg.client_id,
+      client_secret: cfg.client_secret,
+      refresh_token: cfg.refresh_token,
+      grant_type: 'refresh_token',
+    }),
+  });
+  const body = await res.json();
+  if (!res.ok || !body.access_token) {
+    // invalid_grant qui significa quasi sempre consent screen in "Testing":
+    // in quello stato Google scade i refresh token dopo 7 giorni.
+    throw new Error(`Token refresh fallito (${res.status}): ${JSON.stringify(body)}`);
+  }
+  return body.access_token;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cfg = await loadConfig();
+
+  if (argv.includes('--auth')) {
+    requireFields(cfg, ['client_id', 'client_secret']);
+    const portArg = argv[argv.indexOf('--auth') + 1];
+    const port = Number(portArg) > 0 ? Number(portArg) : 8899;
+    const redirect = `http://localhost:${port}`;
+    console.log(buildAuthUrl(cfg.client_id, redirect));
+    console.error(`in attesa del codice su ${redirect} …`);
+
+    const code = await waitForCode(port);
+    const token = await exchange(cfg, code, redirect);
+    await saveRefreshToken(cfg, token);
+    return;
+  }
+
+  const exIdx = argv.indexOf('--exchange');
+  if (exIdx !== -1) {
+    requireFields(cfg, ['client_id', 'client_secret']);
+    const code = argv[exIdx + 1];
+    if (!code) throw new Error('Uso: --exchange <codice> [--redirect <uri>]');
+    const rIdx = argv.indexOf('--redirect');
+    const redirect = rIdx !== -1 ? argv[rIdx + 1] : 'http://localhost:8899';
+    await saveRefreshToken(cfg, await exchange(cfg, code, redirect));
+    return;
+  }
+
+  if (argv.includes('--publish-only')) {
+    // Serve a distinguere due stati che l'API confonde in un solo messaggio di
+    // errore: "in revisione" (non si può fare nulla, si aspetta) e "pronta da
+    // pubblicare" (la revisione è passata e manca solo questa chiamata).
+    requireFields(cfg, ['client_id', 'client_secret', 'refresh_token', 'item_id']);
+    const token = await accessToken(cfg);
+    const res = await fetch(`https://www.googleapis.com/chromewebstore/v1.1/items/${cfg.item_id}/publish`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'x-goog-api-version': '2', 'Content-Length': '0' },
+    });
+    const body = await res.json();
+    console.log(JSON.stringify({ http: res.status, ...body }, null, 2));
+    return;
+  }
+
+  if (argv.includes('--status')) {
+    requireFields(cfg, ['client_id', 'client_secret', 'refresh_token', 'item_id']);
+    const token = await accessToken(cfg);
+    const res = await fetch(
+      `https://www.googleapis.com/chromewebstore/v1.1/items/${cfg.item_id}?projection=DRAFT`,
+      { headers: { Authorization: `Bearer ${token}`, 'x-goog-api-version': '2' } },
+    );
+    const body = await res.json();
+    // uploadState dice se la bozza esiste e in che stato è; crxVersion dice quale
+    // versione è nel cassetto, che è l'unico modo di distinguere "in revisione"
+    // da "mai caricata" senza guardare la vetrina.
+    console.log(JSON.stringify({ http: res.status, ...body }, null, 2));
+    return;
+  }
+
+  const zip = argv.find((a) => a.endsWith('.zip'));
+  if (!zip) throw new Error('Indica lo zip da caricare, o usa --auth / --exchange');
+  requireFields(cfg, ['client_id', 'client_secret', 'refresh_token', 'item_id']);
+
+  const size = (await stat(zip)).size;
+  const token = await accessToken(cfg);
+
+  const up = await fetch(`https://www.googleapis.com/upload/chromewebstore/v1.1/items/${cfg.item_id}`, {
+    method: 'PUT',
+    headers: { Authorization: `Bearer ${token}`, 'x-goog-api-version': '2' },
+    body: await readFile(zip),
+  });
+  const upBody = await up.json();
+  const upRes = interpretUpload(upBody);
+  console.log(`upload ${zip} (${size} B): ${upRes.ok ? 'SUCCESS' : `FALLITO [${upRes.state}] ${upRes.reasons.join(' | ')}`}`);
+  if (!upRes.ok) {
+    // 2 = si riproverà, 1 = serve una persona. Il ritentativo periodico
+    // distingue i due casi da qui.
+    const kind = classifyFailure(upRes.reasons);
+    console.log(`esito: ${kind === 'locked' ? 'ATTESA (si ritenta più tardi)' : 'ERRORE (serve intervento)'}`);
+    process.exit(kind === 'locked' ? 2 : 1);
+  }
+
+  if (!argv.includes('--publish')) {
+    console.log('bozza caricata; ripassa con --publish per mandarla in review');
+    return;
+  }
+
+  const pub = await fetch(`https://www.googleapis.com/chromewebstore/v1.1/items/${cfg.item_id}/publish`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'x-goog-api-version': '2', 'Content-Length': '0' },
+  });
+  const pubRes = interpretPublish(await pub.json());
+  console.log(`publish: ${pubRes.ok ? 'OK' : 'FALLITO'} ${pubRes.status.join(',')} ${pubRes.detail.join(' | ')}`);
+  if (!pubRes.ok) process.exit(1);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error(String(e.message || e)); process.exit(1); });
+}