heyspex 0.1.0 → 0.2.1

package/scripts/lib/console-url-resolver.mjs

@@ -13,47 +13,106 @@
  * documented the drift that causes. This module is the ONE implementation;
  * all five now import/delegate to it.
  *
- * Precedence (cloud-first — an explicit override always wins over ambient
- * discovery, and a paired cloud console outranks a stale local dev-server
- * discovery file):
- *   1. `HEYSPEX_CONSOLE_URL` env (legacy-cockpit: `HEYSPEX_COCKPIT_URL`)
+ * MODE-AWARE precedence ([[HS-VOJ7-YL1C-DIAG-console-url-resolver-ignores-dev-mode]];
+ * it also closes [[HS-3UZS-EKLJ-DIAG-a-brand-new-team-member-s-one-command]]
+ * Gap 1 — a fresh clone with nothing configured resolves to the production
+ * console instead of guessing localhost, because the default mode is prod).
+ * The resolved dev mode (`scripts/lib/dev-mode.mjs` `resolveDevMode`: env →
+ * `~/.heyspex/dev-mode.json` → default prod) decides whether the repo's
+ * discovery file is even eligible, because that file is an ADMIN-LOCAL
+ * artifact: cloud is the default reliance for every HeySpex customer, and
+ * local reliance exists only for HeySpex admins developing HeySpex. A stale
+ * localhost pointer must never outrank the resolved cloud console.
+ *
+ *   1. `HEYSPEX_CONSOLE_URL` env
  *   2. `console_url:` in `~/.heyspex/credentials.yaml` — written by
- *      `hs mcp pair <code>` when a machine pairs with a deployed console,
- *      and by `hs dev local` (owner-only) when the owner's OWN machine
- *      overrides to `http://localhost:3000` — that write is rung 2, so it
- *      wins over the rung-4 default below without needing rung 1
- *   3. `.heyspex/console-url` discovery file in the repo (legacy-cockpit `cockpit-url`)
+ *      `hs mcp pair <code>` / `hs login` / `hs dev mode:<...>`.
+ *      **Skipped when the resolved reliance is `cloud` and the value is a
+ *      loopback address** (localhost / 127.0.0.1 / ::1): `hs dev mode:local`
+ *      writes `http://localhost:3000` here, and a later hand-edit of the mode
+ *      file to prod left that stale pointer outranking the derived
+ *      production console — every cloud call then went to a dev server the
+ *      machine no longer runs. Logged once to stderr; the env override above
+ *      is still honored verbatim (an explicit loopback env is operator intent,
+ *      e.g. the stand-in consoles the test suites bind).
+ *   3. `.heyspex/console-url` discovery file in the repo
  *      — written by the local dev-server launcher
- *      (`spex-console/scripts/ensure-next-dev.mjs`), ephemeral per session
- *   4. `https://app.heyspex.com` (the cloud console — [[HS-3UZS-EKLJ-DIAG-a-brand-new-team-member-s-one-command]]
- *      Gap 1: a fresh clone with none of the above set has no way to
- *      discover the production console, and used to silently guess
- *      localhost instead, which for anyone but the owner is unreachable and
- *      degrades every registration to registry.json-only. The owner's own
- *      daily local tooling is unaffected — rung 2 above always wins for them.)
+ *      (`spex-console/scripts/ensure-next-dev.mjs`), ephemeral per session.
+ *      **Consulted ONLY when the resolved reliance is `local`.**
+ *   4. The DERIVED console URL for the resolved mode — `deriveSemantics()`:
+ *      prod / dev+cloud → `https://app.heyspex.com`, dev+local →
+ *      `http://localhost:3000`. Never a hard-coded literal.
+ *
+ * Steps 1 and 2 are explicit operator intent, so they still win in both
+ * reliances. Local reliance behaves exactly as it did before this change
+ * (discovery file, then the localhost default, including `strict`).
  *
- * Plain Node ESM, zero deps beyond `node:fs`/`node:os`/`node:path` — every
- * consumer (vendor MCP server, Claude-hook scripts, dev-factory dispatchers)
- * can import this directly with no build step and no risk of pulling in a
- * dependency that isn't installed in their execution context.
+ * Plain Node ESM, zero deps beyond `node:fs`/`node:os`/`node:path` (the one
+ * import, `./dev-mode.mjs`, obeys the same rule) — every consumer (vendor MCP
+ * server, Claude-hook scripts, dev-factory dispatchers) can import this
+ * directly with no build step and no risk of pulling in a dependency that
+ * isn't installed in their execution context. Stays SYNCHRONOUS and does zero
+ * network I/O: it runs on every console request.
  */
