fix(cli): address PR #983 review feedback

- play.ts: move --remote-debugging-port parse+deps validation before any
  server setup so an invalid value exits cleanly instead of leaking a
  listening socket (the original bug — server printed 'Player running'
  and 'Press Ctrl+C to stop' before failing).
- Extract validateRemoteDebuggingPortDeps() in openBrowser.ts to keep
  preview.ts and play.ts in sync instead of copy-pasting the dep
  checks.
- Narrow parseRemoteDebuggingPort param to string | undefined; drop the
  dead null branch and the redundant String() / Number.isInteger() now
  that the regex already constrains the input.
- buildBrowserArgs: omit --remote-debugging-port when userDataDir is
  missing so a CDP endpoint cannot leak into the user's main profile
  even if a caller bypasses the CLI validation layer.
- Replace the duplicated buildBrowserArgs case with one that proves
  this defense-in-depth behaviour; add unit tests for
  validateRemoteDebuggingPortDeps.
- Drop the heavy JSDoc on parseRemoteDebuggingPort to match the file's
  surrounding style.
- Both commands: align --remote-debugging-port description (it now
  matches the actual 'requires --browser-path and --user-data-dir'
  contract) and add a CDP example to the --help output.

packages/cli/src/utils/openBrowser.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect } from "vitest";
-import { buildBrowserArgs, parseRemoteDebuggingPort } from "./openBrowser.js";
+import {
+  buildBrowserArgs,
+  parseRemoteDebuggingPort,
+  validateRemoteDebuggingPortDeps,
+} from "./openBrowser.js";
 
 describe("buildBrowserArgs", () => {
   it("returns only the URL when no options are given", () => {
@@ -38,18 +42,16 @@ describe("buildBrowserArgs", () => {
     ).toEqual(["--user-data-dir=C:\\Documents and Settings\\profile", "http://localhost:3002"]);
   });
 
-  it("prepends --remote-debugging-port before the URL", () => {
+  it("omits --remote-debugging-port when userDataDir is missing (defense in depth)", () => {
+    // The CLI validation layer rejects this combination upstream, but
+    // buildBrowserArgs must not leak a CDP endpoint into the user's main
+    // profile even if a caller bypasses that check.
     expect(
       buildBrowserArgs("http://localhost:3002", {
         browserPath: "/usr/bin/chromium",
-        userDataDir: "/tmp/hf-profile",
         remoteDebuggingPort: 9222,
       }),
-    ).toEqual([
-      "--user-data-dir=/tmp/hf-profile",
-      "--remote-debugging-port=9222",
-      "http://localhost:3002",
-    ]);
+    ).toEqual(["http://localhost:3002"]);
   });
 
   it("includes all flags together", () => {
@@ -114,3 +116,45 @@ describe("parseRemoteDebuggingPort", () => {
     expect(() => parseRemoteDebuggingPort("22.5")).toThrow();
   });
 });
+
+describe("validateRemoteDebuggingPortDeps", () => {
+  it("returns null when --remote-debugging-port is not set", () => {
+    expect(validateRemoteDebuggingPortDeps({})).toBeNull();
+  });
+
+  it("returns null when all required flags are present", () => {
+    expect(
+      validateRemoteDebuggingPortDeps({
+        browserPath: "/usr/bin/chromium",
+        userDataDir: "/tmp/hf-profile",
+        remoteDebuggingPort: "9222",
+      }),
+    ).toBeNull();
+  });
+
+  it("requires --browser-path when --remote-debugging-port is set", () => {
+    expect(
+      validateRemoteDebuggingPortDeps({
+        userDataDir: "/tmp/hf-profile",
+        remoteDebuggingPort: "9222",
+      }),
+    ).toBe("--remote-debugging-port requires --browser-path");
+  });
+
+  it("requires --user-data-dir when --remote-debugging-port is set", () => {
+    expect(
+      validateRemoteDebuggingPortDeps({
+        browserPath: "/usr/bin/chromium",
+        remoteDebuggingPort: "9222",
+      }),
+    ).toBe("--remote-debugging-port requires --user-data-dir");
+  });
+
+  it("reports --browser-path first when both deps are missing", () => {
+    expect(
+      validateRemoteDebuggingPortDeps({
+        remoteDebuggingPort: "9222",
+      }),
+    ).toBe("--remote-debugging-port requires --browser-path");
+  });
+});