@digital-gravy/etch-connector 0.1.5 → 0.2.0

package/README.md

@@ -122,12 +122,23 @@ return groups.length;
 `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.
+- **stderr** — forwarded `console.*` output, prefixed with the level, plus
+  connector notes that carry no such prefix (the runtime banner, warnings).
 - **exit code** — `0` success · `2` the script threw · `1` operational failure
   (no such tab, ambiguous target, timeout, daemon unreachable).
 
 ## For AI agents
 
+`etch-connector tabs` reports, per tab, which Etch runtime it is and which
+surfaces that runtime backs (read off `etch.environment`), then prints the
+authoring rules that follow from it: the dynamic-data model (data sources vs
+loops), the media lookup, the namespaces that throw `NOT_AVAILABLE`, and the
+block types the runtime can construct. Not every runtime backs every surface, so
+read that before writing scripts — and branch on a capability, never on the
+product name. `eval` names the runtime it targets on stderr as a reminder, and
+`tabs --quiet` drops the prose when you are only checking that a tab is still
+connected.
+
 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
@@ -144,7 +155,7 @@ 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]
-  etch-connector tabs  [--json] [--control-port 7332] [--cdp]
+  etch-connector tabs  [--json] [--quiet] [--control-port 7332] [--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)
@@ -194,6 +205,8 @@ the same one a future MCP server would call):
   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/guidance.ts`](src/guidance.ts) — turns a tab's `etch.environment`
+  descriptor into the authoring instructions for that runtime.
 - [`src/cli.ts`](src/cli.ts) — the `serve` / `tabs` / `eval` commands.
 
 ## Going to MCP later

package/dist/bridge-server.js

@@ -14,7 +14,7 @@
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
 import { WebSocketServer } from 'ws';
