@ait-co/devtools 0.1.71 → 0.1.73

package/dist/{deeplink-CaO6hZVG.js → deeplink-B-94XmWA.js}

@@ -16,6 +16,11 @@ const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
 * is injected. `&at=<totpCode>` is added only when a code is provided (same
 * conditional as {@link buildDeepLinkAttachUrl}).
 *
+* When `opts.name` is given (non-blank), it is added as `&name=` so the
+* launcher partner bar shows the app name instead of the generic default (#498).
+* When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the
+* launcher can render an icon next to the title (#498).
+*
 * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL
 * via raw string manipulation), this function uses WHATWG `encodeURIComponent`
 * because the target is a standard `https:` URL.
@@ -30,15 +35,26 @@ const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
 * @param totpCode - Optional current TOTP code (6 digits). When provided, it
 *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates
 *   every 30 s. Omit when TOTP is disabled.
+* @param opts - Optional app identity hints: `name` and `icon` (#498).
 * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>
-*   [&at=<code>]` params.
+*   [&at=<code>][&name=<enc>][&icon=<enc>]` params.
 */
-function buildLauncherAttachUrl(tunnelUrl, wssUrl, totpCode) {
+function buildLauncherAttachUrl(tunnelUrl, wssUrl, totpCode, opts) {
 	let url = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}&debug=1&relay=${encodeURIComponent(wssUrl)}`;
 	if (totpCode !== void 0 && totpCode !== "") url += `&at=${encodeURIComponent(totpCode)}`;
+	if (opts?.name !== void 0 && opts.name.trim() !== "") url += `&name=${encodeURIComponent(opts.name.trim())}`;
+	if (opts?.icon !== void 0) {
+		let iconParsed;
+		try {
+			iconParsed = new URL(opts.icon);
+		} catch {
+			iconParsed = null;
+		}
+		if (iconParsed?.protocol === "https:") url += `&icon=${encodeURIComponent(opts.icon)}`;
+	}
 	return url;
 }
 //#endregion
 export { buildLauncherAttachUrl };
 
-//# sourceMappingURL=deeplink-CaO6hZVG.js.map
+//# sourceMappingURL=deeplink-B-94XmWA.js.map

package/dist/deeplink-B-94XmWA.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deeplink-B-94XmWA.js","names":[],"sources":["../src/mcp/deeplink.ts"],"sourcesContent":["/**\n * URL of the AITC Sandbox launcher PWA.\n *\n * Declared here (not imported from `src/unplugin/tunnel.ts`) to respect the\n * mcp → unplugin layering boundary. unplugin/tunnel.ts declares its own copy\n * for the same reason — keep the two in sync when the URL changes.\n */\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Optional metadata that enriches the launcher deep-link (#498).\n *\n * These fields are added as query params so the launcher PWA can display\n * a recognizable identity (name, icon) without the user having to configure\n * anything extra.\n */\nexport interface LauncherAttachUrlOpts {\n  /**\n   * Human-readable app name shown in the partner nav bar (`name=` param).\n   * Blank / whitespace-only values are not added.\n   */\n  name?: string;\n  /**\n   * Absolute `https://` icon URL for the partner nav bar icon slot (`icon=`\n   * param). Non-https or falsy values are not added.\n   */\n  icon?: string;\n}\n\n/**\n * Builds a launcher PWA deep-link for env-2 MCP-attach (issue #378).\n *\n * The launcher at {@link LAUNCHER_URL} renders tunnelUrl in a full-viewport\n * iframe. `&debug=1&relay=<wssUrl>` is forwarded onto the iframe src so the\n * framed page's in-app debug gate (Layer C) is satisfied and a Chii target.js\n * is injected. `&at=<totpCode>` is added only when a code is provided (same\n * conditional as {@link buildDeepLinkAttachUrl}).\n *\n * When `opts.name` is given (non-blank), it is added as `&name=` so the\n * launcher partner bar shows the app name instead of the generic default (#498).\n * When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the\n * launcher can render an icon next to the title (#498).\n *\n * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL\n * via raw string manipulation), this function uses WHATWG `encodeURIComponent`\n * because the target is a standard `https:` URL.\n *\n * SECRET-HANDLING: `totpCode` (when provided) is placed into the `at=` param\n * only — never logged or returned separately. Callers must NOT log the result\n * of this function to stdout/stderr.\n *\n * @param tunnelUrl - The `https://*.trycloudflare.com` app tunnel URL\n *   (`AIT_TUNNEL_BASE_URL`). This is the URL the launcher frames.\n * @param wssUrl - The `wss://` relay URL the framed page will attach to.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Omit when TOTP is disabled.\n * @param opts - Optional app identity hints: `name` and `icon` (#498).\n * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>\n *   [&at=<code>][&name=<enc>][&icon=<enc>]` params.\n */\nexport function buildLauncherAttachUrl(\n  tunnelUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n  opts?: LauncherAttachUrlOpts,\n): string {\n  let url =\n    `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}` +\n    `&debug=1&relay=${encodeURIComponent(wssUrl)}`;\n  if (totpCode !== undefined && totpCode !== '') {\n    url += `&at=${encodeURIComponent(totpCode)}`;\n  }\n  // App identity hints (#498): add non-blank name and valid https icon.\n  if (opts?.name !== undefined && opts.name.trim() !== '') {\n    url += `&name=${encodeURIComponent(opts.name.trim())}`;\n  }\n  if (opts?.icon !== undefined) {\n    let iconParsed: URL;\n    try {\n      iconParsed = new URL(opts.icon);\n    } catch {\n      iconParsed = null as unknown as URL;\n    }\n    if (iconParsed?.protocol === 'https:') {\n      url += `&icon=${encodeURIComponent(opts.icon)}`;\n    }\n  }\n  return url;\n}\n\n/**\n * Build a self-attaching dogfood deep link.\n *\n * `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`\n * URL that opens a dogfood bundle on a phone. The in-app debug gate\n * (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries\n * `debug=1` and `relay=<wss-url>`. This helper splices those params (plus\n * `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result\n * as a QR code and scanning it with the phone camera opens the mini-app and\n * attaches it to the live Chii relay. QR is the single entry path — it needs\n * no USB cable, platform CLI, or driver, and works the same on iOS/Android.\n *\n * The Toss app propagates extra query params from the entry deep link into the\n * mini-app WebView's `location.search` (confirmed behavior), so the gate reads\n * them at attach time.\n *\n * TOTP `at=` param:\n *   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional\n *   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.\n *   The code must be computed by the caller at call time — do NOT pre-compute\n *   and cache it, because the 30-second window expires quickly. The in-app gate\n *   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.\n *\n * Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.\n * The WHATWG `URL` parser treats such schemes opaquely (no host/path/query\n * decomposition you can rely on across runtimes), so query manipulation via\n * `url.searchParams` is not portable here. We splice the query string directly\n * on the raw string instead, which keeps the scheme, authority, path, and any\n * pre-existing params (notably `_deploymentId`) byte-for-byte intact.\n */\n\n/**\n * Suspicious/generic authority values that indicate a malformed or placeholder\n * scheme URL. These are host strings that will almost certainly cause the Toss\n * app to fail with \"bundle not found\" silently.\n *\n * The expected form from `ait deploy --scheme-only` is:\n *   intoss-private://<appName>?_deploymentId=<uuid>\n * where `<appName>` is a non-generic string like `aitc-sdk-example`.\n */\nconst SUSPICIOUS_AUTHORITIES = new Set<string>(['', 'web', 'localhost', '127.0.0.1', 'app']);\n\n/**\n * Validates the authority (host) portion of a scheme URL.\n *\n * Returns a warning message if the authority is missing or looks like a\n * placeholder, or `null` if the authority looks valid.\n *\n * Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`\n * The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).\n */\nexport function validateSchemeAuthority(schemeUrl: string): string | null {\n  // Extract authority from `scheme://authority[/path][?query][#hash]`.\n  // We cannot use the WHATWG URL parser for non-special schemes reliably\n  // (see the deeplink.ts module comment), so we parse the raw string.\n  const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\\-.]*:\\/\\//, '');\n  if (afterScheme === schemeUrl) {\n    // No `://` found — not a scheme URL at all.\n    return (\n      'scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). ' +\n      'Use the URL printed by `ait deploy --scheme-only`.'\n    );\n  }\n\n  // authority ends at the first `/`, `?`, `#`, or end of string.\n  const authorityEnd = afterScheme.search(/[/?#]/);\n  const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);\n\n  if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) {\n    const displayAuthority = authority === '' ? '(empty)' : `\"${authority}\"`;\n    return (\n      `scheme_url authority ${displayAuthority} looks like a placeholder. ` +\n      'Expected an app name like `intoss-private://aitc-sdk-example?_deploymentId=<uuid>`. ' +\n      'Use the URL printed by `ait deploy --scheme-only` — it includes the correct app name as the host.'\n    );\n  }\n\n  return null;\n}\n\n/** A param the helper appends. Existing occurrences are replaced, not duplicated. */\ntype AppendParam = readonly [key: string, value: string];\n\nfunction stripExisting(query: string, key: string): string {\n  if (query === '') return '';\n  return query\n    .split('&')\n    .filter((pair) => pair !== '' && pair.split('=')[0] !== key)\n    .join('&');\n}\n\n/**\n * Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a\n * scheme URL's query string, preserving everything else (scheme, authority,\n * path, hash, and the existing `_deploymentId` param). If any of the spliced\n * params is already present it is replaced so the helper is idempotent.\n *\n * @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed\n *   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B\n *   of the gate); this helper does not invent one.\n * @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the\n *   running debug MCP server's quick tunnel.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Pass `undefined` or omit when TOTP is disabled.\n * @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`\n *   appended.\n * @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so\n *   producing such a link would be a silent dead end).\n */\nexport function buildDeepLinkAttachUrl(\n  schemeUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n): string {\n  let relay: URL;\n  try {\n    relay = new URL(wssUrl);\n  } catch {\n    throw new Error(`relay URL is not a valid URL: ${wssUrl}`);\n  }\n  if (relay.protocol !== 'wss:') {\n    throw new Error(`relay URL must use the wss: scheme, got ${relay.protocol} (${wssUrl})`);\n  }\n\n  const hashIndex = schemeUrl.indexOf('#');\n  const hash = hashIndex === -1 ? '' : schemeUrl.slice(hashIndex);\n  const beforeHash = hashIndex === -1 ? schemeUrl : schemeUrl.slice(0, hashIndex);\n\n  const queryIndex = beforeHash.indexOf('?');\n  const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);\n  let query = queryIndex === -1 ? '' : beforeHash.slice(queryIndex + 1);\n\n  const appended: AppendParam[] = [\n    ['debug', '1'],\n    ['relay', wssUrl],\n  ];\n  // Only splice `at=` when a code is provided (TOTP enabled). Omitting it when\n  // TOTP is disabled preserves backward compatibility with gate deployments\n  // that do not yet evaluate the `at` param.\n  if (totpCode !== undefined && totpCode !== '') {\n    appended.push(['at', totpCode]);\n  }\n\n  // Always strip the `at` key from the existing query so a stale code from a\n  // previous run is removed even when the caller does not provide a fresh code.\n  query = stripExisting(query, 'at');\n\n  for (const [key] of appended) {\n    query = stripExisting(query, key);\n  }\n  for (const [key, value] of appended) {\n    const pair = `${key}=${encodeURIComponent(value)}`;\n    query = query === '' ? pair : `${query}&${pair}`;\n  }\n\n  return `${base}?${query}${hash}`;\n}\n"],"mappings":";;;;;;;;AAOA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDrB,SAAgB,uBACd,WACA,QACA,UACA,MACQ;CACR,IAAI,MACF,GAAG,aAAa,OAAO,mBAAmB,UAAU,CAAA,iBAClC,mBAAmB,OAAO;AAC9C,KAAI,aAAa,KAAA,KAAa,aAAa,GACzC,QAAO,OAAO,mBAAmB,SAAS;AAG5C,KAAI,MAAM,SAAS,KAAA,KAAa,KAAK,KAAK,MAAM,KAAK,GACnD,QAAO,SAAS,mBAAmB,KAAK,KAAK,MAAM,CAAC;AAEtD,KAAI,MAAM,SAAS,KAAA,GAAW;EAC5B,IAAI;AACJ,MAAI;AACF,gBAAa,IAAI,IAAI,KAAK,KAAK;UACzB;AACN,gBAAa;;AAEf,MAAI,YAAY,aAAa,SAC3B,QAAO,SAAS,mBAAmB,KAAK,KAAK;;AAGjD,QAAO"}

package/dist/{deeplink-BONXxWEO.cjs → deeplink-BLU2_hg6.cjs}

@@ -16,6 +16,11 @@ const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
 * is injected. `&at=<totpCode>` is added only when a code is provided (same
 * conditional as {@link buildDeepLinkAttachUrl}).
 *
+* When `opts.name` is given (non-blank), it is added as `&name=` so the
+* launcher partner bar shows the app name instead of the generic default (#498).
+* When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the
+* launcher can render an icon next to the title (#498).
+*
 * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL
 * via raw string manipulation), this function uses WHATWG `encodeURIComponent`
 * because the target is a standard `https:` URL.
@@ -30,15 +35,26 @@ const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
 * @param totpCode - Optional current TOTP code (6 digits). When provided, it
 *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates
 *   every 30 s. Omit when TOTP is disabled.
+* @param opts - Optional app identity hints: `name` and `icon` (#498).
 * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>
-*   [&at=<code>]` params.
+*   [&at=<code>][&name=<enc>][&icon=<enc>]` params.
 */
-function buildLauncherAttachUrl(tunnelUrl, wssUrl, totpCode) {
+function buildLauncherAttachUrl(tunnelUrl, wssUrl, totpCode, opts) {
 	let url = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}&debug=1&relay=${encodeURIComponent(wssUrl)}`;
 	if (totpCode !== void 0 && totpCode !== "") url += `&at=${encodeURIComponent(totpCode)}`;
+	if (opts?.name !== void 0 && opts.name.trim() !== "") url += `&name=${encodeURIComponent(opts.name.trim())}`;
+	if (opts?.icon !== void 0) {
+		let iconParsed;
+		try {
+			iconParsed = new URL(opts.icon);
+		} catch {
+			iconParsed = null;
+		}
+		if (iconParsed?.protocol === "https:") url += `&icon=${encodeURIComponent(opts.icon)}`;
+	}
 	return url;
 }
 //#endregion
 exports.buildLauncherAttachUrl = buildLauncherAttachUrl;
 
-//# sourceMappingURL=deeplink-BONXxWEO.cjs.map
+//# sourceMappingURL=deeplink-BLU2_hg6.cjs.map

package/dist/deeplink-BLU2_hg6.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"deeplink-BLU2_hg6.cjs","names":[],"sources":["../src/mcp/deeplink.ts"],"sourcesContent":["/**\n * URL of the AITC Sandbox launcher PWA.\n *\n * Declared here (not imported from `src/unplugin/tunnel.ts`) to respect the\n * mcp → unplugin layering boundary. unplugin/tunnel.ts declares its own copy\n * for the same reason — keep the two in sync when the URL changes.\n */\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Optional metadata that enriches the launcher deep-link (#498).\n *\n * These fields are added as query params so the launcher PWA can display\n * a recognizable identity (name, icon) without the user having to configure\n * anything extra.\n */\nexport interface LauncherAttachUrlOpts {\n  /**\n   * Human-readable app name shown in the partner nav bar (`name=` param).\n   * Blank / whitespace-only values are not added.\n   */\n  name?: string;\n  /**\n   * Absolute `https://` icon URL for the partner nav bar icon slot (`icon=`\n   * param). Non-https or falsy values are not added.\n   */\n  icon?: string;\n}\n\n/**\n * Builds a launcher PWA deep-link for env-2 MCP-attach (issue #378).\n *\n * The launcher at {@link LAUNCHER_URL} renders tunnelUrl in a full-viewport\n * iframe. `&debug=1&relay=<wssUrl>` is forwarded onto the iframe src so the\n * framed page's in-app debug gate (Layer C) is satisfied and a Chii target.js\n * is injected. `&at=<totpCode>` is added only when a code is provided (same\n * conditional as {@link buildDeepLinkAttachUrl}).\n *\n * When `opts.name` is given (non-blank), it is added as `&name=` so the\n * launcher partner bar shows the app name instead of the generic default (#498).\n * When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the\n * launcher can render an icon next to the title (#498).\n *\n * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL\n * via raw string manipulation), this function uses WHATWG `encodeURIComponent`\n * because the target is a standard `https:` URL.\n *\n * SECRET-HANDLING: `totpCode` (when provided) is placed into the `at=` param\n * only — never logged or returned separately. Callers must NOT log the result\n * of this function to stdout/stderr.\n *\n * @param tunnelUrl - The `https://*.trycloudflare.com` app tunnel URL\n *   (`AIT_TUNNEL_BASE_URL`). This is the URL the launcher frames.\n * @param wssUrl - The `wss://` relay URL the framed page will attach to.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Omit when TOTP is disabled.\n * @param opts - Optional app identity hints: `name` and `icon` (#498).\n * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>\n *   [&at=<code>][&name=<enc>][&icon=<enc>]` params.\n */\nexport function buildLauncherAttachUrl(\n  tunnelUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n  opts?: LauncherAttachUrlOpts,\n): string {\n  let url =\n    `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}` +\n    `&debug=1&relay=${encodeURIComponent(wssUrl)}`;\n  if (totpCode !== undefined && totpCode !== '') {\n    url += `&at=${encodeURIComponent(totpCode)}`;\n  }\n  // App identity hints (#498): add non-blank name and valid https icon.\n  if (opts?.name !== undefined && opts.name.trim() !== '') {\n    url += `&name=${encodeURIComponent(opts.name.trim())}`;\n  }\n  if (opts?.icon !== undefined) {\n    let iconParsed: URL;\n    try {\n      iconParsed = new URL(opts.icon);\n    } catch {\n      iconParsed = null as unknown as URL;\n    }\n    if (iconParsed?.protocol === 'https:') {\n      url += `&icon=${encodeURIComponent(opts.icon)}`;\n    }\n  }\n  return url;\n}\n\n/**\n * Build a self-attaching dogfood deep link.\n *\n * `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`\n * URL that opens a dogfood bundle on a phone. The in-app debug gate\n * (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries\n * `debug=1` and `relay=<wss-url>`. This helper splices those params (plus\n * `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result\n * as a QR code and scanning it with the phone camera opens the mini-app and\n * attaches it to the live Chii relay. QR is the single entry path — it needs\n * no USB cable, platform CLI, or driver, and works the same on iOS/Android.\n *\n * The Toss app propagates extra query params from the entry deep link into the\n * mini-app WebView's `location.search` (confirmed behavior), so the gate reads\n * them at attach time.\n *\n * TOTP `at=` param:\n *   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional\n *   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.\n *   The code must be computed by the caller at call time — do NOT pre-compute\n *   and cache it, because the 30-second window expires quickly. The in-app gate\n *   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.\n *\n * Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.\n * The WHATWG `URL` parser treats such schemes opaquely (no host/path/query\n * decomposition you can rely on across runtimes), so query manipulation via\n * `url.searchParams` is not portable here. We splice the query string directly\n * on the raw string instead, which keeps the scheme, authority, path, and any\n * pre-existing params (notably `_deploymentId`) byte-for-byte intact.\n */\n\n/**\n * Suspicious/generic authority values that indicate a malformed or placeholder\n * scheme URL. These are host strings that will almost certainly cause the Toss\n * app to fail with \"bundle not found\" silently.\n *\n * The expected form from `ait deploy --scheme-only` is:\n *   intoss-private://<appName>?_deploymentId=<uuid>\n * where `<appName>` is a non-generic string like `aitc-sdk-example`.\n */\nconst SUSPICIOUS_AUTHORITIES = new Set<string>(['', 'web', 'localhost', '127.0.0.1', 'app']);\n\n/**\n * Validates the authority (host) portion of a scheme URL.\n *\n * Returns a warning message if the authority is missing or looks like a\n * placeholder, or `null` if the authority looks valid.\n *\n * Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`\n * The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).\n */\nexport function validateSchemeAuthority(schemeUrl: string): string | null {\n  // Extract authority from `scheme://authority[/path][?query][#hash]`.\n  // We cannot use the WHATWG URL parser for non-special schemes reliably\n  // (see the deeplink.ts module comment), so we parse the raw string.\n  const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\\-.]*:\\/\\//, '');\n  if (afterScheme === schemeUrl) {\n    // No `://` found — not a scheme URL at all.\n    return (\n      'scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). ' +\n      'Use the URL printed by `ait deploy --scheme-only`.'\n    );\n  }\n\n  // authority ends at the first `/`, `?`, `#`, or end of string.\n  const authorityEnd = afterScheme.search(/[/?#]/);\n  const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);\n\n  if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) {\n    const displayAuthority = authority === '' ? '(empty)' : `\"${authority}\"`;\n    return (\n      `scheme_url authority ${displayAuthority} looks like a placeholder. ` +\n      'Expected an app name like `intoss-private://aitc-sdk-example?_deploymentId=<uuid>`. ' +\n      'Use the URL printed by `ait deploy --scheme-only` — it includes the correct app name as the host.'\n    );\n  }\n\n  return null;\n}\n\n/** A param the helper appends. Existing occurrences are replaced, not duplicated. */\ntype AppendParam = readonly [key: string, value: string];\n\nfunction stripExisting(query: string, key: string): string {\n  if (query === '') return '';\n  return query\n    .split('&')\n    .filter((pair) => pair !== '' && pair.split('=')[0] !== key)\n    .join('&');\n}\n\n/**\n * Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a\n * scheme URL's query string, preserving everything else (scheme, authority,\n * path, hash, and the existing `_deploymentId` param). If any of the spliced\n * params is already present it is replaced so the helper is idempotent.\n *\n * @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed\n *   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B\n *   of the gate); this helper does not invent one.\n * @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the\n *   running debug MCP server's quick tunnel.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Pass `undefined` or omit when TOTP is disabled.\n * @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`\n *   appended.\n * @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so\n *   producing such a link would be a silent dead end).\n */\nexport function buildDeepLinkAttachUrl(\n  schemeUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n): string {\n  let relay: URL;\n  try {\n    relay = new URL(wssUrl);\n  } catch {\n    throw new Error(`relay URL is not a valid URL: ${wssUrl}`);\n  }\n  if (relay.protocol !== 'wss:') {\n    throw new Error(`relay URL must use the wss: scheme, got ${relay.protocol} (${wssUrl})`);\n  }\n\n  const hashIndex = schemeUrl.indexOf('#');\n  const hash = hashIndex === -1 ? '' : schemeUrl.slice(hashIndex);\n  const beforeHash = hashIndex === -1 ? schemeUrl : schemeUrl.slice(0, hashIndex);\n\n  const queryIndex = beforeHash.indexOf('?');\n  const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);\n  let query = queryIndex === -1 ? '' : beforeHash.slice(queryIndex + 1);\n\n  const appended: AppendParam[] = [\n    ['debug', '1'],\n    ['relay', wssUrl],\n  ];\n  // Only splice `at=` when a code is provided (TOTP enabled). Omitting it when\n  // TOTP is disabled preserves backward compatibility with gate deployments\n  // that do not yet evaluate the `at` param.\n  if (totpCode !== undefined && totpCode !== '') {\n    appended.push(['at', totpCode]);\n  }\n\n  // Always strip the `at` key from the existing query so a stale code from a\n  // previous run is removed even when the caller does not provide a fresh code.\n  query = stripExisting(query, 'at');\n\n  for (const [key] of appended) {\n    query = stripExisting(query, key);\n  }\n  for (const [key, value] of appended) {\n    const pair = `${key}=${encodeURIComponent(value)}`;\n    query = query === '' ? pair : `${query}&${pair}`;\n  }\n\n  return `${base}?${query}${hash}`;\n}\n"],"mappings":";;;;;;;;AAOA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDrB,SAAgB,uBACd,WACA,QACA,UACA,MACQ;CACR,IAAI,MACF,GAAG,aAAa,OAAO,mBAAmB,UAAU,CAAA,iBAClC,mBAAmB,OAAO;AAC9C,KAAI,aAAa,KAAA,KAAa,aAAa,GACzC,QAAO,OAAO,mBAAmB,SAAS;AAG5C,KAAI,MAAM,SAAS,KAAA,KAAa,KAAK,KAAK,MAAM,KAAK,GACnD,QAAO,SAAS,mBAAmB,KAAK,KAAK,MAAM,CAAC;AAEtD,KAAI,MAAM,SAAS,KAAA,GAAW;EAC5B,IAAI;AACJ,MAAI;AACF,gBAAa,IAAI,IAAI,KAAK,KAAK;UACzB;AACN,gBAAa;;AAEf,MAAI,YAAY,aAAa,SAC3B,QAAO,SAAS,mBAAmB,KAAK,KAAK;;AAGjD,QAAO"}

package/dist/{deeplink-CCGiyoHq.cjs → deeplink-CU6opogq.cjs}

@@ -16,6 +16,11 @@ const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
 * is injected. `&at=<totpCode>` is added only when a code is provided (same
 * conditional as {@link buildDeepLinkAttachUrl}).
 *
+* When `opts.name` is given (non-blank), it is added as `&name=` so the
+* launcher partner bar shows the app name instead of the generic default (#498).
+* When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the
+* launcher can render an icon next to the title (#498).
+*
 * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL
 * via raw string manipulation), this function uses WHATWG `encodeURIComponent`
 * because the target is a standard `https:` URL.
@@ -30,15 +35,26 @@ const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
 * @param totpCode - Optional current TOTP code (6 digits). When provided, it
 *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates
 *   every 30 s. Omit when TOTP is disabled.
+* @param opts - Optional app identity hints: `name` and `icon` (#498).
 * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>
-*   [&at=<code>]` params.
+*   [&at=<code>][&name=<enc>][&icon=<enc>]` params.
 */
-function buildLauncherAttachUrl(tunnelUrl, wssUrl, totpCode) {
+function buildLauncherAttachUrl(tunnelUrl, wssUrl, totpCode, opts) {
 	let url = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}&debug=1&relay=${encodeURIComponent(wssUrl)}`;
 	if (totpCode !== void 0 && totpCode !== "") url += `&at=${encodeURIComponent(totpCode)}`;
+	if (opts?.name !== void 0 && opts.name.trim() !== "") url += `&name=${encodeURIComponent(opts.name.trim())}`;
+	if (opts?.icon !== void 0) {
+		let iconParsed;
+		try {
+			iconParsed = new URL(opts.icon);
+		} catch {
+			iconParsed = null;
+		}
+		if (iconParsed?.protocol === "https:") url += `&icon=${encodeURIComponent(opts.icon)}`;
+	}
 	return url;
 }
 //#endregion
 exports.buildLauncherAttachUrl = buildLauncherAttachUrl;
 
-//# sourceMappingURL=deeplink-CCGiyoHq.cjs.map
+//# sourceMappingURL=deeplink-CU6opogq.cjs.map

package/dist/deeplink-CU6opogq.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"deeplink-CU6opogq.cjs","names":[],"sources":["../src/mcp/deeplink.ts"],"sourcesContent":["/**\n * URL of the AITC Sandbox launcher PWA.\n *\n * Declared here (not imported from `src/unplugin/tunnel.ts`) to respect the\n * mcp → unplugin layering boundary. unplugin/tunnel.ts declares its own copy\n * for the same reason — keep the two in sync when the URL changes.\n */\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Optional metadata that enriches the launcher deep-link (#498).\n *\n * These fields are added as query params so the launcher PWA can display\n * a recognizable identity (name, icon) without the user having to configure\n * anything extra.\n */\nexport interface LauncherAttachUrlOpts {\n  /**\n   * Human-readable app name shown in the partner nav bar (`name=` param).\n   * Blank / whitespace-only values are not added.\n   */\n  name?: string;\n  /**\n   * Absolute `https://` icon URL for the partner nav bar icon slot (`icon=`\n   * param). Non-https or falsy values are not added.\n   */\n  icon?: string;\n}\n\n/**\n * Builds a launcher PWA deep-link for env-2 MCP-attach (issue #378).\n *\n * The launcher at {@link LAUNCHER_URL} renders tunnelUrl in a full-viewport\n * iframe. `&debug=1&relay=<wssUrl>` is forwarded onto the iframe src so the\n * framed page's in-app debug gate (Layer C) is satisfied and a Chii target.js\n * is injected. `&at=<totpCode>` is added only when a code is provided (same\n * conditional as {@link buildDeepLinkAttachUrl}).\n *\n * When `opts.name` is given (non-blank), it is added as `&name=` so the\n * launcher partner bar shows the app name instead of the generic default (#498).\n * When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the\n * launcher can render an icon next to the title (#498).\n *\n * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL\n * via raw string manipulation), this function uses WHATWG `encodeURIComponent`\n * because the target is a standard `https:` URL.\n *\n * SECRET-HANDLING: `totpCode` (when provided) is placed into the `at=` param\n * only — never logged or returned separately. Callers must NOT log the result\n * of this function to stdout/stderr.\n *\n * @param tunnelUrl - The `https://*.trycloudflare.com` app tunnel URL\n *   (`AIT_TUNNEL_BASE_URL`). This is the URL the launcher frames.\n * @param wssUrl - The `wss://` relay URL the framed page will attach to.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Omit when TOTP is disabled.\n * @param opts - Optional app identity hints: `name` and `icon` (#498).\n * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>\n *   [&at=<code>][&name=<enc>][&icon=<enc>]` params.\n */\nexport function buildLauncherAttachUrl(\n  tunnelUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n  opts?: LauncherAttachUrlOpts,\n): string {\n  let url =\n    `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}` +\n    `&debug=1&relay=${encodeURIComponent(wssUrl)}`;\n  if (totpCode !== undefined && totpCode !== '') {\n    url += `&at=${encodeURIComponent(totpCode)}`;\n  }\n  // App identity hints (#498): add non-blank name and valid https icon.\n  if (opts?.name !== undefined && opts.name.trim() !== '') {\n    url += `&name=${encodeURIComponent(opts.name.trim())}`;\n  }\n  if (opts?.icon !== undefined) {\n    let iconParsed: URL;\n    try {\n      iconParsed = new URL(opts.icon);\n    } catch {\n      iconParsed = null as unknown as URL;\n    }\n    if (iconParsed?.protocol === 'https:') {\n      url += `&icon=${encodeURIComponent(opts.icon)}`;\n    }\n  }\n  return url;\n}\n\n/**\n * Build a self-attaching dogfood deep link.\n *\n * `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`\n * URL that opens a dogfood bundle on a phone. The in-app debug gate\n * (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries\n * `debug=1` and `relay=<wss-url>`. This helper splices those params (plus\n * `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result\n * as a QR code and scanning it with the phone camera opens the mini-app and\n * attaches it to the live Chii relay. QR is the single entry path — it needs\n * no USB cable, platform CLI, or driver, and works the same on iOS/Android.\n *\n * The Toss app propagates extra query params from the entry deep link into the\n * mini-app WebView's `location.search` (confirmed behavior), so the gate reads\n * them at attach time.\n *\n * TOTP `at=` param:\n *   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional\n *   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.\n *   The code must be computed by the caller at call time — do NOT pre-compute\n *   and cache it, because the 30-second window expires quickly. The in-app gate\n *   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.\n *\n * Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.\n * The WHATWG `URL` parser treats such schemes opaquely (no host/path/query\n * decomposition you can rely on across runtimes), so query manipulation via\n * `url.searchParams` is not portable here. We splice the query string directly\n * on the raw string instead, which keeps the scheme, authority, path, and any\n * pre-existing params (notably `_deploymentId`) byte-for-byte intact.\n */\n\n/**\n * Suspicious/generic authority values that indicate a malformed or placeholder\n * scheme URL. These are host strings that will almost certainly cause the Toss\n * app to fail with \"bundle not found\" silently.\n *\n * The expected form from `ait deploy --scheme-only` is:\n *   intoss-private://<appName>?_deploymentId=<uuid>\n * where `<appName>` is a non-generic string like `aitc-sdk-example`.\n */\nconst SUSPICIOUS_AUTHORITIES = new Set<string>(['', 'web', 'localhost', '127.0.0.1', 'app']);\n\n/**\n * Validates the authority (host) portion of a scheme URL.\n *\n * Returns a warning message if the authority is missing or looks like a\n * placeholder, or `null` if the authority looks valid.\n *\n * Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`\n * The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).\n */\nexport function validateSchemeAuthority(schemeUrl: string): string | null {\n  // Extract authority from `scheme://authority[/path][?query][#hash]`.\n  // We cannot use the WHATWG URL parser for non-special schemes reliably\n  // (see the deeplink.ts module comment), so we parse the raw string.\n  const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\\-.]*:\\/\\//, '');\n  if (afterScheme === schemeUrl) {\n    // No `://` found — not a scheme URL at all.\n    return (\n      'scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). ' +\n      'Use the URL printed by `ait deploy --scheme-only`.'\n    );\n  }\n\n  // authority ends at the first `/`, `?`, `#`, or end of string.\n  const authorityEnd = afterScheme.search(/[/?#]/);\n  const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);\n\n  if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) {\n    const displayAuthority = authority === '' ? '(empty)' : `\"${authority}\"`;\n    return (\n      `scheme_url authority ${displayAuthority} looks like a placeholder. ` +\n      'Expected an app name like `intoss-private://aitc-sdk-example?_deploymentId=<uuid>`. ' +\n      'Use the URL printed by `ait deploy --scheme-only` — it includes the correct app name as the host.'\n    );\n  }\n\n  return null;\n}\n\n/** A param the helper appends. Existing occurrences are replaced, not duplicated. */\ntype AppendParam = readonly [key: string, value: string];\n\nfunction stripExisting(query: string, key: string): string {\n  if (query === '') return '';\n  return query\n    .split('&')\n    .filter((pair) => pair !== '' && pair.split('=')[0] !== key)\n    .join('&');\n}\n\n/**\n * Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a\n * scheme URL's query string, preserving everything else (scheme, authority,\n * path, hash, and the existing `_deploymentId` param). If any of the spliced\n * params is already present it is replaced so the helper is idempotent.\n *\n * @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed\n *   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B\n *   of the gate); this helper does not invent one.\n * @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the\n *   running debug MCP server's quick tunnel.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Pass `undefined` or omit when TOTP is disabled.\n * @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`\n *   appended.\n * @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so\n *   producing such a link would be a silent dead end).\n */\nexport function buildDeepLinkAttachUrl(\n  schemeUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n): string {\n  let relay: URL;\n  try {\n    relay = new URL(wssUrl);\n  } catch {\n    throw new Error(`relay URL is not a valid URL: ${wssUrl}`);\n  }\n  if (relay.protocol !== 'wss:') {\n    throw new Error(`relay URL must use the wss: scheme, got ${relay.protocol} (${wssUrl})`);\n  }\n\n  const hashIndex = schemeUrl.indexOf('#');\n  const hash = hashIndex === -1 ? '' : schemeUrl.slice(hashIndex);\n  const beforeHash = hashIndex === -1 ? schemeUrl : schemeUrl.slice(0, hashIndex);\n\n  const queryIndex = beforeHash.indexOf('?');\n  const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);\n  let query = queryIndex === -1 ? '' : beforeHash.slice(queryIndex + 1);\n\n  const appended: AppendParam[] = [\n    ['debug', '1'],\n    ['relay', wssUrl],\n  ];\n  // Only splice `at=` when a code is provided (TOTP enabled). Omitting it when\n  // TOTP is disabled preserves backward compatibility with gate deployments\n  // that do not yet evaluate the `at` param.\n  if (totpCode !== undefined && totpCode !== '') {\n    appended.push(['at', totpCode]);\n  }\n\n  // Always strip the `at` key from the existing query so a stale code from a\n  // previous run is removed even when the caller does not provide a fresh code.\n  query = stripExisting(query, 'at');\n\n  for (const [key] of appended) {\n    query = stripExisting(query, key);\n  }\n  for (const [key, value] of appended) {\n    const pair = `${key}=${encodeURIComponent(value)}`;\n    query = query === '' ? pair : `${query}&${pair}`;\n  }\n\n  return `${base}?${query}${hash}`;\n}\n"],"mappings":";;;;;;;;AAOA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDrB,SAAgB,uBACd,WACA,QACA,UACA,MACQ;CACR,IAAI,MACF,GAAG,aAAa,OAAO,mBAAmB,UAAU,CAAA,iBAClC,mBAAmB,OAAO;AAC9C,KAAI,aAAa,KAAA,KAAa,aAAa,GACzC,QAAO,OAAO,mBAAmB,SAAS;AAG5C,KAAI,MAAM,SAAS,KAAA,KAAa,KAAK,KAAK,MAAM,KAAK,GACnD,QAAO,SAAS,mBAAmB,KAAK,KAAK,MAAM,CAAC;AAEtD,KAAI,MAAM,SAAS,KAAA,GAAW;EAC5B,IAAI;AACJ,MAAI;AACF,gBAAa,IAAI,IAAI,KAAK,KAAK;UACzB;AACN,gBAAa;;AAEf,MAAI,YAAY,aAAa,SAC3B,QAAO,SAAS,mBAAmB,KAAK,KAAK;;AAGjD,QAAO"}

package/dist/{deeplink-Cqli4qzm.js → deeplink-CYqDwVYs.js}

@@ -16,6 +16,11 @@ const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
 * is injected. `&at=<totpCode>` is added only when a code is provided (same
 * conditional as {@link buildDeepLinkAttachUrl}).
 *
+* When `opts.name` is given (non-blank), it is added as `&name=` so the
+* launcher partner bar shows the app name instead of the generic default (#498).
+* When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the
+* launcher can render an icon next to the title (#498).
+*
 * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL
 * via raw string manipulation), this function uses WHATWG `encodeURIComponent`
 * because the target is a standard `https:` URL.
@@ -30,15 +35,26 @@ const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
 * @param totpCode - Optional current TOTP code (6 digits). When provided, it
 *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates
 *   every 30 s. Omit when TOTP is disabled.
+* @param opts - Optional app identity hints: `name` and `icon` (#498).
 * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>
-*   [&at=<code>]` params.
+*   [&at=<code>][&name=<enc>][&icon=<enc>]` params.
 */
-function buildLauncherAttachUrl(tunnelUrl, wssUrl, totpCode) {
+function buildLauncherAttachUrl(tunnelUrl, wssUrl, totpCode, opts) {
 	let url = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}&debug=1&relay=${encodeURIComponent(wssUrl)}`;
 	if (totpCode !== void 0 && totpCode !== "") url += `&at=${encodeURIComponent(totpCode)}`;
+	if (opts?.name !== void 0 && opts.name.trim() !== "") url += `&name=${encodeURIComponent(opts.name.trim())}`;
+	if (opts?.icon !== void 0) {
+		let iconParsed;
+		try {
+			iconParsed = new URL(opts.icon);
+		} catch {
+			iconParsed = null;
+		}
+		if (iconParsed?.protocol === "https:") url += `&icon=${encodeURIComponent(opts.icon)}`;
+	}
 	return url;
 }
 //#endregion
 export { buildLauncherAttachUrl };
 
-//# sourceMappingURL=deeplink-Cqli4qzm.js.map
+//# sourceMappingURL=deeplink-CYqDwVYs.js.map

package/dist/deeplink-CYqDwVYs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deeplink-CYqDwVYs.js","names":[],"sources":["../src/mcp/deeplink.ts"],"sourcesContent":["/**\n * URL of the AITC Sandbox launcher PWA.\n *\n * Declared here (not imported from `src/unplugin/tunnel.ts`) to respect the\n * mcp → unplugin layering boundary. unplugin/tunnel.ts declares its own copy\n * for the same reason — keep the two in sync when the URL changes.\n */\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Optional metadata that enriches the launcher deep-link (#498).\n *\n * These fields are added as query params so the launcher PWA can display\n * a recognizable identity (name, icon) without the user having to configure\n * anything extra.\n */\nexport interface LauncherAttachUrlOpts {\n  /**\n   * Human-readable app name shown in the partner nav bar (`name=` param).\n   * Blank / whitespace-only values are not added.\n   */\n  name?: string;\n  /**\n   * Absolute `https://` icon URL for the partner nav bar icon slot (`icon=`\n   * param). Non-https or falsy values are not added.\n   */\n  icon?: string;\n}\n\n/**\n * Builds a launcher PWA deep-link for env-2 MCP-attach (issue #378).\n *\n * The launcher at {@link LAUNCHER_URL} renders tunnelUrl in a full-viewport\n * iframe. `&debug=1&relay=<wssUrl>` is forwarded onto the iframe src so the\n * framed page's in-app debug gate (Layer C) is satisfied and a Chii target.js\n * is injected. `&at=<totpCode>` is added only when a code is provided (same\n * conditional as {@link buildDeepLinkAttachUrl}).\n *\n * When `opts.name` is given (non-blank), it is added as `&name=` so the\n * launcher partner bar shows the app name instead of the generic default (#498).\n * When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the\n * launcher can render an icon next to the title (#498).\n *\n * Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL\n * via raw string manipulation), this function uses WHATWG `encodeURIComponent`\n * because the target is a standard `https:` URL.\n *\n * SECRET-HANDLING: `totpCode` (when provided) is placed into the `at=` param\n * only — never logged or returned separately. Callers must NOT log the result\n * of this function to stdout/stderr.\n *\n * @param tunnelUrl - The `https://*.trycloudflare.com` app tunnel URL\n *   (`AIT_TUNNEL_BASE_URL`). This is the URL the launcher frames.\n * @param wssUrl - The `wss://` relay URL the framed page will attach to.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is appended as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Omit when TOTP is disabled.\n * @param opts - Optional app identity hints: `name` and `icon` (#498).\n * @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>\n *   [&at=<code>][&name=<enc>][&icon=<enc>]` params.\n */\nexport function buildLauncherAttachUrl(\n  tunnelUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n  opts?: LauncherAttachUrlOpts,\n): string {\n  let url =\n    `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}` +\n    `&debug=1&relay=${encodeURIComponent(wssUrl)}`;\n  if (totpCode !== undefined && totpCode !== '') {\n    url += `&at=${encodeURIComponent(totpCode)}`;\n  }\n  // App identity hints (#498): add non-blank name and valid https icon.\n  if (opts?.name !== undefined && opts.name.trim() !== '') {\n    url += `&name=${encodeURIComponent(opts.name.trim())}`;\n  }\n  if (opts?.icon !== undefined) {\n    let iconParsed: URL;\n    try {\n      iconParsed = new URL(opts.icon);\n    } catch {\n      iconParsed = null as unknown as URL;\n    }\n    if (iconParsed?.protocol === 'https:') {\n      url += `&icon=${encodeURIComponent(opts.icon)}`;\n    }\n  }\n  return url;\n}\n\n/**\n * Build a self-attaching dogfood deep link.\n *\n * `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`\n * URL that opens a dogfood bundle on a phone. The in-app debug gate\n * (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries\n * `debug=1` and `relay=<wss-url>`. This helper splices those params (plus\n * `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result\n * as a QR code and scanning it with the phone camera opens the mini-app and\n * attaches it to the live Chii relay. QR is the single entry path — it needs\n * no USB cable, platform CLI, or driver, and works the same on iOS/Android.\n *\n * The Toss app propagates extra query params from the entry deep link into the\n * mini-app WebView's `location.search` (confirmed behavior), so the gate reads\n * them at attach time.\n *\n * TOTP `at=` param:\n *   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional\n *   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.\n *   The code must be computed by the caller at call time — do NOT pre-compute\n *   and cache it, because the 30-second window expires quickly. The in-app gate\n *   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.\n *\n * Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.\n * The WHATWG `URL` parser treats such schemes opaquely (no host/path/query\n * decomposition you can rely on across runtimes), so query manipulation via\n * `url.searchParams` is not portable here. We splice the query string directly\n * on the raw string instead, which keeps the scheme, authority, path, and any\n * pre-existing params (notably `_deploymentId`) byte-for-byte intact.\n */\n\n/**\n * Suspicious/generic authority values that indicate a malformed or placeholder\n * scheme URL. These are host strings that will almost certainly cause the Toss\n * app to fail with \"bundle not found\" silently.\n *\n * The expected form from `ait deploy --scheme-only` is:\n *   intoss-private://<appName>?_deploymentId=<uuid>\n * where `<appName>` is a non-generic string like `aitc-sdk-example`.\n */\nconst SUSPICIOUS_AUTHORITIES = new Set<string>(['', 'web', 'localhost', '127.0.0.1', 'app']);\n\n/**\n * Validates the authority (host) portion of a scheme URL.\n *\n * Returns a warning message if the authority is missing or looks like a\n * placeholder, or `null` if the authority looks valid.\n *\n * Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`\n * The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).\n */\nexport function validateSchemeAuthority(schemeUrl: string): string | null {\n  // Extract authority from `scheme://authority[/path][?query][#hash]`.\n  // We cannot use the WHATWG URL parser for non-special schemes reliably\n  // (see the deeplink.ts module comment), so we parse the raw string.\n  const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\\-.]*:\\/\\//, '');\n  if (afterScheme === schemeUrl) {\n    // No `://` found — not a scheme URL at all.\n    return (\n      'scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). ' +\n      'Use the URL printed by `ait deploy --scheme-only`.'\n    );\n  }\n\n  // authority ends at the first `/`, `?`, `#`, or end of string.\n  const authorityEnd = afterScheme.search(/[/?#]/);\n  const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);\n\n  if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) {\n    const displayAuthority = authority === '' ? '(empty)' : `\"${authority}\"`;\n    return (\n      `scheme_url authority ${displayAuthority} looks like a placeholder. ` +\n      'Expected an app name like `intoss-private://aitc-sdk-example?_deploymentId=<uuid>`. ' +\n      'Use the URL printed by `ait deploy --scheme-only` — it includes the correct app name as the host.'\n    );\n  }\n\n  return null;\n}\n\n/** A param the helper appends. Existing occurrences are replaced, not duplicated. */\ntype AppendParam = readonly [key: string, value: string];\n\nfunction stripExisting(query: string, key: string): string {\n  if (query === '') return '';\n  return query\n    .split('&')\n    .filter((pair) => pair !== '' && pair.split('=')[0] !== key)\n    .join('&');\n}\n\n/**\n * Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a\n * scheme URL's query string, preserving everything else (scheme, authority,\n * path, hash, and the existing `_deploymentId` param). If any of the spliced\n * params is already present it is replaced so the helper is idempotent.\n *\n * @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed\n *   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B\n *   of the gate); this helper does not invent one.\n * @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the\n *   running debug MCP server's quick tunnel.\n * @param totpCode - Optional current TOTP code (6 digits). When provided, it\n *   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates\n *   every 30 s. Pass `undefined` or omit when TOTP is disabled.\n * @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`\n *   appended.\n * @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so\n *   producing such a link would be a silent dead end).\n */\nexport function buildDeepLinkAttachUrl(\n  schemeUrl: string,\n  wssUrl: string,\n  totpCode?: string,\n): string {\n  let relay: URL;\n  try {\n    relay = new URL(wssUrl);\n  } catch {\n    throw new Error(`relay URL is not a valid URL: ${wssUrl}`);\n  }\n  if (relay.protocol !== 'wss:') {\n    throw new Error(`relay URL must use the wss: scheme, got ${relay.protocol} (${wssUrl})`);\n  }\n\n  const hashIndex = schemeUrl.indexOf('#');\n  const hash = hashIndex === -1 ? '' : schemeUrl.slice(hashIndex);\n  const beforeHash = hashIndex === -1 ? schemeUrl : schemeUrl.slice(0, hashIndex);\n\n  const queryIndex = beforeHash.indexOf('?');\n  const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);\n  let query = queryIndex === -1 ? '' : beforeHash.slice(queryIndex + 1);\n\n  const appended: AppendParam[] = [\n    ['debug', '1'],\n    ['relay', wssUrl],\n  ];\n  // Only splice `at=` when a code is provided (TOTP enabled). Omitting it when\n  // TOTP is disabled preserves backward compatibility with gate deployments\n  // that do not yet evaluate the `at` param.\n  if (totpCode !== undefined && totpCode !== '') {\n    appended.push(['at', totpCode]);\n  }\n\n  // Always strip the `at` key from the existing query so a stale code from a\n  // previous run is removed even when the caller does not provide a fresh code.\n  query = stripExisting(query, 'at');\n\n  for (const [key] of appended) {\n    query = stripExisting(query, key);\n  }\n  for (const [key, value] of appended) {\n    const pair = `${key}=${encodeURIComponent(value)}`;\n    query = query === '' ? pair : `${query}&${pair}`;\n  }\n\n  return `${base}?${query}${hash}`;\n}\n"],"mappings":";;;;;;;;AAOA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDrB,SAAgB,uBACd,WACA,QACA,UACA,MACQ;CACR,IAAI,MACF,GAAG,aAAa,OAAO,mBAAmB,UAAU,CAAA,iBAClC,mBAAmB,OAAO;AAC9C,KAAI,aAAa,KAAA,KAAa,aAAa,GACzC,QAAO,OAAO,mBAAmB,SAAS;AAG5C,KAAI,MAAM,SAAS,KAAA,KAAa,KAAK,KAAK,MAAM,KAAK,GACnD,QAAO,SAAS,mBAAmB,KAAK,KAAK,MAAM,CAAC;AAEtD,KAAI,MAAM,SAAS,KAAA,GAAW;EAC5B,IAAI;AACJ,MAAI;AACF,gBAAa,IAAI,IAAI,KAAK,KAAK;UACzB;AACN,gBAAa;;AAEf,MAAI,YAAY,aAAa,SAC3B,QAAO,SAAS,mBAAmB,KAAK,KAAK;;AAGjD,QAAO"}

package/dist/devtools-opener-BbUXBzgA.js.map

@@ -1 +1 @@
-{"version":3,"file":"devtools-opener-BbUXBzgA.js","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.  Chii\n * also self-hosts its DevTools frontend at:\n *\n *   <relay-base>/front_end/chii_app.html\n *     ?ws|wss=<encodeURIComponent(\"<relay-host>/client/<uuid>?target=<targetId>&at=<totp>\")>\n *\n * The param name follows the relay base scheme — `ws=` for plain HTTP\n * (env 3/4 local relay), `wss=` for HTTPS (env 2 tunnel) — matching the\n * scheme branch in chii/public/index.js.\n *\n * This is the same URL format that Chii's own index-page inspect-links use\n * (derived from `chii/public/index.js` — the JS that powers the target list\n * page at `<relay-base>/`).  Opening this URL in the developer's local browser\n * gives a full Chrome DevTools UI connected to the phone via the relay.\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 * TOTP expiry caveat:\n *   The `at=` TOTP code embedded in the `wss=` parameter is minted fresh at the\n *   moment `open()` is called. The code is valid for the 30-second RFC 6238\n *   window (±1 step skew = 90 s acceptance). If the developer does not open the\n *   URL within that window the WebSocket upgrade will be rejected with 4401.\n *   In practice the browser opens immediately after the OS `open` command, so\n *   the window is always satisfied; if it is not (e.g. the URL is copied and\n *   opened later) the developer can copy the wss= param, replace `at=`, and\n *   reload. This is documented in the JSDoc below.\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// Chii self-hosted DevTools frontend URL\n// ---------------------------------------------------------------------------\n\n/**\n * Assembles the Chii self-hosted DevTools inspector URL for a given relay\n * and target.\n *\n * Chii serves its own DevTools frontend at\n * `<relayHttpBaseUrl>/front_end/chii_app.html`. The `ws=` (plain HTTP relay)\n * or `wss=` (HTTPS relay) query parameter is a URL-encoded string of the form\n * `<relay-host>/client/<uuid>?target=<id>` (and optionally `&at=<totp>`) —\n * the same format used by Chii's own target list page (derived from\n * `chii/public/index.js`).\n *\n * The `at=` TOTP code is minted at call time via `mintTotp()`.  It is valid\n * for the current 30-second RFC 6238 step (±1 step skew = 90 s acceptance\n * window).  The developer must open the returned URL within that window.  If\n * the window expires before the browser connects, the relay will reject the\n * WebSocket upgrade with close code 4401.\n *\n * SECRET-HANDLING: `mintTotp` returns a code, not a secret. The code is\n * embedded in the `wss=` parameter (inside the `at=` param) of the returned\n * URL. Callers MUST NOT log the returned URL to stdout (stderr is OK — it is\n * the intended fallback surface for the developer to copy the URL).\n *\n * @param relayHttpBaseUrl - Local HTTP base URL of the Chii relay, e.g.\n *   `http://127.0.0.1:9100`. No trailing slash.\n * @param targetId - Chii target id (from `GET <relay>/targets`).\n * @param mintTotp - Optional function that returns a fresh 6-digit TOTP code\n *   string. Called at most once. When omitted (TOTP disabled) no `at=` param\n *   is added.\n * @param panel - Initial panel. Defaults to `\"console\"`.\n *\n * @example\n * buildChiiInspectorUrl(\n *   'http://127.0.0.1:9100',\n *   'abc123',\n *   () => generateTotp(secret),\n * )\n * // → 'http://127.0.0.1:9100/front_end/chii_app.html?ws=127.0.0.1%3A9100%2Fclient%2F<uuid>%3Ftarget%3Dabc123%26at%3D<code>'\n */\nexport function buildChiiInspectorUrl(\n  relayHttpBaseUrl: string,\n  targetId: string,\n  mintTotp?: () => string,\n  panel: 'elements' | 'console' | 'sources' | 'network' = 'console',\n): string {\n  // Extract the host (and port) from the relay HTTP base URL, and pick the\n  // query param name chii_app.html expects: `ws=` dials `ws://` (plain-HTTP\n  // relay — env 3/4 local 127.0.0.1) while `wss=` dials `wss://` (HTTPS\n  // tunnel — env 2). chii/public/index.js does the same scheme branch:\n  // `location.protocol === 'https:' ? 'wss' : 'ws'`. Always sending `wss=`\n  // would make the frontend attempt TLS against the plain-HTTP local relay.\n  let relayHost: string;\n  let wsParamName: 'ws' | 'wss';\n  try {\n    const parsed = new URL(relayHttpBaseUrl);\n    relayHost = parsed.host; // e.g. \"127.0.0.1:9100\"\n    wsParamName = parsed.protocol === 'https:' ? 'wss' : 'ws';\n  } catch {\n    // Fallback: strip the scheme prefix manually if URL parsing fails.\n    relayHost = relayHttpBaseUrl.replace(/^https?:\\/\\//i, '');\n    wsParamName = /^https:/i.test(relayHttpBaseUrl) ? 'wss' : 'ws';\n  }\n\n  // Generate a client UUID that matches the format Chii's index.js uses\n  // (6 random alphanumeric characters).\n  const clientId = `devtools-opener-${Date.now().toString(36)}`;\n\n  // Build the ws=/wss= value: \"<relay-host>/client/<uuid>?target=<id>[&at=<code>]\"\n  // This mirrors the format from chii/public/index.js:\n  //   `${domain}${basePath}client/${randomId(6)}?target=${targetId}`\n  let wsPath = `${relayHost}/client/${clientId}?target=${encodeURIComponent(targetId)}`;\n\n  if (mintTotp) {\n    // SECRET-HANDLING: mintTotp() returns a code (not a secret). The code\n    // rides only in the URL's at= param. Callers must not log the URL.\n    const code = mintTotp();\n    wsPath += `&at=${encodeURIComponent(code)}`;\n  }\n\n  const params = new URLSearchParams({ [wsParamName]: wsPath, panel });\n  return `${relayHttpBaseUrl.replace(/\\/$/, '')}/front_end/chii_app.html?${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 * Options for {@link AutoDevtoolsOpener.open}.\n *\n * The `relayHttpBaseUrl` and `targetId` fields are required to build a working\n * Chii self-hosted inspector URL. When `relayHttpBaseUrl` is absent the open\n * is skipped (no relay available yet).\n */\nexport interface DevtoolsOpenOptions {\n  /**\n   * Local HTTP base URL of the Chii relay, e.g. `http://127.0.0.1:9100`.\n   * Used to build the `<relay-base>/front_end/chii_app.html?wss=…` URL.\n   *\n   * For env 3/4 (intoss relay) this is `http://127.0.0.1:<port>`.\n   * For env 2 (external PWA relay) this is the relay's external HTTP URL\n   * (e.g. `https://<host>.trycloudflare.com`).\n   *\n   * When absent or empty, `open()` is a no-op.\n   *\n   * SECRET-HANDLING: this value contains the relay host. Callers MUST NOT\n   * log it to stdout; stderr is the intended surface.\n   */\n  relayHttpBaseUrl: string | null | undefined;\n  /**\n   * Chii target id of the attached page, from `listTargets()[0].id`.\n   * When absent or empty, `open()` is a no-op.\n   */\n  targetId: string | null | undefined;\n  /**\n   * Function that mints a fresh TOTP code when called. Called at most once per\n   * `open()` invocation, immediately before building the inspector URL.\n   *\n   * Pass `undefined` when TOTP is disabled (no `at=` param is added).\n   *\n   * SECRET-HANDLING: the function MUST return only the code (6 digits), not\n   * the secret. The code rides in the URL's `at=` param only.\n   */\n  mintTotp?: () => string;\n  /** Current MCP environment (`mock` | `relay`). `open()` no-ops on `mock`. */\n  env: McpEnvironment;\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 Chii DevTools in the developer's browser.\n   *\n   * Builds a `<relay-base>/front_end/chii_app.html?wss=…` URL pointing at the\n   * attached target. A fresh TOTP `at=` code is minted at call time so the\n   * relay's WebSocket upgrade gate accepts the connection.\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. `options.env` is `mock` (env 1 — F12 is already available).\n   *   4. `options.relayHttpBaseUrl` is null/undefined/empty (relay not up yet).\n   *   5. `options.targetId` is null/undefined/empty (no page attached yet).\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   * TOTP expiry caveat: the `at=` code embedded in the URL is valid for the\n   * current 30-second RFC 6238 step (±1 skew = 90 s). The developer must open\n   * the URL within that window; if they miss it, reload the page or re-run\n   * `open()` (though the once-per-session guard prevents that — restart the\n   * MCP server if needed).\n   *\n   * SECRET-HANDLING: the inspector URL (written to stderr) contains the relay\n   * host and a short-lived TOTP code. Do NOT write it to stdout or any\n   * persistent log.\n   */\n  open(options: DevtoolsOpenOptions): void {\n    if (this._opened) return;\n    if (isAutoDevtoolsDisabled()) return;\n    if (options.env === 'mock') return;\n    if (!options.relayHttpBaseUrl) return;\n    if (!options.targetId) return;\n\n    this._opened = true;\n\n    const inspectorUrl = buildChiiInspectorUrl(\n      options.relayHttpBaseUrl,\n      options.targetId,\n      options.mintTotp,\n    );\n\n    process.stderr.write(\n      '[ait-debug] 기기가 연결됐습니다 — Chii DevTools를 자동으로 엽니다.\\n' +\n        `[ait-debug] DevTools URL: ${inspectorUrl}\\n` +\n        '[ait-debug] (AIT_AUTO_DEVTOOLS=0 으로 자동 열기를 끌 수 있습니다)\\n' +\n        '[ait-debug] 주의: URL의 at= 코드는 30초 창 안에서만 유효합니다.\\n',\n    );\n\n    const opened = openUrlInBrowser(inspectorUrl);\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":";;;;;;;;;;AAuJA,SAAgB,yBAAkC;AAChD,QAAO,QAAQ,IAAI,sBAAsB;;;;;;;;;AAc3C,SAAgB,iBAAiB,KAAsB;AAGrD,KAAI,QAAQ,IAAI,sCAAsC,IAAK,QAAO;CAElE,MAAM,EAAE,cAAA,UAAsB,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"}
+{"version":3,"file":"devtools-opener-BbUXBzgA.js","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.  Chii\n * also self-hosts its DevTools frontend at:\n *\n *   <relay-base>/front_end/chii_app.html\n *     ?ws|wss=<encodeURIComponent(\"<relay-host>/client/<uuid>?target=<targetId>&at=<totp>\")>\n *\n * The param name follows the relay base scheme — `ws=` for plain HTTP\n * (env 3/4 local relay), `wss=` for HTTPS (env 2 tunnel) — matching the\n * scheme branch in chii/public/index.js.\n *\n * This is the same URL format that Chii's own index-page inspect-links use\n * (derived from `chii/public/index.js` — the JS that powers the target list\n * page at `<relay-base>/`).  Opening this URL in the developer's local browser\n * gives a full Chrome DevTools UI connected to the phone via the relay.\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 * TOTP expiry caveat:\n *   The `at=` TOTP code embedded in the `wss=` parameter is minted fresh at the\n *   moment `open()` is called. The code is valid for ~3 minutes (the relay gate\n *   accepts ±RELAY_VERIFY_SKEW_STEPS=6 steps = 180–210 s). If the developer\n *   does not open the URL within that window the WebSocket upgrade will be\n *   rejected with 4401. In practice the browser opens immediately after the OS\n *   `open` command; if needed the developer can copy the wss= param, replace\n *   `at=`, and reload. This is documented in the JSDoc below.\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// Chii self-hosted DevTools frontend URL\n// ---------------------------------------------------------------------------\n\n/**\n * Assembles the Chii self-hosted DevTools inspector URL for a given relay\n * and target.\n *\n * Chii serves its own DevTools frontend at\n * `<relayHttpBaseUrl>/front_end/chii_app.html`. The `ws=` (plain HTTP relay)\n * or `wss=` (HTTPS relay) query parameter is a URL-encoded string of the form\n * `<relay-host>/client/<uuid>?target=<id>` (and optionally `&at=<totp>`) —\n * the same format used by Chii's own target list page (derived from\n * `chii/public/index.js`).\n *\n * The `at=` TOTP code is minted at call time via `mintTotp()`.  It is valid\n * for ~3 minutes (relay gate accepts ±RELAY_VERIFY_SKEW_STEPS=6 steps =\n * 180–210 s).  The developer must open the returned URL within that window.\n * If the window expires before the browser connects, the relay will reject the\n * WebSocket upgrade with close code 4401.\n *\n * SECRET-HANDLING: `mintTotp` returns a code, not a secret. The code is\n * embedded in the `wss=` parameter (inside the `at=` param) of the returned\n * URL. Callers MUST NOT log the returned URL to stdout (stderr is OK — it is\n * the intended fallback surface for the developer to copy the URL).\n *\n * @param relayHttpBaseUrl - Local HTTP base URL of the Chii relay, e.g.\n *   `http://127.0.0.1:9100`. No trailing slash.\n * @param targetId - Chii target id (from `GET <relay>/targets`).\n * @param mintTotp - Optional function that returns a fresh 6-digit TOTP code\n *   string. Called at most once. When omitted (TOTP disabled) no `at=` param\n *   is added.\n * @param panel - Initial panel. Defaults to `\"console\"`.\n *\n * @example\n * buildChiiInspectorUrl(\n *   'http://127.0.0.1:9100',\n *   'abc123',\n *   () => generateTotp(secret),\n * )\n * // → 'http://127.0.0.1:9100/front_end/chii_app.html?ws=127.0.0.1%3A9100%2Fclient%2F<uuid>%3Ftarget%3Dabc123%26at%3D<code>'\n */\nexport function buildChiiInspectorUrl(\n  relayHttpBaseUrl: string,\n  targetId: string,\n  mintTotp?: () => string,\n  panel: 'elements' | 'console' | 'sources' | 'network' = 'console',\n): string {\n  // Extract the host (and port) from the relay HTTP base URL, and pick the\n  // query param name chii_app.html expects: `ws=` dials `ws://` (plain-HTTP\n  // relay — env 3/4 local 127.0.0.1) while `wss=` dials `wss://` (HTTPS\n  // tunnel — env 2). chii/public/index.js does the same scheme branch:\n  // `location.protocol === 'https:' ? 'wss' : 'ws'`. Always sending `wss=`\n  // would make the frontend attempt TLS against the plain-HTTP local relay.\n  let relayHost: string;\n  let wsParamName: 'ws' | 'wss';\n  try {\n    const parsed = new URL(relayHttpBaseUrl);\n    relayHost = parsed.host; // e.g. \"127.0.0.1:9100\"\n    wsParamName = parsed.protocol === 'https:' ? 'wss' : 'ws';\n  } catch {\n    // Fallback: strip the scheme prefix manually if URL parsing fails.\n    relayHost = relayHttpBaseUrl.replace(/^https?:\\/\\//i, '');\n    wsParamName = /^https:/i.test(relayHttpBaseUrl) ? 'wss' : 'ws';\n  }\n\n  // Generate a client UUID that matches the format Chii's index.js uses\n  // (6 random alphanumeric characters).\n  const clientId = `devtools-opener-${Date.now().toString(36)}`;\n\n  // Build the ws=/wss= value: \"<relay-host>/client/<uuid>?target=<id>[&at=<code>]\"\n  // This mirrors the format from chii/public/index.js:\n  //   `${domain}${basePath}client/${randomId(6)}?target=${targetId}`\n  let wsPath = `${relayHost}/client/${clientId}?target=${encodeURIComponent(targetId)}`;\n\n  if (mintTotp) {\n    // SECRET-HANDLING: mintTotp() returns a code (not a secret). The code\n    // rides only in the URL's at= param. Callers must not log the URL.\n    const code = mintTotp();\n    wsPath += `&at=${encodeURIComponent(code)}`;\n  }\n\n  const params = new URLSearchParams({ [wsParamName]: wsPath, panel });\n  return `${relayHttpBaseUrl.replace(/\\/$/, '')}/front_end/chii_app.html?${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 * Options for {@link AutoDevtoolsOpener.open}.\n *\n * The `relayHttpBaseUrl` and `targetId` fields are required to build a working\n * Chii self-hosted inspector URL. When `relayHttpBaseUrl` is absent the open\n * is skipped (no relay available yet).\n */\nexport interface DevtoolsOpenOptions {\n  /**\n   * Local HTTP base URL of the Chii relay, e.g. `http://127.0.0.1:9100`.\n   * Used to build the `<relay-base>/front_end/chii_app.html?wss=…` URL.\n   *\n   * For env 3/4 (intoss relay) this is `http://127.0.0.1:<port>`.\n   * For env 2 (external PWA relay) this is the relay's external HTTP URL\n   * (e.g. `https://<host>.trycloudflare.com`).\n   *\n   * When absent or empty, `open()` is a no-op.\n   *\n   * SECRET-HANDLING: this value contains the relay host. Callers MUST NOT\n   * log it to stdout; stderr is the intended surface.\n   */\n  relayHttpBaseUrl: string | null | undefined;\n  /**\n   * Chii target id of the attached page, from `listTargets()[0].id`.\n   * When absent or empty, `open()` is a no-op.\n   */\n  targetId: string | null | undefined;\n  /**\n   * Function that mints a fresh TOTP code when called. Called at most once per\n   * `open()` invocation, immediately before building the inspector URL.\n   *\n   * Pass `undefined` when TOTP is disabled (no `at=` param is added).\n   *\n   * SECRET-HANDLING: the function MUST return only the code (6 digits), not\n   * the secret. The code rides in the URL's `at=` param only.\n   */\n  mintTotp?: () => string;\n  /** Current MCP environment (`mock` | `relay`). `open()` no-ops on `mock`. */\n  env: McpEnvironment;\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 Chii DevTools in the developer's browser.\n   *\n   * Builds a `<relay-base>/front_end/chii_app.html?wss=…` URL pointing at the\n   * attached target. A fresh TOTP `at=` code is minted at call time so the\n   * relay's WebSocket upgrade gate accepts the connection.\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. `options.env` is `mock` (env 1 — F12 is already available).\n   *   4. `options.relayHttpBaseUrl` is null/undefined/empty (relay not up yet).\n   *   5. `options.targetId` is null/undefined/empty (no page attached yet).\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   * TOTP expiry caveat: the `at=` code embedded in the URL is valid for ~3\n   * minutes (relay gate ±RELAY_VERIFY_SKEW_STEPS=6 steps = 180–210 s). The\n   * developer must open the URL within that window; if they miss it, reload\n   * the page or re-run `open()` (though the once-per-session guard prevents\n   * that — restart the MCP server if needed).\n   *\n   * SECRET-HANDLING: the inspector URL (written to stderr) contains the relay\n   * host and a short-lived TOTP code. Do NOT write it to stdout or any\n   * persistent log.\n   */\n  open(options: DevtoolsOpenOptions): void {\n    if (this._opened) return;\n    if (isAutoDevtoolsDisabled()) return;\n    if (options.env === 'mock') return;\n    if (!options.relayHttpBaseUrl) return;\n    if (!options.targetId) return;\n\n    this._opened = true;\n\n    const inspectorUrl = buildChiiInspectorUrl(\n      options.relayHttpBaseUrl,\n      options.targetId,\n      options.mintTotp,\n    );\n\n    process.stderr.write(\n      '[ait-debug] 기기가 연결됐습니다 — Chii DevTools를 자동으로 엽니다.\\n' +\n        `[ait-debug] DevTools URL: ${inspectorUrl}\\n` +\n        '[ait-debug] (AIT_AUTO_DEVTOOLS=0 으로 자동 열기를 끌 수 있습니다)\\n' +\n        '[ait-debug] 주의: URL의 at= 코드는 ~3분 안에서만 유효합니다.\\n',\n    );\n\n    const opened = openUrlInBrowser(inspectorUrl);\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":";;;;;;;;;;AAsJA,SAAgB,yBAAkC;AAChD,QAAO,QAAQ,IAAI,sBAAsB;;;;;;;;;AAc3C,SAAgB,iBAAiB,KAAsB;AAGrD,KAAI,QAAQ,IAAI,sCAAsC,IAAK,QAAO;CAElE,MAAM,EAAE,cAAA,UAAsB,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"}

package/dist/devtools-opener-Bp671YXu.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"devtools-opener-Bp671YXu.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.  Chii\n * also self-hosts its DevTools frontend at:\n *\n *   <relay-base>/front_end/chii_app.html\n *     ?ws|wss=<encodeURIComponent(\"<relay-host>/client/<uuid>?target=<targetId>&at=<totp>\")>\n *\n * The param name follows the relay base scheme — `ws=` for plain HTTP\n * (env 3/4 local relay), `wss=` for HTTPS (env 2 tunnel) — matching the\n * scheme branch in chii/public/index.js.\n *\n * This is the same URL format that Chii's own index-page inspect-links use\n * (derived from `chii/public/index.js` — the JS that powers the target list\n * page at `<relay-base>/`).  Opening this URL in the developer's local browser\n * gives a full Chrome DevTools UI connected to the phone via the relay.\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 * TOTP expiry caveat:\n *   The `at=` TOTP code embedded in the `wss=` parameter is minted fresh at the\n *   moment `open()` is called. The code is valid for the 30-second RFC 6238\n *   window (±1 step skew = 90 s acceptance). If the developer does not open the\n *   URL within that window the WebSocket upgrade will be rejected with 4401.\n *   In practice the browser opens immediately after the OS `open` command, so\n *   the window is always satisfied; if it is not (e.g. the URL is copied and\n *   opened later) the developer can copy the wss= param, replace `at=`, and\n *   reload. This is documented in the JSDoc below.\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// Chii self-hosted DevTools frontend URL\n// ---------------------------------------------------------------------------\n\n/**\n * Assembles the Chii self-hosted DevTools inspector URL for a given relay\n * and target.\n *\n * Chii serves its own DevTools frontend at\n * `<relayHttpBaseUrl>/front_end/chii_app.html`. The `ws=` (plain HTTP relay)\n * or `wss=` (HTTPS relay) query parameter is a URL-encoded string of the form\n * `<relay-host>/client/<uuid>?target=<id>` (and optionally `&at=<totp>`) —\n * the same format used by Chii's own target list page (derived from\n * `chii/public/index.js`).\n *\n * The `at=` TOTP code is minted at call time via `mintTotp()`.  It is valid\n * for the current 30-second RFC 6238 step (±1 step skew = 90 s acceptance\n * window).  The developer must open the returned URL within that window.  If\n * the window expires before the browser connects, the relay will reject the\n * WebSocket upgrade with close code 4401.\n *\n * SECRET-HANDLING: `mintTotp` returns a code, not a secret. The code is\n * embedded in the `wss=` parameter (inside the `at=` param) of the returned\n * URL. Callers MUST NOT log the returned URL to stdout (stderr is OK — it is\n * the intended fallback surface for the developer to copy the URL).\n *\n * @param relayHttpBaseUrl - Local HTTP base URL of the Chii relay, e.g.\n *   `http://127.0.0.1:9100`. No trailing slash.\n * @param targetId - Chii target id (from `GET <relay>/targets`).\n * @param mintTotp - Optional function that returns a fresh 6-digit TOTP code\n *   string. Called at most once. When omitted (TOTP disabled) no `at=` param\n *   is added.\n * @param panel - Initial panel. Defaults to `\"console\"`.\n *\n * @example\n * buildChiiInspectorUrl(\n *   'http://127.0.0.1:9100',\n *   'abc123',\n *   () => generateTotp(secret),\n * )\n * // → 'http://127.0.0.1:9100/front_end/chii_app.html?ws=127.0.0.1%3A9100%2Fclient%2F<uuid>%3Ftarget%3Dabc123%26at%3D<code>'\n */\nexport function buildChiiInspectorUrl(\n  relayHttpBaseUrl: string,\n  targetId: string,\n  mintTotp?: () => string,\n  panel: 'elements' | 'console' | 'sources' | 'network' = 'console',\n): string {\n  // Extract the host (and port) from the relay HTTP base URL, and pick the\n  // query param name chii_app.html expects: `ws=` dials `ws://` (plain-HTTP\n  // relay — env 3/4 local 127.0.0.1) while `wss=` dials `wss://` (HTTPS\n  // tunnel — env 2). chii/public/index.js does the same scheme branch:\n  // `location.protocol === 'https:' ? 'wss' : 'ws'`. Always sending `wss=`\n  // would make the frontend attempt TLS against the plain-HTTP local relay.\n  let relayHost: string;\n  let wsParamName: 'ws' | 'wss';\n  try {\n    const parsed = new URL(relayHttpBaseUrl);\n    relayHost = parsed.host; // e.g. \"127.0.0.1:9100\"\n    wsParamName = parsed.protocol === 'https:' ? 'wss' : 'ws';\n  } catch {\n    // Fallback: strip the scheme prefix manually if URL parsing fails.\n    relayHost = relayHttpBaseUrl.replace(/^https?:\\/\\//i, '');\n    wsParamName = /^https:/i.test(relayHttpBaseUrl) ? 'wss' : 'ws';\n  }\n\n  // Generate a client UUID that matches the format Chii's index.js uses\n  // (6 random alphanumeric characters).\n  const clientId = `devtools-opener-${Date.now().toString(36)}`;\n\n  // Build the ws=/wss= value: \"<relay-host>/client/<uuid>?target=<id>[&at=<code>]\"\n  // This mirrors the format from chii/public/index.js:\n  //   `${domain}${basePath}client/${randomId(6)}?target=${targetId}`\n  let wsPath = `${relayHost}/client/${clientId}?target=${encodeURIComponent(targetId)}`;\n\n  if (mintTotp) {\n    // SECRET-HANDLING: mintTotp() returns a code (not a secret). The code\n    // rides only in the URL's at= param. Callers must not log the URL.\n    const code = mintTotp();\n    wsPath += `&at=${encodeURIComponent(code)}`;\n  }\n\n  const params = new URLSearchParams({ [wsParamName]: wsPath, panel });\n  return `${relayHttpBaseUrl.replace(/\\/$/, '')}/front_end/chii_app.html?${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 * Options for {@link AutoDevtoolsOpener.open}.\n *\n * The `relayHttpBaseUrl` and `targetId` fields are required to build a working\n * Chii self-hosted inspector URL. When `relayHttpBaseUrl` is absent the open\n * is skipped (no relay available yet).\n */\nexport interface DevtoolsOpenOptions {\n  /**\n   * Local HTTP base URL of the Chii relay, e.g. `http://127.0.0.1:9100`.\n   * Used to build the `<relay-base>/front_end/chii_app.html?wss=…` URL.\n   *\n   * For env 3/4 (intoss relay) this is `http://127.0.0.1:<port>`.\n   * For env 2 (external PWA relay) this is the relay's external HTTP URL\n   * (e.g. `https://<host>.trycloudflare.com`).\n   *\n   * When absent or empty, `open()` is a no-op.\n   *\n   * SECRET-HANDLING: this value contains the relay host. Callers MUST NOT\n   * log it to stdout; stderr is the intended surface.\n   */\n  relayHttpBaseUrl: string | null | undefined;\n  /**\n   * Chii target id of the attached page, from `listTargets()[0].id`.\n   * When absent or empty, `open()` is a no-op.\n   */\n  targetId: string | null | undefined;\n  /**\n   * Function that mints a fresh TOTP code when called. Called at most once per\n   * `open()` invocation, immediately before building the inspector URL.\n   *\n   * Pass `undefined` when TOTP is disabled (no `at=` param is added).\n   *\n   * SECRET-HANDLING: the function MUST return only the code (6 digits), not\n   * the secret. The code rides in the URL's `at=` param only.\n   */\n  mintTotp?: () => string;\n  /** Current MCP environment (`mock` | `relay`). `open()` no-ops on `mock`. */\n  env: McpEnvironment;\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 Chii DevTools in the developer's browser.\n   *\n   * Builds a `<relay-base>/front_end/chii_app.html?wss=…` URL pointing at the\n   * attached target. A fresh TOTP `at=` code is minted at call time so the\n   * relay's WebSocket upgrade gate accepts the connection.\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. `options.env` is `mock` (env 1 — F12 is already available).\n   *   4. `options.relayHttpBaseUrl` is null/undefined/empty (relay not up yet).\n   *   5. `options.targetId` is null/undefined/empty (no page attached yet).\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   * TOTP expiry caveat: the `at=` code embedded in the URL is valid for the\n   * current 30-second RFC 6238 step (±1 skew = 90 s). The developer must open\n   * the URL within that window; if they miss it, reload the page or re-run\n   * `open()` (though the once-per-session guard prevents that — restart the\n   * MCP server if needed).\n   *\n   * SECRET-HANDLING: the inspector URL (written to stderr) contains the relay\n   * host and a short-lived TOTP code. Do NOT write it to stdout or any\n   * persistent log.\n   */\n  open(options: DevtoolsOpenOptions): void {\n    if (this._opened) return;\n    if (isAutoDevtoolsDisabled()) return;\n    if (options.env === 'mock') return;\n    if (!options.relayHttpBaseUrl) return;\n    if (!options.targetId) return;\n\n    this._opened = true;\n\n    const inspectorUrl = buildChiiInspectorUrl(\n      options.relayHttpBaseUrl,\n      options.targetId,\n      options.mintTotp,\n    );\n\n    process.stderr.write(\n      '[ait-debug] 기기가 연결됐습니다 — Chii DevTools를 자동으로 엽니다.\\n' +\n        `[ait-debug] DevTools URL: ${inspectorUrl}\\n` +\n        '[ait-debug] (AIT_AUTO_DEVTOOLS=0 으로 자동 열기를 끌 수 있습니다)\\n' +\n        '[ait-debug] 주의: URL의 at= 코드는 30초 창 안에서만 유효합니다.\\n',\n    );\n\n    const opened = openUrlInBrowser(inspectorUrl);\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":";;;;;;AAuJA,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"}
+{"version":3,"file":"devtools-opener-Bp671YXu.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.  Chii\n * also self-hosts its DevTools frontend at:\n *\n *   <relay-base>/front_end/chii_app.html\n *     ?ws|wss=<encodeURIComponent(\"<relay-host>/client/<uuid>?target=<targetId>&at=<totp>\")>\n *\n * The param name follows the relay base scheme — `ws=` for plain HTTP\n * (env 3/4 local relay), `wss=` for HTTPS (env 2 tunnel) — matching the\n * scheme branch in chii/public/index.js.\n *\n * This is the same URL format that Chii's own index-page inspect-links use\n * (derived from `chii/public/index.js` — the JS that powers the target list\n * page at `<relay-base>/`).  Opening this URL in the developer's local browser\n * gives a full Chrome DevTools UI connected to the phone via the relay.\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 * TOTP expiry caveat:\n *   The `at=` TOTP code embedded in the `wss=` parameter is minted fresh at the\n *   moment `open()` is called. The code is valid for ~3 minutes (the relay gate\n *   accepts ±RELAY_VERIFY_SKEW_STEPS=6 steps = 180–210 s). If the developer\n *   does not open the URL within that window the WebSocket upgrade will be\n *   rejected with 4401. In practice the browser opens immediately after the OS\n *   `open` command; if needed the developer can copy the wss= param, replace\n *   `at=`, and reload. This is documented in the JSDoc below.\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// Chii self-hosted DevTools frontend URL\n// ---------------------------------------------------------------------------\n\n/**\n * Assembles the Chii self-hosted DevTools inspector URL for a given relay\n * and target.\n *\n * Chii serves its own DevTools frontend at\n * `<relayHttpBaseUrl>/front_end/chii_app.html`. The `ws=` (plain HTTP relay)\n * or `wss=` (HTTPS relay) query parameter is a URL-encoded string of the form\n * `<relay-host>/client/<uuid>?target=<id>` (and optionally `&at=<totp>`) —\n * the same format used by Chii's own target list page (derived from\n * `chii/public/index.js`).\n *\n * The `at=` TOTP code is minted at call time via `mintTotp()`.  It is valid\n * for ~3 minutes (relay gate accepts ±RELAY_VERIFY_SKEW_STEPS=6 steps =\n * 180–210 s).  The developer must open the returned URL within that window.\n * If the window expires before the browser connects, the relay will reject the\n * WebSocket upgrade with close code 4401.\n *\n * SECRET-HANDLING: `mintTotp` returns a code, not a secret. The code is\n * embedded in the `wss=` parameter (inside the `at=` param) of the returned\n * URL. Callers MUST NOT log the returned URL to stdout (stderr is OK — it is\n * the intended fallback surface for the developer to copy the URL).\n *\n * @param relayHttpBaseUrl - Local HTTP base URL of the Chii relay, e.g.\n *   `http://127.0.0.1:9100`. No trailing slash.\n * @param targetId - Chii target id (from `GET <relay>/targets`).\n * @param mintTotp - Optional function that returns a fresh 6-digit TOTP code\n *   string. Called at most once. When omitted (TOTP disabled) no `at=` param\n *   is added.\n * @param panel - Initial panel. Defaults to `\"console\"`.\n *\n * @example\n * buildChiiInspectorUrl(\n *   'http://127.0.0.1:9100',\n *   'abc123',\n *   () => generateTotp(secret),\n * )\n * // → 'http://127.0.0.1:9100/front_end/chii_app.html?ws=127.0.0.1%3A9100%2Fclient%2F<uuid>%3Ftarget%3Dabc123%26at%3D<code>'\n */\nexport function buildChiiInspectorUrl(\n  relayHttpBaseUrl: string,\n  targetId: string,\n  mintTotp?: () => string,\n  panel: 'elements' | 'console' | 'sources' | 'network' = 'console',\n): string {\n  // Extract the host (and port) from the relay HTTP base URL, and pick the\n  // query param name chii_app.html expects: `ws=` dials `ws://` (plain-HTTP\n  // relay — env 3/4 local 127.0.0.1) while `wss=` dials `wss://` (HTTPS\n  // tunnel — env 2). chii/public/index.js does the same scheme branch:\n  // `location.protocol === 'https:' ? 'wss' : 'ws'`. Always sending `wss=`\n  // would make the frontend attempt TLS against the plain-HTTP local relay.\n  let relayHost: string;\n  let wsParamName: 'ws' | 'wss';\n  try {\n    const parsed = new URL(relayHttpBaseUrl);\n    relayHost = parsed.host; // e.g. \"127.0.0.1:9100\"\n    wsParamName = parsed.protocol === 'https:' ? 'wss' : 'ws';\n  } catch {\n    // Fallback: strip the scheme prefix manually if URL parsing fails.\n    relayHost = relayHttpBaseUrl.replace(/^https?:\\/\\//i, '');\n    wsParamName = /^https:/i.test(relayHttpBaseUrl) ? 'wss' : 'ws';\n  }\n\n  // Generate a client UUID that matches the format Chii's index.js uses\n  // (6 random alphanumeric characters).\n  const clientId = `devtools-opener-${Date.now().toString(36)}`;\n\n  // Build the ws=/wss= value: \"<relay-host>/client/<uuid>?target=<id>[&at=<code>]\"\n  // This mirrors the format from chii/public/index.js:\n  //   `${domain}${basePath}client/${randomId(6)}?target=${targetId}`\n  let wsPath = `${relayHost}/client/${clientId}?target=${encodeURIComponent(targetId)}`;\n\n  if (mintTotp) {\n    // SECRET-HANDLING: mintTotp() returns a code (not a secret). The code\n    // rides only in the URL's at= param. Callers must not log the URL.\n    const code = mintTotp();\n    wsPath += `&at=${encodeURIComponent(code)}`;\n  }\n\n  const params = new URLSearchParams({ [wsParamName]: wsPath, panel });\n  return `${relayHttpBaseUrl.replace(/\\/$/, '')}/front_end/chii_app.html?${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 * Options for {@link AutoDevtoolsOpener.open}.\n *\n * The `relayHttpBaseUrl` and `targetId` fields are required to build a working\n * Chii self-hosted inspector URL. When `relayHttpBaseUrl` is absent the open\n * is skipped (no relay available yet).\n */\nexport interface DevtoolsOpenOptions {\n  /**\n   * Local HTTP base URL of the Chii relay, e.g. `http://127.0.0.1:9100`.\n   * Used to build the `<relay-base>/front_end/chii_app.html?wss=…` URL.\n   *\n   * For env 3/4 (intoss relay) this is `http://127.0.0.1:<port>`.\n   * For env 2 (external PWA relay) this is the relay's external HTTP URL\n   * (e.g. `https://<host>.trycloudflare.com`).\n   *\n   * When absent or empty, `open()` is a no-op.\n   *\n   * SECRET-HANDLING: this value contains the relay host. Callers MUST NOT\n   * log it to stdout; stderr is the intended surface.\n   */\n  relayHttpBaseUrl: string | null | undefined;\n  /**\n   * Chii target id of the attached page, from `listTargets()[0].id`.\n   * When absent or empty, `open()` is a no-op.\n   */\n  targetId: string | null | undefined;\n  /**\n   * Function that mints a fresh TOTP code when called. Called at most once per\n   * `open()` invocation, immediately before building the inspector URL.\n   *\n   * Pass `undefined` when TOTP is disabled (no `at=` param is added).\n   *\n   * SECRET-HANDLING: the function MUST return only the code (6 digits), not\n   * the secret. The code rides in the URL's `at=` param only.\n   */\n  mintTotp?: () => string;\n  /** Current MCP environment (`mock` | `relay`). `open()` no-ops on `mock`. */\n  env: McpEnvironment;\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 Chii DevTools in the developer's browser.\n   *\n   * Builds a `<relay-base>/front_end/chii_app.html?wss=…` URL pointing at the\n   * attached target. A fresh TOTP `at=` code is minted at call time so the\n   * relay's WebSocket upgrade gate accepts the connection.\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. `options.env` is `mock` (env 1 — F12 is already available).\n   *   4. `options.relayHttpBaseUrl` is null/undefined/empty (relay not up yet).\n   *   5. `options.targetId` is null/undefined/empty (no page attached yet).\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   * TOTP expiry caveat: the `at=` code embedded in the URL is valid for ~3\n   * minutes (relay gate ±RELAY_VERIFY_SKEW_STEPS=6 steps = 180–210 s). The\n   * developer must open the URL within that window; if they miss it, reload\n   * the page or re-run `open()` (though the once-per-session guard prevents\n   * that — restart the MCP server if needed).\n   *\n   * SECRET-HANDLING: the inspector URL (written to stderr) contains the relay\n   * host and a short-lived TOTP code. Do NOT write it to stdout or any\n   * persistent log.\n   */\n  open(options: DevtoolsOpenOptions): void {\n    if (this._opened) return;\n    if (isAutoDevtoolsDisabled()) return;\n    if (options.env === 'mock') return;\n    if (!options.relayHttpBaseUrl) return;\n    if (!options.targetId) return;\n\n    this._opened = true;\n\n    const inspectorUrl = buildChiiInspectorUrl(\n      options.relayHttpBaseUrl,\n      options.targetId,\n      options.mintTotp,\n    );\n\n    process.stderr.write(\n      '[ait-debug] 기기가 연결됐습니다 — Chii DevTools를 자동으로 엽니다.\\n' +\n        `[ait-debug] DevTools URL: ${inspectorUrl}\\n` +\n        '[ait-debug] (AIT_AUTO_DEVTOOLS=0 으로 자동 열기를 끌 수 있습니다)\\n' +\n        '[ait-debug] 주의: URL의 at= 코드는 ~3분 안에서만 유효합니다.\\n',\n    );\n\n    const opened = openUrlInBrowser(inspectorUrl);\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":";;;;;;AAsJA,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"}

package/dist/devtools-opener-D84kZFtR.js.map

@@ -1 +1 @@
-{"version":3,"file":"devtools-opener-D84kZFtR.js","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.  Chii\n * also self-hosts its DevTools frontend at:\n *\n *   <relay-base>/front_end/chii_app.html\n *     ?ws|wss=<encodeURIComponent(\"<relay-host>/client/<uuid>?target=<targetId>&at=<totp>\")>\n *\n * The param name follows the relay base scheme — `ws=` for plain HTTP\n * (env 3/4 local relay), `wss=` for HTTPS (env 2 tunnel) — matching the\n * scheme branch in chii/public/index.js.\n *\n * This is the same URL format that Chii's own index-page inspect-links use\n * (derived from `chii/public/index.js` — the JS that powers the target list\n * page at `<relay-base>/`).  Opening this URL in the developer's local browser\n * gives a full Chrome DevTools UI connected to the phone via the relay.\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 * TOTP expiry caveat:\n *   The `at=` TOTP code embedded in the `wss=` parameter is minted fresh at the\n *   moment `open()` is called. The code is valid for the 30-second RFC 6238\n *   window (±1 step skew = 90 s acceptance). If the developer does not open the\n *   URL within that window the WebSocket upgrade will be rejected with 4401.\n *   In practice the browser opens immediately after the OS `open` command, so\n *   the window is always satisfied; if it is not (e.g. the URL is copied and\n *   opened later) the developer can copy the wss= param, replace `at=`, and\n *   reload. This is documented in the JSDoc below.\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// Chii self-hosted DevTools frontend URL\n// ---------------------------------------------------------------------------\n\n/**\n * Assembles the Chii self-hosted DevTools inspector URL for a given relay\n * and target.\n *\n * Chii serves its own DevTools frontend at\n * `<relayHttpBaseUrl>/front_end/chii_app.html`. The `ws=` (plain HTTP relay)\n * or `wss=` (HTTPS relay) query parameter is a URL-encoded string of the form\n * `<relay-host>/client/<uuid>?target=<id>` (and optionally `&at=<totp>`) —\n * the same format used by Chii's own target list page (derived from\n * `chii/public/index.js`).\n *\n * The `at=` TOTP code is minted at call time via `mintTotp()`.  It is valid\n * for the current 30-second RFC 6238 step (±1 step skew = 90 s acceptance\n * window).  The developer must open the returned URL within that window.  If\n * the window expires before the browser connects, the relay will reject the\n * WebSocket upgrade with close code 4401.\n *\n * SECRET-HANDLING: `mintTotp` returns a code, not a secret. The code is\n * embedded in the `wss=` parameter (inside the `at=` param) of the returned\n * URL. Callers MUST NOT log the returned URL to stdout (stderr is OK — it is\n * the intended fallback surface for the developer to copy the URL).\n *\n * @param relayHttpBaseUrl - Local HTTP base URL of the Chii relay, e.g.\n *   `http://127.0.0.1:9100`. No trailing slash.\n * @param targetId - Chii target id (from `GET <relay>/targets`).\n * @param mintTotp - Optional function that returns a fresh 6-digit TOTP code\n *   string. Called at most once. When omitted (TOTP disabled) no `at=` param\n *   is added.\n * @param panel - Initial panel. Defaults to `\"console\"`.\n *\n * @example\n * buildChiiInspectorUrl(\n *   'http://127.0.0.1:9100',\n *   'abc123',\n *   () => generateTotp(secret),\n * )\n * // → 'http://127.0.0.1:9100/front_end/chii_app.html?ws=127.0.0.1%3A9100%2Fclient%2F<uuid>%3Ftarget%3Dabc123%26at%3D<code>'\n */\nexport function buildChiiInspectorUrl(\n  relayHttpBaseUrl: string,\n  targetId: string,\n  mintTotp?: () => string,\n  panel: 'elements' | 'console' | 'sources' | 'network' = 'console',\n): string {\n  // Extract the host (and port) from the relay HTTP base URL, and pick the\n  // query param name chii_app.html expects: `ws=` dials `ws://` (plain-HTTP\n  // relay — env 3/4 local 127.0.0.1) while `wss=` dials `wss://` (HTTPS\n  // tunnel — env 2). chii/public/index.js does the same scheme branch:\n  // `location.protocol === 'https:' ? 'wss' : 'ws'`. Always sending `wss=`\n  // would make the frontend attempt TLS against the plain-HTTP local relay.\n  let relayHost: string;\n  let wsParamName: 'ws' | 'wss';\n  try {\n    const parsed = new URL(relayHttpBaseUrl);\n    relayHost = parsed.host; // e.g. \"127.0.0.1:9100\"\n    wsParamName = parsed.protocol === 'https:' ? 'wss' : 'ws';\n  } catch {\n    // Fallback: strip the scheme prefix manually if URL parsing fails.\n    relayHost = relayHttpBaseUrl.replace(/^https?:\\/\\//i, '');\n    wsParamName = /^https:/i.test(relayHttpBaseUrl) ? 'wss' : 'ws';\n  }\n\n  // Generate a client UUID that matches the format Chii's index.js uses\n  // (6 random alphanumeric characters).\n  const clientId = `devtools-opener-${Date.now().toString(36)}`;\n\n  // Build the ws=/wss= value: \"<relay-host>/client/<uuid>?target=<id>[&at=<code>]\"\n  // This mirrors the format from chii/public/index.js:\n  //   `${domain}${basePath}client/${randomId(6)}?target=${targetId}`\n  let wsPath = `${relayHost}/client/${clientId}?target=${encodeURIComponent(targetId)}`;\n\n  if (mintTotp) {\n    // SECRET-HANDLING: mintTotp() returns a code (not a secret). The code\n    // rides only in the URL's at= param. Callers must not log the URL.\n    const code = mintTotp();\n    wsPath += `&at=${encodeURIComponent(code)}`;\n  }\n\n  const params = new URLSearchParams({ [wsParamName]: wsPath, panel });\n  return `${relayHttpBaseUrl.replace(/\\/$/, '')}/front_end/chii_app.html?${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 * Options for {@link AutoDevtoolsOpener.open}.\n *\n * The `relayHttpBaseUrl` and `targetId` fields are required to build a working\n * Chii self-hosted inspector URL. When `relayHttpBaseUrl` is absent the open\n * is skipped (no relay available yet).\n */\nexport interface DevtoolsOpenOptions {\n  /**\n   * Local HTTP base URL of the Chii relay, e.g. `http://127.0.0.1:9100`.\n   * Used to build the `<relay-base>/front_end/chii_app.html?wss=…` URL.\n   *\n   * For env 3/4 (intoss relay) this is `http://127.0.0.1:<port>`.\n   * For env 2 (external PWA relay) this is the relay's external HTTP URL\n   * (e.g. `https://<host>.trycloudflare.com`).\n   *\n   * When absent or empty, `open()` is a no-op.\n   *\n   * SECRET-HANDLING: this value contains the relay host. Callers MUST NOT\n   * log it to stdout; stderr is the intended surface.\n   */\n  relayHttpBaseUrl: string | null | undefined;\n  /**\n   * Chii target id of the attached page, from `listTargets()[0].id`.\n   * When absent or empty, `open()` is a no-op.\n   */\n  targetId: string | null | undefined;\n  /**\n   * Function that mints a fresh TOTP code when called. Called at most once per\n   * `open()` invocation, immediately before building the inspector URL.\n   *\n   * Pass `undefined` when TOTP is disabled (no `at=` param is added).\n   *\n   * SECRET-HANDLING: the function MUST return only the code (6 digits), not\n   * the secret. The code rides in the URL's `at=` param only.\n   */\n  mintTotp?: () => string;\n  /** Current MCP environment (`mock` | `relay`). `open()` no-ops on `mock`. */\n  env: McpEnvironment;\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 Chii DevTools in the developer's browser.\n   *\n   * Builds a `<relay-base>/front_end/chii_app.html?wss=…` URL pointing at the\n   * attached target. A fresh TOTP `at=` code is minted at call time so the\n   * relay's WebSocket upgrade gate accepts the connection.\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. `options.env` is `mock` (env 1 — F12 is already available).\n   *   4. `options.relayHttpBaseUrl` is null/undefined/empty (relay not up yet).\n   *   5. `options.targetId` is null/undefined/empty (no page attached yet).\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   * TOTP expiry caveat: the `at=` code embedded in the URL is valid for the\n   * current 30-second RFC 6238 step (±1 skew = 90 s). The developer must open\n   * the URL within that window; if they miss it, reload the page or re-run\n   * `open()` (though the once-per-session guard prevents that — restart the\n   * MCP server if needed).\n   *\n   * SECRET-HANDLING: the inspector URL (written to stderr) contains the relay\n   * host and a short-lived TOTP code. Do NOT write it to stdout or any\n   * persistent log.\n   */\n  open(options: DevtoolsOpenOptions): void {\n    if (this._opened) return;\n    if (isAutoDevtoolsDisabled()) return;\n    if (options.env === 'mock') return;\n    if (!options.relayHttpBaseUrl) return;\n    if (!options.targetId) return;\n\n    this._opened = true;\n\n    const inspectorUrl = buildChiiInspectorUrl(\n      options.relayHttpBaseUrl,\n      options.targetId,\n      options.mintTotp,\n    );\n\n    process.stderr.write(\n      '[ait-debug] 기기가 연결됐습니다 — Chii DevTools를 자동으로 엽니다.\\n' +\n        `[ait-debug] DevTools URL: ${inspectorUrl}\\n` +\n        '[ait-debug] (AIT_AUTO_DEVTOOLS=0 으로 자동 열기를 끌 수 있습니다)\\n' +\n        '[ait-debug] 주의: URL의 at= 코드는 30초 창 안에서만 유효합니다.\\n',\n    );\n\n    const opened = openUrlInBrowser(inspectorUrl);\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":";;;;;;;;;;AAuJA,SAAgB,yBAAkC;AAChD,QAAO,QAAQ,IAAI,sBAAsB;;;;;;;;;AAc3C,SAAgB,iBAAiB,KAAsB;AAGrD,KAAI,QAAQ,IAAI,sCAAsC,IAAK,QAAO;CAElE,MAAM,EAAE,cAAA,UAAsB,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"}
+{"version":3,"file":"devtools-opener-D84kZFtR.js","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.  Chii\n * also self-hosts its DevTools frontend at:\n *\n *   <relay-base>/front_end/chii_app.html\n *     ?ws|wss=<encodeURIComponent(\"<relay-host>/client/<uuid>?target=<targetId>&at=<totp>\")>\n *\n * The param name follows the relay base scheme — `ws=` for plain HTTP\n * (env 3/4 local relay), `wss=` for HTTPS (env 2 tunnel) — matching the\n * scheme branch in chii/public/index.js.\n *\n * This is the same URL format that Chii's own index-page inspect-links use\n * (derived from `chii/public/index.js` — the JS that powers the target list\n * page at `<relay-base>/`).  Opening this URL in the developer's local browser\n * gives a full Chrome DevTools UI connected to the phone via the relay.\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 * TOTP expiry caveat:\n *   The `at=` TOTP code embedded in the `wss=` parameter is minted fresh at the\n *   moment `open()` is called. The code is valid for ~3 minutes (the relay gate\n *   accepts ±RELAY_VERIFY_SKEW_STEPS=6 steps = 180–210 s). If the developer\n *   does not open the URL within that window the WebSocket upgrade will be\n *   rejected with 4401. In practice the browser opens immediately after the OS\n *   `open` command; if needed the developer can copy the wss= param, replace\n *   `at=`, and reload. This is documented in the JSDoc below.\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// Chii self-hosted DevTools frontend URL\n// ---------------------------------------------------------------------------\n\n/**\n * Assembles the Chii self-hosted DevTools inspector URL for a given relay\n * and target.\n *\n * Chii serves its own DevTools frontend at\n * `<relayHttpBaseUrl>/front_end/chii_app.html`. The `ws=` (plain HTTP relay)\n * or `wss=` (HTTPS relay) query parameter is a URL-encoded string of the form\n * `<relay-host>/client/<uuid>?target=<id>` (and optionally `&at=<totp>`) —\n * the same format used by Chii's own target list page (derived from\n * `chii/public/index.js`).\n *\n * The `at=` TOTP code is minted at call time via `mintTotp()`.  It is valid\n * for ~3 minutes (relay gate accepts ±RELAY_VERIFY_SKEW_STEPS=6 steps =\n * 180–210 s).  The developer must open the returned URL within that window.\n * If the window expires before the browser connects, the relay will reject the\n * WebSocket upgrade with close code 4401.\n *\n * SECRET-HANDLING: `mintTotp` returns a code, not a secret. The code is\n * embedded in the `wss=` parameter (inside the `at=` param) of the returned\n * URL. Callers MUST NOT log the returned URL to stdout (stderr is OK — it is\n * the intended fallback surface for the developer to copy the URL).\n *\n * @param relayHttpBaseUrl - Local HTTP base URL of the Chii relay, e.g.\n *   `http://127.0.0.1:9100`. No trailing slash.\n * @param targetId - Chii target id (from `GET <relay>/targets`).\n * @param mintTotp - Optional function that returns a fresh 6-digit TOTP code\n *   string. Called at most once. When omitted (TOTP disabled) no `at=` param\n *   is added.\n * @param panel - Initial panel. Defaults to `\"console\"`.\n *\n * @example\n * buildChiiInspectorUrl(\n *   'http://127.0.0.1:9100',\n *   'abc123',\n *   () => generateTotp(secret),\n * )\n * // → 'http://127.0.0.1:9100/front_end/chii_app.html?ws=127.0.0.1%3A9100%2Fclient%2F<uuid>%3Ftarget%3Dabc123%26at%3D<code>'\n */\nexport function buildChiiInspectorUrl(\n  relayHttpBaseUrl: string,\n  targetId: string,\n  mintTotp?: () => string,\n  panel: 'elements' | 'console' | 'sources' | 'network' = 'console',\n): string {\n  // Extract the host (and port) from the relay HTTP base URL, and pick the\n  // query param name chii_app.html expects: `ws=` dials `ws://` (plain-HTTP\n  // relay — env 3/4 local 127.0.0.1) while `wss=` dials `wss://` (HTTPS\n  // tunnel — env 2). chii/public/index.js does the same scheme branch:\n  // `location.protocol === 'https:' ? 'wss' : 'ws'`. Always sending `wss=`\n  // would make the frontend attempt TLS against the plain-HTTP local relay.\n  let relayHost: string;\n  let wsParamName: 'ws' | 'wss';\n  try {\n    const parsed = new URL(relayHttpBaseUrl);\n    relayHost = parsed.host; // e.g. \"127.0.0.1:9100\"\n    wsParamName = parsed.protocol === 'https:' ? 'wss' : 'ws';\n  } catch {\n    // Fallback: strip the scheme prefix manually if URL parsing fails.\n    relayHost = relayHttpBaseUrl.replace(/^https?:\\/\\//i, '');\n    wsParamName = /^https:/i.test(relayHttpBaseUrl) ? 'wss' : 'ws';\n  }\n\n  // Generate a client UUID that matches the format Chii's index.js uses\n  // (6 random alphanumeric characters).\n  const clientId = `devtools-opener-${Date.now().toString(36)}`;\n\n  // Build the ws=/wss= value: \"<relay-host>/client/<uuid>?target=<id>[&at=<code>]\"\n  // This mirrors the format from chii/public/index.js:\n  //   `${domain}${basePath}client/${randomId(6)}?target=${targetId}`\n  let wsPath = `${relayHost}/client/${clientId}?target=${encodeURIComponent(targetId)}`;\n\n  if (mintTotp) {\n    // SECRET-HANDLING: mintTotp() returns a code (not a secret). The code\n    // rides only in the URL's at= param. Callers must not log the URL.\n    const code = mintTotp();\n    wsPath += `&at=${encodeURIComponent(code)}`;\n  }\n\n  const params = new URLSearchParams({ [wsParamName]: wsPath, panel });\n  return `${relayHttpBaseUrl.replace(/\\/$/, '')}/front_end/chii_app.html?${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 * Options for {@link AutoDevtoolsOpener.open}.\n *\n * The `relayHttpBaseUrl` and `targetId` fields are required to build a working\n * Chii self-hosted inspector URL. When `relayHttpBaseUrl` is absent the open\n * is skipped (no relay available yet).\n */\nexport interface DevtoolsOpenOptions {\n  /**\n   * Local HTTP base URL of the Chii relay, e.g. `http://127.0.0.1:9100`.\n   * Used to build the `<relay-base>/front_end/chii_app.html?wss=…` URL.\n   *\n   * For env 3/4 (intoss relay) this is `http://127.0.0.1:<port>`.\n   * For env 2 (external PWA relay) this is the relay's external HTTP URL\n   * (e.g. `https://<host>.trycloudflare.com`).\n   *\n   * When absent or empty, `open()` is a no-op.\n   *\n   * SECRET-HANDLING: this value contains the relay host. Callers MUST NOT\n   * log it to stdout; stderr is the intended surface.\n   */\n  relayHttpBaseUrl: string | null | undefined;\n  /**\n   * Chii target id of the attached page, from `listTargets()[0].id`.\n   * When absent or empty, `open()` is a no-op.\n   */\n  targetId: string | null | undefined;\n  /**\n   * Function that mints a fresh TOTP code when called. Called at most once per\n   * `open()` invocation, immediately before building the inspector URL.\n   *\n   * Pass `undefined` when TOTP is disabled (no `at=` param is added).\n   *\n   * SECRET-HANDLING: the function MUST return only the code (6 digits), not\n   * the secret. The code rides in the URL's `at=` param only.\n   */\n  mintTotp?: () => string;\n  /** Current MCP environment (`mock` | `relay`). `open()` no-ops on `mock`. */\n  env: McpEnvironment;\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 Chii DevTools in the developer's browser.\n   *\n   * Builds a `<relay-base>/front_end/chii_app.html?wss=…` URL pointing at the\n   * attached target. A fresh TOTP `at=` code is minted at call time so the\n   * relay's WebSocket upgrade gate accepts the connection.\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. `options.env` is `mock` (env 1 — F12 is already available).\n   *   4. `options.relayHttpBaseUrl` is null/undefined/empty (relay not up yet).\n   *   5. `options.targetId` is null/undefined/empty (no page attached yet).\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   * TOTP expiry caveat: the `at=` code embedded in the URL is valid for ~3\n   * minutes (relay gate ±RELAY_VERIFY_SKEW_STEPS=6 steps = 180–210 s). The\n   * developer must open the URL within that window; if they miss it, reload\n   * the page or re-run `open()` (though the once-per-session guard prevents\n   * that — restart the MCP server if needed).\n   *\n   * SECRET-HANDLING: the inspector URL (written to stderr) contains the relay\n   * host and a short-lived TOTP code. Do NOT write it to stdout or any\n   * persistent log.\n   */\n  open(options: DevtoolsOpenOptions): void {\n    if (this._opened) return;\n    if (isAutoDevtoolsDisabled()) return;\n    if (options.env === 'mock') return;\n    if (!options.relayHttpBaseUrl) return;\n    if (!options.targetId) return;\n\n    this._opened = true;\n\n    const inspectorUrl = buildChiiInspectorUrl(\n      options.relayHttpBaseUrl,\n      options.targetId,\n      options.mintTotp,\n    );\n\n    process.stderr.write(\n      '[ait-debug] 기기가 연결됐습니다 — Chii DevTools를 자동으로 엽니다.\\n' +\n        `[ait-debug] DevTools URL: ${inspectorUrl}\\n` +\n        '[ait-debug] (AIT_AUTO_DEVTOOLS=0 으로 자동 열기를 끌 수 있습니다)\\n' +\n        '[ait-debug] 주의: URL의 at= 코드는 ~3분 안에서만 유효합니다.\\n',\n    );\n\n    const opened = openUrlInBrowser(inspectorUrl);\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":";;;;;;;;;;AAsJA,SAAgB,yBAAkC;AAChD,QAAO,QAAQ,IAAI,sBAAsB;;;;;;;;;AAc3C,SAAgB,iBAAiB,KAAsB;AAGrD,KAAI,QAAQ,IAAI,sCAAsC,IAAK,QAAO;CAElE,MAAM,EAAE,cAAA,UAAsB,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"}