@digital-gravy/etch-connector 0.1.1

package/dist/cli.js

@@ -0,0 +1,452 @@
+#!/usr/bin/env node
+/**
+ * etch-connector CLI — the thing an AI harness (Claude Code, Cowork, …) shells
+ * out to. Three commands:
+ *
+ *   etch-connector serve            start the bridge daemon (run this once)
+ *   etch-connector tabs             list connected Etch tabs
+ *   etch-connector eval [code]      run a script in a tab; value → stdout
+ *
+ * `eval` prints forwarded console output to *stderr* and the script's return
+ * value as JSON to *stdout*, so an agent can capture stdout as the clean result.
+ * Exit codes: 0 ok · 2 the script threw · 1 everything else (no tab, timeout…).
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { BridgeServer } from './bridge-server.js';
+import { createControlServer, controlBaseUrl } from './control-server.js';
+import { CdpClient, CdpError, CdpEvalError } from './cdp-client.js';
+import { DEFAULT_CONTROL_PORT, DEFAULT_HOST, DEFAULT_WS_PORT } from './protocol.js';
+const DEFAULT_CDP_PORT = 9222;
+/** Long flags that never take a value, so they don't swallow the next token. */
+const BOOLEAN_FLAGS = new Set([
+    'cdp',
+    'full',
+    'jpeg',
+    'json',
+    'unsafe',
+    'safe',
+    'help',
+    'freeze'
+]);
+function parseArgs(argv) {
+    const command = argv[0] ?? 'help';
+    const positional = [];
+    const flags = {};
+    for (let i = 1; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith('--')) {
+            // Support --key=value (e.g. --freeze=false) explicitly.
+            const eq = arg.indexOf('=');
+            if (eq !== -1) {
+                flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+                continue;
+            }
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (BOOLEAN_FLAGS.has(key)) {
+                flags[key] = true;
+            }
+            else if (next !== undefined && !next.startsWith('-')) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+        else if (arg.startsWith('-') && arg.length === 2) {
+            const map = {
+                t: 'tab',
+                f: 'file',
+                p: 'port',
+                s: 'selector',
+                o: 'out'
+            };
+            const key = map[arg.slice(1)] ?? arg.slice(1);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('-')) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { command, positional, flags };
+}
+function num(flag, fallback) {
+    if (typeof flag === 'string') {
+        const n = Number(flag);
+        if (!Number.isNaN(n))
+            return n;
+    }
+    return fallback;
+}
+function str(flag) {
+    return typeof flag === 'string' ? flag : undefined;
+}
+/** Resolve a boolean flag, honoring bare `--flag` and `--flag=false|true`. */
+function bool(flag, fallback) {
+    if (flag === undefined)
+        return fallback;
+    if (typeof flag === 'boolean')
+        return flag;
+    return !/^(false|0|no|off)$/i.test(flag);
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => (data += chunk));
+        process.stdin.on('end', () => resolve(data));
+    });
+}
+async function runServe(flags) {
+    const wsHost = str(flags['ws-host']) ?? DEFAULT_HOST;
+    const wsPort = num(flags['ws-port'], DEFAULT_WS_PORT);
+    const controlHost = str(flags['control-host']) ?? DEFAULT_HOST;
+    const controlPort = num(flags['control-port'], DEFAULT_CONTROL_PORT);
+    const defaultMode = flags['unsafe'] ? 'unsafe' : 'safe';
+    const bridge = new BridgeServer({ host: wsHost, port: wsPort });
+    bridge.on('connect', (tab) => console.error(`[etch-connector] + tab "${tab.name}" (${tab.url})`));
+    bridge.on('disconnect', (tab) => console.error(`[etch-connector] - tab "${tab.name}"`));
+    const { port: boundWsPort } = await bridge.listen();
+    const control = createControlServer(bridge, { defaultMode });
+    await new Promise((resolve) => control.listen(controlPort, controlHost, resolve));
+    // Periodic liveness probe so dead tabs that never fired `close` get pruned.
+    const heartbeat = setInterval(() => bridge.pingAll(), 30_000);
+    heartbeat.unref();
+    console.error(`[etch-connector] bridge   ws://${wsHost}:${boundWsPort}`);
+    console.error(`[etch-connector] control  ${controlBaseUrl({ host: controlHost, port: controlPort })}`);
+    console.error(`[etch-connector] default mode: ${defaultMode}${defaultMode === 'unsafe' ? '  ⚠  scripts get full access to the page' : '  (scripts see only window.etch + JS built-ins)'}`);
+    console.error('[etch-connector] In an Etch builder tab, run:');
+    console.error(`[etch-connector]     etch.connectTo('my-tab'${boundWsPort === DEFAULT_WS_PORT ? '' : `, { port: ${boundWsPort} }`})`);
+    console.error('[etch-connector] then drive it with:  etch-connector eval -t my-tab "return window.etch.apiVersion"');
+    const shutdown = () => {
+        clearInterval(heartbeat);
+        control.close();
+        void bridge.close().then(() => process.exit(0));
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+function controlUrlFromFlags(flags) {
+    return controlBaseUrl({
+        host: str(flags['control-host']),
+        port: num(flags['control-port'], DEFAULT_CONTROL_PORT)
+    });
+}
+/**
+ * CDP (Chrome remote-debugging) config when the caller opted in via `--cdp`,
+ * `--cdp-port`, `--cdp-host`, or `--remote-debugging-port`; otherwise null.
+ */
+function cdpFromFlags(flags) {
+    const rdp = flags['remote-debugging-port'];
+    const opted = Boolean(flags['cdp']) ||
+        rdp !== undefined ||
+        flags['cdp-port'] !== undefined ||
+        flags['cdp-host'] !== undefined;
+    if (!opted)
+        return null;
+    return {
+        host: str(flags['cdp-host']) ?? DEFAULT_HOST,
+        port: num(flags['cdp-port'], num(rdp, DEFAULT_CDP_PORT))
+    };
+}
+/** Connect a CDP client to the matched target, run `fn`, then always close. */
+async function withCdp(cdp, match, fn) {
+    const client = new CdpClient(cdp);
+    try {
+        await client.connect(match);
+        return await fn(client);
+    }
+    finally {
+        await client.close();
+    }
+}
+/**
+ * Shown when no CDP endpoint can be reached. Addressed to the agent/LLM: it
+ * must relay these steps to the user rather than act on them itself — launching
+ * a fresh browser here would not carry the user's WordPress/Etch login.
+ */
+function cdpLaunchHint(port) {
+    return [
+        '',
+        `No Chromium browser with remote debugging is open on port ${port}.`,
+        '',
+        'AGENT: do not launch a browser yourself — a fresh instance would not have',
+        "the user's WordPress/Etch session. Tell the user to start their own browser",
+        'with remote debugging enabled, then retry this command:',
+        '',
+        '  1. Fully quit the Chromium-family browser first (Chrome / Brave / Edge /',
+        "     Chromium) — the flag is ignored if it's already running.",
+        '  2. Relaunch it with the remote-debugging flag:',
+        `       Linux:   google-chrome --remote-debugging-port=${port}`,
+        `       macOS:   open -a "Google Chrome" --args --remote-debugging-port=${port}`,
+        `       Windows: chrome.exe --remote-debugging-port=${port}`,
+        '       (Brave / Edge / Chromium work the same — just swap the binary.)',
+        '  3. Open the Etch builder tab and log in, then re-run this command.',
+        '',
+        'Firefox is not supported — CDP requires a Chromium-family browser.'
+    ].join('\n');
+}
+/** Map a thrown CDP error to the right exit: 2 for script throws, 1 otherwise. */
+function failCdp(err, port = DEFAULT_CDP_PORT) {
+    if (err instanceof CdpEvalError) {
+        console.error(`script error: ${err.message}`);
+        if (err.details)
+            console.error(err.details);
+        process.exit(2);
+    }
+    console.error(err instanceof CdpError ? err.message : String(err));
+    // The connection-failure message comes from CdpClient.listTargets/connect.
+    if (err instanceof CdpError &&
+        /cannot reach|ECONNREFUSED|failed to attach/i.test(err.message)) {
+        console.error(cdpLaunchHint(port));
+    }
+    process.exit(1);
+}
+async function runTabs(flags) {
+    const cdp = cdpFromFlags(flags);
+    if (cdp) {
+        const targets = await CdpClient.listTargets(cdp).catch((e) => failCdp(e, cdp.port));
+        if (flags['json']) {
+            process.stdout.write(`${JSON.stringify(targets, null, 2)}\n`);
+            return;
+        }
+        if (targets.length === 0) {
+            console.error('No Chrome page targets open.');
+            return;
+        }
+        for (const t of targets)
+            process.stdout.write(`${t.title}\t${t.url}\n`);
+        return;
+    }
+    const res = await fetch(`${controlUrlFromFlags(flags)}/tabs`).catch((err) => {
+        throw new Error(`cannot reach the connector daemon — is \`etch-connector serve\` running? (${err})`);
+    });
+    const { tabs } = (await res.json());
+    if (flags['json']) {
+        process.stdout.write(`${JSON.stringify(tabs, null, 2)}\n`);
+        return;
+    }
+    if (tabs.length === 0) {
+        console.error('No Etch tabs connected.');
+        return;
+    }
+    for (const tab of tabs) {
+        process.stdout.write(`${tab.name}\t${tab.hasEtch ? 'etch' : 'no-etch'}\t${tab.title}\t${tab.url}\n`);
+    }
+}
+async function gatherCode(positional, flags) {
+    const file = str(flags['file']);
+    if (file)
+        return readFileSync(file, 'utf8');
+    if (positional.length > 0)
+        return positional.join(' ');
+    return (await readStdin()).trim();
+}
+async function runEval(positional, flags) {
+    const code = await gatherCode(positional, flags);
+    if (!code) {
+        console.error('eval: no script provided (pass code as an argument, --file, or stdin)');
+        process.exit(1);
+    }
+    const timeoutMs = typeof flags['timeout'] === 'string'
+        ? num(flags['timeout'], 30_000)
+        : undefined;
+    // CDP mode: eval over Chrome remote debugging (full window access, no daemon).
+    const cdp = cdpFromFlags(flags);
+    if (cdp) {
+        try {
+            const value = await withCdp(cdp, str(flags['tab']), (c) => c.eval(code, { timeoutMs }));
+            process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+        }
+        catch (err) {
+            failCdp(err, cdp.port);
+        }
+        return;
+    }
+    // --unsafe / --safe override the daemon default; omitting both defers to it.
+    let mode;
+    if (flags['unsafe'])
+        mode = 'unsafe';
+    else if (flags['safe'])
+        mode = 'safe';
+    if (mode === 'unsafe') {
+        console.error('⚠  running in unsafe mode — the script has full access to the page');
+    }
+    const body = {
+        tab: str(flags['tab']),
+        code,
+        timeoutMs,
+        mode
+    };
+    const res = await fetch(`${controlUrlFromFlags(flags)}/eval`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body)
+    }).catch((err) => {
+        throw new Error(`cannot reach the connector daemon — is \`etch-connector serve\` running? (${err})`);
+    });
+    if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        console.error(`eval failed: ${err.error ?? res.statusText}`);
+        process.exit(1);
+    }
+    const result = (await res.json());
+    // Forwarded console output → stderr, so stdout stays clean for the value.
+    for (const log of result.logs) {
+        const text = log.args
+            .map((a) => (typeof a === 'string' ? a : JSON.stringify(a)))
+            .join(' ');
+        console.error(`[${log.level}] ${text}`);
+    }
+    if (!result.ok) {
+        console.error(`script error: ${result.error}`);
+        if (result.stack)
+            console.error(result.stack);
+        process.exit(2);
+    }
+    process.stdout.write(`${JSON.stringify(result.value, null, 2)}\n`);
+}
+/** `shot` / `html` / `computed` are CDP-only; default to localhost:9222. */
+function requireCdp(flags) {
+    return (cdpFromFlags(flags) ?? { host: DEFAULT_HOST, port: DEFAULT_CDP_PORT });
+}
+async function runShot(flags) {
+    const cdp = requireCdp(flags);
+    const selector = str(flags['selector']);
+    const full = Boolean(flags['full']);
+    const format = flags['jpeg'] ? 'jpeg' : 'png';
+    const freeze = bool(flags['freeze'], true); // default on (animations → deterministic)
+    const out = str(flags['out']) ?? `etch-shot.${format === 'jpeg' ? 'jpg' : 'png'}`;
+    try {
+        const buf = await withCdp(cdp, str(flags['tab']), (c) => c.screenshot({ selector, full, format, freeze }));
+        writeFileSync(out, buf);
+        const scope = selector
+            ? ` — clipped to ${selector}`
+            : full
+                ? ' — full page'
+                : ' — viewport';
+        console.error(`wrote ${out} (${buf.length} bytes)${scope}${freeze ? ' (frozen)' : ''}`);
+    }
+    catch (err) {
+        failCdp(err, cdp.port);
+    }
+}
+async function runHtml(positional, flags) {
+    const selector = str(flags['selector']) ?? positional[0];
+    if (!selector) {
+        console.error('html: pass a CSS selector (-s/--selector or positional)');
+        process.exit(1);
+    }
+    const cdp = requireCdp(flags);
+    try {
+        const html = await withCdp(cdp, str(flags['tab']), (c) => c.outerHtml(selector));
+        process.stdout.write(`${html}\n`);
+    }
+    catch (err) {
+        failCdp(err, cdp.port);
+    }
+}
+async function runComputed(positional, flags) {
+    const selector = str(flags['selector']) ?? positional[0];
+    if (!selector) {
+        console.error('computed: pass a CSS selector (-s/--selector or positional)');
+        process.exit(1);
+    }
+    const props = str(flags['props'])
+        ?.split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+    const cdp = requireCdp(flags);
+    try {
+        const style = await withCdp(cdp, str(flags['tab']), (c) => c.computedStyle(selector, props));
+        process.stdout.write(`${JSON.stringify(style, null, 2)}\n`);
+    }
+    catch (err) {
+        failCdp(err, cdp.port);
+    }
+}
+function printHelp() {
+    console.error(`etch-connector — drive a live Etch tab from the command line
+
+Usage:
+  etch-connector serve [--ws-port ${DEFAULT_WS_PORT}] [--control-port ${DEFAULT_CONTROL_PORT}] [--ws-host ${DEFAULT_HOST}] [--unsafe]
+  etch-connector tabs  [--json] [--control-port ${DEFAULT_CONTROL_PORT}] [--cdp]
+  etch-connector eval  [code] [-t|--tab name] [-f|--file path] [--timeout ms] [--safe|--unsafe|--cdp]
+  etch-connector shot      [-t name] [-s|--selector css] [--full] [--jpeg] [-o|--out file] [--freeze=false]   (CDP)
+  etch-connector html      <selector> [-t name]                                              (CDP)
+  etch-connector computed  <selector> [-t name] [--props a,b,c]                               (CDP)
+
+Two backends:
+  bridge  (default) the tab dials in via etch.connectTo(); page-sandboxed.
+          safe   = script sees only "etch" + JS built-ins (default)
+          unsafe = full page access (--unsafe per eval, or serve --unsafe)
+  cdp     connect OUT to a Chrome started with --remote-debugging-port=${DEFAULT_CDP_PORT}.
+          No daemon. Runs at DevTools privilege: full "window", plus screenshots,
+          rendered HTML, and computed styles. Opt in with --cdp (or --cdp-port /
+          --remote-debugging-port / --cdp-host). Target a tab with -t <url|title substring>.
+
+AGENT: before running anything, ask the user how they want to connect — bridge
+safe (API only), bridge unsafe (full page access), or cdp (DevTools privilege).
+Each grants more reach than the last; don't assume — let the user choose.
+
+Examples:
+  etch-connector serve
+  etch-connector tabs
+  etch-connector eval -t homepage "return etch.apiVersion"
+  echo "return await etch.blocks.getTree()" | etch-connector eval -t homepage
+  etch-connector eval -t homepage -f ./script.js
+  # CDP backend (Chrome launched with --remote-debugging-port=${DEFAULT_CDP_PORT}):
+  etch-connector tabs --cdp
+  etch-connector eval --cdp -t etch "return document.title"
+  etch-connector shot --cdp -t etch -s .orbit -o orbit.png
+  etch-connector computed --cdp -t etch -s .orbit__chip --props transform,animation-duration
+
+The eval body runs as an async function, so it may 'return' a value and use
+top-level 'await'. In bridge safe mode reference the API as "etch.*" ("window"
+is withheld); in cdp mode the full page is available.
+
+Docs (AGENT: pull these BEFORE writing scripts against etch.* — the API surface
+changes and training data may be stale):
+  Context7 MCP (preferred)  resolve-library-id "Etch" → query-docs for the
+                            specific call (e.g. etch.blocks.create).
+  Manual fallback           https://docs.etchwp.com/public-api (window.etch.*)
+                            https://docs.etchwp.com (everything else)
+See AGENTS.md for project conventions.`);
+}
+async function main() {
+    const { command, positional, flags } = parseArgs(process.argv.slice(2));
+    switch (command) {
+        case 'serve':
+            return runServe(flags);
+        case 'tabs':
+            return runTabs(flags);
+        case 'eval':
+            return runEval(positional, flags);
+        case 'shot':
+            return runShot(flags);
+        case 'html':
+            return runHtml(positional, flags);
+        case 'computed':
+            return runComputed(positional, flags);
+        case 'help':
+        case '--help':
+        case '-h':
+            return printHelp();
+        default:
+            console.error(`unknown command: ${command}\n`);
+            printHelp();
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(String(err instanceof Error ? err.message : err));
+    process.exit(1);
+});

