@digital-gravy/etch-connector 0.1.1 → 0.1.3

package/README.md

@@ -1,5 +1,12 @@
 # etch-connector
 
+> **AGENT: read this first.** Before interacting with Etch in any way, run
+> `etch-connector --help` (or `npx @digital-gravy/etch-connector --help`) and
+> read the **entire** output. It documents the backends, commands, flags, the
+> stdout/stderr/exit-code contract, and how to pull the current Etch docs —
+> everything you need to drive a tab correctly. Do not call any other command
+> until you have read it.
+
 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)
@@ -28,25 +35,40 @@ 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:
+Scripts run in a **page-enforced safe mode**: the script sees only `etch` and
+the standard JS built-ins. `window`, `document`, `fetch`, storage, `eval`, … are
+withheld.
+
+## Install & run
+
+No install needed — run it on demand with `npx` (npm) or `bunx` (Bun):
 
-- **`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.
+```bash
+npx @digital-gravy/etch-connector serve
+# or
+bunx @digital-gravy/etch-connector serve
+```
 
-## Install
+To get the short `etch-connector` command on your `PATH`, install it globally:
 
 ```bash
-bun install   # or npm install
+npm install -g @digital-gravy/etch-connector   # or: bun install -g …
+etch-connector serve
 ```
 
+> Using the connector requires a valid, active Etch license — see
+> [`LICENSE`](LICENSE).
+
+The examples below use the bare `etch-connector` command; if you're running via
+`npx`/`bunx` instead, prefix them with `npx @digital-gravy/etch-connector` (or
+`bunx …`).
+
 ## Use
 
 ### 1. Start the daemon (once)
 
 ```bash
-bun run serve
+etch-connector serve
 # bridge   ws://127.0.0.1:7331
 # control  http://127.0.0.1:7332
 ```
@@ -70,20 +92,17 @@ started the daemon on a non-default WebSocket port.)
 etch-connector tabs
 
 # run a script (value → stdout, console output → stderr).
-# Default is safe mode: reference the API as `etch.*`.
+# 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:
+use top-level `await`. Write scripts against the `etch-public-api` surface via
+the `etch` binding (`window` is not available). Examples:
 
 ```js
 return etch.apiVersion;
@@ -93,16 +112,6 @@ 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:
@@ -112,40 +121,14 @@ Pick per call with `--safe` / `--unsafe`, or change the daemon default with
 - **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.
+## For AI agents
 
-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).
+The authoritative agent instructions live in **`etch-connector --help`** — read
+the entire output before interacting with Etch. It covers the backends, commands
+and flags, the stdout/stderr/exit-code contract, how to pull the current Etch
+docs (Context7 MCP or <https://docs.etchwp.com/public-api>), and the conventions
+for structuring pages (e.g. the section/container layout pattern). Project
+conventions for working on this repo live in [`AGENTS.md`](AGENTS.md).
 
 ## CLI
 
@@ -153,17 +136,16 @@ of the API docs, follow the project-specific conventions in
 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 serve [--ws-port 7331] [--control-port 7332] [--ws-host 127.0.0.1]
   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 eval  [code] [-t|--tab name] [-f|--file path] [--timeout ms] [--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)
+          Scripts see only "etch" + the standard JS built-ins.
   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 /
@@ -234,17 +216,14 @@ Two layers, neither a substitute for the other:
 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.
+**Execution.** Bridge mode 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`). It reliably keeps casual and AI-authored
+scripts on the `etch` surface and closes the obvious escape hatches; it does
+**not** contain hostile code.
 
 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

package/dist/cli.js

@@ -17,6 +17,14 @@ 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;
+/**
+ * Unsafe mode (scripts get full, unconstrained access to the page) is
+ * intentionally DISABLED. The `--unsafe` flag and the branches that honor it
+ * are kept below as a deliberate dead path behind this constant — never
+ * reachable in shipped builds, and undocumented in --help and the README — so
+ * the machinery can be revived later without rebuilding it. Leave it `false`.
+ */
+const ALLOW_UNSAFE = false;
 /** Long flags that never take a value, so they don't swallow the next token. */
 const BOOLEAN_FLAGS = new Set([
     'cdp',
@@ -110,7 +118,8 @@ async function runServe(flags) {
     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';
+    // --unsafe is a dead path (see ALLOW_UNSAFE); defaultMode is always 'safe'.
+    const defaultMode = ALLOW_UNSAFE && 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}"`));
@@ -271,9 +280,10 @@ async function runEval(positional, flags) {
         }
         return;
     }
-    // --unsafe / --safe override the daemon default; omitting both defers to it.
+    // --safe overrides the daemon default; omitting it defers to the daemon.
+    // --unsafe is a dead path (see ALLOW_UNSAFE): it never sets unsafe mode.
     let mode;
