chrome-relay 0.5.2 → 0.5.3

package/dist/cli.js

@@ -4,15 +4,6 @@
 import { Command } from "commander";
 import { writeFileSync } from "fs";
 
-// src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.5.2" : "0.0.0-dev";
-
-// src/install/install.ts
-import os from "os";
-import path from "path";
-import { chmod, mkdir, readFile, stat, writeFile } from "fs/promises";
-import { fileURLToPath } from "url";
-
 // ../protocol/dist/index.js
 var NATIVE_HOST_NAME = "dev.chrome_relay.native_host";
 var DEFAULT_HTTP_PORT = 12122;
@@ -24,8 +15,41 @@ var DEFAULT_EXTENSION_IDS = [
   LEGACY_DEV_EXTENSION_ID,
   LOCAL_UNPACKED_EXTENSION_ID
 ];
+var RelayError = class extends Error {
+  code;
+  tool;
+  phase;
+  details;
+  retryable;
+  constructor(spec) {
+    super(spec.message);
+    this.name = "RelayError";
+    this.code = spec.code;
+    this.tool = spec.tool;
+    this.phase = spec.phase;
+    this.details = spec.details;
+    this.retryable = spec.retryable;
+  }
+  toBridgeError() {
+    return {
+      code: this.code,
+      message: this.message,
+      ...this.tool ? { tool: this.tool } : {},
+      ...this.phase ? { phase: this.phase } : {},
+      ...this.details ? { details: this.details } : {},
+      ...this.retryable !== void 0 ? { retryable: this.retryable } : {}
+    };
+  }
+};
+
+// src/index.ts
+var CHROME_RELAY_VERSION = true ? "0.5.3" : "0.0.0-dev";
 
 // src/install/install.ts
