@digital-gravy/etch-connector 0.3.0 → 0.5.0

package/README.md

@@ -157,6 +157,8 @@ Usage:
   etch-connector serve [--ws-port 7331] [--control-port 7332] [--ws-host 127.0.0.1]
   etch-connector tabs  [--json] [--quiet] [--control-port 7332] [--cdp]
   etch-connector eval  [code] [-t|--tab name] [-f|--file path] [--timeout ms] [--cdp]
+  etch-connector upload   <file…> [-t name] [--alt text] [--collection id] [--compress webp:80[:maxWidth]] [--cdp]
+  etch-connector download <id…>   [-t name] [-o|--out dir|file] [--force] [--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)
@@ -185,6 +187,31 @@ Examples:
 When exactly one tab is connected, `-t` is optional. With several tabs you must
 name one.
 
+### Assets
+
+On a runtime that backs the `assets` capability (Etch Studio), `upload` and
+`download` move files between disk and `etch.assets`. The bridge carries JSON
+only, so the connector base64-encodes the bytes; you work with paths.
+
+```sh
+# Store a photo as WebP at quality 80, capped at 2400px wide; prints the asset
+etch-connector upload ./hero.jpg --alt "Team on the roof" --compress webp:80:2400
+
+# Write an asset's bytes to a file (or into a directory, under its own name)
+etch-connector download 12 --out /tmp/hero.webp
+```
+
+`upload` prints the stored asset (its `id` is what an `etch/dynamic-image`
+`mediaId` takes) and `download` prints `{ id, path, bytes }`. A file over Etch's
+24.9 MiB limit fails locally, before anything is sent; with `--compress` the
+limit is on the stored result, so a source up to 60 MiB may go. `--alt` takes
+one file per command. `download` refuses to overwrite an existing file, or to
+write a name starting with `.`, unless `--force` is given (the name comes from
+the tab). Both default to a 4-minute timeout, since compressing a large photo in
+the tab is slow; `--timeout` overrides it. A timed-out upload may still land, so
+check `etch.assets.listAsync()` before retrying. A runtime without
+`etch.assets` fails the script with "this runtime has no etch.assets" (exit 2).
+
 ## HTTP control API
 
 The daemon also exposes a loopback HTTP API (this is the seam the CLI uses, and
@@ -222,7 +249,9 @@ 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.
+loopback. The control API refuses any request carrying an `Origin` header —
+browsers always send one, local tools do not — and `/eval` only takes
+`application/json`, so a web page you visit cannot drive a tab through it.
 
 **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`,

package/dist/assets.js

@@ -0,0 +1,159 @@
+/**
+ * `upload` / `download`: files on disk ↔ `etch.assets` in the tab. The bridge
+ * carries JSON only, so bytes cross as base64 and this module does the
+ * encoding — an agent works with paths, never with base64.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, extname, join, sep } from 'node:path';
+/** Etch Studio's per-file cap (`MAX_ASSET_FILE_BYTES` there), on what it stores. */
+export const MAX_ASSET_FILE_BYTES = Math.floor(24.9 * 1024 * 1024);
+/**
+ * A file to compress may start larger, since Studio checks what it stores. Its
+ * base64 still has to fit the bridge's WebSocket frame (100 MiB).
+ */
+// ponytail: fixed cap; raise it with the ws maxPayload if photos outgrow it.
+export const MAX_COMPRESS_SOURCE_BYTES = 60 * 1024 * 1024;
+const FORMATS = ['webp', 'avif', 'jpeg', 'png'];
+function isFormat(value) {
+    return FORMATS.some((format) => format === value);
+}
+// NaN would cross the bridge as null and reach the encoder unchecked.
+function wholeNumber(value, [min, max], expected) {
+    const n = Number(value);
+    if (Number.isInteger(n) && n >= min && n <= max)
+        return n;
+    throw new Error(`--compress: expected ${expected} (got "${value}")`);
+}
+/** `webp`, `webp:80` or `webp:80:2400` → format, quality, max width. */
+export function parseCompress(spec) {
+    const [format = '', quality, maxWidth] = spec.split(':');
+    if (!isFormat(format)) {
+        throw new Error(`--compress: format must be one of ${FORMATS.join(', ')} (got "${format}")`);
+    }
+    return {
+        format,
+        ...(quality && {
+            quality: wholeNumber(quality, [0, 100], 'a quality as a whole number 0–100')
+        }),
+        ...(maxWidth && {
+            resize: {
+                type: 'axis',
+                axis: 'width',
+                pixels: wholeNumber(maxWidth, [1, Infinity], 'a max width in whole pixels')
+            }
+        })
+    };
+}
+/** A flag's value; a bare `--flag` that needs one is an error, not a no-op. */
+export function flagValue(name, value) {
+    if (value === true)
+        throw new Error(`--${name} needs a value`);
+    return typeof value === 'string' ? value : undefined;
+}
+function collectionIds(collection) {
+    const id = Number(collection);
+    if (!Number.isInteger(id)) {
+        throw new Error(`--collection: "${collection}" is not a collection id`);
+    }
+    return [id];
+}
+export function uploadOptions(flags, fileCount) {
+    const alt = flagValue('alt', flags.alt);
+    const collection = flagValue('collection', flags.collection);
+    const compress = flagValue('compress', flags.compress);
+    if (alt !== undefined && fileCount > 1) {
+        throw new Error('--alt describes one image: upload the files one at a time to give each its own');
+    }
+    return {
+        ...(alt !== undefined && { alt }),
+        ...(collection !== undefined && {
+            collectionIds: collectionIds(collection)
+        }),
+        ...(compress !== undefined && { compress: parseCompress(compress) })
+    };
+}
+/** Cheap: a stat, so every file can be checked before the first upload. */
+export function assertUploadable(path, compressing) {
+    const size = statSync(path).size;
+    const limit = compressing
+        ? MAX_COMPRESS_SOURCE_BYTES
+        : MAX_ASSET_FILE_BYTES;
+    if (size > limit) {
+        const mib = (bytes) => (bytes / 1024 / 1024).toFixed(1);
+        const what = compressing ? 'a file to compress' : 'a file';
+        throw new Error(`${path} is ${mib(size)} MiB, over the ${mib(limit)} MiB limit for ${what}`);
+    }
+}
+/** Reads the file; check it with `assertUploadable` first. */
+export function uploadInput(path, options) {
+    return {
+        data: readFileSync(path).toString('base64'),
+        fileName: basename(path),
+        ...options
+    };
+}
+const REQUIRE_ASSETS = "if (!etch.assets) throw new Error('this runtime has no etch.assets');";
+export function uploadScript(input) {
+    return `${REQUIRE_ASSETS} return etch.assets.uploadAsync(${JSON.stringify(input)});`;
+}
+export function downloadScript(id) {
+    return `${REQUIRE_ASSETS} return etch.assets.downloadAsync(${JSON.stringify(id)});`;
+}
+function isAssetFile(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'fileName' in value &&
+        typeof value.fileName === 'string' &&
+        'data' in value &&
+        typeof value.data === 'string');
+}
+export function isDirectory(path) {
+    return existsSync(path) && statSync(path).isDirectory();
+}
+// `sep` too: on Windows a folder is typed `out\`.
+function namesDirectory(out) {
+    return out.endsWith('/') || out.endsWith(sep) || isDirectory(out);
+}
+/**
+ * Where `out` puts the asset, creating a named directory. The tab picks the
+ * name, and whatever connected may not be Etch.
+ */
+function downloadPath(id, out, file) {
+    const name = basename(file.fileName);
+    if (!name || name.startsWith('.')) {
+        throw new Error(`asset ${id}: refusing to write "${file.fileName}", which is not a plain file name`);
+    }
+    if (namesDirectory(out)) {
+        mkdirSync(out, { recursive: true });
+        return join(out, name);
+    }
+    if (!existsSync(out) && !extname(out)) {
+        throw new Error(`--out ${out}: no such directory, and no extension to name a file by`);
+    }
+    return out;
+}
+function writeFile(path, bytes, { force }) {
+    try {
+        writeFileSync(path, bytes, { flag: force ? 'w' : 'wx' });
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            throw new Error(`${path} already exists; pass --force to overwrite it`);
+        }
+        throw err;
+    }
+}
+/**
+ * Write what `downloadAsync` returned. `out` is a directory (the asset's own
+ * name goes inside it) or, for a single id, the file path itself. An existing
+ * file is left alone unless `force` is set.
+ */
+export function saveDownload(id, value, out, { force = false } = {}) {
+    if (!isAssetFile(value)) {
+        throw new Error(`asset ${id}: the tab returned no file`);
+    }
+    const path = downloadPath(id, out, value);
+    const bytes = Buffer.from(value.data, 'base64');
+    writeFile(path, bytes, { force });
+    return { id, path, bytes: bytes.length };
+}

package/dist/cli.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 /**
  * etch-connector CLI — the thing an AI harness (Claude Code, Cowork, …) shells
- * out to. Three commands:
+ * out to. The core 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
+ *   etch-connector upload <file…>   store files through etch.assets
+ *   etch-connector download <id…>   write assets' bytes to disk
  *
  * `eval` prints forwarded console output to *stderr* — alongside unprefixed
  * connector notes such as the runtime banner — and the script's return value as
@@ -13,6 +15,7 @@
  * Exit codes: 0 ok · 2 the script threw · 1 everything else (no tab, timeout…).
  */
 import { readFileSync, writeFileSync } from 'node:fs';
+import { assertUploadable, downloadScript, flagValue, isDirectory, saveDownload, uploadInput, uploadOptions, uploadScript } from './assets.js';
 import { BridgeServer } from './bridge-server.js';
 import { createControlServer, controlBaseUrl } from './control-server.js';
 import { CdpClient, CdpError, CdpEvalError } from './cdp-client.js';
@@ -229,13 +232,25 @@ function cdpLaunchHint(port) {
         'Firefox is not supported — CDP requires a Chromium-family browser.'
     ].join('\n');
 }
+/**
+ * A failure already reported on stderr, carrying the exit code `main` ends
+ * with. Thrown rather than exiting on the spot, so a multi-file command can
+ * still print what it finished first.
+ */
+class CliExit extends Error {
+    code;
+    constructor(code) {
+        super(`exit ${code}`);
+        this.code = code;
+    }
+}
 /** 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);
+        throw new CliExit(2);
     }
     console.error(err instanceof CdpError ? err.message : String(err));
     // The connection-failure message comes from CdpClient.listTargets/connect.
@@ -243,7 +258,7 @@ function failCdp(err, port = DEFAULT_CDP_PORT) {
         /cannot reach|ECONNREFUSED|failed to attach/i.test(err.message)) {
         console.error(cdpLaunchHint(port));
     }
-    process.exit(1);
+    throw new CliExit(1);
 }
 /**
  * Run a CDP command against the required endpoint (defaulting to localhost:9222
@@ -362,8 +377,7 @@ function printForwardedLogs(logs) {
 // CDP mode: eval over Chrome remote debugging (full window access, no daemon).
 async function evalViaCdp(cdp, flags, code, timeoutMs) {
     try {
-        const value = await withCdp(cdp, str(flags['tab']), (c) => c.eval(code, { timeoutMs }));
-        writeJson(value);
+        return await withCdp(cdp, str(flags['tab']), (c) => c.eval(code, { timeoutMs }));
     }
     catch (err) {
         failCdp(err, cdp.port);
@@ -417,7 +431,7 @@ async function evalViaDaemon(flags, code, timeoutMs) {
     if (!res.ok) {
         const err = (await res.json().catch(() => ({})));
         console.error(`eval failed: ${err.error ?? res.statusText}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const result = (await res.json());
     printForwardedLogs(result.logs);
@@ -425,9 +439,16 @@ async function evalViaDaemon(flags, code, timeoutMs) {
         console.error(`script error: ${result.error}`);
         if (result.stack)
             console.error(result.stack);
-        process.exit(2);
+        throw new CliExit(2);
     }
-    writeJson(result.value);
+    return result.value;
+}
+/** Run `code` in the tab and return its value; exits 2 if it threw, 1 otherwise. */
+function evaluate(flags, code, timeoutMs) {
+    const cdp = cdpFromFlags(flags);
+    return cdp
+        ? evalViaCdp(cdp, flags, code, timeoutMs)
+        : evalViaDaemon(flags, code, timeoutMs);
 }
 async function runEval(positional, flags) {
     const code = await gatherCode(positional, flags);
@@ -435,11 +456,59 @@ async function runEval(positional, flags) {
         console.error('eval: no script provided (pass code as an argument, --file, or stdin)');
         process.exit(1);
     }
-    const timeoutMs = timeoutFromFlags(flags);
-    const cdp = cdpFromFlags(flags);
-    return cdp
-        ? evalViaCdp(cdp, flags, code, timeoutMs)
-        : evalViaDaemon(flags, code, timeoutMs);
+    writeJson(await evaluate(flags, code, timeoutFromFlags(flags)));
+}
+// Compressing and sizing a large photo in the tab takes far longer than a
+// script. Kept under Node fetch's own 300 s wait for the daemon's answer.
+const ASSET_TIMEOUT_MS = 240_000;
+async function runUpload(positional, flags) {
+    if (positional.length === 0) {
+        console.error('upload: pass one or more files');
+        process.exit(1);
+    }
+    const options = uploadOptions(flags, positional.length);
+    for (const path of positional) {
+        assertUploadable(path, options.compress !== undefined);
+    }
+    // One file in memory at a time: each is read only when its turn comes.
+    const timeoutMs = timeoutFromFlags(flags) ?? ASSET_TIMEOUT_MS;
+    await eachReported(positional, (path) => evaluate(flags, uploadScript(uploadInput(path, options)), timeoutMs));
+}
+/**
+ * Run `step` per item and print the results. When one fails, what already
+ * succeeded is printed before the failure exits, so the agent keeps the ids
+ * of the assets that did land.
+ */
+async function eachReported(items, step) {
+    const done = [];
+    try {
+        for (const item of items)
+            done.push(await step(item));
+    }
+    catch (err) {
+        if (done.length > 0) {
+            writeJson(done);
+            console.error(`${done.length} of ${items.length} done before the failure`);
+        }
+        throw err;
+    }
+    writeJson(done.length === 1 ? done[0] : done);
+}
+const isIdList = (ids) => ids.length > 0 && ids.every(Number.isInteger);
+async function runDownload(positional, flags) {
+    const ids = positional.map(Number);
+    if (!isIdList(ids)) {
+        console.error('download: pass one or more numeric asset ids');
+        process.exit(1);
+    }
+    const out = flagValue('out', flags['out']) ?? '.';
+    const force = bool(flags['force'], false);
+    if (ids.length > 1 && !isDirectory(out)) {
+        console.error('download: --out must be an existing directory for several ids');
+        process.exit(1);
+    }
+    const timeoutMs = timeoutFromFlags(flags) ?? ASSET_TIMEOUT_MS;
+    await eachReported(ids, async (id) => saveDownload(id, await evaluate(flags, downloadScript(id), timeoutMs), out, { force }));
 }
 /** `shot` / `html` / `computed` are CDP-only; default to localhost:9222. */
 function requireCdp(flags) {
@@ -490,6 +559,8 @@ Usage:
   etch-connector serve [--ws-port ${DEFAULT_WS_PORT}] [--control-port ${DEFAULT_CONTROL_PORT}] [--ws-host ${DEFAULT_HOST}]
   etch-connector tabs  [--json] [--quiet] [--control-port ${DEFAULT_CONTROL_PORT}] [--cdp]
   etch-connector eval  [code] [-t|--tab name] [-f|--file path] [--timeout ms] [--cdp]
+  etch-connector upload   <file…> [-t name] [--alt text] [--collection id] [--compress webp:80[:maxWidth]] [--cdp]
+  etch-connector download <id…>   [-t name] [-o|--out dir|file] [--force] [--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)
@@ -582,6 +653,29 @@ it, narrate it, or explain these state changes — just keep it accurate):
         etch.ai.setState('working');
         try { /* …drive the builder… */ } finally { etch.ai.setState('thinking'); }
 
