@ait-co/devtools 0.1.21 → 0.1.23

package/dist/in-app/index.js

@@ -0,0 +1,163 @@
+//#region src/in-app/gate.ts
+/**
+* Pure function that evaluates the 3-layer debug activation gate.
+*
+* Has no side effects. All inputs are explicit. Returns a discriminated union
+* so callers can pattern-match on `result.attach`.
+*
+* @example
+* ```ts
+* const result = evaluateDebugGate({
+*   isDebugBuild: __DEBUG_BUILD__,
+*   searchParams: new URLSearchParams(window.location.search),
+* });
+* if (result.attach) {
+*   // Proceed to load Chii client
+* }
+* ```
+*/
+function evaluateDebugGate(input) {
+	if (!input.isDebugBuild) return {
+		attach: false,
+		reason: "build"
+	};
+	const deploymentId = input.searchParams.get("_deploymentId") ?? "";
+	if (deploymentId === "") return {
+		attach: false,
+		reason: "entry"
+	};
+	if (input.searchParams.get("debug") !== "1") return {
+		attach: false,
+		reason: "opt-in"
+	};
+	const relayRaw = input.searchParams.get("relay") ?? "";
+	if (relayRaw === "") return {
+		attach: false,
+		reason: "invalid-relay"
+	};
+	let relayUrl;
+	try {
+		relayUrl = new URL(relayRaw);
+	} catch {
+		return {
+			attach: false,
+			reason: "invalid-relay"
+		};
+	}
+	if (relayUrl.protocol !== "wss:") return {
+		attach: false,
+		reason: "invalid-relay"
+	};
+	return {
+		attach: true,
+		relayUrl: relayUrl.href,
+		deploymentId
+	};
+}
+//#endregion
+//#region src/in-app/attach.ts
+/**
+* In-app Chii target injection for the debug attach flow.
+*
+* Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md
+* "MCP attach" topology section — Phase 1 browser-side implementation.
+*
+* This module bridges the 3-layer gate result to a Chii `target.js` script
+* injection. The Chii npm package is the relay SERVER — the in-app side is
+* a plain `<script src="…/target.js">` pointing at the relay host. No chii
+* npm dependency is needed here.
+*/
+/**
+* Converts a validated `wss:` relay URL into the Chii `target.js` script URL.
+*
+* Scheme is mapped `wss:` → `https:`. Host and port are preserved.
+* Pathname is set to `/target.js` regardless of the relay path.
+* Query params and hash from the relay URL are dropped — the target script
+* URL is a static asset path on the same host.
+*
+* @example
+* deriveTargetScriptUrl('wss://abc.trycloudflare.com/relay')
+* // → 'https://abc.trycloudflare.com/target.js'
+*
+* deriveTargetScriptUrl('wss://h.example.com:9100/')
+* // → 'https://h.example.com:9100/target.js'
+*/
+function deriveTargetScriptUrl(relayUrl) {
+	const u = new URL(relayUrl);
+	u.protocol = "https:";
+	u.pathname = "/target.js";
+	u.search = "";
+	u.hash = "";
+	return u.toString();
+}
+/** Module-level guard against double-injection within a page lifecycle. */
+let attached = false;
+/**
+* Evaluates the 3-layer debug gate and, if the gate passes, injects the Chii
+* `target.js` script into `document.head`.
+*
+* Idempotent — calling more than once is safe. The second call is a no-op if
+* a script with the same `src` is already present in the document, and the
+* module-level `attached` flag prevents redundant DOM queries after the first
+* successful injection.
+*
+* Safe to call even if `document` is somehow unavailable (defensive boundary
+* guard — in practice this always runs in a real WebView).
+*
+* @param gateResult - Optional pre-evaluated gate result for testability.
+*   Defaults to `checkDebugGate()` which reads the current page URL and the
+*   `__DEBUG_BUILD__` compile-time constant. Passing a custom value avoids
+*   the need to manipulate `window.location` in tests.
+*/
+function maybeAttach(gateResult = checkDebugGate()) {
+	if (!gateResult.attach) {
+		console.debug(`[@ait-co/devtools] debug attach skipped — gate blocked (reason: ${gateResult.reason})`);
+		return;
+	}
+	if (attached) return;
+	if (typeof document === "undefined") return;
+	const src = deriveTargetScriptUrl(gateResult.relayUrl);
+	if (document.querySelector(`script[src="${src}"]`) !== null) {
+		attached = true;
+		return;
+	}
+	const script = document.createElement("script");
+	script.src = src;
+	script.async = true;
+	(document.head ?? document.documentElement).appendChild(script);
+	attached = true;
+}
+//#endregion
+//#region src/in-app/index.ts
+/**
+* @ait-co/devtools/in-app entry point.
+*
+* Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md
+*
+* Phase 1 — gate + browser-side Chii target injection.
+* WebSocket relay, QR/paste UI, and AI-host MCP bin are later phases that
+* require real-device validation and are not included here.
+*
+* This thin entry reads `__DEBUG_BUILD__` and `window.location`, then calls
+* the pure {@link evaluateDebugGate} function. All testable logic lives in
+* `./gate.ts` and `./attach.ts`, not here.
+*/
+/**
+* Evaluates the 3-layer debug activation gate against the current page URL.
+*
+* Returns the gate result. Callers can check `result.attach` to decide whether
+* to proceed with debug surface attachment.
+*
+* This function reads `window.location` and the `__DEBUG_BUILD__` compile-time
+* constant. It has no other side effects.
+*/
+function checkDebugGate() {
+	return evaluateDebugGate({
+		isDebugBuild: false,
+		searchParams: new URLSearchParams(window.location.search)
+	});
+}
+//#endregion
+export { checkDebugGate, deriveTargetScriptUrl, evaluateDebugGate, maybeAttach };
+
+//# sourceMappingURL=index.js.map

