chrome-relay 0.5.2 → 0.5.4

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.4" : "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,22 @@ async function callTool(name, args) {
 
 // src/release-notes.ts
 var RELEASE_NOTES = {
+  "0.5.4": [
+    "Strict target routing (code-quality-hardening PR 2). Within a single scope, --tab / --workspace / --group are mutually exclusive \u2014 passing more than one on the same subcommand (or both at the program level) now fails with `target_conflict` and exit code 2.",
+    "Cross-scope override is still allowed but visible: `chrome-relay --workspace W <cmd> --workspace W2` works, but stderr prints a `target_overridden: workspace W \u2192 W2` notice so the agent (or user) knows what happened.",
+    "Fixed silent drops: `viewport set` and `console` previously hand-rolled their args and ignored global --workspace/--group. They now route through baseArgs() like every other targetable command.",
+    "New target-routing test matrix (55 tests) proves every targetable subcommand forwards --tab, --workspace, and --group correctly \u2014 and that the strict-conflict + override behavior holds. If you add a new targetable command to the CLI, add it to TARGETABLE_COMMANDS in packages/cli/test/target-routing.test.ts.",
+    "New TargetSelector type in @chrome-relay/protocol (future-proofing). Wire still carries the three loose fields; a future PR migrates the extension to read a single structured `target` field."
+  ],
+  "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 +325,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);
     }
   }
@@ -290,15 +340,53 @@ Notes:
     return cmd.option("-t, --tab <id>", "target tab ID", (v) => Number(v)).option("--workspace <name>", "target the active tab in a named workspace window (see `chrome-relay workspace`)").option("--group <name>", "target the active tab in a named tab-group (see `chrome-relay group`)");
   }
   function baseArgs(opts) {
+    const parentOpts = program.opts();
+    rejectIntraScopeConflict("subcommand", {
+      tab: opts.tab,
+      workspace: opts.workspace,
+      group: opts.group
+    });
+    rejectIntraScopeConflict("program-level", {
+      workspace: parentOpts.workspace,
+      group: parentOpts.group
+    });
+    if (opts.workspace && parentOpts.workspace && opts.workspace !== parentOpts.workspace) {
+      emitTargetOverride("workspace", parentOpts.workspace, opts.workspace);
+    }
+    if (opts.group && parentOpts.group && opts.group !== parentOpts.group) {
+      emitTargetOverride("group", parentOpts.group, opts.group);
+    }
+    if (opts.tab !== void 0 && (parentOpts.workspace || parentOpts.group)) {
+      const prior = parentOpts.workspace ? `workspace=${parentOpts.workspace}` : `group=${parentOpts.group}`;
+      emitTargetOverride("tab", prior, String(opts.tab));
+    }
     const args = {};
     if (opts.tab !== void 0) args.tabId = opts.tab;
-    const parentOpts = program.opts();
     const effectiveWorkspace = opts.workspace ?? parentOpts.workspace;
     const effectiveGroup = opts.group ?? parentOpts.group;
-    if (effectiveWorkspace) args.workspaceName = effectiveWorkspace;
-    if (effectiveGroup) args.groupName = effectiveGroup;
+    if (opts.tab === void 0 && effectiveWorkspace) args.workspaceName = effectiveWorkspace;
+    if (opts.tab === void 0 && effectiveGroup) args.groupName = effectiveGroup;
     return args;
   }
+  function rejectIntraScopeConflict(scope, fields) {
+    const present = [];
+    if (fields.tab !== void 0) present.push("--tab");
+    if (fields.workspace) present.push("--workspace");
+    if (fields.group) present.push("--group");
+    if (present.length > 1) {
+      process.stderr.write(
+        `[chrome-relay] target_conflict: ${scope} flags ${present.join(" + ")} are mutually exclusive. Pass exactly one of --tab, --workspace, or --group on the same ${scope}.
+`
+      );
+      process.exit(2);
+    }
+  }
+  function emitTargetOverride(kind, from, to) {
+    process.stderr.write(
+      `[chrome-relay] target_overridden: ${kind} ${from} \u2192 ${to} (subcommand-level overrides program-level)
+`
+    );
+  }
   program.command("tabs [verb]").description("List open Chrome windows and tabs. (verb 'list' is accepted as alias)").action(async (verb) => {
     if (verb && verb !== "list") {
       process.stderr.write(`unknown tabs verb: ${verb}. Use 'tabs' or 'tabs list'.
@@ -494,7 +582,7 @@ Notes:
     viewport.command("set").description("Apply explicit viewport dimensions.").requiredOption("--width <px>", "viewport width in CSS pixels", (v) => Number(v)).requiredOption("--height <px>", "viewport height in CSS pixels", (v) => Number(v)).option("--dpr <ratio>", "device pixel ratio (1, 2, 3...)", (v) => Number(v)).option("--mobile", "set the mobile flag (affects meta viewport interpretation)").option("--touch", "enable touch event emulation").option("--user-agent <ua>", "override the User-Agent header")
   ).action(async (opts) => {
     const args = { action: "set", width: opts.width, height: opts.height };
-    if (opts.tab !== void 0) args.tabId = opts.tab;
+    Object.assign(args, baseArgs(opts));
     if (opts.dpr !== void 0) args.dpr = opts.dpr;
     if (opts.mobile) args.mobile = true;
     if (opts.touch) args.hasTouch = true;
@@ -726,8 +814,7 @@ Notes:
 `
     )
   ).action(async (opts) => {
-    const args = {};
-    if (opts.tab !== void 0) args.tabId = opts.tab;
+    const args = baseArgs(opts);
     if (opts.clear) args.action = "clear";
     if (opts.level) args.levels = opts.level;
     if (typeof opts.since === "number") args.since = opts.since;

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.4" : "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.4" : "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.4",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",