package/dist/control-server.js

@@ -0,0 +1,108 @@
+/**
+ * HTTP control API — the seam between the bridge core and whatever drives it.
+ *
+ * The `serve` daemon holds the live WebSocket connections to tabs, so a one-shot
+ * CLI invocation (or any other local process) can't reach them directly. This
+ * small loopback HTTP server is how they ask the daemon to do work:
+ *
+ *   GET  /health          → { ok: true }
+ *   GET  /tabs            → TabInfo[]
+ *   POST /eval            → { tab?, code, timeoutMs? }  → EvalResult
+ *
+ * It is deliberately the same shape a future MCP server would call, so swapping
+ * the CLI for MCP changes the caller, not this contract.
+ */
+import { createServer } from 'node:http';
+import { z } from 'zod';
+import { BridgeError } from './bridge-server.js';
+import { DEFAULT_CONTROL_PORT, DEFAULT_HOST } from './protocol.js';
+const evalBodySchema = z.object({
+    tab: z.string().min(1).optional(),
+    code: z.string().min(1),
+    timeoutMs: z.number().int().positive().optional(),
+    mode: z.enum(['safe', 'unsafe']).optional()
+});
+function send(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(payload)
+    });
+    res.end(payload);
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            // Guard against an unbounded body; scripts are small.
+            if (size > 5_000_000) {
+                reject(new Error('request body too large'));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+/** HTTP status for an operational bridge failure. */
+function statusForBridgeError(code) {
+    switch (code) {
+        case 'NO_TAB':
+        case 'AMBIGUOUS_TAB':
+            return 409;
+        case 'TIMEOUT':
+            return 504;
+        case 'DISCONNECTED':
+            return 502;
+    }
+}
+export function createControlServer(bridge, options = {}) {
+    const defaultMode = options.defaultMode ?? 'safe';
+    return createServer(async (req, res) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        if (req.method === 'GET' && url.pathname === '/health') {
+            return send(res, 200, { ok: true });
+        }
+        if (req.method === 'GET' && url.pathname === '/tabs') {
+            return send(res, 200, { tabs: bridge.listTabs() });
+        }
+        if (req.method === 'POST' && url.pathname === '/eval') {
+            let parsed;
+            try {
+                parsed = evalBodySchema.parse(JSON.parse(await readBody(req)));
+            }
+            catch (err) {
+                return send(res, 400, {
+                    error: `invalid request body: ${String(err)}`
+                });
+            }
+            try {
+                const result = await bridge.evalInTab(parsed.code, {
+                    tab: parsed.tab,
+                    timeoutMs: parsed.timeoutMs,
+                    mode: parsed.mode ?? defaultMode
+                });
+                return send(res, 200, result);
+            }
+            catch (err) {
+                if (err instanceof BridgeError) {
+                    return send(res, statusForBridgeError(err.code), {
+                        error: err.message,
+                        code: err.code
+                    });
+                }
+                return send(res, 500, { error: String(err) });
+            }
+        }
+        send(res, 404, { error: `not found: ${req.method} ${url.pathname}` });
+    });
+}
+export function controlBaseUrl(options = {}) {
+    const host = options.host ?? DEFAULT_HOST;
+    const port = options.port ?? DEFAULT_CONTROL_PORT;
+    return `http://${host}:${port}`;
+}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * Programmatic entry point.
+ *
+ * Import the core to embed the connector in another process — most notably a
+ * future MCP server, which would `new BridgeServer()`, register an
+ * `eval_etch_script` tool that calls `evalInTab`, and a `list_etch_tabs` tool
+ * that calls `listTabs`. No transport code needs to move to get there.
+ */
+export { BridgeServer, BridgeError } from './bridge-server.js';
+export { createControlServer, controlBaseUrl } from './control-server.js';
+export { DEFAULT_WS_PORT, DEFAULT_CONTROL_PORT, DEFAULT_HOST } from './protocol.js';

