heyspex 0.1.0

package/scripts/lib/dev-mode.mjs

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+/**
+ * dev-mode.mjs — shared dev/prod mode + local/cloud reliance core
+ * (epic HS-Q6M2 "Admin dev/prod mode control").
+ *
+ * The ONE plain-Node implementation of the mode contract for every non-TS
+ * consumer (vendor MCP server via dynamic import — the handleDevServerStatus
+ * precedent — plus any hook/dev-factory script). The console-side TypeScript
+ * twin is `spex-console/src/lib/dev-mode.ts`; the two share the SAME contract
+ * and the SAME machine-local record file — change one, change both.
+ *
+ * Model:
+ *   mode: "prod" | "dev"; when dev, reliance: "local" | "cloud".
+ *   prod       => cloud console (app.heyspex.com), Neon reads, cloud writes
+ *   dev+cloud  => cloud console,                   Neon reads, cloud writes
+ *   dev+local  => localhost:3000 console,          disk reads, local writes
+ *
+ * Resolution order (owner-ruled): env override → machine-local override
+ * (~/.heyspex/dev-mode.json) → cloud admin setting (account_settings.dev_mode,
+ * injected by the caller — this module never talks to Neon) → default prod.
+ *
+ * MACHINE-LOCAL RECORD — CROSS-COMPONENT CONTRACT (the Windows Companion
+ * reads the same file; keep the shape exactly this):
+ *   ~/.heyspex/dev-mode.json
+ *   { "mode": "dev"|"prod", "reliance": "local"|"cloud",
+ *     "console_url": "<url>", "updated_at": "<ISO>", "source": "<who wrote it>" }
+ *
+ * Env overrides:
+ *   HEYSPEX_DEV_MODE = prod | dev | local | cloud   (local/cloud imply dev)
+ *   HEYSPEX_DEV_RELIANCE = local | cloud            (refines HEYSPEX_DEV_MODE=dev)
+ *
+ * Zero deps beyond node builtins (same rule as console-url-resolver.mjs).
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+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';
+
+/** Absolute path of the machine-local record. */
+export function devModeFilePath(homeDir = homedir()) {
+  return join(homeDir, '.heyspex', DEV_MODE_FILENAME);
+}
+
+function normalizeMode(raw) {
+  const v = String(raw ?? '').trim().toLowerCase();
+  if (v === 'prod' || v === 'production') return { mode: 'prod', reliance: 'cloud' };
+  if (v === 'dev') return { mode: 'dev', reliance: null };
+  if (v === 'local') return { mode: 'dev', reliance: 'local' };
+  if (v === 'cloud') return { mode: 'dev', reliance: 'cloud' };
+  return null;
+}
+
+function normalizeReliance(raw) {
+  const v = String(raw ?? '').trim().toLowerCase();
+  return v === 'local' || v === 'cloud' ? v : null;
+}
+
+/** Map mode+reliance to the derived semantics. prod forces cloud reliance. */
+export function deriveSemantics(mode, reliance) {
+  const effectiveReliance = mode === 'prod' ? 'cloud' : (reliance ?? 'local');
+  const local = mode === 'dev' && effectiveReliance === 'local';
+  return {
+    reliance: effectiveReliance,
+    consoleUrl: local ? LOCAL_CONSOLE_URL : CLOUD_CONSOLE_URL,
+    readTier: local ? 'disk' : 'neon',
+    vaultWriteMode: local ? 'local' : 'cloud',
+  };
+}
+
+/**
+ * Read + validate ~/.heyspex/dev-mode.json. Never throws:
+ * returns { record, parseError } — record null when missing/invalid.
+ */
+export function readLocalDevModeRecord({ homeDir = homedir() } = {}) {
+  let raw;
+  try {
+    raw = readFileSync(devModeFilePath(homeDir), 'utf8');
+  } catch {
+    return { record: null, parseError: null }; // absent — not an error
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    const mode = parsed?.mode === 'prod' || parsed?.mode === 'dev' ? parsed.mode : null;
+    const reliance = normalizeReliance(parsed?.reliance);
+    if (!mode || (mode === 'dev' && !reliance)) {
+      return { record: null, parseError: `invalid dev-mode record: ${JSON.stringify(parsed)}` };
+    }
+    return {
+      record: {
+        mode,
+        reliance: mode === 'prod' ? 'cloud' : reliance,
+        console_url: typeof parsed.console_url === 'string' ? parsed.console_url : null,
+        updated_at: typeof parsed.updated_at === 'string' ? parsed.updated_at : null,
+        source: typeof parsed.source === 'string' ? parsed.source : null,
+      },
+      parseError: null,
+    };
+  } catch (err) {
+    return { record: null, parseError: `unparseable dev-mode.json: ${String(err?.message ?? err)}` };
+  }
+}
+
+/**
+ * Resolve the effective mode. `cloudSetting` is injected by the caller:
+ *   { mode, reliance } when the account_settings.dev_mode value is known,
+ *   null when known-empty, undefined when unreachable/unknown.
+ * Returns the full resolved envelope with per-field sources so a stale
+ * local override is visible, never silent.
+ */
+export function resolveDevMode({
+  env = process.env,
+  homeDir = homedir(),
+  cloudSetting = undefined,
+} = {}) {
+  const local = readLocalDevModeRecord({ homeDir });
+  const cloudKnown = cloudSetting !== undefined;
+  const cloudValue =
+    cloudKnown && cloudSetting
+      ? {
+          mode: cloudSetting.mode === 'dev' ? 'dev' : 'prod',
+          reliance: normalizeReliance(cloudSetting.reliance) ?? 'cloud',
+        }
+      : null;
+
+  let mode;
+  let reliance;
+  let source;
+  const envParsed = normalizeMode(env.HEYSPEX_DEV_MODE);
+  if (envParsed) {
+    mode = envParsed.mode;
+    reliance = envParsed.reliance ?? normalizeReliance(env.HEYSPEX_DEV_RELIANCE) ?? 'local';
+    source = 'env';
+  } else if (local.record) {
+    mode = local.record.mode;
+    reliance = local.record.reliance;
+    source = 'local-override';
+  } else if (cloudValue) {
+    mode = cloudValue.mode;
+    reliance = cloudValue.reliance;
+    source = 'cloud-setting';
+  } else {
+    mode = 'prod';
+    reliance = 'cloud';
+    source = 'default';
+  }
+
+  const semantics = deriveSemantics(mode, reliance);
+  // Honor a console_url pinned in the local record only when the record won.
+  const consoleUrl =
+    source === 'local-override' && local.record?.console_url
+      ? local.record.console_url.replace(/\/+$/, '')
+      : semantics.consoleUrl;
+
+  const staleAgainstCloud =
+    source === 'local-override' &&
+    cloudValue !== null &&
+    (cloudValue.mode !== mode || (mode === 'dev' && cloudValue.reliance !== semantics.reliance));
+
+  return {
+    mode,
+    reliance: semantics.reliance,
+    consoleUrl,
+    readTier: semantics.readTier,
+    vaultWriteMode: semantics.vaultWriteMode,
+    sources: {
+      mode: source,
+      reliance: source,
+      consoleUrl:
+        source === 'local-override' && local.record?.console_url ? 'local-override' : 'derived',
+      readTier: 'derived',
+      vaultWriteMode: 'derived',
+    },
+    localOverride: {
+      present: local.record !== null,
+      record: local.record,
+      parseError: local.parseError,
+      staleAgainstCloud,
+    },
+    cloudSetting: { known: cloudKnown, value: cloudValue },
+  };
+}
+
+/**
+ * Upsert top-level `key: value` lines in ~/.heyspex/credentials.yaml without a
+ * full YAML round-trip (same targeted approach as the vendor MCP `pair`
+ * writer and console-url-resolver's targeted read — the file carries
+ * hand-maintained blocks a naive parse/dump could reformat). Creates the
+ * directory/file with restrictive permissions when absent. Never repo files.
+ */
+export function upsertCredentialsYamlKeys(homeDir, updates) {
+  const dir = join(homeDir, '.heyspex');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const filePath = join(dir, 'credentials.yaml');
+  let content = '';
+  try {
+    content = readFileSync(filePath, 'utf8');
+  } catch {
+    content = '';
+  }
+  const lines = content.length > 0 ? content.split(/\r?\n/) : [];
+  for (const [key, value] of Object.entries(updates)) {
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`^${escapedKey}:.*$`);
+    const serialized = `${key}: ${value}`;
+    const idx = lines.findIndex((line) => pattern.test(line));
+    if (idx >= 0) lines[idx] = serialized;
+    else lines.push(serialized);
+  }
+  while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  writeFileSync(filePath, `${lines.join('\n')}\n`, { mode: 0o600 });
+  return filePath;
+}
+
+/** Targeted read of `mcp_token:` from credentials.yaml (bearer for cloud calls). */
+export function readCredentialsMcpToken({ homeDir = homedir() } = {}) {
+  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;
+  } catch {
+    return null;
+  }
+}
+
+/** Best-effort GET of the cloud admin setting via the console API. */
+export async function fetchCloudDevMode({
+  consoleUrl,
+  fetchImpl = fetch,
+  homeDir = homedir(),
+  timeoutMs = 4000,
+} = {}) {
+  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 body = await res.json();
+    return { ok: true, setting: body?.cloud ?? null, error: null };
+  } catch (err) {
+    return { ok: false, setting: undefined, error: String(err?.message ?? err) };
+  }
+}
+
+/** Raised by {@link applyDevMode} when the cloud confirms the caller is not an admin. */
+export class DevModeNotAdminError extends Error {
+  constructor() {
+    super('This account runs on HeySpex Cloud. Switching to local-disk mode is reserved for the HeySpex team\'s own build machines.');
+    this.name = 'DevModeNotAdminError';
+  }
+}
+
+/**
+ * THE SWITCHER — apply a mode change end to end:
+ *   0. LOCAL RELIANCE ONLY, and only when this machine is paired to a cloud
+ *      account (a stored mcp_token): confirm admin server-side via
+ *      POST /api/admin/dev-mode BEFORE touching anything on disk. A 403
+ *      throws {@link DevModeNotAdminError} — the whole switch is refused, the
+ *      local record is never written. An unpaired machine (no token — the
+ *      HeySpex team's own local checkout) has nothing to check against and
+ *      behaves exactly as before. A network failure here is NOT a role
+ *      verdict, so it falls through to step 3's best-effort behavior instead
+ *      of blocking the switch.
+ *   1. write ~/.heyspex/dev-mode.json (the cross-component contract file)
+ *   2. upsert `console_url:` in ~/.heyspex/credentials.yaml — rung 2 of the
+ *      shared console-url resolver, so MCP / hooks / dev-factory flip with it
+ *   3. best-effort write of the cloud account_settings row via the target
+ *      console's /api/admin/dev-mode (skipped/reported when unreachable, or
+ *      already done by step 0's precheck — never POSTed twice)
+ * Never edits repo-tracked files. Returns what happened, field by field.
+ *
+ * `target`: { mode: "prod"|"dev"|"local"|"cloud", reliance? } — local/cloud
+ * shorthands imply dev with that reliance.
+ */
+export async function applyDevMode(
+  target,
+  {
+    homeDir = homedir(),
+    fetchImpl = fetch,
+    source = 'cli',
+    now = () => new Date().toISOString(),
+    syncCloud = true,
+  } = {},
+) {
+  const parsed = normalizeMode(target?.mode);
+  if (!parsed) {
+    throw new Error(
+      `applyDevMode: invalid mode "${target?.mode}" (expected prod | dev | local | cloud)`,
+    );
+  }
+  const reliance =
+    parsed.reliance ?? normalizeReliance(target?.reliance) ?? 'local';
+  const mode = parsed.mode;
+  const semantics = deriveSemantics(mode, reliance);
+
+  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;
+  }
+
+  // 0. Authorization precheck — see the doc comment above.
+  let cloud = { attempted: false, updated: false, error: null };
+  if (syncCloud && semantics.reliance === 'local') {
+    const token = readCredentialsMcpToken({ homeDir });
+    if (token) {
+      try {
+        const res = await postCloud(token);
+        if (res.status === 403) throw new DevModeNotAdminError();
+        cloud = { attempted: true, updated: res.ok, error: res.ok ? null : `HTTP ${res.status}` };
+      } catch (err) {
+        if (err instanceof DevModeNotAdminError) throw err;
+        cloud = { attempted: true, updated: false, error: String(err?.message ?? err) };
+      }
+    }
+  }
+
+  // 1. machine-local record — EXACT contract shape, do not add/rename keys.
+  const record = {
+    mode,
+    reliance: semantics.reliance,
+    console_url: semantics.consoleUrl,
+    updated_at: now(),
+    source,
+  };
+  const dir = join(homeDir, '.heyspex');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const recordPath = devModeFilePath(homeDir);
+  writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+
+  // 2. credentials.yaml console_url (rung 2 of the shared resolver).
+  const credentialsPath = upsertCredentialsYamlKeys(homeDir, {
+    console_url: semantics.consoleUrl,
+  });
+
+  // 3. cloud account_settings row — best effort, never blocks the switch.
+  // Skipped when step 0 already attempted it (same endpoint, same payload).
+  if (syncCloud && !cloud.attempted) {
+    cloud = { attempted: true, updated: false, error: null };
+    try {
+      const token = readCredentialsMcpToken({ homeDir });
+      const res = await postCloud(token);
+      if (res.ok) cloud.updated = true;
+      else cloud.error = `HTTP ${res.status}`;
+    } catch (err) {
+      cloud.error = String(err?.message ?? err);
+    }
+  }
+
+  return {
+    applied: { mode, reliance: semantics.reliance, ...deriveSemantics(mode, reliance) },
+    record,
+    recordPath,
+    credentialsPath,
+    cloud,
+  };
+}