+Assets (AGENT: where the runtime backs \`assets\` — see \`tabs\` — files live in
+the product's own store, reached through etch.assets.*. NEVER call /wp/v2/media
+there):
+  • To put a local image on a page: \`upload\` it, take the \`id\` from the
+    printed asset, and bind an etch/dynamic-image by \`mediaId\` (the id, as a
+    string). Never bind a URL.
+  • ALWAYS set alt text: --alt on upload (one file per command, so each gets
+    its own), or etch.assets.updateAsync(id, { alt }).
+  • Prefer --compress webp:80 for photos (add :2400 to cap the width); keep
+    PNG/SVG for logos and line art. Responsive sizes are generated either way.
+  • To inspect or edit an existing image: \`download\` it to a path you choose,
+    work on the file, then etch.assets.replaceAsync or upload a new one.
+    \`download\` never overwrites a file unless you pass --force.
+  • Organizing means collections — the Asset Manager shows them as folders:
+    etch.assets.createCollectionAsync(name), then updateAsync(id, { collectionIds }).
+  • The commands print JSON on stdout and exit 2 when the tab refuses (a taken
+    name, ASSET_IN_USE on delete, a runtime with no etch.assets).
+  • A TIMEOUT does not mean nothing was stored: the tab may still finish. Check
+    etch.assets.listAsync() before uploading again.
+    Examples:
+      etch-connector upload ./hero.jpg --alt "Team on the roof" --compress webp:80
+      etch-connector download 12 --out /tmp/hero.webp
+
 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
@@ -636,39 +730,41 @@ render what you author):
       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.) Without it the ids are the product's own asset store and there is
-      nothing to look a URL up against.
+      ones.) Without it the ids are the product's own asset store: use
+      etch.assets and \`upload\` where the runtime backs \`assets\` (see Assets).
 
 See AGENTS.md for project conventions.`;
 function printHelp() {
     console.error(HELP_TEXT);
 }
+const COMMANDS = {
+    serve: (_, flags) => runServe(flags),
+    tabs: (_, flags) => runTabs(flags),
+    eval: runEval,
+    upload: runUpload,
+    download: runDownload,
+    shot: (_, flags) => runShot(flags),
+    html: runHtml,
+    computed: runComputed,
+    help: printHelp,
+    '--help': printHelp,
+    '-h': printHelp
+};
 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);