package/dist/manual.js

@@ -0,0 +1,2 @@
+// AUTO-GENERATED from README.md by scripts/build-manual.mjs — do not edit by hand.
+export const MANUAL = "# etch-connector\n\nA tiny local bridge that lets an AI harness — Claude Code, Cowork, or any tool\nthat can run a shell command — **drive a live Etch builder tab** by evaluating\nscripts against the [`etch-public-api`](https://www.npmjs.com/package/@digital-gravy/etch-public-api)\nsurface (`window.etch.*`).\n\nEtch's scriptable API only exists *inside the browser*. There is no server you\ncan call directly. So this connector inverts the usual direction: the browser\n**dials out** to the connector over a WebSocket (the same way Chrome remote\ndebugging works, but in reverse), and the connector relays scripts into the tab\nand streams the result back.\n\n```\nClaude Code / Cowork\n      │  shell:  etch-connector eval -t homepage \"return ...\"\n      ▼\n  etch-connector  (the `serve` daemon)\n      │  ▲   WebSocket  (tab dials in via etch.connectTo)\n      ▼  │\n  Etch builder tab  ──►  window.etch.*\n```\n\n## Status\n\nThis is an **eval relay**: the harness sends a JavaScript snippet, the page runs\nit as an async function, and the return value + console output come back. It is\nintentionally *not* an MCP server yet, but it is built so that becoming one is a\nthin add — see [Going to MCP](#going-to-mcp-later).\n\nScripts run in one of two modes, enforced by the page:\n\n- **`safe`** (default) — the script sees only `etch` and the standard JS\n  built-ins. `window`, `document`, `fetch`, storage, `eval`, … are withheld.\n- **`unsafe`** — the script runs with full access to the page. Opt in\n  explicitly.\n\n## Install\n\n```bash\nbun install   # or npm install\n```\n\n## Use\n\n### 1. Start the daemon (once)\n\n```bash\nbun run serve\n# bridge   ws://127.0.0.1:7331\n# control  http://127.0.0.1:7332\n```\n\n### 2. Connect a tab\n\nOpen an Etch builder page and, in the browser console:\n\n```js\netch.connectTo('homepage');\n```\n\n(`connectTo` is part of the public API; it opens the WebSocket back to the\ndaemon and registers this tab under the given name. Pass `{ port: <n> }` if you\nstarted the daemon on a non-default WebSocket port.)\n\n### 3. Drive it\n\n```bash\n# list connected tabs\netch-connector tabs\n\n# run a script (value → stdout, console output → stderr).\n# Default is safe mode: reference the API as `etch.*`.\netch-connector eval -t homepage \"return etch.apiVersion\"\n\n# multi-line / from a file / from stdin\netch-connector eval -t homepage -f ./script.js\necho \"return await etch.blocks.getTree()\" | etch-connector eval -t homepage\n\n# full page access (opt in)\netch-connector eval -t homepage --unsafe \"return document.title\"\n```\n\nThe script body runs as an **async function**, so it can `return` a value and\nuse top-level `await`. In safe mode write scripts against the `etch-public-api`\nsurface via the `etch` binding (`window` is not available). Examples:\n\n```js\nreturn etch.apiVersion;\nreturn await etch.blocks.getTree();\netch.blocks.select('block-id-123');\nconst groups = await etch.fields.listGroupsAsync();\nreturn groups.length;\n```\n\n### Modes\n\n| Mode            | In scope                              | Use for                          |\n| --------------- | ------------------------------------- | -------------------------------- |\n| `safe` (default)| `etch` + standard JS built-ins        | Driving the builder via the API  |\n| `unsafe`        | everything (`window`, `document`, …)  | Debugging, page internals        |\n\nPick per call with `--safe` / `--unsafe`, or change the daemon default with\n`serve --unsafe`. A per-call flag overrides the daemon default.\n\n### Output contract (for agents)\n\n`eval` keeps stdout clean so a harness can capture it as the result:\n\n- **stdout** — the script's return value, as pretty JSON.\n- **stderr** — forwarded `console.*` output, prefixed with the level.\n- **exit code** — `0` success · `2` the script threw · `1` operational failure\n  (no such tab, ambiguous target, timeout, daemon unreachable).\n\n## CLI\n\n```\netch-connector serve [--ws-port 7331] [--control-port 7332] [--ws-host 127.0.0.1] [--unsafe]\netch-connector tabs  [--json] [--control-port 7332]\netch-connector eval  [code] [-t|--tab name] [-f|--file path] [--timeout ms] [--safe|--unsafe]\n```\n\nWhen exactly one tab is connected, `-t` is optional. With several tabs you must\nname one.\n\n## HTTP control API\n\nThe daemon also exposes a loopback HTTP API (this is the seam the CLI uses, and\nthe same one a future MCP server would call):\n\n| Method | Path      | Body                                 | Returns      |\n| ------ | --------- | ------------------------------------ | ------------ |\n| GET    | `/health` | —                                    | `{ ok }`     |\n| GET    | `/tabs`   | —                                    | `{ tabs }`   |\n| POST   | `/eval`   | `{ tab?, code, timeoutMs?, mode? }`  | `EvalResult` |\n\n## Architecture\n\n- [`src/protocol.ts`](src/protocol.ts) — the wire format, mirrored from the\n  Etch-side `bridge.ts`. Keep the two in sync.\n- [`src/bridge-server.ts`](src/bridge-server.ts) — `BridgeServer`, the\n  transport-agnostic core: owns the sockets, tracks tabs by name, correlates\n  requests, handles timeouts and disconnects. **This is the reusable piece.**\n- [`src/control-server.ts`](src/control-server.ts) — the HTTP control API over\n  the core.\n- [`src/cli.ts`](src/cli.ts) — the `serve` / `tabs` / `eval` commands.\n\n## Going to MCP later\n\nNothing in the transport changes. An MCP server is `new BridgeServer()` plus two\ntool definitions over the same core:\n\n```ts\nimport { BridgeServer } from 'etch-connector';\n\nconst bridge = new BridgeServer();\nawait bridge.listen();\n\n// list_etch_tabs   -> bridge.listTabs()\n// eval_etch_script -> bridge.evalInTab(code, { tab })\n```\n\nWhen you want first-class per-tool MCP tools (rather than one eval tool), have\nthe Etch tab advertise a tool manifest in its `hello` and register those\ndynamically — keeping a single source of truth in the browser registry.\n\n## Security\n\nTwo layers, neither a substitute for the other:\n\n**Transport.** Everything binds to `127.0.0.1`, so any local process can reach\nthe daemon. Run it only on a trusted machine and do not expose the ports beyond\nloopback.\n\n**Execution.** `safe` mode (the default) runs the script inside a `with`-bound\nProxy that exposes only `etch` plus the standard JS built-ins and throws on\n`window`, `document`, `fetch`, storage, `eval`, `Function`, … This is a\n**guardrail, not a hardened sandbox**: because the script shares the page's JS\nrealm, a *determined* author can still reach globals through prototype /\nconstructor chains (e.g. `({}).constructor.constructor`). Safe mode reliably\nkeeps casual and AI-authored scripts on the `etch` surface and closes the\nobvious escape hatches; it does **not** contain hostile code.\n\n`unsafe` mode runs the script with full, unconstrained access to the page — only\nuse it for trusted debugging.\n\nFor a true boundary against adversarial scripts you would need to harden the\nrealm (SES `lockdown()`), which freezes all intrinsics app-wide and is out of\nscope for this relay. The enforcement lives in the Etch page (`bridge.ts`), not\nthis connector — the connector only carries the requested mode; a string filter\nhere would be theater.\n";