+import os from "os";
+import path from "path";
+import { chmod, mkdir, readFile, stat, writeFile } from "fs/promises";
+import { fileURLToPath } from "url";
 var APP_DIR = path.join(os.homedir(), ".chrome-relay");
 var KNOWN_EXTENSION_IDS = [
   ["Chrome Web Store", CHROME_WEB_STORE_EXTENSION_ID],
@@ -140,25 +164,30 @@ function emitNoticeOnce(notice) {
 async function callToolWithMeta(name, args) {
   const response = await fetch(`http://127.0.0.1:${DEFAULT_HTTP_PORT}/call`, {
     method: "POST",
-    headers: {
-      "content-type": "application/json"
-    },
+    headers: { "content-type": "application/json" },
     body: JSON.stringify({
       name,
       args
     })
   });
   const payload = await response.json().catch(() => null);
+  const noticeString = payload?.notice ?? payload?.notices?.[0]?.message;
   if (!response.ok) {
-    if (payload?.notice) emitNoticeOnce(payload.notice);
-    throw new Error(payload?.error || `Bridge request failed with ${response.status}`);
+    if (noticeString) emitNoticeOnce(noticeString);
+    throw rebuildError(payload, `Bridge request failed with ${response.status}`);
   }
   if (!payload?.ok) {
-    if (payload?.notice) emitNoticeOnce(payload.notice);
-    throw new Error(payload?.error || "Bridge call failed.");
+    if (noticeString) emitNoticeOnce(noticeString);
+    throw rebuildError(payload, "Bridge call failed.");
   }
-  if (payload.notice) emitNoticeOnce(payload.notice);
-  return { data: payload.data, notice: payload.notice };
+  if (noticeString) emitNoticeOnce(noticeString);
+  return { data: payload.data, notice: payload.notice, notices: payload.notices };
+}
+function rebuildError(payload, fallbackMessage) {
+  if (payload?.errorDetails) {
+    return new RelayError(payload.errorDetails);
+  }
+  return new Error(payload?.error || fallbackMessage);
 }
 async function callTool(name, args) {
   const { data } = await callToolWithMeta(name, args);
@@ -167,6 +196,15 @@ async function callTool(name, args) {
 
 // src/release-notes.ts
 var RELEASE_NOTES = {
+  "0.5.3": [
+    "Structured errors and notices (code-quality-hardening PR 1). New `BridgeError` and `BridgeNotice` types in @chrome-relay/protocol carry a code, tool, phase, and details \u2014 agents can branch on `errorDetails.code === 'invalid_arguments'` instead of regex-matching message strings.",
+    "Tool result JSON now carries BOTH the legacy fields (`error: string`, `notice: string`) AND the new structured fields (`errorDetails: BridgeError`, `notices: BridgeNotice[]`). Old consumers keep working; new consumers prefer the structured shape.",
+    "The cli-outdated notice is now a `BridgeNotice` with `code:'cli_outdated'`, `details.currentVersion`, `details.expectedVersion`, and an `action.command` field.",
+    "Every strict parser (PR 0 strict enums) now throws `RelayError` with `code:'invalid_arguments'`, the offending tool, the phase that failed, and the list of valid choices.",
+    "All action-validator throws (chrome_console, chrome_network, chrome_viewport, chrome_workspace, chrome_group, chrome_screencast) carry the same structured shape.",
+    "Unknown tool dispatch now returns `code:'unsupported_tool'`.",
+    "CLI: when a RelayError flows back, stderr prints the human message AND a `relayError` JSON object so agents can parse the structured details from stderr without needing a separate flag."
+  ],
   "0.5.2": [
     "Strict input parsers (code-quality-hardening PR 0). Invalid console levels, network status filters, tab-group colors, and tab-id lists now throw instead of being silently dropped \u2014 an agent that asks for `errors` (typo of `error`) gets a precise error rather than all levels back.",
     "Affected tools: chrome_console (levels), chrome_network (status), chrome_group (color, tabIds), chrome_screencast (format, action), chrome_network (action).",
@@ -280,9 +318,14 @@ Notes:
         process.stdout.write(JSON.stringify(result, null, 2) + "\n");
       }
     } catch (error) {
-      process.stderr.write(
-        (error instanceof Error ? error.message : String(error)) + "\n"
-      );
+      if (error instanceof RelayError) {
+        process.stderr.write(error.message + "\n");
+        process.stderr.write(JSON.stringify({ relayError: error.toBridgeError() }, null, 2) + "\n");
+      } else {
+        process.stderr.write(
+          (error instanceof Error ? error.message : String(error)) + "\n"
+        );
+      }
       process.exit(1);
     }
   }

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.5.2" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.5.3" : "0.0.0-dev";
 export {
   CHROME_RELAY_VERSION
 };

package/dist/native-host.js

@@ -8,9 +8,47 @@ import Fastify from "fastify";
 
 // ../protocol/dist/index.js
 var DEFAULT_HTTP_PORT = 12122;
+var RelayError = class extends Error {
+  code;
+  tool;
+  phase;
+  details;
+  retryable;
+  constructor(spec) {
+    super(spec.message);
+    this.name = "RelayError";
+    this.code = spec.code;
+    this.tool = spec.tool;
+    this.phase = spec.phase;
+    this.details = spec.details;
+    this.retryable = spec.retryable;
+  }
+  toBridgeError() {
+    return {
+      code: this.code,
+      message: this.message,
+      ...this.tool ? { tool: this.tool } : {},
+      ...this.phase ? { phase: this.phase } : {},
+      ...this.details ? { details: this.details } : {},
+      ...this.retryable !== void 0 ? { retryable: this.retryable } : {}
+    };
+  }
+};
+function toBridgeError(unknownErr, fallbackTool) {
+  if (unknownErr instanceof RelayError) {
+    const e = unknownErr.toBridgeError();
+    return fallbackTool && !e.tool ? { ...e, tool: fallbackTool } : e;
+  }
+  const message = unknownErr instanceof Error ? unknownErr.message : String(unknownErr);
+  return {
+    code: "internal_error",
+    message,
+    ...fallbackTool ? { tool: fallbackTool } : {}
+  };
+}
 
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.5.2" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.5.3" : "0.0.0-dev";
 
 // src/release-notes.ts
 function compareSemver(a, b) {
@@ -30,7 +68,20 @@ function buildOutdatedNotice(bridge2) {
   const extVersion = bridge2.getExtensionVersion();
   if (!extVersion) return void 0;
   if (compareSemver(CHROME_RELAY_VERSION, extVersion) >= 0) return void 0;
-  return `cli-outdated: ${CHROME_RELAY_VERSION} < extension ${extVersion}; run \`chrome-relay update\``;
+  return {
+    code: "cli_outdated",
+    message: `cli-outdated: ${CHROME_RELAY_VERSION} < extension ${extVersion}; run \`chrome-relay update\``,
+    details: {
+      currentVersion: CHROME_RELAY_VERSION,
+      expectedVersion: extVersion
+    },
+    action: { command: "chrome-relay update" }
+  };
+}
+function attachNotices(payload, notice) {
+  if (!notice) return;
+  payload.notice = notice.message;
+  payload.notices = [notice];
 }
 var RelayHttpServer = class {
   constructor(bridge2, port = DEFAULT_HTTP_PORT) {
@@ -63,15 +114,19 @@ var RelayHttpServer = class {
           body.args ?? {}
         );
         const notice = buildOutdatedNotice(this.bridge);
-        reply.send(notice ? { ok: true, data, notice } : { ok: true, data });
+        const payload = { ok: true, data };
+        attachNotices(payload, notice);
+        reply.send(payload);
       } catch (error) {
         const notice = buildOutdatedNotice(this.bridge);
-        const body2 = {
+        const errorDetails = error instanceof RelayError ? error.toBridgeError() : toBridgeError(error, body.name);
+        const payload = {
           ok: false,
-          error: error instanceof Error ? error.message : String(error)
+          error: errorDetails.message,
+          errorDetails
         };
-        if (notice) body2.notice = notice;
-        reply.code(500).send(body2);
+        attachNotices(payload, notice);
+        reply.code(500).send(payload);
       }
     });
     await this.app.listen({ port: this.port, host: "127.0.0.1" });
@@ -135,7 +190,12 @@ var ExtensionBridge = class {
       pending.resolve(message.payload.data);
       return;
     }
-    pending.reject(new Error(message.payload.error));
+    const details = message.payload.errorDetails;
+    if (details) {
+      pending.reject(new RelayError(details));
+    } else {
+      pending.reject(new Error(message.payload.error));
+    }
   }
   async waitUntilReady(timeoutMs = 15e3) {
     if (this.ready) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-relay",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",