@ait-co/devtools 0.1.58 → 0.1.60

package/dist/devtools-opener-h6A-UjzC.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools-opener-h6A-UjzC.cjs","names":[],"sources":["../src/mcp/devtools-opener.ts"],"sourcesContent":["/**\n * Auto-opens Chrome DevTools when a page attaches over the Chii relay.\n *\n * When a real device attaches (env 2 / 3 / 4 in the 4-environments fidelity\n * ladder), the Chii relay exposes a standard CDP WebSocket endpoint. The\n * Chrome DevTools frontend can connect to any such endpoint via:\n *\n *   https://chrome-devtools-frontend.appspot.com/serve_file/@/inspector.html\n *     ?wss=<host>[/<path>]\n *     &panel=console\n *\n * Where `<host>` is the public WSS relay URL without the `wss://` scheme prefix\n * (the DevTools frontend adds it). This module assembles that URL and opens it\n * in the OS default browser so the developer immediately gets a full Chrome\n * DevTools UI.\n *\n * IMPORTANT — environment guard:\n *   Auto-open only fires in relay environments (env 2 / 3 / 4). In env 1\n *   (local browser + mock SDK) the developer already has F12 available; opening\n *   a DevTools window pointing at the mock relay would be confusing and useless.\n *   The caller (`startAttachWatcher` in `debug-server.ts`) passes the current\n *   environment and this module bails out when it is `mock`.\n *\n * Opt-out: set `AIT_AUTO_DEVTOOLS=0` in the environment to suppress auto-open\n *   entirely. Any other value (or absent) enables the default behaviour.\n *\n * Duplicate-open guard:\n *   `AutoDevtoolsOpener` tracks whether open was already triggered for the\n *   current session. The open fires at most once per instance — typically one\n *   per `runDebugServer` call.\n *\n * PWA (WebKit) caveat:\n *   The Chii relay injects a chobitsu CDP shim into WebKit-based runtimes (env 2\n *   AITC Sandbox PWA). The DevTools frontend will connect and most panels work.\n *   However, WebKit does not expose the full CDP domain set that V8/Blink does,\n *   so some panels (Network, Layers) may appear empty or show limited data.\n *   This is a WebKit runtime constraint, not a relay or devtools-opener issue.\n *\n * Node-only: uses `child_process.spawnSync` to invoke the OS open command.\n */\n\nimport type { McpEnvironment } from './environment.js';\n\n// ---------------------------------------------------------------------------\n// Chrome DevTools frontend URL\n// ---------------------------------------------------------------------------\n\n/**\n * Base URL for the Chrome DevTools inspector hosted on appspot.\n *\n * The `@` path segment is the \"latest / bleeding edge\" alias which tracks the\n * current Chrome stable CDP protocol version — compatible with the chobitsu-\n * based CDP that Chii injects. A specific commit hash may be pinned here if\n * a regression is observed.\n */\nconst DEVTOOLS_FRONTEND_BASE =\n  'https://chrome-devtools-frontend.appspot.com/serve_file/@/inspector.html';\n\n// ---------------------------------------------------------------------------\n// URL assembly\n// ---------------------------------------------------------------------------\n\n/**\n * Assembles the Chrome DevTools inspector URL that connects to a Chii relay\n * WebSocket.\n *\n * The `wss=` parameter expects a host-and-path string without the `wss://`\n * scheme prefix — the DevTools frontend prepends it automatically.\n *\n * @param wssRelayUrl - Full `wss://` URL of the Chii relay (public tunnel).\n *   Example: `wss://abc.trycloudflare.com`\n * @param panel - Initial panel. Defaults to `\"console\"`.\n *\n * @example\n * buildChromeDevtoolsUrl('wss://abc.trycloudflare.com')\n * // → 'https://chrome-devtools-frontend.appspot.com/serve_file/@/inspector.html?wss=abc.trycloudflare.com&panel=console'\n */\nexport function buildChromeDevtoolsUrl(\n  wssRelayUrl: string,\n  panel: 'elements' | 'console' | 'sources' | 'network' = 'console',\n): string {\n  // Strip `wss://` prefix — the DevTools frontend expects host[/path] only.\n  const wssParam = wssRelayUrl.replace(/^wss:\\/\\//i, '');\n  const params = new URLSearchParams({ wss: wssParam, panel });\n  return `${DEVTOOLS_FRONTEND_BASE}?${params.toString()}`;\n}\n\n// ---------------------------------------------------------------------------\n// Opt-out check\n// ---------------------------------------------------------------------------\n\n/**\n * Returns `true` when auto-open is **disabled** via the `AIT_AUTO_DEVTOOLS`\n * env var. Only the explicit `\"0\"` value disables it; anything else (including\n * absent) leaves auto-open enabled.\n */\nexport function isAutoDevtoolsDisabled(): boolean {\n  return process.env.AIT_AUTO_DEVTOOLS === '0';\n}\n\n// ---------------------------------------------------------------------------\n// Browser open (Node-only, sync)\n// ---------------------------------------------------------------------------\n\n/**\n * Opens the given URL in the OS default browser using a platform-appropriate\n * command. Returns `true` on success.\n *\n * Failures are silent from the caller's perspective — the caller should log\n * the URL to stderr as a fallback before calling this function.\n */\nexport function openUrlInBrowser(url: string): boolean {\n  // Test hook: skip actual spawn when running in vitest / CI where the OS open\n  // command may hang or be absent. Production code never sets this.\n  if (process.env.AIT_AUTO_DEVTOOLS_TEST_SKIP_SPAWN === '1') return false;\n  // eslint-disable-next-line @typescript-eslint/no-require-imports\n  const { spawnSync } = require('node:child_process') as typeof import('node:child_process');\n  const platform = process.platform;\n\n  type Candidate = { cmd: string; args: string[] };\n  let candidates: Candidate[];\n  if (platform === 'darwin') {\n    candidates = [{ cmd: 'open', args: [url] }];\n  } else if (platform === 'win32') {\n    candidates = [{ cmd: 'cmd', args: ['/c', 'start', '', url] }];\n  } else {\n    // Linux + fallback\n    candidates = [\n      { cmd: 'xdg-open', args: [url] },\n      { cmd: 'sensible-browser', args: [url] },\n      { cmd: 'x-www-browser', args: [url] },\n    ];\n  }\n\n  for (const { cmd, args } of candidates) {\n    try {\n      const result = spawnSync(cmd, args, { encoding: 'utf8', timeout: 5_000 });\n      if (!result.error && result.status === 0) return true;\n    } catch {\n      // Try next candidate.\n    }\n  }\n  return false;\n}\n\n// ---------------------------------------------------------------------------\n// AutoDevtoolsOpener — stateful once-per-session open guard\n// ---------------------------------------------------------------------------\n\n/**\n * Manages auto-opening Chrome DevTools exactly once per relay attach session.\n *\n * Create one instance per `runDebugServer` call and pass its `open()` method\n * as the `onFirstAttach` callback to `startAttachWatcher`.\n *\n * The open fires at most once. Subsequent `open()` calls are no-ops.\n * Opt-out and mock-environment guard are checked at call time.\n */\nexport class AutoDevtoolsOpener {\n  private _opened = false;\n\n  /**\n   * Attempts to auto-open Chrome DevTools.\n   *\n   * No-op when any of the following conditions hold:\n   *   1. Already opened this session (`_opened` is true).\n   *   2. `AIT_AUTO_DEVTOOLS=0` opt-out is set.\n   *   3. Environment is `mock` (env 1 — F12 is already available).\n   *   4. `wssRelayUrl` is null/undefined/empty (tunnel not yet up).\n   *\n   * Always writes the DevTools URL to stderr so the developer can copy it\n   * if the browser open fails or the popup is blocked.\n   *\n   * @param wssRelayUrl - The public `wss://` relay URL (from tunnel status).\n   * @param env - Current MCP environment (`mock` | `relay`).\n   */\n  open(wssRelayUrl: string | null | undefined, env: McpEnvironment): void {\n    if (this._opened) return;\n    if (isAutoDevtoolsDisabled()) return;\n    if (env === 'mock') return;\n    if (!wssRelayUrl) return;\n\n    this._opened = true;\n\n    const devtoolsUrl = buildChromeDevtoolsUrl(wssRelayUrl);\n\n    process.stderr.write(\n      '[ait-debug] 기기가 연결됐습니다 — Chrome DevTools를 자동으로 엽니다.\\n' +\n        `[ait-debug] Chrome DevTools URL: ${devtoolsUrl}\\n` +\n        '[ait-debug] (AIT_AUTO_DEVTOOLS=0 으로 자동 열기를 끌 수 있습니다)\\n',\n    );\n\n    const opened = openUrlInBrowser(devtoolsUrl);\n    if (!opened) {\n      process.stderr.write(\n        '[ait-debug] 브라우저 자동 열기 실패 — 위 URL을 브라우저에서 직접 여세요.\\n',\n      );\n    }\n  }\n\n  /** Returns `true` if `open()` has passed all guards and fired once. */\n  get opened(): boolean {\n    return this._opened;\n  }\n}\n"],"mappings":";;;;;;AAgGA,SAAgB,yBAAkC;AAChD,QAAO,QAAQ,IAAI,sBAAsB;;;;;;;;;AAc3C,SAAgB,iBAAiB,KAAsB;AAGrD,KAAI,QAAQ,IAAI,sCAAsC,IAAK,QAAO;CAElE,MAAM,EAAE,cAAc,QAAQ,qBAAqB;CACnD,MAAM,WAAW,QAAQ;CAGzB,IAAI;AACJ,KAAI,aAAa,SACf,cAAa,CAAC;EAAE,KAAK;EAAQ,MAAM,CAAC,IAAI;EAAE,CAAC;UAClC,aAAa,QACtB,cAAa,CAAC;EAAE,KAAK;EAAO,MAAM;GAAC;GAAM;GAAS;GAAI;GAAI;EAAE,CAAC;KAG7D,cAAa;EACX;GAAE,KAAK;GAAY,MAAM,CAAC,IAAI;GAAE;EAChC;GAAE,KAAK;GAAoB,MAAM,CAAC,IAAI;GAAE;EACxC;GAAE,KAAK;GAAiB,MAAM,CAAC,IAAI;GAAE;EACtC;AAGH,MAAK,MAAM,EAAE,KAAK,UAAU,WAC1B,KAAI;EACF,MAAM,SAAS,UAAU,KAAK,MAAM;GAAE,UAAU;GAAQ,SAAS;GAAO,CAAC;AACzE,MAAI,CAAC,OAAO,SAAS,OAAO,WAAW,EAAG,QAAO;SAC3C;AAIV,QAAO"}