heyspex 0.1.0 → 0.2.0

package/scripts/lib/dev-mode.mjs

@@ -19,6 +19,15 @@
  * (~/.heyspex/dev-mode.json) → cloud admin setting (account_settings.dev_mode,
  * injected by the caller — this module never talks to Neon) → default prod.
  *
+ * ONE HOME ([[HS-R0YM-WW9R-TASK-publish-the-routing-fact-table-test]], routing
+ * fact G in `spex-console/src/lib/cli/routing-facts.ts`): the cloud
+ * `account_settings.dev_mode` row is the home of the mode. `dev-mode.json` is a
+ * machine-local CACHE of it (owner decision: kept as a cache, not deleted),
+ * validated by the `hs doctor` `mode-override` row, which names the file's
+ * writer and date and fails when it disagrees with a known cloud setting.
+ * Both implementations are held to the one precedence table in
+ * `./dev-mode.fixtures.mjs`.
+ *
  * MACHINE-LOCAL RECORD — CROSS-COMPONENT CONTRACT (the Windows Companion
  * reads the same file; keep the shape exactly this):
  *   ~/.heyspex/dev-mode.json
@@ -28,6 +37,13 @@
  * Env overrides:
  *   HEYSPEX_DEV_MODE = prod | dev | local | cloud   (local/cloud imply dev)
  *   HEYSPEX_DEV_RELIANCE = local | cloud            (refines HEYSPEX_DEV_MODE=dev)
+ *   `HEYSPEX_DEV_MODE=dev` with no reliance still resolves local, but the
+ *   envelope reports `sources.reliance: "assumed-local"` — never silently.
+ *
+ * Any active switch (env or file) is reported as ONE structured object by
+ * `modeOverrideOf(resolved)` — `hs dev --json`, `hs doctor --json` and the MCP
+ * `heyspex_dev_mode` all carry it as `mode_override`
+ * ([[HS-EVVI-WW9R-TASK-show-any-dev-mode-override-in-hs-dev]]).
  *
  * Zero deps beyond node builtins (same rule as console-url-resolver.mjs).
  */
@@ -35,6 +51,8 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
+import { assertNotRealHomeUnderTest, readBearer } from '../../vendor/heyspex-mcp/credentials.mjs';
+
 export const CLOUD_CONSOLE_URL = 'https://app.heyspex.com';
 export const LOCAL_CONSOLE_URL = 'http://localhost:3000';
 export const DEV_MODE_FILENAME = 'dev-mode.json';
@@ -70,14 +88,19 @@ export function deriveSemantics(mode, reliance) {
   };
 }
 
+/** Default file reader — injectable so tests never touch the real HOME. */
+const defaultReadFile = (p) => readFileSync(p, 'utf8');
+
 /**
  * Read + validate ~/.heyspex/dev-mode.json. Never throws:
  * returns { record, parseError } — record null when missing/invalid.
+ * `readFile` is an injectable seam (same shape as the TS twin's) so the
+ * parity test can feed both implementations the SAME in-memory fixture.
  */
