@ait-co/devtools 0.1.144 → 0.2.1

package/dist/relay-url-store-xmUuTjXA.js

@@ -1,122 +0,0 @@
-import { nearestPackageJsonDir } from "./relay-secret-store-DKxs7zwq.js";
-import { join } from "node:path";
-//#region src/mcp/relay-url-store.ts
-/**
-* Project-local ephemeral URL store (#424).
-*
-* Environment-2 ("AITC Sandbox PWA") cold-start requires two ephemeral URLs:
-*   - `relayBaseUrl` — the CDP relay's https base (was `AIT_RELAY_BASE_URL`)
-*   - `tunnelBaseUrl` — the app's https tunnel base (was `AIT_TUNNEL_BASE_URL`)
-*
-* Quick-tunnel URLs change every run. Previously the user had to copy-paste them
-* into env vars on every cold-start — a single typo silently broke attach. This
-* module replaces that manual hand-off with a file-based discovery pattern that
-* exactly mirrors the `.ait_relay` TOTP-secret store (relay-secret-store.ts).
-*
-* Two surfaces, intentionally split by who is allowed to write:
-*
-*   - {@link writeRelayUrls} — WRITE path, called ONLY from the unplugin
-*     (env-2 tunnel boot). Writes JSON to `<projectRoot>/.ait_urls` (0600) on
-*     every boot (`flag: 'w'` — overwrite). A single file — no directory is
-*     created.
-*
-*   - {@link readRelayUrls} — READ-ONLY path, called from the MCP daemon as a
-*     fallback when `AIT_RELAY_BASE_URL`/`AIT_TUNNEL_BASE_URL` are not set. It
-*     NEVER writes, chmods, or creates anything: it only reads an existing
-*     `.ait_urls`. On any failure (missing file / bad JSON / wrong shape) it
-*     returns `null` silently, letting the downstream assertion be the single
-*     fail-fast.
-*
-*   - {@link deleteRelayUrls} — called from the unplugin `cleanup()` on
-*     teardown (via `void deleteRelayUrls(...)`). A stale `.ait_urls` pointing
-*     at a dead tunnel would cause the MCP daemon to attempt a doomed attach on
-*     the next cold-start — deletion is non-negotiable. Silently swallows all
-*     errors.
-*
-* Design note: the env vars (`AIT_RELAY_BASE_URL`, `AIT_TUNNEL_BASE_URL`) are
-* PRESERVED as operator overrides. The file is the fallback — env wins.
-*
-* Why `nearestPackageJsonDir` instead of `process.cwd()`: see relay-secret-store.ts.
-* The unplugin (writer) and the MCP daemon (reader) both anchor to the nearest
-* package.json from their respective `projectRoot` inputs, ensuring both sides
-* find the same file.
-*
-* SECRET-HANDLING: `relayBaseUrl` and `tunnelBaseUrl` carry the relay/tunnel host
-* — same sensitivity class as `.ait_relay`. The raw URL values, partial values,
-* and the resolved file path MUST NOT appear in any log, error message, stdout,
-* stderr, or assertion output anywhere in this module or at its call sites.
-* Only boolean pass/fail signals are safe to surface. The file is written mode
-* 0600.
-*/
-/** Project-local ephemeral URL file name (single file, not a directory). */
-const URLS_FILE_NAME = ".ait_urls";
-/**
-* Absolute path to the project-local `.ait_urls` file for a given start
-* directory (resolved against the nearest package.json directory).
-*
-* Exported so tests can compute the expected path without duplicating the
-* resolution logic.
-*/
-function urlsFilePath(start, existsSyncFn) {
-	return join(nearestPackageJsonDir(start, existsSyncFn), URLS_FILE_NAME);
-}
-/**
-* Reads `<projectRoot>/.ait_urls` and returns the stored URLs, or `null` on
-* any failure.
-*
-* Strictly READ-ONLY: only `existsSync` + `readFileSync`. Never writes,
-* chmods, or creates files/directories.
-*
-* Returns `null` (silently, no throw, no log) on:
-*   - missing `projectRoot`
-*   - missing `.ait_urls` file
-*   - unreadable file (permissions, transient FS error)
-*   - invalid JSON
-*   - wrong shape (non-object, non-string values)
-*
-* Trims string values before returning. Ignores non-string fields.
-*
-* SECRET-HANDLING: URL values and the file path are never logged.
-*/
-async function readRelayUrls(deps) {
-	const { projectRoot, fs: fsDep, existsSync: existsSyncDep } = deps ?? {};
-	if (projectRoot === void 0) return null;
-	const fs = fsDep ?? await import("node:fs");
-	const filePath = urlsFilePath(projectRoot, existsSyncDep ?? fs.existsSync);
-	if (!fs.existsSync(filePath)) return null;
-	let raw;
-	try {
-		raw = fs.readFileSync(filePath, "utf8");
-	} catch {
-		return null;
-	}
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		return null;
-	}
-	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
-	const obj = parsed;
-	const result = {};
-	const relay = obj.relayBaseUrl;
-	if (typeof relay === "string") {
-		const trimmed = relay.trim();
-		if (trimmed !== "") result.relayBaseUrl = trimmed;
-	}
-	const relayLocal = obj.relayLocalUrl;
-	if (typeof relayLocal === "string") {
-		const trimmed = relayLocal.trim();
-		if (trimmed !== "") result.relayLocalUrl = trimmed;
-	}
-	const tunnel = obj.tunnelBaseUrl;
-	if (typeof tunnel === "string") {
-		const trimmed = tunnel.trim();
-		if (trimmed !== "") result.tunnelBaseUrl = trimmed;
-	}
-	return result;
-}
-//#endregion
-export { readRelayUrls };
-
-//# sourceMappingURL=relay-url-store-xmUuTjXA.js.map