+    const run = Object.hasOwn(COMMANDS, command)
+        ? COMMANDS[command]
+        : undefined;
+    if (!run) {
+        console.error(`unknown command: ${command}\n`);
+        printHelp();
+        process.exit(1);
     }
+    return run(positional, flags);
 }
 main().catch((err) => {
+    if (err instanceof CliExit)
+        process.exit(err.code);
     console.error(String(err instanceof Error ? err.message : err));
     process.exit(1);
 });

package/dist/control-server.js

@@ -14,6 +14,7 @@
  */
 import { createServer } from 'node:http';
 import { z } from 'zod';
+import { MAX_COMPRESS_SOURCE_BYTES } from './assets.js';
 import { BridgeError } from './bridge-server.js';
 import { DEFAULT_CONTROL_PORT, DEFAULT_HOST } from './protocol.js';
 const evalBodySchema = z.object({
@@ -22,6 +23,8 @@ const evalBodySchema = z.object({
     timeoutMs: z.number().int().positive().optional(),
     mode: z.enum(['safe', 'unsafe']).optional()
 });
+// An `upload` carries the file as base64 (4/3 of its size) inside the script.
+const MAX_BODY_BYTES = Math.ceil((MAX_COMPRESS_SOURCE_BYTES * 4) / 3) + 5_000_000;
 function send(res, status, body) {
     const payload = JSON.stringify(body);
     res.writeHead(status, {
@@ -36,8 +39,7 @@ function readBody(req) {
         let size = 0;
         req.on('data', (chunk) => {
             size += chunk.length;
-            // Guard against an unbounded body; scripts are small.
-            if (size > 5_000_000) {
+            if (size > MAX_BODY_BYTES) {
                 reject(new Error('request body too large'));
                 req.destroy();
                 return;
@@ -60,10 +62,51 @@ function statusForBridgeError(code) {
             return 502;
     }
 }
+async function handleEval(bridge, req, res, defaultMode) {
+    if (!req.headers['content-type']?.startsWith('application/json')) {
+        return send(res, 415, {
+            error: 'send the body as application/json'
+        });
+    }
+    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) });
+    }
+}
 export function createControlServer(bridge, options = {}) {
     const defaultMode = options.defaultMode ?? 'safe';
     return createServer(async (req, res) => {
         const url = new URL(req.url ?? '/', 'http://localhost');
+        // Browsers always send Origin and local tools do not. A page can POST
+        // here without a preflight, or rebind its own name to this address, so
+        // anything a browser sends is refused before it can reach a tab.
+        if (req.headers.origin !== undefined) {
+            return send(res, 403, {
+                error: 'requests from web pages are refused'
+            });
+        }
         if (req.method === 'GET' && url.pathname === '/health') {
             return send(res, 200, { ok: true });
         }
@@ -71,32 +114,7 @@ export function createControlServer(bridge, options = {}) {
             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) });
-            }
+            return handleEval(bridge, req, res, defaultMode);
         }
         send(res, 404, { error: `not found: ${req.method} ${url.pathname}` });
     });

package/dist/guidance.js

@@ -81,6 +81,14 @@ function routesGuidance(environment) {
         "  templateId, or its nearest ancestor's (templateId: null in a patch",
         '  inherits again). Read getPathsAsync() after a change — only',
         '  `published` paths are built.',
+        '  SEO lives on the route, set through updateAsync: title, description,',
+        '  language, canonical, socialImageId, faviconId (root only),',
+        "  searchVisibility ('inherit' | 'hidden' | 'visible'), redirect",
+        '  ({ to, status: 301 | 302 }, never on the root) and notFoundId. null',
+        '  clears a field so it inherits; title, description and canonical may',
+        "  hold expressions ('{this.title} | {site.name}'). listSeoAsync() returns",
+        '  every published page resolved — one call for the whole site, so read',
+        '  it before and after a pass rather than getSeoAsync(path) per page.',
         '  Do not build links from .slug (this.slug, item.slug in a loop, or',
         '  PostSummary.slug): only a record a static route serves has one. A',
         '  record served by a dynamic route has none, and listPostsAsync() reports',
@@ -131,6 +139,18 @@ function mediaGuidance(environment) {
             binding
         ];
     }
+    if (hasCapability(environment, 'assets')) {
+        return [
+            "Media — this runtime's own asset store, through etch.assets.*, NOT the",
+            '  WordPress library: never call /wp/v2/media here.',
+            "  etch.assets.listAsync({ mimeType: 'image/' }) lists files with their ids.",
+            '  A local file: `etch-connector upload <file> --alt "…"` prints the asset;',
+            '  bind its id. To inspect or edit one: `etch-connector download <id> --out <path>`.',
+            '  Folders are collections (createCollectionAsync, then updateAsync(id,',
+            '  { collectionIds })). updateAsync(id, { alt }) sets alt text.',
+            binding
+        ];
+    }
     return [
         "Media — this runtime's own asset store, NOT the WordPress library:",
         '  /wp/v2/media does not apply and there is nothing to look a URL up against.',

package/dist/protocol.js

@@ -18,7 +18,8 @@ const CAPABILITY_NAMES = [
     'templates',
     'wpMedia',
     'routes',
-    'content'
+    'content',
+    'assets'
 ];
 /** Whether a runtime backs a capability. Absent or unknown counts as no. */
 export function hasCapability(environment, capability) {

package/package.json

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