-    if (flags['unsafe'])
+    if (ALLOW_UNSAFE && flags['unsafe'])
         mode = 'unsafe';
     else if (flags['safe'])
         mode = 'safe';
@@ -376,26 +386,33 @@ async function runComputed(positional, flags) {
 function printHelp() {
     console.error(`etch-connector — drive a live Etch tab from the command line
 
+Run without installing (requires a valid, active Etch license):
+  npx @digital-gravy/etch-connector serve
+  bunx @digital-gravy/etch-connector serve
+Or install globally for the bare \`etch-connector\` command:
+  npm install -g @digital-gravy/etch-connector   # or: bun install -g …
+(When running via npx/bunx, prefix the commands below with
+ \`npx @digital-gravy/etch-connector\` / \`bunx …\`.)
+
 Usage:
-  etch-connector serve [--ws-port ${DEFAULT_WS_PORT}] [--control-port ${DEFAULT_CONTROL_PORT}] [--ws-host ${DEFAULT_HOST}] [--unsafe]
+  etch-connector serve [--ws-port ${DEFAULT_WS_PORT}] [--control-port ${DEFAULT_CONTROL_PORT}] [--ws-host ${DEFAULT_HOST}]
   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 eval  [code] [-t|--tab name] [-f|--file path] [--timeout ms] [--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)
+          Scripts see only "etch" + the standard JS built-ins.
   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.
+(API only) or cdp (DevTools privilege: full page access). cdp grants more reach;
+don't assume — let the user choose.
 
 Examples:
   etch-connector serve
@@ -410,8 +427,8 @@ Examples:
   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.
+top-level 'await'. In bridge 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):
@@ -419,6 +436,52 @@ changes and training data may be stale):
                             specific call (e.g. etch.blocks.create).
   Manual fallback           https://docs.etchwp.com/public-api (window.etch.*)
                             https://docs.etchwp.com (everything else)
+
+Building Etch pages (AGENT: conventions — follow these or the builder won't
+render what you author):
+  Images. ALWAYS use the Dynamic Image element (etch/dynamic-image, <etch:img>),
+    NEVER a plain etch/element with tag "img". Bind it by WP media ID, not a URL:
+        attributes: { mediaId: "{props.image}", useSrcSet: "true", alt: "{props.name}" }
+    The backing prop must be a Media prop, not a text prop:
+        type: { primitive: "string", specialized: "wpMediaId" }
+    (specialized "image" is the URL-based picker — NOT for mediaId.) Instances
+    then pass the numeric media ID, e.g. image: "10" — not the file URL.
+
+  Classes. A block's classes ARE its read-only \`styles\` array, not an HTML
+    attribute. Setting attributes.class in authored JSON is silently dropped, and
+    \`styles\` is rejected on authoring. Assign classes with etch.blocks.addClass()
+    — for component blocks, inside enterComponentEditMode() →
+    saveComponentEditModeAsync() → exitComponentEditMode(). An existing class
+    name re-links to its style record automatically (styling is preserved).
+
+  Sections. When you create a top-level section, always tag it
+    data-etch-element="section" and nest ONE container inside it as its inner —
+    a div block with data-etch-element="container" — and put the section's
+    content inside that container, not directly in the section:
+
+        section   data-etch-element="section"
+        └─ div    data-etch-element="container"   ← content goes here
+           └─ … your blocks …
+
+    section + container carry Etch's default styles, so you get vertical spacing
+    / gutter between sections, horizontal edge padding, and a constrained,
+    centered content width for free. Do NOT hand-roll wrapper widths, max-widths,
+    side padding, or inter-section margins — the pair already handles layout
+    structure, spacing, and content width.
+
+  Gotchas.
+    • NEVER call etch.*.saveAsync (or otherwise persist) unless the user
+      explicitly asks to save — authored changes stay in the builder until then.
+    • Component instance props are attributes: set them at create()/replace()
+      time, or update an existing instance in place with
+          etch.blocks.update(instanceId, { attributes: { image: "10" } })
+    • updateAsync({ blocks }) requires styles:[] on every element block
+      (validation differs from blocks.create(), which omits styles entirely).
+    • No etch.media API. Resolve a URL → media ID via the WP REST API:
+          curl 'http://<site>/?rest_route=/wp/v2/media&per_page=100&_fields=id,source_url'
+      (rest_route form works on plain permalinks; /wp-json/wp/v2/media on pretty
+      ones.)
+
 See AGENTS.md for project conventions.`);
 }
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@digital-gravy/etch-connector",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"publishConfig": {
 		"access": "public"
 	},