-export function readLocalDevModeRecord({ homeDir = homedir() } = {}) {
+export function readLocalDevModeRecord({ homeDir = homedir(), readFile = defaultReadFile } = {}) {
   let raw;
   try {
-    raw = readFileSync(devModeFilePath(homeDir), 'utf8');
+    raw = readFile(devModeFilePath(homeDir));
   } catch {
     return { record: null, parseError: null }; // absent — not an error
   }
@@ -113,9 +136,10 @@ export function readLocalDevModeRecord({ homeDir = homedir() } = {}) {
 export function resolveDevMode({
   env = process.env,
   homeDir = homedir(),
+  readFile = defaultReadFile,
   cloudSetting = undefined,
 } = {}) {
-  const local = readLocalDevModeRecord({ homeDir });
+  const local = readLocalDevModeRecord({ homeDir, readFile });
   const cloudKnown = cloudSetting !== undefined;
   const cloudValue =
     cloudKnown && cloudSetting
@@ -128,11 +152,19 @@ export function resolveDevMode({
   let mode;
   let reliance;
   let source;
+  // Where the RELIANCE came from. Equals `source` except in one case:
+  // `HEYSPEX_DEV_MODE=dev` with no `HEYSPEX_DEV_RELIANCE` used to mean local
+  // silently; it still means local, but the envelope now says the reliance
+  // was ASSUMED ([[HS-EVVI-WW9R-TASK-show-any-dev-mode-override-in-hs-dev]]
+  // AC1, invariant 10 — no hidden mode switch).
+  let relianceSource;
   const envParsed = normalizeMode(env.HEYSPEX_DEV_MODE);
   if (envParsed) {
     mode = envParsed.mode;
-    reliance = envParsed.reliance ?? normalizeReliance(env.HEYSPEX_DEV_RELIANCE) ?? 'local';
+    const envReliance = envParsed.reliance ?? normalizeReliance(env.HEYSPEX_DEV_RELIANCE);
+    reliance = envReliance ?? 'local';
     source = 'env';
+    relianceSource = envReliance ? 'env' : 'assumed-local';
   } else if (local.record) {
     mode = local.record.mode;
     reliance = local.record.reliance;
@@ -167,7 +199,7 @@ export function resolveDevMode({
     vaultWriteMode: semantics.vaultWriteMode,
     sources: {
       mode: source,
-      reliance: source,
+      reliance: relianceSource ?? source,
       consoleUrl:
         source === 'local-override' && local.record?.console_url ? 'local-override' : 'derived',
       readTier: 'derived',
@@ -183,6 +215,131 @@ export function resolveDevMode({
   };
 }
 
+/** The `source` values {@link modeOverrideOf} can report. */
+export const MODE_OVERRIDE_SOURCE_ENV = 'env';
+export const MODE_OVERRIDE_SOURCE_FILE = 'dev-mode.json';
+
+/**
+ * The one structured answer to "is a mode switch active on this machine?" —
+ * what `hs dev --json`, `hs doctor --json` and `heyspex_dev_mode` all report
+ * as `mode_override` ([[HS-EVVI-WW9R-TASK-show-any-dev-mode-override-in-hs-dev]]
+ * AC1/AC2; epic [[HS-P1AW-WW9R-EPIC-identity-threading-and-the-end-of-the]]
+ * criterion 4). Pure: reads only the resolved envelope, never the file.
+ *
+ *   null                                   — nothing overrides the cloud/default
+ *   { source: "env",           written_at: null,  written_by: "HEYSPEX_DEV_MODE", disagrees_with_cloud }
+ *   { source: "dev-mode.json", written_at: <ISO>, written_by: <record.source>,    disagrees_with_cloud }
+ *
+ * `written_at` / `written_by` are the record's `updated_at` / `source` (the
+ * cross-component file contract keeps its own key names; the Companion reads
+ * that file). `disagrees_with_cloud` is only ever true when the cloud setting
+ * is KNOWN and differs — an unreachable cloud is never a disagreement.
+ */
+export function modeOverrideOf(resolved) {
+  if (!resolved) return null;
+  const cloud = resolved.cloudSetting?.value ?? null;
+  if (resolved.sources?.mode === 'env') {
+    const disagrees =
+      cloud !== null &&
+      (cloud.mode !== resolved.mode ||
+        (resolved.mode === 'dev' && cloud.reliance !== resolved.reliance));
+    return {
+      source: MODE_OVERRIDE_SOURCE_ENV,
+      written_at: null,
+      written_by: 'HEYSPEX_DEV_MODE',
+      disagrees_with_cloud: disagrees,
+    };
+  }
+  if (resolved.localOverride?.present) {
+    const record = resolved.localOverride.record;
+    return {
+      source: MODE_OVERRIDE_SOURCE_FILE,
+      written_at: record?.updated_at ?? null,
+      written_by: record?.source ?? null,
+      disagrees_with_cloud: resolved.localOverride.staleAgainstCloud === true,
+    };
+  }
+  return null;
+}
+
+/** `prod` / `dev+local` / `dev+cloud` — the label doctor and hs dev print. */
+export function describeModeLabel(resolved) {
+  return `${resolved.mode}${resolved.mode === 'dev' ? `+${resolved.reliance}` : ''}`;
+}
+
+/**
+ * The `hs doctor` row for {@link modeOverrideOf} (row id `mode-override`).
+ * Pure — the caller resolves ONCE and passes the envelope in; this never
+ * re-reads the file. Shape matches every other doctor row
+ * (`{ id, label, status, detail, human? }`) plus the structured
+ * `mode_override` so `--json` carries the same object `hs dev --json` does.
+ *
+ *   ok    no override; or one that pins prod (the default) and does not
+ *         disagree with a known cloud setting — the file is then just a
+ *         cache of the normal mode, and the detail still names its date and
+ *         writer so nothing on disk stays invisible.
+ *   warn  an override puts this machine in dev mode (cloud setting unknown
+ *         or agreeing) — names the file, date and writer, repair `hs dev prod`.
+ *   fail  the override DISAGREES with a known cloud setting — same repair.
+ *
+ * `repairCommand` is rendered by the caller (`hsCommand('dev prod')`) so the
+ * advice is in the form THIS machine can run.
+ */
+export function modeOverrideDoctorRow(resolved, { recordPath, repairCommand = 'hs dev prod' } = {}) {
+  const id = 'mode-override';
+  const label = 'Dev-mode override (env / ~/.heyspex/dev-mode.json)';
+  const override = modeOverrideOf(resolved);
+  const modeLabel = describeModeLabel(resolved);
+  if (!override) {
+    return {
+      id,
+      label,
+      status: 'ok',
+      detail: `none — ${modeLabel} from ${resolved.sources.mode}`,
+      mode_override: null,
+    };
+  }
+  const where =
+    override.source === MODE_OVERRIDE_SOURCE_ENV
+      ? `HEYSPEX_DEV_MODE env override`
+      : `${recordPath ?? devModeFilePath()}`;
+  const stamp =
+    override.source === MODE_OVERRIDE_SOURCE_ENV
+      ? ''
+      : ` (written ${override.written_at ?? 'unknown date'} by ${override.written_by ?? 'unknown writer'})`;
+  const cloud = resolved.cloudSetting?.value;
+  const cloudLabel = cloud ? describeModeLabel({ mode: cloud.mode, reliance: cloud.reliance }) : null;
+  const repair = `Run \`${repairCommand}\` to put this machine back on the cloud console, or set the mode on purpose with \`${repairCommand.replace(/\bdev prod$/, 'dev <mode>')}\`.`;
+
+  if (override.disagrees_with_cloud) {
+    return {
+      id,
+      label,
+      status: 'fail',
+      detail: `${modeLabel} from ${where}${stamp} — DISAGREES with the cloud setting (${cloudLabel})`,
+      human: repair,
+      mode_override: override,
+    };
+  }
+  if (resolved.mode === 'dev') {
+    return {
+      id,
+      label,
+      status: 'warn',
+      detail: `${modeLabel} from ${where}${stamp}${cloudLabel ? ` — matches the cloud setting (${cloudLabel})` : ' — cloud setting not checked (offline)'}`,
+      human: repair,
+      mode_override: override,
+    };
+  }
+  return {
+    id,
+    label,
+    status: 'ok',
+    detail: `${where}${stamp} pins ${modeLabel} — the default, nothing overridden`,
+    mode_override: override,
+  };
+}
+
 /**
  * Upsert top-level `key: value` lines in ~/.heyspex/credentials.yaml without a
  * full YAML round-trip (same targeted approach as the vendor MCP `pair`
@@ -192,8 +349,11 @@ export function resolveDevMode({
  */
 export function upsertCredentialsYamlKeys(homeDir, updates) {
   const dir = join(homeDir, '.heyspex');
-  mkdirSync(dir, { recursive: true, mode: 0o700 });
   const filePath = join(dir, 'credentials.yaml');
+  // The real-home guard the credentials and registry writers carry: under a
+  // test runner, refuse to touch the REAL ~/.heyspex (checked before mkdir).
+  assertNotRealHomeUnderTest(filePath);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
   let content = '';
   try {
     content = readFileSync(filePath, 'utf8');
@@ -214,14 +374,57 @@ export function upsertCredentialsYamlKeys(homeDir, updates) {
   return filePath;
 }
 
-/** Targeted read of `mcp_token:` from credentials.yaml (bearer for cloud calls). */
-export function readCredentialsMcpToken({ homeDir = homedir() } = {}) {
+/**
+ * The bearer for cloud calls — `HEYSPEX_MCP_TOKEN` env, then `mcp_token:` in
+ * credentials.yaml — via the ONE shared reader
+ * (`vendor/heyspex-mcp/credentials.mjs`,
+ * [[HS-HL0D-WW9R-TASK-share-one-bearer-reader-and-one-console]]). Kept under
+ * its historical name for the hook scripts that import it; the precedence is
+ * the shared module's, never re-implemented here.
+ */
+export function readCredentialsMcpToken({ env = process.env, homeDir = homedir() } = {}) {
+  return readBearer({ env, homeDir }).token;
+}
+
+/**
+ * Run `fn(signal)` under a request timeout that is ALWAYS cleared and can
+ * never fire after the request has settled.
+ *
+ * Why not `AbortSignal.timeout(ms)`: that signal owns a timer nothing can
+ * cancel — it stays armed for the whole window even once the response has
+ * resolved, so a late abort can land on an already-settled request. Here the
+ * controller is ours: the timer is cleared in `finally` (rule 1 of
+ * [[HS-SWW3-Z9WP-DIAG-hs-dev-crashes-with-a-libuv-assertion]]) and `unref`'d
+ * so it can never hold the event loop open on its own.
+ */
+async function withRequestTimeout(timeoutMs, fn) {
+  const controller = new AbortController();
+  const state = { timedOut: false };
+  const timer = setTimeout(() => {
+    state.timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+  timer.unref?.();
+  try {
+    return await fn(controller.signal);
+  } catch (err) {
+    if (state.timedOut) throw new Error(`timed out after ${timeoutMs}ms`);
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Release a response we are not going to read. An undrained body keeps its
+ * socket half-read in the keep-alive pool; cancelling hands it back so the
+ * process can tear down cleanly. Never throws (the body may already be gone).
+ */
+async function discardResponseBody(res) {
   try {
-    const raw = readFileSync(join(homeDir, '.heyspex', 'credentials.yaml'), 'utf8');
-    const match = raw.match(/^mcp_token:\s*["']?([^"'\r\n#]+)/m);
-    return match?.[1]?.trim() || null;
+    await res?.body?.cancel();
   } catch {
-    return null;
+    /* already consumed, closed, or bodyless — nothing to release */
   }
 }
 
@@ -235,11 +438,16 @@ export async function fetchCloudDevMode({
   if (!consoleUrl) return { ok: false, setting: undefined, error: 'no console url' };
   try {
     const token = readCredentialsMcpToken({ homeDir });
-    const res = await fetchImpl(`${consoleUrl.replace(/\/+$/, '')}/api/admin/dev-mode`, {
-      headers: token ? { Authorization: `Bearer ${token}` } : {},
-      signal: AbortSignal.timeout(timeoutMs),
-    });
-    if (!res.ok) return { ok: false, setting: undefined, error: `HTTP ${res.status}` };
+    const res = await withRequestTimeout(timeoutMs, (signal) =>
+      fetchImpl(`${consoleUrl.replace(/\/+$/, '')}/api/admin/dev-mode`, {
+        headers: token ? { Authorization: `Bearer ${token}` } : {},
+        signal,
+      }),
+    );
+    if (!res.ok) {
+      await discardResponseBody(res);
+      return { ok: false, setting: undefined, error: `HTTP ${res.status}` };
+    }
     const body = await res.json();
     return { ok: true, setting: body?.cloud ?? null, error: null };
   } catch (err) {
@@ -297,18 +505,24 @@ export async function applyDevMode(
     parsed.reliance ?? normalizeReliance(target?.reliance) ?? 'local';
   const mode = parsed.mode;
   const semantics = deriveSemantics(mode, reliance);
+  // Under a test runner, refuse a real-home target BEFORE the cloud precheck
+  // or any write (the same guard the credentials and registry writers carry).
+  assertNotRealHomeUnderTest(devModeFilePath(homeDir));
 
+  // Timer-safe on purpose — never `AbortSignal.timeout` here
+  // ([[HS-SWW3-Z9WP-DIAG-hs-dev-crashes-with-a-libuv-assertion]]).
   async function postCloud(token) {
-    const res = await fetchImpl(`${semantics.consoleUrl}/api/admin/dev-mode`, {
-      method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        ...(token ? { Authorization: `Bearer ${token}` } : {}),
-      },
-      body: JSON.stringify({ mode, reliance: semantics.reliance, source }),
-      signal: AbortSignal.timeout(5000),
-    });
-    return res;
+    return withRequestTimeout(5000, (signal) =>
+      fetchImpl(`${semantics.consoleUrl}/api/admin/dev-mode`, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        },
+        body: JSON.stringify({ mode, reliance: semantics.reliance, source }),
+        signal,
+      }),
+    );
   }
 
   // 0. Authorization precheck — see the doc comment above.
@@ -318,6 +532,7 @@ export async function applyDevMode(
     if (token) {
       try {
         const res = await postCloud(token);
+        await discardResponseBody(res);
         if (res.status === 403) throw new DevModeNotAdminError();
         cloud = { attempted: true, updated: res.ok, error: res.ok ? null : `HTTP ${res.status}` };
       } catch (err) {
@@ -336,8 +551,8 @@ export async function applyDevMode(
     source,
   };
   const dir = join(homeDir, '.heyspex');
-  mkdirSync(dir, { recursive: true, mode: 0o700 });
   const recordPath = devModeFilePath(homeDir);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
   writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
 
   // 2. credentials.yaml console_url (rung 2 of the shared resolver).
@@ -354,6 +569,7 @@ export async function applyDevMode(
       const res = await postCloud(token);
       if (res.ok) cloud.updated = true;
       else cloud.error = `HTTP ${res.status}`;
+      await discardResponseBody(res);
     } catch (err) {
       cloud.error = String(err?.message ?? err);
     }

package/scripts/lib/heyspex-home.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * heyspex-home.mjs — the ONE resolver for "which home directory does
+ * `.heyspex/` live under".
+ *
+ * Every machine-global HeySpex file (`credentials.yaml`, `registry.json`,
+ * `dev-mode.json`, `config.yaml`, `env.keys`, companion pairing state) lives at
+ * `<home>/.heyspex/…`, and before this module `<home>` was always a bare
+ * `os.homedir()`. That makes the machine single-tenant: one signed-in identity,
+ * one vault registry, one console URL. There is no way to run a second,
+ * isolated HeySpex identity on the same box — which is exactly what a
+ * fresh-customer onboarding rehearsal needs (see
+ * [[HS-ONB-customer-install-checklist]] and
+ * [[HS-BFXF-DIAG-hs-never-resolves-on-a-fresh-machine]]).
+ *
+ * `HEYSPEX_HOME` overrides that home directory. It names the directory that
+ * CONTAINS `.heyspex/`, not the `.heyspex/` directory itself — so every
+ * existing `join(homeDir, '.heyspex', …)` call site keeps its shape and only
+ * its default changes:
+ *
+ *   HEYSPEX_HOME=C:\heyspex-test\paul-mg   →   C:\heyspex-test\paul-mg\.heyspex\credentials.yaml
+ *
+ * Deliberately NOT an override of the `.heyspex` directory name: the two
+ * conventions collide (some callers hold `homeDir`, some hold the full
+ * `.heyspex` path), and a home-dir override substitutes cleanly at both.
+ *
+ * Scope note: this covers HeySpex's own state. It does not redirect `~/.claude`,
+ * `~/.gitconfig`, or npm — a full-fidelity clean-machine test still wants a
+ * separate OS user profile. What it buys is a second HeySpex identity (account,
+ * registry, active vault, console URL) alongside the builder identity on one
+ * machine.
+ *
+ * Plain Node ESM, zero deps beyond `node:os` — importable from the vendored MCP
+ * server, the Claude hooks, and the dev-factory dispatchers with no build step,
+ * exactly like `console-url-resolver.mjs` next to it.
+ */
+import { homedir } from 'node:os';
+
+/**
+ * The home directory `.heyspex/` lives under.
+ *
+ * Precedence:
+ *   1. `HEYSPEX_HOME` env — an absolute path to the directory containing `.heyspex/`
+ *   2. `os.homedir()`
+ *
+ * A blank or whitespace-only `HEYSPEX_HOME` is treated as unset rather than as
+ * an empty path, so `HEYSPEX_HOME=` in a shell profile fails safe to the real
+ * home instead of resolving `.heyspex/` against the process CWD.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function heyspexHome(env = process.env) {
+  const override = env?.HEYSPEX_HOME;
+  if (typeof override === 'string' && override.trim().length > 0) {
+    return override.trim();
+  }
+  return homedir();
+}
+
+/**
+ * True when the resolved home came from `HEYSPEX_HOME` rather than the real
+ * user profile. Used by `hs doctor` and the login banner so an isolated
+ * identity is never mistaken for the machine's default one.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean}
+ */
+export function isHeyspexHomeOverridden(env = process.env) {
+  const override = env?.HEYSPEX_HOME;
+  return typeof override === 'string' && override.trim().length > 0;
+}