+import { heyspexHome } from './heyspex-home.mjs';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
+import { CLOUD_CONSOLE_URL, LOCAL_CONSOLE_URL, resolveDevMode } from './dev-mode.mjs';
+
 /**
- * The rung-4 fallback when nothing else resolves — the cloud console, so a
- * fresh clone reaches production instead of guessing localhost. Literal
- * mirror of `CLOUD_CONSOLE_URL` (`spex-console/src/lib/dev-mode.ts`): this
- * file stays dependency-free plain Node (see module doc), so it cannot
- * import that TS module — keep the two literals in sync by hand.
+ * The last-resort console URL for LOCAL reliance only (cloud reliance falls
+ * back to the derived cloud console instead). Re-exported from
+ * `dev-mode.mjs` so there is exactly one localhost literal in the codebase.
  */
-export const DEFAULT_CONSOLE_URL = 'https://app.heyspex.com';
+export const DEFAULT_CONSOLE_URL = LOCAL_CONSOLE_URL;
 
 function trimTrailingSlash(url) {
   return url.replace(/\/+$/, '');
 }
 
+/** Host names that can only ever name THIS machine's own dev console. */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]', '0.0.0.0']);
+
+/**
+ * True when `url` points at a loopback host — a console that lives on this
+ * machine, which a cloud-reliance session has no business talking to. Never
+ * throws: an unparseable value is simply "not loopback" and falls through to
+ * the same handling it had before.
+ */
+export function isLoopbackConsoleUrl(url) {
+  if (typeof url !== 'string' || !url) return false;
+  try {
+    return LOOPBACK_HOSTS.has(new URL(url).hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+// Once per process: the resolver runs on every console request, and a stale
+// pointer repeating itself on each call would bury the one line that matters.
+let staleLoopbackCredentialsWarned = false;
+
+/** Test seam — re-arm the once-per-process stderr notice. */
+export function resetConsoleUrlResolverWarnings() {
+  staleLoopbackCredentialsWarned = false;
+}
+
+function warnStaleLoopbackCredentialsOnce(credentialsUrl, derivedUrl, { log }) {
+  if (staleLoopbackCredentialsWarned) return;
+  staleLoopbackCredentialsWarned = true;
+  try {
+    log(
+      `[heyspex] ignoring console_url ${credentialsUrl} from ~/.heyspex/credentials.yaml: ` +
+        `the resolved reliance is cloud, and a loopback console cannot serve it — using ${derivedUrl} ` +
+        '(set HEYSPEX_CONSOLE_URL to override explicitly, or run `hs dev mode:local` to go back to a local console).\n',
+    );
+  } catch {
+    // A logging failure must never break URL resolution.
+  }
+}
+
 /**
  * Read `console_url:` out of `~/.heyspex/credentials.yaml` with a targeted
  * regex rather than a full YAML parse — mirrors the same
@@ -62,10 +121,10 @@ function trimTrailingSlash(url) {
  * consumers (some of which run standalone, outside the npm workspace's
  * hoisted `node_modules`) can call it with zero new dependencies.
  */
-export function readCredentialsConsoleUrl({ homeDir = homedir() } = {}) {
+export function readCredentialsConsoleUrl({ homeDir = heyspexHome(), readFile = defaultReadFile } = {}) {
   try {
-    const raw = readFileSync(join(homeDir, '.heyspex', 'credentials.yaml'), 'utf8');
-    const match = raw.match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
+    const raw = readFile(join(homeDir, '.heyspex', 'credentials.yaml'));
+    const match = String(raw ?? '').match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
     const value = match?.[1]?.trim();
     return value && value.length > 0 ? trimTrailingSlash(value) : null;
   } catch {
@@ -74,49 +133,92 @@ export function readCredentialsConsoleUrl({ homeDir = homedir() } = {}) {
   }
 }
 
-/** Read the repo's `.heyspex/console-url` (or legacy-cockpit `cockpit-url`) discovery file. */
-export function readDiscoveryFileConsoleUrl(repoRoot) {
+/** Default IO for the two file rungs — `readFileSync` utf8; tests inject their own. */
+function defaultReadFile(p) {
+  return readFileSync(p, 'utf8');
+}
+
+/**
+ * Read the repo's `.heyspex/console-url` discovery file. `readDiscovery` is
+ * the seam the `hs` bins already inject (a `(path) => string | null` reader);
+ * it defaults to the real file read.
+ */
+export function readDiscoveryFileConsoleUrl(repoRoot, { readDiscovery = defaultReadFile } = {}) {
   if (!repoRoot) return null;
-  for (const name of ['console-url', 'cockpit-url' /* legacy-cockpit */]) {
-    // legacy-cockpit: pre-rename launchers only wrote cockpit-url — keep resolving it.
-    try {
-      const discovery = readFileSync(join(repoRoot, '.heyspex', name), 'utf8').trim();
-      if (discovery.length > 0) return trimTrailingSlash(discovery);
-    } catch {
-      // Missing or unreadable — try the next candidate.
-    }
+  try {
+    const discovery = String(readDiscovery(join(repoRoot, '.heyspex', 'console-url')) ?? '').trim();
+    if (discovery.length > 0) return trimTrailingSlash(discovery);
+  } catch {
+    // Missing or unreadable — no discovery-file override.
   }
   return null;
 }
 
 /**
- * Thrown by {@link resolveConsoleUrl} in `strict` mode when nothing in the
- * precedence chain (env → credentials file → discovery file) resolves —
- * i.e. the caller is about to guess `DEFAULT_CONSOLE_URL` instead of knowing
- * the real console URL ([[HS-OQ34-G59F-DIAG-console-url-silently-defaults-to]]:
- * "not knowing the port produces a guess, not an error").
+ * Thrown by {@link resolveConsoleUrl} in `strict` mode when the resolved
+ * reliance is `local` and nothing in the precedence chain (env → credentials
+ * file → discovery file) resolves — i.e. the caller is about to guess a
+ * localhost PORT instead of knowing the real console URL
+ * ([[HS-OQ34-G59F-DIAG-console-url-silently-defaults-to]]: "not knowing the
+ * port produces a guess, not an error").
+ *
+ * Cloud reliance never throws: the derived cloud console
+ * (`https://app.heyspex.com`) is a resolved answer, not a guess
+ * ([[HS-VOJ7-YL1C-DIAG-console-url-resolver-ignores-dev-mode]]).
  */
 export class ConsoleUrlUnresolvedError extends Error {
   constructor() {
     super(
-      'resolveConsoleUrl: no HEYSPEX_CONSOLE_URL/HEYSPEX_COCKPIT_URL env, no console_url: in ' + // legacy-cockpit env name
-        '~/.heyspex/credentials.yaml, and no .heyspex/console-url discovery file — refusing to ' +
-        `silently fall back to the ${DEFAULT_CONSOLE_URL} default in strict mode.`,
+      'resolveConsoleUrl: local reliance with no HEYSPEX_CONSOLE_URL env, ' +
+        'no console_url: in ~/.heyspex/credentials.yaml, and no .heyspex/console-url discovery ' +
+        'file — refusing to silently fall back to the localhost:3000 default in strict mode.',
     );
     this.name = 'ConsoleUrlUnresolvedError';
   }
 }
 
+/**
+ * The resolved dev mode, read synchronously and with zero network I/O:
+ * `resolveDevMode` consults env → `~/.heyspex/dev-mode.json` → default prod,
+ * and never talks to Neon when `cloudSetting` is left undefined (as here).
+ * Fail-open: any unexpected failure degrades to the legacy local answer so a
+ * hook script can never be broken by a malformed mode record.
+ */
+function resolveModeEnvelope({ env, homeDir }) {
+  try {
+    const resolved = resolveDevMode({ env, homeDir });
+    return {
+      reliance: resolved.reliance === 'cloud' ? 'cloud' : 'local',
+      consoleUrl: resolved.consoleUrl || DEFAULT_CONSOLE_URL,
+    };
+  } catch {
+    return { reliance: 'local', consoleUrl: DEFAULT_CONSOLE_URL };
+  }
+}
+
 /**
  * Resolve the console base URL (no trailing slash) per the precedence above.
  * Every input is injectable so callers/tests can run hermetically:
- *   - `repoRoot` — needed only for step 3 (discovery file); omit if the
- *     caller has no vault root to check (env/credentials-only resolution).
- *   - `env` — defaults to `process.env`.
- *   - `homeDir` — defaults to `os.homedir()`.
+ *   - `repoRoot` — needed only for step 3 (discovery file, local reliance
+ *     only); omit if the caller has no vault root to check.
+ *   - `env` — defaults to `process.env`. Also feeds the mode resolver, so
+ *     `HEYSPEX_DEV_MODE` / `HEYSPEX_DEV_RELIANCE` are honored here too.
+ *   - `homeDir` — defaults to `os.homedir()`. Source of both
+ *     `credentials.yaml` and the machine-local `dev-mode.json` record.
  *   - `strict` — when `true`, throw {@link ConsoleUrlUnresolvedError} instead
- *     of returning `DEFAULT_CONSOLE_URL` when nothing resolves. Opt-in only —
+ *     of guessing the localhost default in LOCAL reliance. Opt-in only —
  *     default `false` preserves every existing caller's fail-open behavior.
+ *   - `devMode` — optional pre-resolved `{ reliance, consoleUrl }` envelope,
+ *     a test/caller seam so a consumer that already resolved the mode does
+ *     not re-read `dev-mode.json`.
+ *   - `log` — where the once-per-process "ignoring stale loopback
+ *     credentials" notice goes. Defaults to stderr (stdout is the MCP
+ *     JSON-RPC channel and must stay clean); tests inject a collector.
+ *   - `readFile` / `readDiscovery` — IO seams for the credentials rung and
+ *     the discovery-file rung ([[HS-HL0D-WW9R-TASK-share-one-bearer-reader-and-one-console]]):
+ *     the `hs` bins inject these through `resolveSpexConsoleUrl`
+ *     (spex-console/src/lib/cli/defer.ts), which is now a thin call into
+ *     THIS function instead of a second, non-mode-aware copy of it.
  *
  * Non-strict (default): never throws — every read is wrapped and falls
  * through to the next step, so a caller in a fail-open context (a
@@ -127,26 +229,62 @@ export class ConsoleUrlUnresolvedError extends Error {
  * @param {object} [options]
  * @param {string} [options.repoRoot] - needed only for step 3 (discovery file); omit if the
  *   caller has no vault root to check (env/credentials-only resolution).
- * @param {NodeJS.ProcessEnv} [options.env] - defaults to `process.env`.
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [options.env] - defaults to `process.env`.
  * @param {string} [options.homeDir] - defaults to `os.homedir()`.
  * @param {boolean} [options.strict] - throw {@link ConsoleUrlUnresolvedError} instead of
  *   returning `DEFAULT_CONSOLE_URL` when nothing resolves. Default `false`.
+ * @param {{ reliance: string, consoleUrl: string }} [options.devMode] - pre-resolved mode envelope.
+ * @param {(line: string) => void} [options.log] - sink for the once-per-process stale-loopback notice.
+ * @param {(path: string) => string} [options.readFile] - reads `~/.heyspex/credentials.yaml`.
+ * @param {(path: string) => string | null} [options.readDiscovery] - reads `<repoRoot>/.heyspex/console-url`.
+ * @returns {string}
  */
 export function resolveConsoleUrl({
   repoRoot,
   env = process.env,
-  homeDir = homedir(),
+  homeDir = heyspexHome(),
   strict = false,
+  devMode,
+  log = (line) => process.stderr.write(line),
+  readFile = defaultReadFile,
+  readDiscovery = defaultReadFile,
 } = {}) {
-  const envUrl = (env.HEYSPEX_CONSOLE_URL ?? env.HEYSPEX_COCKPIT_URL)?.trim(); // legacy-cockpit env
+  const envUrl = env.HEYSPEX_CONSOLE_URL?.trim();
   if (envUrl) return trimTrailingSlash(envUrl);
 
-  const credentialsUrl = readCredentialsConsoleUrl({ homeDir });
-  if (credentialsUrl) return credentialsUrl;
+  // Resolved before step 2 now: the credentials rung is mode-aware. Still
+  // synchronous, still zero network I/O (see resolveModeEnvelope).
+  const mode = devMode ?? resolveModeEnvelope({ env, homeDir });
+  const cloud = mode.reliance === 'cloud';
 
-  const discoveryUrl = readDiscoveryFileConsoleUrl(repoRoot);
-  if (discoveryUrl) return discoveryUrl;
+  // Derived answer for the resolved mode. A cloud-reliance mode record that
+  // still carries a loopback `console_url` (a hand-edited `dev-mode.json`) is
+  // the same stale pointer in a different file, so it gets the same treatment:
+  // cloud derives the production console, never a localhost guess.
+  const derivedUrl = trimTrailingSlash(
+    cloud && isLoopbackConsoleUrl(mode.consoleUrl)
+      ? CLOUD_CONSOLE_URL
+      : mode.consoleUrl || DEFAULT_CONSOLE_URL,
+  );
+
+  const credentialsUrl = readCredentialsConsoleUrl({ homeDir, readFile });
+  if (credentialsUrl) {
+    if (cloud && isLoopbackConsoleUrl(credentialsUrl)) {
+      warnStaleLoopbackCredentialsOnce(credentialsUrl, derivedUrl, { log });
+    } else {
+      return credentialsUrl;
+    }
+  }
+
+  // Step 3 is ADMIN-LOCAL: the repo discovery file points at a local Next.js
+  // dev server, which a cloud-reliance machine has no business talking to
+  // (and which is routinely stale). Cloud reliance skips straight to the
+  // derived cloud console.
+  if (!cloud) {
+    const discoveryUrl = readDiscoveryFileConsoleUrl(repoRoot, { readDiscovery });
+    if (discoveryUrl) return discoveryUrl;
+    if (strict) throw new ConsoleUrlUnresolvedError();
+  }
 
-  if (strict) throw new ConsoleUrlUnresolvedError();
-  return DEFAULT_CONSOLE_URL;
+  return derivedUrl;
 }