@digital-gravy/etch-connector 0.1.1

package/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2026 Digital Gravy LLC. All rights reserved.
+
+Permission to install and use this software (the "Software") for its intended
+purpose, including via package managers such as npm, is granted free of charge
+solely to persons who hold a valid and active "Etch" license. This permission
+is conditional upon, and continues only for so long as, the user maintains a
+valid and active Etch license; it terminates automatically if that license
+lapses, expires, or is revoked.
+
+All other rights are reserved by Digital Gravy LLC. Without the prior written
+permission of Digital Gravy LLC, no person may copy, modify, merge, publish,
+distribute, sublicense, sell, reverse engineer, decompile, disassemble, or
+create derivative works of the Software or its source code, in whole or in
+part.
+
+Unauthorized reproduction, modification, or distribution of this software, or
+any portion of it, may result in civil and criminal penalties, and will be
+prosecuted to the maximum extent possible under the law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# etch-connector
+
+A tiny local bridge that lets an AI harness — Claude Code, Cowork, or any tool
+that can run a shell command — **drive a live Etch builder tab** by evaluating
+scripts against the [`etch-public-api`](https://www.npmjs.com/package/@digital-gravy/etch-public-api)
+surface (`window.etch.*`).
+
+Etch's scriptable API only exists _inside the browser_. There is no server you
+can call directly. So this connector inverts the usual direction: the browser
+**dials out** to the connector over a WebSocket (the same way Chrome remote
+debugging works, but in reverse), and the connector relays scripts into the tab
+and streams the result back.
+
+```
+Claude Code / Cowork
+      │  shell:  etch-connector eval -t homepage "return ..."
+      ▼
+  etch-connector  (the `serve` daemon)
+      │  ▲   WebSocket  (tab dials in via etch.connectTo)
+      ▼  │
+  Etch builder tab  ──►  window.etch.*
+```
+
+## Status
+
+This is an **eval relay**: the harness sends a JavaScript snippet, the page runs
+it as an async function, and the return value + console output come back. It is
+intentionally _not_ an MCP server yet, but it is built so that becoming one is a
+thin add — see [Going to MCP](#going-to-mcp-later).
+
+Scripts run in one of two modes, enforced by the page:
+
+- **`safe`** (default) — the script sees only `etch` and the standard JS
+  built-ins. `window`, `document`, `fetch`, storage, `eval`, … are withheld.
+- **`unsafe`** — the script runs with full access to the page. Opt in
+  explicitly.
+
+## Install
+
+```bash
+bun install   # or npm install
+```
+
+## Use
+
+### 1. Start the daemon (once)
+
+```bash
+bun run serve
+# bridge   ws://127.0.0.1:7331
+# control  http://127.0.0.1:7332
+```
+
+### 2. Connect a tab
+
+Open an Etch builder page and, in the browser console:
+
+```js
+etch.connectTo('homepage');
+```
+
+(`connectTo` is part of the public API; it opens the WebSocket back to the
+daemon and registers this tab under the given name. Pass `{ port: <n> }` if you
+started the daemon on a non-default WebSocket port.)
+
+### 3. Drive it
+
+```bash
+# list connected tabs
+etch-connector tabs
+
+# run a script (value → stdout, console output → stderr).
+# Default is safe mode: reference the API as `etch.*`.
+etch-connector eval -t homepage "return etch.apiVersion"
+
+# multi-line / from a file / from stdin
+etch-connector eval -t homepage -f ./script.js
+echo "return await etch.blocks.getTree()" | etch-connector eval -t homepage
+
+# full page access (opt in)
+etch-connector eval -t homepage --unsafe "return document.title"
+```
+
+The script body runs as an **async function**, so it can `return` a value and
+use top-level `await`. In safe mode write scripts against the `etch-public-api`
+surface via the `etch` binding (`window` is not available). Examples:
+
+```js
+return etch.apiVersion;
+return await etch.blocks.getTree();
+etch.blocks.select('block-id-123');
+const groups = await etch.fields.listGroupsAsync();
+return groups.length;
+```
+
+### Modes
+
+| Mode             | In scope                             | Use for                         |
+| ---------------- | ------------------------------------ | ------------------------------- |
+| `safe` (default) | `etch` + standard JS built-ins       | Driving the builder via the API |
+| `unsafe`         | everything (`window`, `document`, …) | Debugging, page internals       |
+
+Pick per call with `--safe` / `--unsafe`, or change the daemon default with
+`serve --unsafe`. A per-call flag overrides the daemon default.
+
+### Output contract (for agents)
+
+`eval` keeps stdout clean so a harness can capture it as the result:
+
+- **stdout** — the script's return value, as pretty JSON.
+- **stderr** — forwarded `console.*` output, prefixed with the level.
+- **exit code** — `0` success · `2` the script threw · `1` operational failure
+  (no such tab, ambiguous target, timeout, daemon unreachable).
+
+## Documentation (for AI agents)
+
+Before writing scripts against `etch.*`, **always pull the current Etch
+documentation first** — the `etch-public-api` surface changes and training data
+may be stale. Fetch the docs, _then_ write scripts.
+
+### Preferred: Context7 MCP
+
+If a Context7 MCP server is available, fetch the Etch docs through it:
+
+1. Call `resolve-library-id` with the library name **`Etch`** (pass the user's
+   question alongside it).
+2. From the matches, pick the entry for Etch / the Etch public API — prefer an
+   exact name match, and a version-specific id if the user named a version.
+3. Call `query-docs` with the selected library id and the specific question
+   (e.g. _"how do I create a block with etch.blocks.create"_).
+4. Write the script using the fetched docs, referencing `etch.*` exactly as the
+   docs show.
+
+### Fallback: pull the docs manually
+
+If no Context7 server is available, fetch the documentation directly from the
+Etch docs site:
+
+- **Public API reference:** <https://docs.etchwp.com/public-api> — the
+  authoritative surface for `window.etch.*` (`etch.blocks`, `etch.styles`,
+  `etch.components`, `etch.fields`, `etch.stylesheets`, …).
+- **Main docs:** <https://docs.etchwp.com> — for everything else about Etch
+  (concepts, blocks, components, ACSS, units, …). Follow the links from there to
+  the specific page that answers the question.
+
+Read the relevant page(s), then write scripts against the documented API. On top
+of the API docs, follow the project-specific conventions in
+[`AGENTS.md`](AGENTS.md).
+
+## CLI
+
+```
+etch-connector — drive a live Etch tab from the command line
+
+Usage:
+  etch-connector serve [--ws-port 7331] [--control-port 7332] [--ws-host 127.0.0.1] [--unsafe]
+  etch-connector tabs  [--json] [--control-port 7332] [--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=9222.
+          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>.
+
+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=9222):
+  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
+```
+
+When exactly one tab is connected, `-t` is optional. With several tabs you must
+name one.
+
+## HTTP control API
+
+The daemon also exposes a loopback HTTP API (this is the seam the CLI uses, and
+the same one a future MCP server would call):
+
+| Method | Path      | Body                                | Returns      |
+| ------ | --------- | ----------------------------------- | ------------ |
+| GET    | `/health` | —                                   | `{ ok }`     |
+| GET    | `/tabs`   | —                                   | `{ tabs }`   |
+| POST   | `/eval`   | `{ tab?, code, timeoutMs?, mode? }` | `EvalResult` |
+
+## Architecture
+
+- [`src/protocol.ts`](src/protocol.ts) — the wire format, mirrored from the
+  Etch-side `bridge.ts`. Keep the two in sync.
+- [`src/bridge-server.ts`](src/bridge-server.ts) — `BridgeServer`, the
+  transport-agnostic core: owns the sockets, tracks tabs by name, correlates
+  requests, handles timeouts and disconnects. **This is the reusable piece.**
+- [`src/control-server.ts`](src/control-server.ts) — the HTTP control API over
+  the core.
+- [`src/cli.ts`](src/cli.ts) — the `serve` / `tabs` / `eval` commands.
+
+## Going to MCP later
+
+Nothing in the transport changes. An MCP server is `new BridgeServer()` plus two
+tool definitions over the same core:
+
+```ts
+import { BridgeServer } from 'etch-connector';
+
+const bridge = new BridgeServer();
+await bridge.listen();
+
+// list_etch_tabs   -> bridge.listTabs()
+// eval_etch_script -> bridge.evalInTab(code, { tab })
+```
+
+When you want first-class per-tool MCP tools (rather than one eval tool), have
+the Etch tab advertise a tool manifest in its `hello` and register those
+dynamically — keeping a single source of truth in the browser registry.
+
+## Security
+
+Two layers, neither a substitute for the other:
+
+**Transport.** Everything binds to `127.0.0.1`, so any local process can reach
+the daemon. Run it only on a trusted machine and do not expose the ports beyond
+loopback.
+
+**Execution.** `safe` mode (the default) runs the script inside a `with`-bound
+Proxy that exposes only `etch` plus the standard JS built-ins and throws on
+`window`, `document`, `fetch`, storage, `eval`, `Function`, … This is a
+**guardrail, not a hardened sandbox**: because the script shares the page's JS
+realm, a _determined_ author can still reach globals through prototype /
+constructor chains (e.g. `({}).constructor.constructor`). Safe mode reliably
+keeps casual and AI-authored scripts on the `etch` surface and closes the
+obvious escape hatches; it does **not** contain hostile code.
+
+`unsafe` mode runs the script with full, unconstrained access to the page — only
+use it for trusted debugging.
+
+For a true boundary against adversarial scripts you would need to harden the
+realm (SES `lockdown()`), which freezes all intrinsics app-wide and is out of
+scope for this relay. The enforcement lives in the Etch page (`bridge.ts`), not
+this connector — the connector only carries the requested mode; a string filter
+here would be theater.

package/dist/bridge-server.js

@@ -0,0 +1,242 @@
+/**
+ * The interface-agnostic core of etch-connector.
+ *
+ * `BridgeServer` owns the WebSocket endpoint that Etch tabs dial into via
+ * `etch.connectTo(...)`, tracks every connected tab by the name it registered
+ * under, and exposes a single capability: {@link BridgeServer.evalInTab}.
+ *
+ * Everything that drives the connector — the HTTP control API and CLI today, an
+ * MCP server tomorrow — is a thin adapter over this class. Keeping the transport
+ * concerns here (sockets, correlation, timeouts, cleanup) means a future MCP
+ * server is just `new BridgeServer()` plus tool definitions; no protocol code
+ * moves.
+ */
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { WebSocketServer } from 'ws';
+import { DEFAULT_HOST, DEFAULT_WS_PORT, parsePageMessage } from './protocol.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Raised for operational failures (no matching tab, ambiguous target, timeout,
+ * disconnect) so callers can distinguish them from a script that threw.
+ */
+export class BridgeError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'BridgeError';
+    }
+}
+export class BridgeServer extends EventEmitter {
+    /* eslint-enable @typescript-eslint/no-unsafe-declaration-merging */
+    host;
+    port;
+    wss = null;
+    sessions = new Set();
+    constructor(options = {}) {
+        super();
+        this.host = options.host ?? DEFAULT_HOST;
+        this.port = options.port ?? DEFAULT_WS_PORT;
+    }
+    /** Start listening. Resolves with the bound address (useful when port is 0). */
+    listen() {
+        return new Promise((resolve, reject) => {
+            const wss = new WebSocketServer({
+                host: this.host,
+                port: this.port
+            });
+            wss.on('connection', (ws) => this.onConnection(ws));
+            wss.on('error', reject);
+            wss.on('listening', () => {
+                const address = wss.address();
+                const port = typeof address === 'object' && address
+                    ? address.port
+                    : this.port;
+                resolve({ host: this.host, port });
+            });
+            this.wss = wss;
+        });
+    }
+    /** Stop listening and tear down every session. */
+    close() {
+        return new Promise((resolve) => {
+            for (const session of this.sessions) {
+                this.failPending(session, new BridgeError('connector shutting down', 'DISCONNECTED'));
+                try {
+                    session.ws.terminate();
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            this.sessions.clear();
+            if (!this.wss)
+                return resolve();
+            this.wss.close(() => resolve());
+            this.wss = null;
+        });
+    }
+    /** Snapshot of every tab that has completed its handshake. */
+    listTabs() {
+        const tabs = [];
+        for (const session of this.sessions) {
+            if (session.info)
+                tabs.push(session.info);
+        }
+        return tabs.sort((a, b) => b.connectedAt - a.connectedAt);
+    }
+    /**
+     * Evaluate `code` in a tab as an async function body (so it can `return` and
+     * use top-level `await`, and reach `window.etch`).
+     *
+     * @throws {BridgeError} when no tab matches, the target is ambiguous, the tab
+     *   disconnects, or the eval times out.
+     */
+    evalInTab(code, options = {}) {
+        const id = randomUUID();
+        const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        return new Promise((resolve, reject) => {
+            // Inside the executor so a bad target rejects the promise rather than
+            // throwing synchronously to the caller.
+            const session = this.resolveTarget(options.tab);
+            const timer = setTimeout(() => {
+                session.pending.delete(id);
+                reject(new BridgeError(`eval timed out after ${timeoutMs}ms`, 'TIMEOUT'));
+            }, timeoutMs);
+            session.pending.set(id, { resolve, reject, logs: [], timer });
+            const request = {
+                type: 'eval',
+                id,
+                code,
+                mode: options.mode ?? 'safe'
+            };
+            try {
+                session.ws.send(JSON.stringify(request));
+            }
+            catch (err) {
+                session.pending.delete(id);
+                clearTimeout(timer);
+                reject(new BridgeError(`failed to send eval: ${String(err)}`, 'DISCONNECTED'));
+            }
+        });
+    }
+    resolveTarget(name) {
+        const ready = [...this.sessions].filter((s) => s.info !== null);
+        if (name !== undefined) {
+            // Most-recently connected wins, so a reconnected tab supersedes a stale one.
+            const matches = ready
+                .filter((s) => s.info.name === name)
+                .sort((a, b) => b.info.connectedAt - a.info.connectedAt);
+            if (matches.length === 0) {
+                throw new BridgeError(`no connected tab named "${name}"`, 'NO_TAB');
+            }
+            return matches[0];
+        }
+        if (ready.length === 0) {
+            throw new BridgeError('no Etch tab is connected', 'NO_TAB');
+        }
+        if (ready.length > 1) {
+            const names = ready.map((s) => s.info.name).join(', ');
+            throw new BridgeError(`multiple tabs connected (${names}); pass a tab name to disambiguate`, 'AMBIGUOUS_TAB');
+        }
+        return ready[0];
+    }
+    onConnection(ws) {
+        const session = { ws, info: null, pending: new Map() };
+        this.sessions.add(session);
+        ws.on('message', (data) => this.onMessage(session, data.toString()));
+        ws.on('close', () => this.onClose(session));
+        ws.on('error', () => {
+            try {
+                ws.terminate();
+            }
+            catch {
+                /* already gone */
+            }
+        });
+    }
+    onMessage(session, raw) {
+        const msg = parsePageMessage(raw);
+        if (!msg)
+            return;
+        switch (msg.type) {
+            case 'hello':
+                this.onHello(session, msg);
+                return;
+            case 'log': {
+                const pending = session.pending.get(msg.id);
+                pending?.logs.push({ level: msg.level, args: msg.args });
+                return;
+            }
+            case 'result': {
+                const pending = session.pending.get(msg.id);
+                if (!pending)
+                    return;
+                session.pending.delete(msg.id);
+                clearTimeout(pending.timer);
+                pending.resolve({
+                    ok: true,
+                    value: msg.value,
+                    logs: pending.logs
+                });
+                return;
+            }
+            case 'error': {
+                const pending = session.pending.get(msg.id);
+                if (!pending)
+                    return;
+                session.pending.delete(msg.id);
+                clearTimeout(pending.timer);
+                pending.resolve({
+                    ok: false,
+                    error: msg.error,
+                    stack: msg.stack,
+                    logs: pending.logs
+                });
+                return;
+            }
+            case 'pong':
+                return;
+        }
+    }
+    onHello(session, hello) {
+        session.info = {
+            name: hello.name,
+            url: hello.url,
+            title: hello.title,
+            hasEtch: hello.hasEtch,
+            apiVersion: hello.apiVersion,
+            version: hello.version,
+            meta: hello.meta ?? {},
+            connectedAt: Date.now()
+        };
+        this.emit('connect', session.info);
+    }
+    onClose(session) {
+        this.failPending(session, new BridgeError('tab disconnected', 'DISCONNECTED'));
+        this.sessions.delete(session);
+        if (session.info)
+            this.emit('disconnect', session.info);
+    }
+    failPending(session, error) {
+        for (const [id, pending] of session.pending) {
+            clearTimeout(pending.timer);
+            session.pending.delete(id);
+            pending.reject(error);
+        }
+    }
+    /** Send a liveness probe to every connected tab (the page replies `pong`). */
+    pingAll() {
+        const ping = { type: 'ping' };
+        const frame = JSON.stringify(ping);
+        for (const session of this.sessions) {
+            try {
+                session.ws.send(frame);
+            }
+            catch {
+                /* will surface via close/error */
+            }
+        }
+    }
+}