heyspex 0.1.0 → 0.2.0

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

@@ -0,0 +1,166 @@
+// Console HTTP transport shared by every tool that talks to the spex-console
+// API: fetch wrappers, transport-failure recovery, and the controlOk/controlError
+// result envelopes. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import {
+  consoleErrorCode,
+  consoleErrorMessage,
+  getAuthHeader,
+  makeConsoleFetch,
+  resolveConsoleReliance,
+  rewriteUrlOrigin,
+} from './console-fetch.mjs';
+import { effectiveConsoleUrl, getConfig } from './mcp-config.mjs';
+import { contextAuthHeader } from './request-context.mjs';
+import { pathToFileURL } from 'node:url';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { PACKAGE_ROOT } from './package-root.mjs';
+import { resolveCodeRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+
+// scripts/dev-server-status.mjs is a CODE-repo artifact that ships with this
+// package — since the repo split (2026-08-31) the vault root no longer holds
+// it, so resolve it relative to THIS file's checkout first and fall back to
+// the vault root only for pre-split layouts where they were the same repo.
+// `HS_PKG_ROOT` wins when set (same precedence as dev-tools.mjs's
+// CHECKOUT_ROOT / plan-review.mjs's resolveCodeAuditRoots).
+const CHECKOUT_ROOT = resolveCodeRoot({ packageRoot: PACKAGE_ROOT });
+
+function resolveDevServerStatusScript(vaultRoot) {
+  const local = join(CHECKOUT_ROOT, 'scripts', 'dev-server-status.mjs');
+  return existsSync(local) ? local : join(vaultRoot, 'scripts', 'dev-server-status.mjs');
+}
+
+/**
+ * True when the console URL was set by deliberate, explicit operator intent
+ * rather than resolved by discovery/default ([[HS-WP6O-AP0X-DIAG-console-
+ * transport-self-heals-an]]). `HEYSPEX_CONSOLE_URL` is today's concrete case;
+ * an explicit `--console` flag on a future caller (e.g. the hs chat front,
+ * [[HS-F7N3-NYPR-EPIC-the-powershell-front-hs-chat]]) is expected to set this
+ * same env var before invoking the transport rather than inventing a second
+ * override channel — that keeps this one check authoritative. Injectable
+ * `env` for tests.
+ */
+export function isExplicitConsoleOverride({ env = process.env } = {}) {
+  return Boolean(env.HEYSPEX_CONSOLE_URL?.trim());
+}
+
+// Console HTTP transport — extracted to `console-fetch.mjs` so timeout/retry
+// behavior is unit-testable. On network failure, port-scan recovery heals
+// stale `.heyspex/console-url` drift ([[HS-EPIC-PT8A]] follow-on).
+export async function recoverConsoleTransportFailure(_failedResult, { url }) {
+  // Explicit override ([[HS-WP6O-AP0X-DIAG]]): an unreachable, deliberately
+  // configured console URL is NOT a stale lockfile. Fail closed here — return
+  // null so the caller reports CONSOLE_UNREACHABLE against the URL the
+  // operator asked for — and never port-scan/discover a DIFFERENT console
+  // (a real dev server on another port is not what was requested, and
+  // writing to it silently is exactly the bug this guards against).
+  if (isExplicitConsoleOverride()) return null;
+
+  const { vaultRoot } = getConfig();
+  // Local-dev recovery ONLY ([[HS-9R6S-N8VP-DIAG]]). Port-scanning for a local
+  // dev server and WRITING `.heyspex/console-url` is how a stale localhost
+  // pointer is born and made sticky: in cloud reliance one network blip would
+  // silently reroute every later call to this machine. Unknown reliance keeps
+  // today's fail-open behavior; only a resolved `cloud` skips recovery.
+  try {
+    if ((await resolveConsoleReliance()) === 'cloud') return null;
+  } catch {
+    // Mode unresolvable — fall through to the legacy behavior.
+  }
+  try {
+    const coreUrl = pathToFileURL(resolveDevServerStatusScript(vaultRoot)).href;
+    const mod = await import(coreUrl);
+    const status = await mod.getDevServerStatus({ vaultRoot });
+    if (!status.running) return { devServerStatus: status };
+    const live = status.servers.find((s) => s.probe === 'console');
+    if (!live?.url) return { devServerStatus: status };
+    const retryUrl = rewriteUrlOrigin(url, live.url);
+    let attemptedOrigin;
+    try {
+      attemptedOrigin = new URL(url).origin;
+    } catch {
+      attemptedOrigin = url;
+    }
+    if (retryUrl === url || new URL(retryUrl).origin === attemptedOrigin) {
+      return { devServerStatus: status };
+    }
+    let discoveryHealed = false;
+    if (typeof mod.writeConsoleUrlFile === 'function') {
+      mod.writeConsoleUrlFile(vaultRoot, live.url);
+      discoveryHealed = true;
+    }
+    return {
+      retryUrl,
+      reason: 'port_discovery',
+      healedUrl: live.url,
+      discoveryHealed,
+      devServerStatus: status,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function enrichConsoleFailurePayload(result, base) {
+  return {
+    ...base,
+    ...(result.devServerStatus ? { dev_server_status: result.devServerStatus } : {}),
+    ...(result.suggestedUrl ? { suggested_console_url: result.suggestedUrl } : {}),
+    ...(result.discoveryHealed ? { discovery_healed: true } : {}),
+    ...(result.recoveredVia ? { recovered_via: result.recoveredVia } : {}),
+  };
+}
+
+export async function enrichConsoleFailurePayloadAsync(result, base) {
+  const payload = enrichConsoleFailurePayload(result, base);
+  if (
+    payload.dev_server_status
+    || (base.error !== 'CONSOLE_UNREACHABLE' && base.error !== 'CONSOLE_URL_MISMATCH')
+  ) {
+    return payload;
+  }
+  try {
+    const { vaultRoot } = getConfig();
+    const coreUrl = pathToFileURL(resolveDevServerStatusScript(vaultRoot)).href;
+    const mod = await import(coreUrl);
+    payload.dev_server_status = await mod.getDevServerStatus({ vaultRoot });
+    if (payload.dev_server_status?.running) {
+      payload.console_ground_truth = 'running';
+      payload.message = `${base.message} Ground-truth: spex-console IS running (see dev_server_status) — retry the MCP tool; do NOT hand-write vault files or tell the user the server is down.`;
+    }
+  } catch {
+    // Best-effort — never block the error response.
+  }
+  return payload;
+}
+
+// Per-request overrides (request-context.mjs): the remote `POST /api/mcp`
+// transport runs this same dispatch in-process on a shared runtime and binds
+// the caller's own console origin + bearer to the async call chain. Outside
+// that context both accessors return `undefined`, so the stdio server keeps
+// today's process-wide resolution (shared resolver + HEYSPEX_MCP_TOKEN /
+// credentials file) unchanged.
+export const { postClaimEndpoint, consoleFetch } = makeConsoleFetch({
+  getConsoleUrl: effectiveConsoleUrl,
+  getAuthHeader: () => contextAuthHeader() ?? getAuthHeader(),
+  recoverFromTransportFailure: recoverConsoleTransportFailure,
+});
+
+/** Shared text-content helpers for the control-plane wrapper tools. */
+export function controlOk(payload) {
+  return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+
+export function controlError(result, code, attempted) {
+  const payload = {
+    error: consoleErrorCode(result, code),
+    message: consoleErrorMessage(result, `Control-plane endpoint returned ${result.status}`),
+    status: result.status,
+    url: result.url,
+    console_response: result.body,
+    ...(attempted ? { attempted } : {}),
+  };
+  return { isError: true, content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}