heyspex 0.2.1 → 0.2.3

package/dist/cli/hs-defer.mjs

@@ -234,6 +234,11 @@ function readLocalDevModeRecord({ homeDir = heyspexHome(), readFile = defaultRea
     return { record: null, parseError: `unparseable dev-mode.json: ${String(err?.message ?? err)}` };
   }
 }
+function overrideCloudCheck(source, cloudKnown, staleAgainstCloud) {
+  if (source !== "local-override") return "not-applicable";
+  if (!cloudKnown) return "unverified";
+  return staleAgainstCloud ? "stale" : "in-sync";
+}
 function resolveDevMode({
   env = process.env,
   homeDir = heyspexHome(),
@@ -273,6 +278,7 @@ function resolveDevMode({
   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);
+  const cloudCheck = overrideCloudCheck(source, cloudKnown, staleAgainstCloud);
   return {
     mode,
     reliance: semantics.reliance,
@@ -290,7 +296,8 @@ function resolveDevMode({
       present: local.record !== null,
       record: local.record,
       parseError: local.parseError,
-      staleAgainstCloud
+      staleAgainstCloud,
+      cloudCheck
     },
     cloudSetting: { known: cloudKnown, value: cloudValue }
   };
@@ -3615,7 +3622,7 @@ var init_satellite = __esm({
 });
 
 // spex-console/src/lib/vault-resolve/index.ts
-import { existsSync as existsSync2, readFileSync as readFileSync7 } from "node:fs";
+import { existsSync as existsSync2, readFileSync as readFileSync7, realpathSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path2 from "node:path";
 async function defaultRegistryLookup() {
@@ -3669,8 +3676,44 @@ function readMarkerSatellite(dir) {
 function isVaultRootDir(dir) {
   const norm = (p) => path2.resolve(p).replace(/[\\/]+/g, "/").replace(/\/+$/, "").toLowerCase();
   if (norm(dir) === norm(tmpdir())) return false;
+  if (!existsSync2(path2.join(dir, "specs")) && readRepoBinding(dir)) return false;
   return existsSync2(path2.join(dir, "heyspex.yaml")) || existsSync2(path2.join(dir, "specs"));
 }
+function parseRepoBinding(content) {
+  const src = String(content ?? "");
+  if (/^(vault_id|vault_root):/m.test(src)) return null;
+  const kind = src.match(/^kind:\s*(.+?)\s*$/m)?.[1]?.replace(/^["']|["']$/g, "").trim();
+  if (kind && kind !== "repo-binding") return null;
+  const lines = src.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^vault:(\s|$)/.test(l));
+  if (start === -1) return null;
+  const unq = (v) => v.trim().replace(/\s+#.*$/, "").replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1").trim();
+  const scalar = lines[start].slice("vault:".length).trim();
+  if (scalar && !scalar.startsWith("#")) {
+    const id = unq(scalar);
+    return id ? { id, name: null, remote: null } : null;
+  }
+  const out = {
+    id: null,
+    name: null,
+    remote: null
+  };
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const l = lines[i];
+    if (!l.trim() || /^\s*#/.test(l)) continue;
+    if (!/^\s+/.test(l)) break;
+    const m = l.match(/^\s+([a-z_]+):\s*(.*)$/);
+    if (m && (m[1] === "id" || m[1] === "name" || m[1] === "remote")) out[m[1]] = unq(m[2]) || null;
+  }
+  return out.id ? { id: out.id, name: out.name, remote: out.remote } : null;
+}
+function readRepoBinding(dir) {
+  try {
+    return parseRepoBinding(readFileSync7(path2.join(dir, "heyspex.yaml"), "utf8"));
+  } catch {
+    return null;
+  }
+}
 function findCwdVaultOrAttachment(startDir, stopAt) {
   const deps = {
     fileExists: (p) => existsSync2(p),
@@ -3697,6 +3740,8 @@ function findCwdVaultOrAttachment(startDir, stopAt) {
     const pinned = readPinnedVaultRoot(dir, deps).find((pin) => !isAtOrUnder(pin.value, dir));
     if (pinned) return { repoRootAbs: path2.resolve(pinned.value), satellite: true };
     if (isVaultRootDir(dir)) return { repoRootAbs: dir, satellite: false };
+    const binding = readRepoBinding(dir);
+    if (binding) return { repoRootAbs: dir, satellite: false, binding };
     if (boundary && dir === boundary) return null;
     const parent = path2.dirname(dir);
     if (parent === dir) return null;
@@ -3704,6 +3749,22 @@ function findCwdVaultOrAttachment(startDir, stopAt) {
   }
   return null;
 }
+function isExistingDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function envNotVaultError(name, raw, abs, from) {
+  const shown = abs.replace(/\\/g, "/");
+  return new VaultResolutionFailure(
+    "VAULT_NOT_FOUND",
+    `${name}=${raw} does not name a vault checkout (${shown}). Unset ${name} so the vault bound to this repo is used (\`hs vault resolve\` shows it), or point it at a vault checkout.`,
+    `unset ${name}`,
+    from
+  );
+}
 async function resolveActiveVaultRoot(options2 = {}) {
   const registryLookup = options2.registryLookup ?? defaultRegistryLookup;
   const accountPointerLookup = options2.accountPointerLookup ?? defaultAccountPointerLookup;
@@ -3735,8 +3796,70 @@ async function resolveActiveVaultRoot(options2 = {}) {
       detail: `explicit vaultId "${options2.vaultId}" has no registry.json row and no Neon row`
     });
   }
-  const cwdBase = path2.resolve(options2.cwd ?? process.cwd());
+  const fromDir = path2.resolve(options2.cwd ?? process.cwd());
+  const envRoot = process.env.HEYSPEX_VAULT_ROOT;
+  if (envRoot) {
+    const root = path2.resolve(envRoot.trim());
+    const envIsVault = isExistingDir(root) && isVaultRootDir(root);
+    if (!envIsVault && !await registryLookupByRoot(root)) {
+      onTier({
+        tier: "env-vault-root",
+        outcome: "empty",
+        detail: `${envRoot} is not a vault checkout`
+      });
+      throw envNotVaultError("HEYSPEX_VAULT_ROOT", envRoot, root, fromDir);
+    }
+    onTier({ tier: "env-vault-root", outcome: "resolved", detail: envRoot });
+    return finalizePathTier(root, "env-vault-root");
+  }
+  onTier({ tier: "env-vault-root", outcome: "skipped", detail: "HEYSPEX_VAULT_ROOT unset" });
+  const envDir = process.env.HEYSPEX_VAULT_DIR;
+  if (envDir) {
+    const specsDirFromEnv = path2.resolve(envDir.trim());
+    const envDirIsSpecs = isExistingDir(specsDirFromEnv) && path2.basename(specsDirFromEnv).toLowerCase() === "specs";
+    const envDirRegistered = Boolean(await registryLookupByRoot(path2.dirname(specsDirFromEnv)));
+    if (!envDirIsSpecs && !envDirRegistered) {
+      onTier({
+        tier: "env-vault-dir",
+        outcome: "empty",
+        detail: `${envDir} is not a specs/ folder`
+      });
+      throw envNotVaultError("HEYSPEX_VAULT_DIR", envDir, specsDirFromEnv, fromDir);
+    }
+    onTier({ tier: "env-vault-dir", outcome: "resolved", detail: envDir });
+    return finalizePathTier(path2.dirname(specsDirFromEnv), "env-vault-dir");
+  }
+  onTier({ tier: "env-vault-dir", outcome: "skipped", detail: "HEYSPEX_VAULT_DIR unset" });
+  let cwdBase = path2.resolve(options2.cwd ?? process.cwd());
+  try {
+    cwdBase = realpathSync(cwdBase);
+  } catch {
+  }
   const cwdMatch = findCwdVaultOrAttachment(cwdBase, options2.cwdWalkRoot);
+  if (cwdMatch?.binding) {
+    const record = await registryLookup(cwdMatch.binding.id);
+    const root = record ? record.repoRootAbs : null;
+    if (root) {
+      onTier({
+        tier: "repo-binding",
+        outcome: "resolved",
+        detail: `${cwdMatch.repoRootAbs} -> ${cwdMatch.binding.id}`
+      });
+      return finalize(cwdMatch.binding.id, root, "repo-binding");
+    }
+    onTier({
+      tier: "repo-binding",
+      outcome: "no-registry-row",
+      detail: `${cwdMatch.repoRootAbs}/heyspex.yaml binds ${cwdMatch.binding.id}, which has no registry row (or folder) on this machine`
+    });
+    const bindingDir = cwdMatch.repoRootAbs.replace(/\\/g, "/");
+    throw new VaultResolutionFailure(
+      "VAULT_BINDING_BROKEN",
+      `${bindingDir}/heyspex.yaml binds this repo to vault ${cwdMatch.binding.name ?? cwdMatch.binding.id} (${cwdMatch.binding.id}), but this machine has no registered checkout of it. Clone it (or \`hs pull\` in an existing checkout), \`hs vault register <path>\`, then \`hs vault bind --vault ${cwdMatch.binding.id}\` in ${bindingDir}.`,
+      `hs vault bind --vault ${cwdMatch.binding.id}`,
+      cwdBase
+    );
+  }
   if (cwdMatch?.satellite) {
     onTier({ tier: "satellite-pin", outcome: "resolved", detail: cwdMatch.repoRootAbs });
     if (cwdMatch.markerVaultId) {
@@ -3744,7 +3867,7 @@ async function resolveActiveVaultRoot(options2 = {}) {
     }
     return finalizePathTier(cwdMatch.repoRootAbs, "satellite-pin");
   }
-  if (cwdMatch) {
+  if (cwdMatch && !cwdMatch.binding) {
     const root = path2.resolve(cwdMatch.repoRootAbs);
     const record = await registryLookupByRoot(root);
     const markerVaultId = readMarkerVaultId(root);
@@ -3768,19 +3891,18 @@ async function resolveActiveVaultRoot(options2 = {}) {
     outcome: "empty",
     detail: `no satellite pin, heyspex.yaml or specs/ at or above ${cwdBase}`
   });
-  const envRoot = process.env.HEYSPEX_VAULT_ROOT;
-  if (envRoot) {
-    onTier({ tier: "env-vault-root", outcome: "resolved", detail: envRoot });
-    return finalizePathTier(path2.resolve(envRoot), "env-vault-root");
-  }
-  onTier({ tier: "env-vault-root", outcome: "skipped", detail: "HEYSPEX_VAULT_ROOT unset" });
-  const envDir = process.env.HEYSPEX_VAULT_DIR;
-  if (envDir) {
-    const specsDirFromEnv = path2.resolve(envDir);
-    onTier({ tier: "env-vault-dir", outcome: "resolved", detail: envDir });
-    return finalizePathTier(path2.dirname(specsDirFromEnv), "env-vault-dir");
+  if (!options2.allowAccountPointer) {
+    onTier({
+      tier: "account-pointer",
+      outcome: "skipped",
+      detail: "account pointer retired for local resolution (HS-TYJA)"
+    });
+    const unbound = new NoActiveVaultError(
+      `No HeySpex vault is bound to ${cwdBase.replace(/\\/g, "/")}, and it is not inside a vault checkout. There is no default "active" vault. Bind this repo: \`hs vault bind --vault <name|id>\` (register a vault checkout first with \`hs vault register <path>\` if \`hs vault list\` shows none).`
+    );
+    unbound.from = cwdBase.replace(/\\/g, "/");
+    throw unbound;
   }
-  onTier({ tier: "env-vault-dir", outcome: "skipped", detail: "HEYSPEX_VAULT_DIR unset" });
   const pointerVaultId = await accountPointerLookup(options2.accountId);
   if (pointerVaultId) {
     const record = await registryLookup(pointerVaultId);
@@ -3802,7 +3924,7 @@ async function resolveActiveVaultRoot(options2 = {}) {
   }
   throw new NoActiveVaultError();
 }
-var UNREGISTERED_VAULT_ID, NoActiveVaultError;
+var UNREGISTERED_VAULT_ID, NoActiveVaultError, VaultResolutionFailure;
 var init_vault_resolve = __esm({
   "spex-console/src/lib/vault-resolve/index.ts"() {
     "use strict";
@@ -3814,6 +3936,22 @@ var init_vault_resolve = __esm({
         this.name = "NoActiveVaultError";
         Object.setPrototypeOf(this, _NoActiveVaultError.prototype);
       }
+      /** Stable machine code ([[HS-TYJA]]), shared with `vault-binding.mjs`. */
+      code = "VAULT_UNBOUND";
+      /** The exact repair command. */
+      fix = "hs vault bind --vault <name|id>";
+      /** The folder resolution walked from (forward slashes), when known. */
+      from = null;
+    };
+    VaultResolutionFailure = class _VaultResolutionFailure extends NoActiveVaultError {
+      constructor(code, message, fix, from) {
+        super(message);
+        this.name = "VaultResolutionError";
+        this.code = code;
+        this.fix = fix;
+        this.from = from ? from.replace(/\\/g, "/") : null;
+        Object.setPrototypeOf(this, _VaultResolutionFailure.prototype);
+      }
     };
   }
 });
@@ -4484,7 +4622,11 @@ async function ensureActiveVaultResolved(options2 = {}) {
       registryLookup: buildRegistryLookup(options2),
       accountPointerLookup: buildAccountPointerLookup(accountId, options2),
       registryLookupByRoot: buildRegistryLookupByRoot(options2.registryOpts),
-      onTier: recordVaultResolveTier
+      onTier: recordVaultResolveTier,
+      // Cloud console server: no repo on disk to walk, so the account pointer
+      // is still its last resort until every request names its vault
+      // (follow-up to [[HS-TYJA]]; local resolvers never read it).
+      allowAccountPointer: true
     });
   } catch (err) {
     markVaultResolveFailed(err);
@@ -9523,7 +9665,7 @@ var init_search_body_hit = __esm({
 
 // spex-console/src/lib/vault.ts
 import { spawn } from "node:child_process";
-import { readdirSync, readFileSync as readFileSync9, statSync } from "node:fs";
+import { readdirSync, readFileSync as readFileSync9, statSync as statSync2 } from "node:fs";
 import { promises as fs6 } from "node:fs";
 import path11 from "node:path";
 import yaml3 from "js-yaml";

package/dist/cli/hs-dev.mjs

@@ -56,6 +56,11 @@ function assertNotRealHomeUnderTest(filePath) {
 // spex-console/src/lib/dev-mode.ts
 var CLOUD_CONSOLE_URL = "https://app.heyspex.com";
 var LOCAL_CONSOLE_URL = "http://localhost:3000";
+function overrideCloudCheck(source, cloudKnown, staleAgainstCloud) {
+  if (source !== "local-override") return "not-applicable";
+  if (!cloudKnown) return "unverified";
+  return staleAgainstCloud ? "stale" : "in-sync";
+}
 function normalizeMode(raw) {
   const v = String(raw ?? "").trim().toLowerCase();
   if (v === "prod" || v === "production") return { mode: "prod", reliance: "cloud" };
@@ -163,6 +168,7 @@ function resolveDevMode({
   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);
+  const cloudCheck = overrideCloudCheck(source, cloudKnown, staleAgainstCloud);
   return {
     mode,
     reliance: semantics.reliance,
@@ -180,7 +186,8 @@ function resolveDevMode({
       present: local.record !== null,
       record: local.record,
       parseError: local.parseError,
-      staleAgainstCloud
+      staleAgainstCloud,
+      cloudCheck
     },
     cloudSetting: { known: cloudKnown, value: cloudValue }
   };
@@ -275,7 +282,7 @@ async function discardResponseBody(res) {
   }
 }
 async function fetchCloudDevMode({
-  consoleUrl,
+  consoleUrl = CLOUD_CONSOLE_URL,
   fetchImpl = fetch,
   homeDir = heyspexHome(),
   readFile = defaultReadFile,
@@ -493,7 +500,7 @@ function printStatus(resolved, cloudError) {
   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?)" : "")
+      `  local override: active (written ${rec?.updated_at ?? "?"} by ${rec?.source ?? "?"})` + (resolved.localOverride.cloudCheck === "stale" ? " \u2014 DISAGREES with the cloud setting (stale override?)" : resolved.localOverride.cloudCheck === "unverified" ? " \u2014 UNVERIFIED: the cloud setting could not be read, so staleness is unknown" : "")
     );
   } else if (resolved.localOverride.parseError) {
     out.push(`  local override: UNREADABLE, ignored \u2014 ${resolved.localOverride.parseError}`);
@@ -523,8 +530,7 @@ async function main() {
   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 cloud = await fetchCloudDevMode({ consoleUrl: CLOUD_CONSOLE_URL });
     const resolved = resolveDevMode({ cloudSetting: cloud.known ? cloud.value : void 0 });
     if (json) {
       process3.stdout.write(