package/scripts/lib/hs-link.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * hs-link.mjs — "does `hs` on PATH actually run THIS checkout's bin/hs.mjs?"
+ *
+ * On a fresh clone nothing puts `hs` / `heyspex` / `heyspex-mcp` on PATH: the
+ * only thing that does is `npm link`, run once per machine from the repo root
+ * ([[HS-BFXF-WBJU-DIAG-hs-never-resolves-on-a-fresh-machine]]). `npm install`
+ * does not, and `npx hs` is actively harmful — `hs` is an unrelated package on
+ * the public registry, so `npx hs login` silently runs SOMEBODY ELSE'S tool and
+ * looks like nothing happened.
+ *
+ * Mere existence of a binary named `hs` therefore proves nothing. This module
+ * resolves the shim the shell would actually run and follows it to the script
+ * it executes, so three distinct failures read differently:
+ *
+ *   missing        — nothing named `hs` anywhere on PATH
+ *   foreign        — an `hs` that is not a HeySpex checkout at all (the npm
+ *                    package, or any other tool that grabbed the name)
+ *   other-checkout — a HeySpex `bin/hs.mjs`, but a DIFFERENT clone's. The most
+ *                    dangerous case: everything appears to work while `hs`
+ *                    reads another vault.
+ *
+ * Read-only by construction. Nothing here runs `npm link` — that mutates global
+ * machine state and is a human's call; callers report the remedy instead.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Filenames a shell would try for `name`, most-preferred first.
+ *
+ * Windows resolves via PATHEXT, and npm writes three shims per bin (`hs.cmd`
+ * for cmd/PowerShell, `hs.ps1`, and an extensionless `hs` sh script for Git
+ * Bash / MSYS). All three point at the same target, so any of them answers the
+ * question — `.cmd` leads because that is what a stock terminal runs.
+ */
+function candidateNames(name) {
+  return process.platform === 'win32'
+    ? [`${name}.cmd`, `${name}.exe`, `${name}.bat`, `${name}.ps1`, name]
+    : [name];
+}
+
+/**
+ * The file a shell would run for `name`, or null. Deliberately a PATH walk
+ * rather than shelling out to `where` / `which`: those are not on every box,
+ * and spawning a shell to answer "is this wired up" invites the quoting bugs
+ * `run()` in heyspex-doctor.mjs already documents.
+ */
+export function resolveOnPath(name, env = process.env) {
+  const dirs = (env.PATH ?? env.Path ?? '').split(path.delimiter).filter(Boolean);
+  for (const rawDir of dirs) {
+    const dir = rawDir.replace(/^"|"$/g, '');
+    for (const candidate of candidateNames(name)) {
+      const full = path.join(dir, candidate);
+      try {
+        if (fs.statSync(full).isFile()) return full;
+      } catch {
+        // Unreadable or nonexistent PATH entry — skip it, never throw.
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * The script a shim executes. npm's shims embed the target as a quoted,
+ * shim-relative path (`%dp0%\node_modules\<pkg>\bin\hs.mjs` in the .cmd,
+ * `$basedir/node_modules/...` in the sh and .ps1 forms); on POSIX npm instead
+ * symlinks the bin straight at the script. Handle both, and fall back to the
+ * shim itself so an unrelated `hs.exe` still yields a path worth printing.
+ */
+export function shimTarget(shimPath) {
+  try {
+    if (fs.lstatSync(shimPath).isSymbolicLink()) return fs.realpathSync(shimPath);
+  } catch {
+    return null;
+  }
+  let body;
+  try {
+    body = fs.readFileSync(shimPath, 'utf8');
+  } catch {
+    return shimPath; // a binary we cannot read is still "some other hs"
+  }
+  const dir = path.dirname(shimPath);
+  const quoted = body.match(/"[^"\r\n]*\.(?:mjs|cjs|js)"|'[^'\r\n]*\.(?:mjs|cjs|js)'/g) ?? [];
+  for (const raw of quoted) {
+    const expanded = raw
+      .slice(1, -1)
+      // A function replacement, not a string one: a shim directory containing
+      // `$` would otherwise be re-read as a `$&`-style replacement pattern.
+      .replace(/%~?dp0%?|\$basedir|\$\{?PSScriptRoot\}?/gi, () => dir)
+      .replace(/\//g, path.sep);
+    const abs = path.isAbsolute(expanded) ? expanded : path.resolve(dir, expanded);
+    if (fs.existsSync(abs)) return abs;
+  }
+  return shimPath;
+}
+
+/** Same file on disk? Resolves symlinks (npm link IS a symlink) and, on Windows, case. */
+export function samePath(a, b) {
+  const norm = (p) => {
+    let resolved;
+    try {
+      resolved = fs.realpathSync(p);
+    } catch {
+      resolved = path.resolve(p);
+    }
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+  };
+  return norm(a) === norm(b);
+}
+
+/** Does `target` look like SOME HeySpex checkout's bin/hs.mjs (just not ours)? */
+function looksLikeAHeySpexCheckout(target) {
+  if (path.basename(target).toLowerCase() !== 'hs.mjs') return false;
+  const pkgPath = path.join(path.dirname(path.dirname(target)), 'package.json');
+  try {
+    const name = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))?.name;
+    // `workflow-pm` is this package's former name — a link made before the
+    // rename still resolves here and is genuinely this repo, not a stranger.
+    return name === 'heyspex' || name === 'workflow-pm';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The whole answer, as data. `status` is one of:
+ *   linked | missing | foreign | other-checkout | unreadable
+ *
+ * `repoRoot` is the checkout being asked about — the one `npm link` would need
+ * to be run from.
+ */
+export function describeHsLink(repoRoot, { name = 'hs', env = process.env } = {}) {
+  const own = path.join(repoRoot, 'bin', 'hs.mjs');
+  const shim = resolveOnPath(name, env);
+  if (!shim) return { status: 'missing', name, shim: null, target: null, own };
+
+  const target = shimTarget(shim);
+  if (!target) return { status: 'unreadable', name, shim, target: null, own };
+  if (samePath(target, own)) return { status: 'linked', name, shim, target, own };
+  return {
+    status: looksLikeAHeySpexCheckout(target) ? 'other-checkout' : 'foreign',
+    name,
+    shim,
+    target,
+    own,
+  };
+}
+
+/** `npm link` is per-machine and links all three bins at once; report the strays. */
+export function missingSiblingBins(env = process.env) {
+  return ['heyspex', 'heyspex-mcp'].filter((n) => !resolveOnPath(n, env));
+}