package/dist/in-app/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/in-app/gate.ts","../../src/in-app/attach.ts","../../src/in-app/index.ts"],"sourcesContent":["/**\n * 3-layer activation gate for the in-app debug surface.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n * \"3-layer activation gate\" — Phase 1 implementation (gate logic only).\n * Chii client, WebSocket transport, and QR UI are later phases.\n *\n * Decision matrix:\n *\n *   build channel | _deploymentId | debug=1 | result\n *   release       | (any)         | (any)   | BLOCKED  (Layer A — code absent via DCE)\n *   dogfood       | absent        | (any)   | BLOCKED  (Layer B — entry gate)\n *   dogfood       | present       | absent  | BLOCKED  (Layer C — opt-in gate)\n *   dogfood       | present       | present | ATTACH\n */\n\n/** Shape returned when the gate allows attachment. */\nexport interface GateResultAttach {\n  readonly attach: true;\n  /** The validated `wss:` relay URL from the `relay` query param. */\n  readonly relayUrl: string;\n  /** The deployment ID extracted from the `_deploymentId` query param. */\n  readonly deploymentId: string;\n}\n\n/** Shape returned when the gate blocks attachment, with a reason code. */\nexport interface GateResultBlocked {\n  readonly attach: false;\n  /**\n   * - `'build'`        Layer A: `__DEBUG_BUILD__` is false (release build).\n   * - `'entry'`        Layer B: `_deploymentId` param is absent or empty.\n   * - `'opt-in'`       Layer C: `debug=1` param is absent.\n   * - `'invalid-relay'` Layer C: `relay` param is absent, empty, or not a `wss:` URL.\n   */\n  readonly reason: 'build' | 'entry' | 'opt-in' | 'invalid-relay';\n}\n\nexport type GateResult = GateResultAttach | GateResultBlocked;\n\n/**\n * Input for {@link evaluateDebugGate}.\n *\n * Keeping each field explicit makes the function trivially testable without\n * needing to manipulate `window.location`.\n */\nexport interface GateInput {\n  /**\n   * Whether this is a debug build. Corresponds to the `__DEBUG_BUILD__`\n   * compile-time constant injected by tsdown.\n   *\n   * In source code consumed via `@ait-co/devtools/in-app`, the thin\n   * `src/in-app/index.ts` entry reads `__DEBUG_BUILD__` and passes it here.\n   * Tests supply it directly.\n   */\n  readonly isDebugBuild: boolean;\n\n  /**\n   * The URL search params to inspect for gate signals.\n   *\n   * Prefer `URLSearchParams` so callers can pass `new URLSearchParams(location.search)`\n   * without coupling the pure function to `window`.\n   *\n   * Layer B open seam (spec open question 2): if the Toss SDK ever exposes\n   * `getEntryScheme()` or a similar API that reliably signals a dogfood entry,\n   * that signal should be checked before `_deploymentId` here. For now only the\n   * `_deploymentId` query param fallback is implemented. Pass a custom\n   * `URLSearchParams` to inject the SDK signal at the call site without\n   * modifying this function.\n   */\n  readonly searchParams: URLSearchParams;\n}\n\n/**\n * Pure function that evaluates the 3-layer debug activation gate.\n *\n * Has no side effects. All inputs are explicit. Returns a discriminated union\n * so callers can pattern-match on `result.attach`.\n *\n * @example\n * ```ts\n * const result = evaluateDebugGate({\n *   isDebugBuild: __DEBUG_BUILD__,\n *   searchParams: new URLSearchParams(window.location.search),\n * });\n * if (result.attach) {\n *   // Proceed to load Chii client\n * }\n * ```\n */\nexport function evaluateDebugGate(input: GateInput): GateResult {\n  // Layer A — build-time gate.\n  // When false, the entire in-app entry + Chii imports are dead-code-eliminated\n  // by the bundler (tsdown/Rolldown constant folding). Release builds never\n  // contain this branch at all.\n  if (!input.isDebugBuild) {\n    return { attach: false, reason: 'build' };\n  }\n\n  // Layer B — runtime entry scheme gate.\n  // `_deploymentId` must be present and non-empty. The `intoss-private://`\n  // scheme used for dogfood entries includes this param; general user entry\n  // paths do not.\n  //\n  // Open seam (spec open question 2): if the Toss SDK exposes getEntryScheme()\n  // or similar, that should be the 1st-priority signal checked here, with\n  // `_deploymentId` as fallback. Extend this check at the call site by\n  // pre-populating `searchParams` with the SDK signal, or add an optional\n  // `entryScheme` field to `GateInput` in a later phase.\n  const deploymentId = input.searchParams.get('_deploymentId') ?? '';\n  if (deploymentId === '') {\n    return { attach: false, reason: 'entry' };\n  }\n\n  // Layer C — explicit opt-in gate.\n  // Require `debug=1` so that an operator who opens a dogfood URL by accident\n  // does not inadvertently trigger the debug surface.\n  const debugParam = input.searchParams.get('debug');\n  if (debugParam !== '1') {\n    return { attach: false, reason: 'opt-in' };\n  }\n\n  // Layer C continued — relay URL validation.\n  // `relay=<wss-url>` must be present and must use the `wss:` scheme.\n  // Plain `ws:` is rejected (no TLS). `http:`/`https:` are rejected.\n  const relayRaw = input.searchParams.get('relay') ?? '';\n  if (relayRaw === '') {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  let relayUrl: URL;\n  try {\n    relayUrl = new URL(relayRaw);\n  } catch {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  if (relayUrl.protocol !== 'wss:') {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  return { attach: true, relayUrl: relayUrl.href, deploymentId };\n}\n","/**\n * In-app Chii target injection for the debug attach flow.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n * \"MCP attach\" topology section — Phase 1 browser-side implementation.\n *\n * This module bridges the 3-layer gate result to a Chii `target.js` script\n * injection. The Chii npm package is the relay SERVER — the in-app side is\n * a plain `<script src=\"…/target.js\">` pointing at the relay host. No chii\n * npm dependency is needed here.\n */\n\nimport { checkDebugGate, type GateResult } from './index.js';\n\n/**\n * Converts a validated `wss:` relay URL into the Chii `target.js` script URL.\n *\n * Scheme is mapped `wss:` → `https:`. Host and port are preserved.\n * Pathname is set to `/target.js` regardless of the relay path.\n * Query params and hash from the relay URL are dropped — the target script\n * URL is a static asset path on the same host.\n *\n * @example\n * deriveTargetScriptUrl('wss://abc.trycloudflare.com/relay')\n * // → 'https://abc.trycloudflare.com/target.js'\n *\n * deriveTargetScriptUrl('wss://h.example.com:9100/')\n * // → 'https://h.example.com:9100/target.js'\n */\nexport function deriveTargetScriptUrl(relayUrl: string): string {\n  const u = new URL(relayUrl);\n  u.protocol = 'https:';\n  u.pathname = '/target.js';\n  u.search = '';\n  u.hash = '';\n  return u.toString();\n}\n\n/** Module-level guard against double-injection within a page lifecycle. */\nlet attached = false;\n\n/**\n * Evaluates the 3-layer debug gate and, if the gate passes, injects the Chii\n * `target.js` script into `document.head`.\n *\n * Idempotent — calling more than once is safe. The second call is a no-op if\n * a script with the same `src` is already present in the document, and the\n * module-level `attached` flag prevents redundant DOM queries after the first\n * successful injection.\n *\n * Safe to call even if `document` is somehow unavailable (defensive boundary\n * guard — in practice this always runs in a real WebView).\n *\n * @param gateResult - Optional pre-evaluated gate result for testability.\n *   Defaults to `checkDebugGate()` which reads the current page URL and the\n *   `__DEBUG_BUILD__` compile-time constant. Passing a custom value avoids\n *   the need to manipulate `window.location` in tests.\n */\nexport function maybeAttach(gateResult: GateResult = checkDebugGate()): void {\n  if (!gateResult.attach) {\n    console.debug(\n      `[@ait-co/devtools] debug attach skipped — gate blocked (reason: ${gateResult.reason})`,\n    );\n    return;\n  }\n\n  // Guard against double-injection across repeated calls.\n  if (attached) {\n    return;\n  }\n\n  // Defensive: if document is not available (unusual, but possible in some\n  // SSR-adjacent edge cases), bail silently rather than throwing.\n  if (typeof document === 'undefined') {\n    return;\n  }\n\n  const src = deriveTargetScriptUrl(gateResult.relayUrl);\n\n  // Also guard against a script with the same src already in the DOM\n  // (e.g. injected by a different code path or a page reload within SPA).\n  const existing = document.querySelector<HTMLScriptElement>(`script[src=\"${src}\"]`);\n  if (existing !== null) {\n    attached = true;\n    return;\n  }\n\n  const script = document.createElement('script');\n  script.src = src;\n  script.async = true;\n  (document.head ?? document.documentElement).appendChild(script);\n\n  attached = true;\n}\n","/**\n * @ait-co/devtools/in-app entry point.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n *\n * Phase 1 — gate + browser-side Chii target injection.\n * WebSocket relay, QR/paste UI, and AI-host MCP bin are later phases that\n * require real-device validation and are not included here.\n *\n * This thin entry reads `__DEBUG_BUILD__` and `window.location`, then calls\n * the pure {@link evaluateDebugGate} function. All testable logic lives in\n * `./gate.ts` and `./attach.ts`, not here.\n */\n\nimport { evaluateDebugGate, type GateResult } from './gate.js';\n\nexport { deriveTargetScriptUrl, maybeAttach } from './attach.js';\nexport type { GateInput, GateResult, GateResultAttach, GateResultBlocked } from './gate.js';\nexport { evaluateDebugGate } from './gate.js';\n\n/**\n * Evaluates the 3-layer debug activation gate against the current page URL.\n *\n * Returns the gate result. Callers can check `result.attach` to decide whether\n * to proceed with debug surface attachment.\n *\n * This function reads `window.location` and the `__DEBUG_BUILD__` compile-time\n * constant. It has no other side effects.\n */\nexport function checkDebugGate(): GateResult {\n  return evaluateDebugGate({\n    isDebugBuild: __DEBUG_BUILD__,\n    searchParams: new URLSearchParams(window.location.search),\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAyFA,SAAgB,kBAAkB,OAA8B;AAK9D,KAAI,CAAC,MAAM,aACT,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAS;CAa3C,MAAM,eAAe,MAAM,aAAa,IAAI,gBAAgB,IAAI;AAChE,KAAI,iBAAiB,GACnB,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAS;AAO3C,KADmB,MAAM,aAAa,IAAI,QAAQ,KAC/B,IACjB,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAU;CAM5C,MAAM,WAAW,MAAM,aAAa,IAAI,QAAQ,IAAI;AACpD,KAAI,aAAa,GACf,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAiB;CAGnD,IAAI;AACJ,KAAI;AACF,aAAW,IAAI,IAAI,SAAS;SACtB;AACN,SAAO;GAAE,QAAQ;GAAO,QAAQ;GAAiB;;AAGnD,KAAI,SAAS,aAAa,OACxB,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAiB;AAGnD,QAAO;EAAE,QAAQ;EAAM,UAAU,SAAS;EAAM;EAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC/GhE,SAAgB,sBAAsB,UAA0B;CAC9D,MAAM,IAAI,IAAI,IAAI,SAAS;AAC3B,GAAE,WAAW;AACb,GAAE,WAAW;AACb,GAAE,SAAS;AACX,GAAE,OAAO;AACT,QAAO,EAAE,UAAU;;;AAIrB,IAAI,WAAW;;;;;;;;;;;;;;;;;;AAmBf,SAAgB,YAAY,aAAyB,gBAAgB,EAAQ;AAC3E,KAAI,CAAC,WAAW,QAAQ;AACtB,UAAQ,MACN,mEAAmE,WAAW,OAAO,GACtF;AACD;;AAIF,KAAI,SACF;AAKF,KAAI,OAAO,aAAa,YACtB;CAGF,MAAM,MAAM,sBAAsB,WAAW,SAAS;AAKtD,KADiB,SAAS,cAAiC,eAAe,IAAI,IAAI,KACjE,MAAM;AACrB,aAAW;AACX;;CAGF,MAAM,SAAS,SAAS,cAAc,SAAS;AAC/C,QAAO,MAAM;AACb,QAAO,QAAQ;AACf,EAAC,SAAS,QAAQ,SAAS,iBAAiB,YAAY,OAAO;AAE/D,YAAW;;;;;;;;;;;;;;;;;;;;;;;;;;AC/Db,SAAgB,iBAA6B;AAC3C,QAAO,kBAAkB;EACvB,cAAA;EACA,cAAc,IAAI,gBAAgB,OAAO,SAAS,OAAO;EAC1D,CAAC"}

package/dist/mcp/cli.d.ts

@@ -0,0 +1,20 @@
+
+//#region src/mcp/cli.d.ts
+/**
+ * `devtools-mcp` bin entry.
+ *
+ * Single bin, two transports selected by `--mode`:
+ *   - (default, no flag) debug mode — CDP/Chii relay + cloudflared quick tunnel.
+ *     Attach a running mini-app (real Toss WebView or a browser) and read its
+ *     console + network over CDP without a human watching a phone.
+ *   - `--mode=dev` — dev mode — reads the live browser mock state from a running
+ *     Vite dev server (the devtools#130 `devtools_get_mock_state` surface).
+ *
+ * Node-only stdio process.
+ */
+type Mode = 'debug' | 'dev';
+/** Parses `--mode=<value>` / `--mode <value>` from argv; default `debug`. */
+declare function parseMode(argv: readonly string[]): Mode;
+//#endregion
+export { parseMode };
+//# sourceMappingURL=cli.d.ts.map

package/dist/mcp/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","names":[],"sources":["../../src/mcp/cli.ts"],"mappings":";;;;;;;AAsBA;;;;;;;KAHK,IAAA;;iBAGW,SAAA,CAAU,IAAA,sBAA0B,IAAA"}