package/dist/relay-url-store-xmUuTjXA.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"relay-url-store-xmUuTjXA.js","names":[],"sources":["../src/mcp/relay-url-store.ts"],"sourcesContent":["/**\n * Project-local ephemeral URL store (#424).\n *\n * Environment-2 (\"AITC Sandbox PWA\") cold-start requires two ephemeral URLs:\n *   - `relayBaseUrl` — the CDP relay's https base (was `AIT_RELAY_BASE_URL`)\n *   - `tunnelBaseUrl` — the app's https tunnel base (was `AIT_TUNNEL_BASE_URL`)\n *\n * Quick-tunnel URLs change every run. Previously the user had to copy-paste them\n * into env vars on every cold-start — a single typo silently broke attach. This\n * module replaces that manual hand-off with a file-based discovery pattern that\n * exactly mirrors the `.ait_relay` TOTP-secret store (relay-secret-store.ts).\n *\n * Two surfaces, intentionally split by who is allowed to write:\n *\n *   - {@link writeRelayUrls} — WRITE path, called ONLY from the unplugin\n *     (env-2 tunnel boot). Writes JSON to `<projectRoot>/.ait_urls` (0600) on\n *     every boot (`flag: 'w'` — overwrite). A single file — no directory is\n *     created.\n *\n *   - {@link readRelayUrls} — READ-ONLY path, called from the MCP daemon as a\n *     fallback when `AIT_RELAY_BASE_URL`/`AIT_TUNNEL_BASE_URL` are not set. It\n *     NEVER writes, chmods, or creates anything: it only reads an existing\n *     `.ait_urls`. On any failure (missing file / bad JSON / wrong shape) it\n *     returns `null` silently, letting the downstream assertion be the single\n *     fail-fast.\n *\n *   - {@link deleteRelayUrls} — called from the unplugin `cleanup()` on\n *     teardown (via `void deleteRelayUrls(...)`). A stale `.ait_urls` pointing\n *     at a dead tunnel would cause the MCP daemon to attempt a doomed attach on\n *     the next cold-start — deletion is non-negotiable. Silently swallows all\n *     errors.\n *\n * Design note: the env vars (`AIT_RELAY_BASE_URL`, `AIT_TUNNEL_BASE_URL`) are\n * PRESERVED as operator overrides. The file is the fallback — env wins.\n *\n * Why `nearestPackageJsonDir` instead of `process.cwd()`: see relay-secret-store.ts.\n * The unplugin (writer) and the MCP daemon (reader) both anchor to the nearest\n * package.json from their respective `projectRoot` inputs, ensuring both sides\n * find the same file.\n *\n * SECRET-HANDLING: `relayBaseUrl` and `tunnelBaseUrl` carry the relay/tunnel host\n * — same sensitivity class as `.ait_relay`. The raw URL values, partial values,\n * and the resolved file path MUST NOT appear in any log, error message, stdout,\n * stderr, or assertion output anywhere in this module or at its call sites.\n * Only boolean pass/fail signals are safe to surface. The file is written mode\n * 0600.\n */\n\nimport { join } from 'node:path';\nimport { nearestPackageJsonDir } from './relay-secret-store.js';\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/** Project-local ephemeral URL file name (single file, not a directory). */\nexport const URLS_FILE_NAME = '.ait_urls';\n\n// ---------------------------------------------------------------------------\n// Dependency injection surfaces\n// ---------------------------------------------------------------------------\n\n/** Minimal fs subset needed by {@link writeRelayUrls} — injectable for tests. */\nexport interface RelayUrlWriteFs {\n  writeFileSync(path: string, data: string, options: { mode: number; flag: string }): void;\n  existsSync(path: string): boolean;\n}\n\n/** Minimal fs subset needed by {@link readRelayUrls} — injectable for tests. */\nexport interface RelayUrlReadFs {\n  existsSync(path: string): boolean;\n  readFileSync(path: string, encoding: BufferEncoding): string;\n}\n\n/** Minimal fs subset needed by {@link deleteRelayUrls} — injectable for tests. */\nexport interface RelayUrlDeleteFs {\n  existsSync(path: string): boolean;\n  unlinkSync(path: string): void;\n}\n\n// ---------------------------------------------------------------------------\n// Path helper\n// ---------------------------------------------------------------------------\n\n/**\n * Absolute path to the project-local `.ait_urls` file for a given start\n * directory (resolved against the nearest package.json directory).\n *\n * Exported so tests can compute the expected path without duplicating the\n * resolution logic.\n */\nexport function urlsFilePath(start: string, existsSyncFn: (path: string) => boolean): string {\n  return join(nearestPackageJsonDir(start, existsSyncFn), URLS_FILE_NAME);\n}\n\n// ---------------------------------------------------------------------------\n// WRITE path (unplugin only) — overwrite on every boot\n// ---------------------------------------------------------------------------\n\nexport interface WriteRelayUrlsDeps {\n  /** Project root (typically Vite `server.config.root`). */\n  projectRoot: string;\n  /**\n   * The CDP relay's https base URL (same value as `AIT_RELAY_BASE_URL`).\n   * Omit when the relay was not started (e.g. `cdp:false`).\n   * SECRET-HANDLING: never log this value.\n   */\n  relayBaseUrl?: string;\n  /**\n   * The CDP relay's LOCAL http base URL (`http://127.0.0.1:<relay-port>`).\n   * Set when `cdp: true` and the local relay port is known. Used by the MCP\n   * daemon's `bootExternalRelayFamily` to build the Chii inspector URL against\n   * the local relay rather than the cloudflare tunnel, so front_end page load\n   * and the client WS leg do not traverse the tunnel (issue #530).\n   * SECRET-HANDLING: local loopback URL — no tunnel host, safe to surface.\n   */\n  relayLocalUrl?: string;\n  /**\n   * The app tunnel's https base URL (same value as `AIT_TUNNEL_BASE_URL`).\n   * Omit when no tunnel URL is available.\n   * SECRET-HANDLING: never log this value.\n   */\n  tunnelBaseUrl?: string;\n  /** Filesystem operations. Defaults to node:fs synchronous functions. */\n  fs?: RelayUrlWriteFs;\n  /** existsSync used to resolve the nearest package.json directory. Defaults to node:fs. */\n  existsSync?: (path: string) => boolean;\n}\n\n/**\n * Writes `{ relayBaseUrl, tunnelBaseUrl }` (omitting absent keys) to\n * `<projectRoot>/.ait_urls` (mode 0600). Uses `flag: 'w'` (overwrite) because\n * URLs are ephemeral — a fresh URL replaces the previous one on every boot.\n *\n * Unlike the `.ait_relay` secret store this does NOT use `O_EXCL` (`'wx'`):\n * there is no race concern here (only the unplugin writes this file) and the\n * URL must be fresh on every cold-start.\n *\n * Called ONLY from the unplugin (env-2 tunnel boot). The MCP daemon uses\n * {@link readRelayUrls} (read-only) — it must never write.\n *\n * SECRET-HANDLING: URL values are never logged.\n */\nexport async function writeRelayUrls(deps: WriteRelayUrlsDeps): Promise<void> {\n  const { projectRoot, relayBaseUrl, tunnelBaseUrl, fs: fsDep, existsSync: existsSyncDep } = deps;\n\n  const fs: RelayUrlWriteFs = fsDep ?? (await import('node:fs'));\n  const existsSyncFn: (path: string) => boolean = existsSyncDep ?? fs.existsSync;\n\n  const filePath = urlsFilePath(projectRoot, existsSyncFn);\n\n  // Build the payload — omit keys whose values are absent.\n  const payload: { relayBaseUrl?: string; relayLocalUrl?: string; tunnelBaseUrl?: string } = {};\n  if (typeof relayBaseUrl === 'string' && relayBaseUrl !== '') {\n    payload.relayBaseUrl = relayBaseUrl;\n  }\n  const { relayLocalUrl } = deps;\n  if (typeof relayLocalUrl === 'string' && relayLocalUrl !== '') {\n    payload.relayLocalUrl = relayLocalUrl;\n  }\n  if (typeof tunnelBaseUrl === 'string' && tunnelBaseUrl !== '') {\n    payload.tunnelBaseUrl = tunnelBaseUrl;\n  }\n\n  // SECRET-HANDLING: JSON content (which includes URL values) is written to\n  // the file only — never to any log, stdout, or stderr.\n  const data = JSON.stringify(payload);\n\n  // Overwrite on every boot (`flag: 'w'`) — URLs are ephemeral.\n  fs.writeFileSync(filePath, data, { mode: 0o600, flag: 'w' });\n}\n\n// ---------------------------------------------------------------------------\n// READ-ONLY path (daemon only) — never writes, chmods, or creates anything\n// ---------------------------------------------------------------------------\n\nexport interface ReadRelayUrlsDeps {\n  /** Project root supplied per-debug-session. When omitted, returns `null`. */\n  projectRoot?: string;\n  /** Read-only filesystem operations. Defaults to node:fs (existsSync + readFileSync). */\n  fs?: RelayUrlReadFs;\n  /** existsSync used to resolve the nearest package.json directory. Defaults to node:fs. */\n  existsSync?: (path: string) => boolean;\n}\n\n/**\n * Reads `<projectRoot>/.ait_urls` and returns the stored URLs, or `null` on\n * any failure.\n *\n * Strictly READ-ONLY: only `existsSync` + `readFileSync`. Never writes,\n * chmods, or creates files/directories.\n *\n * Returns `null` (silently, no throw, no log) on:\n *   - missing `projectRoot`\n *   - missing `.ait_urls` file\n *   - unreadable file (permissions, transient FS error)\n *   - invalid JSON\n *   - wrong shape (non-object, non-string values)\n *\n * Trims string values before returning. Ignores non-string fields.\n *\n * SECRET-HANDLING: URL values and the file path are never logged.\n */\nexport async function readRelayUrls(deps?: ReadRelayUrlsDeps): Promise<{\n  relayBaseUrl?: string;\n  relayLocalUrl?: string;\n  tunnelBaseUrl?: string;\n} | null> {\n  const { projectRoot, fs: fsDep, existsSync: existsSyncDep } = deps ?? {};\n\n  if (projectRoot === undefined) {\n    return null;\n  }\n\n  const fs: RelayUrlReadFs = fsDep ?? (await import('node:fs'));\n  const existsSyncFn: (path: string) => boolean = existsSyncDep ?? fs.existsSync;\n\n  const filePath = urlsFilePath(projectRoot, existsSyncFn);\n\n  if (!fs.existsSync(filePath)) {\n    return null;\n  }\n\n  let raw: string;\n  try {\n    raw = fs.readFileSync(filePath, 'utf8');\n  } catch {\n    // Unreadable file — silent no-op, let the downstream assert be the fail-fast.\n    // SECRET-HANDLING: the error and path are not surfaced.\n    return null;\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch {\n    // Invalid JSON — silent no-op.\n    return null;\n  }\n\n  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n    return null;\n  }\n\n  const obj = parsed as Record<string, unknown>;\n  const result: { relayBaseUrl?: string; relayLocalUrl?: string; tunnelBaseUrl?: string } = {};\n\n  const relay = obj.relayBaseUrl;\n  if (typeof relay === 'string') {\n    const trimmed = relay.trim();\n    if (trimmed !== '') result.relayBaseUrl = trimmed;\n  }\n\n  const relayLocal = obj.relayLocalUrl;\n  if (typeof relayLocal === 'string') {\n    const trimmed = relayLocal.trim();\n    if (trimmed !== '') result.relayLocalUrl = trimmed;\n  }\n\n  const tunnel = obj.tunnelBaseUrl;\n  if (typeof tunnel === 'string') {\n    const trimmed = tunnel.trim();\n    if (trimmed !== '') result.tunnelBaseUrl = trimmed;\n  }\n\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// DELETE path (unplugin cleanup only)\n// ---------------------------------------------------------------------------\n\nexport interface DeleteRelayUrlsDeps {\n  /** Project root. */\n  projectRoot: string;\n  /** Filesystem operations. Defaults to node:fs (existsSync + unlinkSync). */\n  fs?: RelayUrlDeleteFs;\n  /** existsSync used to resolve the nearest package.json directory. */\n  existsSync?: (path: string) => boolean;\n}\n\n/**\n * Removes `<projectRoot>/.ait_urls` if present. Silently swallows ENOENT and\n * any other error so cleanup always succeeds.\n *\n * Called ONLY from the unplugin's `cleanup()` on `httpServer 'close'` + signals\n * (via `void deleteRelayUrls(...)`). A stale `.ait_urls` pointing at a dead\n * tunnel would cause the MCP daemon to attempt a doomed attach on the next\n * cold-start — deletion is non-negotiable.\n *\n * SECRET-HANDLING: the file path is never logged.\n */\nexport async function deleteRelayUrls(deps: DeleteRelayUrlsDeps): Promise<void> {\n  const { projectRoot, fs: fsDep, existsSync: existsSyncDep } = deps;\n\n  const fs: RelayUrlDeleteFs = fsDep ?? (await import('node:fs'));\n  const existsSyncFn: (path: string) => boolean = existsSyncDep ?? fs.existsSync;\n\n  const filePath = urlsFilePath(projectRoot, existsSyncFn);\n\n  try {\n    if (fs.existsSync(filePath)) {\n      fs.unlinkSync(filePath);\n    }\n  } catch {\n    // Swallow ENOENT and any other error — cleanup is best-effort.\n    // SECRET-HANDLING: the path is not logged.\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwDA,MAAa,iBAAiB;;;;;;;;AAmC9B,SAAgB,aAAa,OAAe,cAAiD;AAC3F,QAAO,KAAK,sBAAsB,OAAO,aAAa,EAAE,eAAe;;;;;;;;;;;;;;;;;;;;AA+GzE,eAAsB,cAAc,MAI1B;CACR,MAAM,EAAE,aAAa,IAAI,OAAO,YAAY,kBAAkB,QAAQ,EAAE;AAExE,KAAI,gBAAgB,KAAA,EAClB,QAAO;CAGT,MAAM,KAAqB,SAAU,MAAM,OAAO;CAGlD,MAAM,WAAW,aAAa,aAFkB,iBAAiB,GAAG,WAEZ;AAExD,KAAI,CAAC,GAAG,WAAW,SAAS,CAC1B,QAAO;CAGT,IAAI;AACJ,KAAI;AACF,QAAM,GAAG,aAAa,UAAU,OAAO;SACjC;AAGN,SAAO;;CAGT,IAAI;AACJ,KAAI;AACF,WAAS,KAAK,MAAM,IAAI;SAClB;AAEN,SAAO;;AAGT,KAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,MAAM,QAAQ,OAAO,CACxE,QAAO;CAGT,MAAM,MAAM;CACZ,MAAM,SAAoF,EAAE;CAE5F,MAAM,QAAQ,IAAI;AAClB,KAAI,OAAO,UAAU,UAAU;EAC7B,MAAM,UAAU,MAAM,MAAM;AAC5B,MAAI,YAAY,GAAI,QAAO,eAAe;;CAG5C,MAAM,aAAa,IAAI;AACvB,KAAI,OAAO,eAAe,UAAU;EAClC,MAAM,UAAU,WAAW,MAAM;AACjC,MAAI,YAAY,GAAI,QAAO,gBAAgB;;CAG7C,MAAM,SAAS,IAAI;AACnB,KAAI,OAAO,WAAW,UAAU;EAC9B,MAAM,UAAU,OAAO,MAAM;AAC7B,MAAI,YAAY,GAAI,QAAO,gBAAgB;;AAG7C,QAAO"}