-import { DEFAULT_HOST, DEFAULT_WS_PORT, parsePageMessage } from './protocol.js';
+import { DEFAULT_HOST, DEFAULT_WS_PORT, parseEnvironment, parsePageMessage } from './protocol.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 /**
  * Raised for operational failures (no matching tab, ambiguous target, timeout,
@@ -208,6 +208,7 @@ export class BridgeServer extends EventEmitter {
             hasEtch: hello.hasEtch,
             apiVersion: hello.apiVersion,
             version: hello.version,
+            environment: parseEnvironment(hello.environment),
             meta: hello.meta ?? {},
             connectedAt: Date.now()
         };

package/dist/cli.js

@@ -7,8 +7,9 @@
  *   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.
+ * `eval` prints forwarded console output to *stderr* — alongside unprefixed
+ * connector notes such as the runtime banner — 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';
@@ -16,6 +17,7 @@ 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';
+import { backedCapabilities, environmentGuidance, runtimeBanner } from './guidance.js';
 const DEFAULT_CDP_PORT = 9222;
 /**
  * Unsafe mode (scripts get full, unconstrained access to the page) is
@@ -31,6 +33,7 @@ const BOOLEAN_FLAGS = new Set([
     'full',
     'jpeg',
     'json',
+    'quiet',
     'unsafe',
     'safe',
     'help',
@@ -275,6 +278,33 @@ async function tabsViaCdp(cdp, flags) {
     for (const t of targets)
         process.stdout.write(`${t.title}\t${t.url}\n`);
 }
+/** The runtime column: what the tab is and which surfaces it actually backs. */
+function describeRuntime(tab) {
+    if (!tab.hasEtch)
+        return 'no-etch';
+    if (!tab.environment)
+        return 'etch';
+    const backed = backedCapabilities(tab.environment);
+    return `${tab.environment.product}(${backed.join(',') || 'none'})`;
+}
+/**
+ * Instructions for the runtimes actually on the wire, to stderr so stdout stays
+ * the plain listing. Tabs sharing a runtime share one block — an agent needs the
+ * guidance once per runtime, not once per tab.
+ */
+function printRuntimeGuidance(tabs) {
+    const byRuntime = new Map();
+    for (const tab of tabs.filter((t) => t.hasEtch)) {
+        const guidance = environmentGuidance(tab.environment);
+        const names = byRuntime.get(guidance) ?? [];
+        names.push(tab.name);
+        byRuntime.set(guidance, names);
+    }
+    for (const [guidance, names] of byRuntime) {
+        console.error(`\nAGENT — authoring against ${names.join(', ')}:`);
+        console.error(guidance);
+    }
+}
 async function tabsViaDaemon(flags) {
     const res = await controlFetch(flags, '/tabs');
     const { tabs } = (await res.json());
@@ -285,8 +315,11 @@ async function tabsViaDaemon(flags) {
         return;
     }
     for (const tab of tabs) {
-        process.stdout.write(`${tab.name}\t${tab.hasEtch ? 'etch' : 'no-etch'}\t${tab.title}\t${tab.url}\n`);
+        process.stdout.write(`${tab.name}\t${describeRuntime(tab)}\t${tab.title}\t${tab.url}\n`);
     }
+    // `tabs` doubles as the liveness check, so let a poller opt out of the prose.
+    if (!flags['quiet'])
+        printRuntimeGuidance(tabs);
 }
 async function runTabs(flags) {
     const cdp = cdpFromFlags(flags);
@@ -336,17 +369,51 @@ async function evalViaCdp(cdp, flags, code, timeoutMs) {
         failCdp(err, cdp.port);
     }
 }
+/**
+ * Which tab an eval will land on, mirroring the daemon's own resolution: a named
+ * tab (most recently connected wins), or the only one connected. Anything the
+ * daemon would reject resolves to nothing — the eval reports that itself.
+ */
+function resolveTargetTab(tabs, name) {
+    if (name === undefined)
+        return tabs.length === 1 ? tabs[0] : undefined;
+    return tabs
+        .filter((tab) => tab.name === name)
+        .sort((a, b) => b.connectedAt - a.connectedAt)[0];
+}
+/**
+ * Name the runtime this eval targets, on stderr. Best-effort: a listing we
+ * cannot fetch or a target we cannot pin down just means no banner — never a
+ * failed eval.
+ */
+async function announceTargetRuntime(flags) {
+    try {
+        const res = await controlFetch(flags, '/tabs');
+        if (!res.ok)
+            return;
+        const { tabs } = (await res.json());
+        const target = resolveTargetTab(tabs, str(flags['tab']));
+        if (target)
+            console.error(runtimeBanner(target.environment));
+    }
+    catch {
+        /* the eval itself reports anything that actually matters */
+    }
+}
 async function evalViaDaemon(flags, code, timeoutMs) {
     const mode = resolveEvalMode(flags);
     if (mode === 'unsafe') {
         console.error('⚠  running in unsafe mode — the script has full access to the page');
     }
+    // Started before the eval so naming the runtime costs no wall-clock.
+    const announced = announceTargetRuntime(flags);
     const body = { tab: str(flags['tab']), code, timeoutMs, mode };
     const res = await controlFetch(flags, '/eval', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify(body)
     });
+    await announced;
     if (!res.ok) {
         const err = (await res.json().catch(() => ({})));
         console.error(`eval failed: ${err.error ?? res.statusText}`);
@@ -419,7 +486,7 @@ Or install globally for the bare \`etch-connector\` command:
 
 Usage:
   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 tabs  [--json] [--quiet] [--control-port ${DEFAULT_CONTROL_PORT}] [--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)
@@ -437,6 +504,15 @@ AGENT: before running anything, ask the user how they want to connect — bridge
 (API only) or cdp (DevTools privilege: full page access). cdp grants more reach;
 don't assume — let the user choose.
 
+AGENT: \`etch-connector tabs\` prints, per connected tab, which runtime it is and
+which surfaces that runtime backs (from \`etch.environment\`), followed by the
+authoring rules for it — the dynamic-data model, the media lookup, the
+namespaces that throw, and the block types it can construct. Read that before
+writing scripts: not every runtime backs every surface, so the same script does
+not work everywhere. Branch on a capability, never on the product name.
+(\`eval\` names the runtime it targets on stderr as a reminder; \`tabs --quiet\`
+drops the prose when you are only checking a tab is still connected.)
+
 Connecting a bridge tab (AGENT: walk the user through activating it — the AI
 button is the primary path; don't just wait for a tab to appear):
   1. Tell them to open Etch Settings and enable the AI Connector.
@@ -539,10 +615,13 @@ render what you author):
           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:
+    • No etch.media API. Where the runtime backs the WordPress media library
+      (capability \`wpMedia\` — see \`tabs\`), 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.)
+      ones.) Without it the ids are the product's own asset store and there is
+      nothing to look a URL up against.
 
 See AGENTS.md for project conventions.`;
 function printHelp() {

package/dist/guidance.js

@@ -0,0 +1,129 @@
+/**
+ * Turns a tab's `etch.environment` descriptor into the instructions for
+ * authoring against *that* runtime.
+ *
+ * The two dynamic-data models are mutually exclusive and are authored
+ * differently, the media lookup depends on whether WordPress is underneath, and
+ * several namespaces are declared everywhere but backed only somewhere — so a
+ * script written for one product silently produces nothing on the other. This
+ * is what turns the descriptor from something the connector relays into
+ * something it acts on.
+ *
+ * Every branch keys off {@link hasCapability}, never `product`: capabilities
+ * move between products, and a product check rots the day one does.
+ */
+import { hasCapability } from './protocol.js';
+/** Namespaces that are declared on every runtime but backed only on some. */
+const GATED_NAMESPACES = [
+    { capability: 'loops', namespace: 'etch.loops.*' },
+    { capability: 'fields', namespace: 'etch.fields.*' },
+    { capability: 'templates', namespace: "etch.navigation.goTo('templates')" }
+];
+const UNKNOWN_RUNTIME = [
+    'Runtime: not reported — this Etch predates etch.environment, so what follows',
+    '  is an ASSUMPTION, not a reading of the runtime: WordPress rules (loops,',
+    '  fields, templates, WP media), and every block type may exist. Confirm with',
+    '  the user before relying on it — a non-WordPress runtime throws on most of',
+    '  that.'
+];
+function dynamicDataGuidance(environment) {
+    if (hasCapability(environment, 'dataSources')) {
+        return [
+            'Dynamic data — data sources. Named project sources (json, api, js) are',
+            "  reached through a data('key') expression. An etch/loop block carries",
+            '  ONLY a required `target`, and that target is any dynamic expression',
+            "  yielding a list: data('products'), a path into one",
+            "  (data('products').items), nested data from an enclosing loop",
+            '  (item.tags), or a generated list (range(1, 10)). There is no',
+            '  loopId/loopParams here.'
+        ];
+    }
+    if (hasCapability(environment, 'loops')) {
+        return [
+            'Dynamic data — loops. etch.loops.* is a registry of named loop',
+            '  definitions. An etch/loop block binds one by `loopId`, passes',
+            '  $-prefixed `loopParams`, and `target` is an optional sub-path within',
+            "  it. There are no data sources here — a data('key') expression",
+            '  resolves to nothing.'
+        ];
+    }
+    return [
+        'Dynamic data: unavailable. This runtime backs neither loops nor data',
+        '  sources — do not author etch/loop blocks against it.'
+    ];
+}
+function mediaGuidance(environment) {
+    const binding = '  Bind an etch/dynamic-image by a numeric `mediaId` attribute, never a URL.';
+    if (hasCapability(environment, 'wpMedia')) {
+        return [
+            'Media — the WordPress library. Media ids resolve against /wp/v2/media, so',
+            '  a URL can be looked up:',
+            "    curl '<site>/?rest_route=/wp/v2/media&per_page=100&_fields=id,source_url'",
+            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.',
+        binding
+    ];
+}
+function unavailableGuidance(environment) {
+    const throwing = GATED_NAMESPACES.filter((gated) => !hasCapability(environment, gated.capability)).map((gated) => gated.namespace);
+    if (throwing.length === 0)
+        return [];
+    return [
+        'Throws EtchApiError NOT_AVAILABLE here — do not call:',
+        `  ${throwing.join(', ')}`
+    ];
+}
+function blockTypeGuidance(environment) {
+    if (environment.blockTypes.length === 0)
+        return [];
+    return [
+        'Block types this runtime can construct — author nothing outside this list:',
+        `  ${environment.blockTypes.join(', ')}`
+    ];
+}
+/** Which capabilities a runtime actually backs, for a one-line summary. */
+export function backedCapabilities(environment) {
+    return Object.entries(environment.capabilities)
+        .filter(([, backed]) => backed === true)
+        .map(([capability]) => capability)
+        .sort();
+}
+/**
+ * One stderr line naming the runtime a script is about to run against.
+ *
+ * `tabs` is where the full instructions live, but `-t` is optional with a single
+ * tab connected — so an agent can go straight to `eval` and never see them. This
+ * is the line that keeps that agent from silently authoring for the wrong
+ * product, and points at where the rules are.
+ */
+export function runtimeBanner(environment) {
+    if (!environment) {
+        return '[etch] runtime reports no capabilities — assuming WordPress; confirm before relying on it';
+    }
+    const backed = backedCapabilities(environment);
+    return (`[${environment.product}] backs ${backed.join(', ') || 'no optional surface'}` +
+        " — run 'etch-connector tabs' for the authoring rules");
+}
+/**
+ * Agent-facing instructions for one runtime. An absent descriptor is a runtime
+ * too old to report one, which is always a WordPress build.
+ */
+export function environmentGuidance(environment) {
+    if (!environment)
+        return UNKNOWN_RUNTIME.join('\n');
+    const backed = backedCapabilities(environment);
+    const sections = [
+        [
+            `Runtime: ${environment.product} — backs ${backed.length > 0 ? backed.join(', ') : 'no optional surface'}.`
+        ],
+        dynamicDataGuidance(environment),
+        mediaGuidance(environment),
+        unavailableGuidance(environment),
+        blockTypeGuidance(environment)
+    ].filter((section) => section.length > 0);
+    return sections.map((section) => section.join('\n')).join('\n');
+}

package/dist/index.js

@@ -9,3 +9,5 @@
 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';
+export { hasCapability, parseEnvironment } from './protocol.js';
+export { backedCapabilities, environmentGuidance, runtimeBanner } from './guidance.js';

package/dist/protocol.js

@@ -10,6 +10,48 @@
  *   server → page :  EvalRequest | PingMessage
  *   page → server :  HelloMessage | LogMessage | ResultMessage | ErrorMessage | PongMessage
  */
+/** Every optional surface a runtime may or may not back. */
+const CAPABILITY_NAMES = [
+    'loops',
+    'dataSources',
+    'fields',
+    'templates',
+    'wpMedia'
+];
+/** Whether a runtime backs a capability. Absent or unknown counts as no. */
+export function hasCapability(environment, capability) {
+    return environment?.capabilities[capability] === true;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Narrow an `environment` off the wire. The page is untrusted input, so a
+ * malformed descriptor becomes `undefined` (treated as "runtime too old to
+ * report one") rather than propagating a broken shape.
+ */
+export function parseEnvironment(value) {
+    if (!isRecord(value))
+        return undefined;
+    const { product, capabilities, blockTypes } = value;
+    if (typeof product !== 'string')
+        return undefined;
+    if (!isRecord(capabilities))
+        return undefined;
+    if (!Array.isArray(blockTypes))
+        return undefined;
+    const known = {};
+    for (const name of CAPABILITY_NAMES) {
+        const flag = capabilities[name];
+        if (typeof flag === 'boolean')
+            known[name] = flag;
+    }
+    return {
+        product,
+        capabilities: known,
+        blockTypes: blockTypes.filter((type) => typeof type === 'string')
+    };
+}
 /** 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. */

package/package.json

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