package/dist/protocol.js

@@ -0,0 +1,38 @@
+/**
+ * Wire protocol shared with the Etch-side bridge.
+ *
+ * The browser end of this protocol lives in the Etch repo at
+ * `src/frontend/Builder/src/composables/publicApi/bridge.ts` (`etch.connectTo`).
+ * This file is the server's mirror of those message shapes — keep the two in
+ * sync. The page is the WebSocket *client*; this connector is the *server*.
+ *
+ * Direction of travel:
+ *   server → page :  EvalRequest | PingMessage
+ *   page → server :  HelloMessage | LogMessage | ResultMessage | ErrorMessage | PongMessage
+ */
+/** Default WebSocket port the Etch bridge dials (`ws://127.0.0.1:7331`). */
+export const DEFAULT_WS_PORT = 7331;
+/** Default HTTP control-API port the CLI / AI harness talks to. */
+export const DEFAULT_CONTROL_PORT = 7332;
+export const DEFAULT_HOST = '127.0.0.1';
+/** Narrowing parse of an inbound page message; returns null on anything invalid. */
+export function parsePageMessage(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const type = value.type;
+    if (type === 'hello' ||
+        type === 'log' ||
+        type === 'result' ||
+        type === 'error' ||
+        type === 'pong') {
+        return value;
+    }
+    return null;
+}