heyspex 0.1.0 → 0.2.0

package/dist/cli/hs-dev.mjs

@@ -0,0 +1,564 @@
+import { createRequire as __hsCreateRequire } from 'node:module';
+const require = __hsCreateRequire(import.meta.url);
+
+// spex-console/bin/hs-dev.ts
+import process3 from "node:process";
+
+// spex-console/src/lib/dev-mode.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join2 } from "node:path";
+
+// vendor/heyspex-mcp/credentials.mjs
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import os, { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+function underTestRunner(env = process.env) {
+  return Boolean(env.VITEST) || Boolean(env.NODE_TEST_CONTEXT);
+}
+function samePathLoose(a, b) {
+  const norm = (p) => {
+    const r = resolve(p).replace(/[\\/]+$/, "");
+    return process.platform === "win32" ? r.toLowerCase() : r;
+  };
+  return norm(a) === norm(b);
+}
+function realUserHome() {
+  try {
+    const h = os.userInfo().homedir;
+    if (typeof h === "string" && h) return h;
+  } catch {
+  }
+  return null;
+}
+function assertNotRealHomeUnderTest(filePath) {
+  if (!underTestRunner()) return;
+  const real = realUserHome();
+  if (real && samePathLoose(dirname(filePath), join(real, ".heyspex"))) {
+    throw new Error(
+      `credentials: refusing to write ${filePath} under a test runner \u2014 that is the real ~/.heyspex directory. Point the test at a temp home.`
+    );
+  }
+}
+
+// spex-console/src/lib/dev-mode.ts
+var CLOUD_CONSOLE_URL = "https://app.heyspex.com";
+var LOCAL_CONSOLE_URL = "http://localhost:3000";
+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;
+}
+function normalizeDevModeInput(mode, reliance) {
+  const parsed = normalizeMode(mode);
+  if (!parsed) return null;
+  return {
+    mode: parsed.mode,
+    reliance: parsed.mode === "prod" ? "cloud" : parsed.reliance ?? normalizeReliance(reliance) ?? "local"
+  };
+}
+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"
+  };
+}
+function devModeFilePath(homeDir = homedir2()) {
+  return join2(homeDir, ".heyspex", "dev-mode.json");
+}
+var defaultReadFile = (p) => readFileSync2(p, "utf8");
+function readLocalDevModeRecord({
+  homeDir = homedir2(),
+  readFile = defaultReadFile
+} = {}) {
+  let raw;
+  try {
+    raw = readFile(devModeFilePath(homeDir));
+  } catch {
+    return { record: null, parseError: null };
+  }
+  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: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
+function resolveDevMode({
+  env = process.env,
+  homeDir = homedir2(),
+  readFile = defaultReadFile,
+  cloudSetting = void 0
+} = {}) {
+  const local = readLocalDevModeRecord({ homeDir, readFile });
+  const cloudKnown = cloudSetting !== void 0;
+  const cloudValue = cloudKnown && cloudSetting ? {
+    mode: cloudSetting.mode === "dev" ? "dev" : "prod",
+    reliance: normalizeReliance(cloudSetting.reliance) ?? "cloud"
+  } : null;
+  let mode;
+  let reliance;
+  let source;
+  let relianceSource = null;
+  const envParsed = normalizeMode(env.HEYSPEX_DEV_MODE);
+  if (envParsed) {
+    mode = envParsed.mode;
+    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;
+    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);
+  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: relianceSource ?? 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 }
+  };
+}
+function modeOverrideOf(resolved) {
+  if (!resolved) return null;
+  const cloud = resolved.cloudSetting.value;
+  if (resolved.sources.mode === "env") {
+    const disagrees = cloud !== null && (cloud.mode !== resolved.mode || resolved.mode === "dev" && cloud.reliance !== resolved.reliance);
+    return {
+      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: "dev-mode.json",
+      written_at: record?.updated_at ?? null,
+      written_by: record?.source ?? null,
+      disagrees_with_cloud: resolved.localOverride.staleAgainstCloud === true
+    };
+  }
+  return null;
+}
+function buildDevStatusJson(resolved, cloudError) {
+  return { resolved, cloudError, mode_override: modeOverrideOf(resolved) };
+}
+function upsertCredentialsYamlKeys(homeDir, updates, deps = {}) {
+  const readFile = deps.readFile ?? defaultReadFile;
+  const writeFile = deps.writeFile ?? ((p, c) => writeFileSync2(p, c, { mode: 384 }));
+  const mkdir = deps.mkdir ?? ((p) => mkdirSync2(p, { recursive: true, mode: 448 }));
+  const dir = join2(homeDir, ".heyspex");
+  const filePath = join2(dir, "credentials.yaml");
+  if (!deps.writeFile) assertNotRealHomeUnderTest(filePath);
+  mkdir(dir);
+  let content = "";
+  try {
+    content = readFile(filePath);
+  } 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();
+  writeFile(filePath, `${lines.join("\n")}
+`);
+  return filePath;
+}
+function readCredentialsMcpToken({
+  homeDir = homedir2(),
+  readFile = defaultReadFile
+} = {}) {
+  try {
+    const raw = readFile(join2(homeDir, ".heyspex", "credentials.yaml"));
+    const match = raw.match(/^mcp_token:\s*["']?([^"'\r\n#]+)/m);
+    return match?.[1]?.trim() || null;
+  } catch {
+    return null;
+  }
+}
+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);
+  }
+}
+async function discardResponseBody(res) {
+  try {
+    await res?.body?.cancel();
+  } catch {
+  }
+}
+async function fetchCloudDevMode({
+  consoleUrl,
+  fetchImpl = fetch,
+  homeDir = homedir2(),
+  readFile = defaultReadFile,
+  timeoutMs = 4e3
+}) {
+  try {
+    const token = readCredentialsMcpToken({ homeDir, readFile });
+    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 { known: false, value: null, error: `HTTP ${res.status}` };
+    }
+    const body = await res.json();
+    if (body.cloudKnown === false)
+      return { known: false, value: null, error: "storage unavailable" };
+    const cloud = body.cloud;
+    return {
+      known: true,
+      value: cloud ? normalizeDevModeInput(cloud.mode, cloud.reliance) : null,
+      error: null
+    };
+  } catch (err) {
+    return { known: false, value: null, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+var DevModeNotAdminError = class 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";
+  }
+};
+async function applyDevMode(targetMode, targetReliance, deps = {}) {
+  const {
+    homeDir = homedir2(),
+    fetchImpl = fetch,
+    source = "cli",
+    now = () => (/* @__PURE__ */ new Date()).toISOString(),
+    syncCloud = true
+  } = deps;
+  const writeFile = deps.writeFile ?? ((p, c) => writeFileSync2(p, c, "utf8"));
+  const mkdir = deps.mkdir ?? ((p) => mkdirSync2(p, { recursive: true, mode: 448 }));
+  const parsed = normalizeMode(targetMode);
+  if (!parsed) {
+    throw new Error(
+      `applyDevMode: invalid mode "${targetMode}" (expected prod | dev | local | cloud)`
+    );
+  }
+  const mode = parsed.mode;
+  const reliance = parsed.reliance ?? normalizeReliance(targetReliance) ?? "local";
+  const semantics = deriveSemantics(mode, reliance);
+  if (!deps.writeFile) assertNotRealHomeUnderTest(devModeFilePath(homeDir));
+  async function postCloud(token) {
+    return withRequestTimeout(
+      5e3,
+      (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
+      })
+    );
+  }
+  let cloud = { attempted: false, updated: false, error: null };
+  if (syncCloud && semantics.reliance === "local") {
+    const token = readCredentialsMcpToken({ homeDir, readFile: deps.readFile });
+    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) {
+        if (err instanceof DevModeNotAdminError) throw err;
+        cloud = {
+          attempted: true,
+          updated: false,
+          error: err instanceof Error ? err.message : String(err)
+        };
+      }
+    }
+  }
+  const record = {
+    mode,
+    reliance: semantics.reliance,
+    console_url: semantics.consoleUrl,
+    updated_at: now(),
+    source
+  };
+  mkdir(join2(homeDir, ".heyspex"));
+  const recordPath = devModeFilePath(homeDir);
+  writeFile(recordPath, `${JSON.stringify(record, null, 2)}
+`);
+  const credentialsPath = upsertCredentialsYamlKeys(
+    homeDir,
+    { console_url: semantics.consoleUrl },
+    { readFile: deps.readFile, writeFile: deps.writeFile, mkdir: deps.mkdir }
+  );
+  if (syncCloud && !cloud.attempted) {
+    cloud = { attempted: true, updated: false, error: null };
+    try {
+      const token = readCredentialsMcpToken({ homeDir, readFile: deps.readFile });
+      const res = await postCloud(token);
+      if (res.ok) cloud.updated = true;
+      else cloud.error = `HTTP ${res.status}`;
+      await discardResponseBody(res);
+    } catch (err) {
+      cloud.error = err instanceof Error ? err.message : String(err);
+    }
+  }
+  return {
+    applied: {
+      mode,
+      reliance: semantics.reliance,
+      consoleUrl: semantics.consoleUrl,
+      readTier: semantics.readTier,
+      vaultWriteMode: semantics.vaultWriteMode
+    },
+    record,
+    recordPath,
+    credentialsPath,
+    cloud
+  };
+}
+
+// spex-console/bin/run-entry.ts
+import process2 from "node:process";
+var BinExit = class extends Error {
+  code;
+  constructor(code) {
+    super(`exit ${code}`);
+    this.name = "BinExit";
+    this.code = code;
+  }
+};
+function runEntry(name, main2, options = {}) {
+  const { fallbackCode = 1, unhandledLabel = "unhandled" } = options;
+  void (async () => {
+    try {
+      await main2();
+    } catch (err) {
+      if (err instanceof BinExit) {
+        process2.exitCode = err.code;
+        return;
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      process2.stderr.write(`${name}: ${unhandledLabel}: ${message}
+`);
+      process2.exitCode = fallbackCode;
+    }
+  })();
+}
+
+// spex-console/bin/hs-dev.ts
+var HELP = `hs dev \u2014 dev/prod mode + local/cloud reliance
+
+Usage:
+  hs dev [--json]              Show the resolved mode and the source of each value
+  hs dev mode:local            Switch to dev mode, local reliance (localhost console, disk reads, local writes)
+  hs dev mode:cloud            Switch to dev mode, cloud reliance (cloud console, Neon reads, cloud writes)
+  hs dev mode:prod             Switch to prod (cloud console, Neon reads, cloud writes)
+  hs dev local|cloud|prod      Shorthand for the mode:* forms
+
+Resolution order: env (HEYSPEX_DEV_MODE) \u2192 ~/.heyspex/dev-mode.json \u2192
+cloud admin setting (account_settings.dev_mode) \u2192 default prod.
+
+Switching writes ~/.heyspex/dev-mode.json and console_url in
+~/.heyspex/credentials.yaml (which repoints MCP/hooks/dev-factory via the
+shared console-url resolver), and best-effort updates the cloud admin setting.
+Never touches repo-tracked files.`;
+var SOURCE_LABEL = {
+  env: "env override",
+  "local-override": "local override (~/.heyspex/dev-mode.json)",
+  "cloud-setting": "cloud admin setting",
+  default: "default",
+  derived: "derived",
+  // HS-EVVI AC1: HEYSPEX_DEV_MODE=dev with no HEYSPEX_DEV_RELIANCE is never
+  // silently local any more — the row says the reliance was assumed.
+  "assumed-local": "ASSUMED local \u2014 HEYSPEX_DEV_MODE=dev names no reliance; set HEYSPEX_DEV_RELIANCE"
+};
+function describeCloudFailure(cloudError) {
+  if (cloudError === "HTTP 401") {
+    return "not signed in on this machine (HTTP 401) \u2014 run `hs login`";
+  }
+  return `unavailable${cloudError ? ` (${cloudError})` : ""}`;
+}
+function printStatus(resolved, cloudError) {
+  const rows = [
+    ["mode", resolved.mode, resolved.sources.mode],
+    ["reliance", resolved.reliance, resolved.sources.reliance],
+    ["console URL", resolved.consoleUrl, resolved.sources.consoleUrl],
+    ["read tier", resolved.readTier, resolved.sources.readTier],
+    ["vault writes", resolved.vaultWriteMode, resolved.sources.vaultWriteMode]
+  ];
+  const out = ["hs dev \u2014 resolved mode", ""];
+  for (const [label, value, source] of rows) {
+    out.push(`  ${label.padEnd(13)}${value.padEnd(28)}${SOURCE_LABEL[source] ?? source}`);
+  }
+  out.push("");
+  if (resolved.sources.mode === "env") {
+    out.push(
+      "  env override:   active (HEYSPEX_DEV_MODE) \u2014 hides the local record and the cloud setting"
+    );
+  }
+  if (resolved.localOverride.present) {
+    const rec = resolved.localOverride.record;
+    out.push(
+      `  local override: active (written ${rec?.updated_at ?? "?"} by ${rec?.source ?? "?"})` + (resolved.localOverride.staleAgainstCloud ? " \u2014 DISAGREES with the cloud setting (stale override?)" : "")
+    );
+  } else if (resolved.localOverride.parseError) {
+    out.push(`  local override: UNREADABLE, ignored \u2014 ${resolved.localOverride.parseError}`);
+  } else {
+    out.push("  local override: none");
+  }
+  if (resolved.cloudSetting.known) {
+    const v = resolved.cloudSetting.value;
+    out.push(
+      v ? `  cloud setting:  ${v.mode}${v.mode === "dev" ? ` (${v.reliance})` : ""}` : "  cloud setting:  unset"
+    );
+  } else {
+    out.push(`  cloud setting:  ${describeCloudFailure(cloudError)}`);
+  }
+  process3.stdout.write(`${out.join("\n")}
+`);
+}
+async function main() {
+  const argv = process3.argv.slice(3);
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process3.stdout.write(`${HELP}
+`);
+    process3.exitCode = 0;
+    return;
+  }
+  const json = argv.includes("--json");
+  const positional = argv.filter((a) => !a.startsWith("--"));
+  const token = positional[0]?.toLowerCase();
+  if (token === void 0 || token === "status") {
+    const pre = resolveDevMode();
+    const cloud = await fetchCloudDevMode({ consoleUrl: pre.consoleUrl });
+    const resolved = resolveDevMode({ cloudSetting: cloud.known ? cloud.value : void 0 });
+    if (json) {
+      process3.stdout.write(
+        `${JSON.stringify(buildDevStatusJson(resolved, cloud.error), null, 2)}
+`
+      );
+    } else {
+      printStatus(resolved, cloud.error);
+    }
+    process3.exitCode = 0;
+    return;
+  }
+  const modeToken = token.startsWith("mode:") ? token.slice("mode:".length) : token;
+  if (!["local", "cloud", "prod", "dev"].includes(modeToken)) {
+    process3.stderr.write(`hs dev: unknown subcommand \`${token}\`
+
+${HELP}
+`);
+    process3.exitCode = 2;
+    return;
+  }
+  try {
+    const result = await applyDevMode(modeToken, positional[1] ?? null, { source: "cli" });
+    if (json) {
+      process3.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    } else {
+      const a = result.applied;
+      const lines = [
+        `Switched to ${a.mode}${a.mode === "dev" ? ` (${a.reliance})` : ""}:`,
+        `  console URL   ${a.consoleUrl}`,
+        `  read tier     ${a.readTier}`,
+        `  vault writes  ${a.vaultWriteMode}`,
+        `  wrote ${result.recordPath}`,
+        `  wrote console_url in ${result.credentialsPath}`,
+        result.cloud.attempted ? result.cloud.updated ? "  cloud admin setting updated" : `  cloud admin setting NOT updated (${result.cloud.error}) \u2014 local files still switched` : "  cloud sync skipped"
+      ];
+      process3.stdout.write(`${lines.join("\n")}
+`);
+    }
+    process3.exitCode = 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process3.stderr.write(`hs dev: ${message}
+`);
+    process3.exitCode = 1;
+  }
+}
+runEntry("hs dev", main, { fallbackCode: 1 });