heyspex 0.1.0

package/vendor/heyspex-mcp/console-fetch.mjs

@@ -0,0 +1,342 @@
+/**
+ * Console HTTP helpers — extracted from cli.mjs so the timeout / retry /
+ * error-kind classification are unit-testable without booting the full MCP
+ * stdio server.
+ *
+ * Transport recovery (recurring false `CONSOLE_UNREACHABLE` when the server is up):
+ *
+ *  1. Default timeout is 30 s; one retry on `AbortError` → `CONSOLE_TIMEOUT`.
+ *  2. On network failure (`status: 0`), try alternate loopback hosts (localhost /
+ *     127.0.0.1 / [::1]) — Windows often binds one family only.
+ *  2b. On loopback network failure, backoff-retry the same URL (Next dev restart).
+ *  3. Optional `recoverFromTransportFailure` (wired in cli.mjs to
+ *     `getDevServerStatus`) scans candidate ports; when the console is live on a
+ *     different port than `.heyspex/console-url`, retries once and heals the file.
+ *  4. When discovery finds a live server but the retry still fails →
+ *     `CONSOLE_URL_MISMATCH` (not "server down").
+ *
+ * Factory pattern matches `capture-console-client.mjs`: cli.mjs binds the real
+ * `getConsoleUrl`; tests pass stubs for both URL resolution and the fetch impl.
+ *
+ * TRANSPORT AUTH ([[HS-GD45-MCPC-TASK-mcp-cloud-auth-shared-console-resolver]]):
+ * {@link getAuthHeader} resolves an `Authorization: Bearer <token>` header
+ * (precedence: `HEYSPEX_MCP_TOKEN` env → `~/.heyspex/credentials.yaml`
+ * `mcp_token`, written by `hs mcp pair <code>`) and `makeConsoleFetch` attaches
+ * it to every outbound request — `consoleFetch` AND `postClaimEndpoint` share
+ * one transport, so both get it for free. No token resolvable → no header,
+ * exactly today's (unauthenticated) behavior against a local dev console.
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const DEFAULT_CONSOLE_TIMEOUT_MS = 30000;
+
+/** Backoff when Next dev restarts (next.config change, etc.) — ECONNREFUSED is transient. */
+export const DEV_RESTART_RETRY_DELAYS_MS = [1500, 2500, 4000];
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Detect AbortError from a thrown fetch error. Covers the standard
+ * `AbortError` name and the substring fallback some runtimes use
+ * ("This operation was aborted").
+ */
+export function isAbortError(err) {
+  if (!err) return false;
+  if (err.name === 'AbortError') return true;
+  const msg = typeof err.message === 'string' ? err.message : String(err);
+  return /aborted/i.test(msg);
+}
+
+/**
+ * Same port/path, alternate loopback hosts. Mirrors the probe rationale in
+ * scripts/dev-server-status.mjs (Next may listen on ::1 while fetch tried IPv4).
+ */
+export function loopbackHostVariants(urlString) {
+  let base;
+  try {
+    base = new URL(urlString);
+  } catch {
+    return [urlString];
+  }
+  const alts = new Set([base.hostname]);
+  if (base.hostname === 'localhost' || base.hostname === '127.0.0.1' || base.hostname === '::1') {
+    alts.add('localhost');
+    alts.add('127.0.0.1');
+    alts.add('::1');
+  }
+  const out = [];
+  for (const host of alts) {
+    const u = new URL(base.href);
+    u.hostname = host;
+    out.push(u.href);
+  }
+  return [...new Set(out)];
+}
+
+function isLoopbackUrl(urlString) {
+  try {
+    const { hostname } = new URL(urlString);
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Rewrite the origin of `urlString` to match `originUrl` (port-discovery heal).
+ */
+export function rewriteUrlOrigin(urlString, originUrl) {
+  const target = new URL(urlString);
+  const origin = new URL(originUrl);
+  target.protocol = origin.protocol;
+  target.hostname = origin.hostname;
+  target.port = origin.port;
+  return target.href;
+}
+
+/**
+ * Resolve the outbound `Authorization` header, or `{}` when no token
+ * resolves (no header at all — matches today's unauthenticated behavior
+ * against a local dev console). Precedence: `HEYSPEX_MCP_TOKEN` env →
+ * `~/.heyspex/credentials.yaml` `mcp_token`. Injectable `env`/`homeDir` for
+ * tests; never throws (an unreadable credentials file is just "no token").
+ */
+export function getAuthHeader({ env = process.env, homeDir = homedir() } = {}) {
+  const envToken = env.HEYSPEX_MCP_TOKEN?.trim();
+  if (envToken) return { Authorization: `Bearer ${envToken}` };
+
+  try {
+    const raw = readFileSync(join(homeDir, '.heyspex', 'credentials.yaml'), 'utf8');
+    const match = raw.match(/^mcp_token:\s*["']?([^"'\r\n#]+)/m);
+    const token = match?.[1]?.trim();
+    if (token) return { Authorization: `Bearer ${token}` };
+  } catch {
+    // Missing file, missing key, or unreadable — no credentials-file token.
+  }
+  return {};
+}
+
+/**
+ * Build a console-fetch client bound to the given URL resolver + fetch impl.
+ *
+ * @param {object} deps
+ * @param {() => string} deps.getConsoleUrl
+ * @param {typeof fetch} [deps.fetchImpl]
+ * @param {number} [deps.defaultTimeoutMs]
+ * @param {(failedResult: object, ctx: { url: string, init: object, timeoutMs: number }) => Promise<{ retryUrl?: string, reason?: string, healedUrl?: string, discoveryHealed?: boolean, devServerStatus?: object } | null | undefined>} [deps.recoverFromTransportFailure]
+ * @param {() => object} [deps.getAuthHeader] Resolves the outbound Authorization header (default: {@link getAuthHeader}).
+ */
+export function makeConsoleFetch({
+  getConsoleUrl,
+  fetchImpl = fetch,
+  defaultTimeoutMs = DEFAULT_CONSOLE_TIMEOUT_MS,
+  recoverFromTransportFailure,
+  getAuthHeader: getAuthHeaderDep = getAuthHeader,
+}) {
+  async function attempt(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetchImpl(url, { ...init, signal: controller.signal });
+      const text = await response.text();
+      let parsed = null;
+      try {
+        parsed = text ? JSON.parse(text) : null;
+      } catch {
+        parsed = { raw: text };
+      }
+      return { ok: response.ok, status: response.status, body: parsed, url };
+    } catch (err) {
+      const errorKind = isAbortError(err) ? 'timeout' : 'network';
+      return {
+        ok: false,
+        status: 0,
+        body: null,
+        url,
+        error: err?.message || String(err),
+        errorKind,
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function recoverNetworkFailure(result, ctx) {
+    const { url, init, timeoutMs } = ctx;
+
+    for (const alt of loopbackHostVariants(url)) {
+      if (alt === url) continue;
+      const retry = await attempt(alt, init, timeoutMs);
+      if (retry.ok) {
+        return {
+          ...retry,
+          recoveredVia: 'loopback_host',
+          attemptedUrl: url,
+        };
+      }
+    }
+
+    // Next.js dev restart window (e.g. next.config.mjs change) — loopback only, brief ECONNREFUSED.
+    if (isLoopbackUrl(url)) {
+      let last = result;
+      for (const delay of DEV_RESTART_RETRY_DELAYS_MS) {
+        await sleep(delay);
+        const retry = await attempt(url, init, timeoutMs);
+        if (retry.ok) {
+          return {
+            ...retry,
+            recoveredVia: 'dev_restart',
+            attemptedUrl: url,
+          };
+        }
+        last = retry;
+        if (retry.errorKind === 'timeout') break;
+      }
+      result = last;
+    }
+
+    if (!recoverFromTransportFailure) return result;
+
+    let recovery;
+    try {
+      recovery = await recoverFromTransportFailure(result, ctx);
+    } catch {
+      return result;
+    }
+    if (!recovery) return result;
+
+    if (recovery.retryUrl && recovery.retryUrl !== url) {
+      const retry = await attempt(recovery.retryUrl, init, timeoutMs);
+      if (retry.ok) {
+        return {
+          ...retry,
+          recoveredVia: recovery.reason || 'port_discovery',
+          attemptedUrl: url,
+          ...(recovery.discoveryHealed
+            ? { discoveryHealed: true, healedUrl: recovery.healedUrl || recovery.retryUrl }
+            : {}),
+        };
+      }
+      return {
+        ...result,
+        urlMismatch: true,
+        suggestedUrl: recovery.healedUrl || recovery.retryUrl,
+        devServerStatus: recovery.devServerStatus,
+        discoveryAttempted: recovery.retryUrl,
+        discoveryHealed: recovery.discoveryHealed === true,
+      };
+    }
+
+    if (recovery.devServerStatus?.running) {
+      const live = recovery.devServerStatus.servers?.find((s) => s.probe === 'console');
+      return {
+        ...result,
+        urlMismatch: true,
+        suggestedUrl: live?.url,
+        devServerStatus: recovery.devServerStatus,
+      };
+    }
+
+    return result;
+  }
+
+  async function withRetry(url, init, timeoutMs, { retryOnTimeout = true } = {}) {
+    let result = await attempt(url, init, timeoutMs);
+    if (!result.ok && result.errorKind === 'timeout' && retryOnTimeout) {
+      result = await attempt(url, init, timeoutMs);
+    }
+    if (result.ok) return result;
+    if (result.errorKind === 'network') {
+      result = await recoverNetworkFailure(result, { url, init, timeoutMs });
+    }
+    return result;
+  }
+
+  /**
+   * POST/DELETE/GET against `/api/specs/:id/claim`.
+   */
+  async function postClaimEndpoint(method, specId, bodyJson) {
+    const consoleUrl = getConsoleUrl();
+    const url = `${consoleUrl}/api/specs/${encodeURIComponent(specId)}/claim`;
+    const init = {
+      method,
+      headers: { 'content-type': 'application/json', ...getAuthHeaderDep() },
+    };
+    if (bodyJson !== undefined) {
+      init.body = JSON.stringify(bodyJson);
+    }
+    return withRetry(url, init, defaultTimeoutMs);
+  }
+
+  /**
+   * Generic fetch helper for console API with timeout + JSON parsing + 1 retry
+   * on AbortError. Returns `{ ok, status, body, url, error?, errorKind? }`.
+   *
+   * `options.retryOnTimeout: false` opts a NON-IDEMPOTENT call (a create) out
+   * of the blind timeout-retry against a REMOTE console ([[HS-2FQY]]): the
+   * server-side Idempotency-Key dedup ([[HS-70TD-DIAG]]) lives in a
+   * per-process in-memory registry, so on a serverless deployment
+   * (app.heyspex.com) the retry can land on a DIFFERENT instance and mint a
+   * second spec id for the same logical create. Against a loopback console
+   * the retry is kept — one dev process, the registry replays reliably.
+   */
+  async function consoleFetch(path, options = {}) {
+    const consoleUrl = getConsoleUrl();
+    const url = `${consoleUrl}${path}`;
+    const init = {
+      method: options.method || 'GET',
+      headers: { 'content-type': 'application/json', ...getAuthHeaderDep(), ...options.headers },
+    };
+    if (options.body !== undefined) {
+      init.body = typeof options.body === 'string' ? options.body : JSON.stringify(options.body);
+    }
+    const timeoutMs = options.timeout || defaultTimeoutMs;
+    const retryOnTimeout = options.retryOnTimeout === false ? isLoopbackUrl(url) : true;
+    return withRetry(url, init, timeoutMs, { retryOnTimeout });
+  }
+
+  return { postClaimEndpoint, consoleFetch };
+}
+
+/**
+ * Map a failed transport result to an agent-facing error code. Splits
+ * timeout (server up but slow / cold-compiling) from unreachable (server
+ * actually down). Caller supplies the HTTP-error fallback used when the
+ * transport succeeded but the console returned a 4xx/5xx.
+ */
+export function consoleErrorCode(result, httpFailureCode) {
+  if (result.urlMismatch) return 'CONSOLE_URL_MISMATCH';
+  if (result.errorKind === 'timeout') return 'CONSOLE_TIMEOUT';
+  if (result.status === 0) return 'CONSOLE_UNREACHABLE';
+  return httpFailureCode;
+}
+
+/**
+ * Agent-facing message for a failed transport result. Tailored per
+ * error kind so the agent can act: retry on timeout vs start the dev
+ * server on network error.
+ */
+export function consoleErrorMessage(result, httpFailureMessage) {
+  if (result.urlMismatch) {
+    const live =
+      result.suggestedUrl
+      || result.devServerStatus?.servers?.find((s) => s.probe === 'console')?.url;
+    const healNote = result.discoveryHealed
+      ? ' Updated `.heyspex/console-url` — retry the tool call.'
+      : ' Call `heyspex_dev_server_status` and retry — do NOT hand-write vault files.';
+    return live
+      ? `Spex-console dev server is running at ${live} but MCP tried ${result.url}.${healNote}`
+      : `Spex-console dev server appears to be running on another port than ${result.url}.${healNote}`;
+  }
+  if (result.errorKind === 'timeout') {
+    return `Console at ${result.url} timed out (retried once). It may be cold-compiling or under load — retry shortly. Do not conclude the dev server is down.`;
+  }
+  if (result.status === 0) {
+    return `Could not reach spex-console at ${result.url}: ${result.error}. Call heyspex_dev_server_status before concluding the server is down.`;
+  }
+  return httpFailureMessage;
+}