heyspex 0.2.2 → 0.2.4

package/dist/cli/hs-workspace.mjs

@@ -124,9 +124,9 @@ function resolveBearer({ envToken, credentialsText, accountId: accountId2, legac
   if (entry?.mcp_token) return { token: entry.mcp_token, source: "credentials-file" };
   return { token: null, source: null };
 }
-function readTextOrNull(read, path4) {
+function readTextOrNull(read, path5) {
   try {
-    const raw = read(path4);
+    const raw = read(path5);
     return typeof raw === "string" ? raw : null;
   } catch {
     return null;
@@ -174,8 +174,8 @@ var init_credentials = __esm({
 });
 
 // scripts/lib/dev-mode.mjs
-import { mkdirSync as mkdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
-import { homedir as homedir7 } from "node:os";
+import { mkdirSync as mkdirSync5, readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "node:fs";
+import { homedir as homedir8 } from "node:os";
 import { join as join8 } from "node:path";
 function devModeFilePath(homeDir = heyspexHome()) {
   return join8(homeDir, ".heyspex", DEV_MODE_FILENAME);
@@ -230,6 +230,11 @@ function readLocalDevModeRecord({ homeDir = heyspexHome(), readFile: readFile2 =
     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(),
@@ -269,6 +274,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,
@@ -286,7 +292,8 @@ function resolveDevMode({
       present: local.record !== null,
       record: local.record,
       parseError: local.parseError,
-      staleAgainstCloud
+      staleAgainstCloud,
+      cloudCheck
     },
     cloudSetting: { known: cloudKnown, value: cloudValue }
   };
@@ -300,7 +307,7 @@ var init_dev_mode = __esm({
     CLOUD_CONSOLE_URL = "https://app.heyspex.com";
     LOCAL_CONSOLE_URL = "http://localhost:3000";
     DEV_MODE_FILENAME = "dev-mode.json";
-    defaultReadFile = (p) => readFileSync7(p, "utf8");
+    defaultReadFile = (p) => readFileSync8(p, "utf8");
   }
 });
 
@@ -2053,13 +2060,13 @@ var init_postgres = __esm({
 });
 
 // spex-console/bin/hs-workspace.ts
-import { readFileSync as readFileSync10 } from "node:fs";
-import path3 from "node:path";
+import { readFileSync as readFileSync11 } from "node:fs";
+import path4 from "node:path";
 import process4 from "node:process";
 import { createInterface as createInterface2 } from "node:readline/promises";
 
 // spex-console/src/lib/cli/control-shared.ts
-import path from "node:path";
+import path2 from "node:path";
 
 // scripts/lib/hs-command.mjs
 import { existsSync } from "node:fs";
@@ -2082,8 +2089,8 @@ var HS_DISPATCHER_PREFIX = HS_DISPATCHER_PATH ? `node ${shellQuote(HS_DISPATCHER
 // vendor/heyspex-mcp/console-fetch.mjs
 init_heyspex_home();
 init_credentials();
-import { readFileSync as readFileSync5 } from "node:fs";
-import { homedir as homedir5 } from "node:os";
+import { readFileSync as readFileSync6 } from "node:fs";
+import { homedir as homedir6 } from "node:os";
 import { join as join6 } from "node:path";
 
 // vendor/heyspex-mcp/session-owner.mjs
@@ -2108,14 +2115,14 @@ var VAULT_LESS_ENDPOINTS = Object.freeze([
   "GET /api/workspaces",
   "* /api/admin/dev-mode"
 ]);
-function pathnameOf(path4) {
-  const raw = String(path4 ?? "").split("?")[0].split("#")[0];
+function pathnameOf(path5) {
+  const raw = String(path5 ?? "").split("?")[0].split("#")[0];
   const noTrailing = raw.length > 1 ? raw.replace(/\/+$/, "") : raw;
   return noTrailing || "/";
 }
-function isVaultLessEndpoint(method, path4) {
+function isVaultLessEndpoint(method, path5) {
   const m = String(method || "GET").toUpperCase();
-  const pathname = pathnameOf(path4);
+  const pathname = pathnameOf(path5);
   return VAULT_LESS_ENDPOINTS.some((row) => {
     const [rowMethod, rowPath] = row.split(" ");
     return rowPath === pathname && (rowMethod === "*" || rowMethod === m);
@@ -2135,7 +2142,9 @@ import {
 import { basename, join as join4, isAbsolute as isAbsolute2 } from "node:path";
 
 // scripts/lib/shared-path-helpers.mjs
+import { realpathSync } from "node:fs";
 import { isAbsolute, resolve as resolve2, sep } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 function resolveCodeRoot({
   explicit,
   packageRoot,
@@ -2154,9 +2163,30 @@ function resolveCodeRoot({
 
 // vendor/heyspex-mcp/vault-resolve.mjs
 init_heyspex_home();
-import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
-import { homedir as homedir4, tmpdir } from "node:os";
-import { dirname as dirname3, join as join5, resolve as resolve3 } from "node:path";
+import { existsSync as existsSync4, readFileSync as readFileSync5, realpathSync as realpathSync3, statSync as statSync3 } from "node:fs";
+import { homedir as homedir5, tmpdir } from "node:os";
+
+// vendor/heyspex-mcp/usable-dir-env.mjs
+import { statSync } from "node:fs";
+import { isAbsolute as isAbsolute3 } from "node:path";
+
+// vendor/heyspex-mcp/vault-resolve.mjs
+import { basename as basename2, dirname as dirname3, join as join5, resolve as resolve3 } from "node:path";
+
+// vendor/heyspex-mcp/vault-binding.mjs
+import {
+  copyFileSync,
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync4,
+  realpathSync as realpathSync2,
+  renameSync as renameSync3,
+  statSync as statSync2,
+  unlinkSync,
+  writeFileSync as writeFileSync3
+} from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import path from "node:path";
 
 // vendor/heyspex-mcp/console-fetch.mjs
 var SCOPE_REFUSAL_CODES = Object.freeze(["VAULT_SCOPE_MISMATCH", "ACCOUNT_MISMATCH", "VAULT_NOT_REGISTERED"]);
@@ -2165,17 +2195,17 @@ var SCOPE_REFUSAL_CODES = Object.freeze(["VAULT_SCOPE_MISMATCH", "ACCOUNT_MISMAT
 init_credentials();
 
 // spex-console/src/lib/vault-registry/registry-file.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync6, renameSync as renameSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync7, renameSync as renameSync4, writeFileSync as writeFileSync4 } from "node:fs";
 import { dirname as dirname4, join as join7, resolve as resolve4 } from "node:path";
 
 // spex-console/src/lib/heyspex-home.ts
-import { homedir as homedir6 } from "node:os";
+import { homedir as homedir7 } from "node:os";
 function heyspexHome2(env = process.env) {
   const override = env?.HEYSPEX_HOME;
   if (typeof override === "string" && override.trim().length > 0) {
     return override.trim();
   }
-  return homedir6();
+  return homedir7();
 }
 
 // spex-console/src/lib/vault-registry/types.ts
@@ -2297,9 +2327,9 @@ function parseVaultRegistryFile(json) {
 }
 function readRegistryJson(opts) {
   const filePath = vaultRegistryFilePath(opts);
-  if (!existsSync4(filePath)) return { kind: "missing" };
+  if (!existsSync5(filePath)) return { kind: "missing" };
   try {
-    const raw = readFileSync6(filePath, "utf8");
+    const raw = readFileSync7(filePath, "utf8");
     const json = JSON.parse(raw);
     if (registryFileSchemaOf(json) === null) return { kind: "unreadable" };
     return { kind: "ok", raw, json };
@@ -2369,10 +2399,10 @@ function assertNotRealHomeRegistryUnderTest(filePath) {
 function writeVaultRegistry(registry, opts = {}) {
   const filePath = vaultRegistryFilePath(opts);
   assertNotRealHomeRegistryUnderTest(filePath);
-  mkdirSync3(dirname4(filePath), { recursive: true });
+  mkdirSync4(dirname4(filePath), { recursive: true });
   const tmpPath = `${filePath}.tmp`;
-  writeFileSync3(tmpPath, serializeVaultRegistry(registry), "utf8");
-  renameSync3(tmpPath, filePath);
+  writeFileSync4(tmpPath, serializeVaultRegistry(registry), "utf8");
+  renameSync4(tmpPath, filePath);
 }
 function isValidId(id) {
   if (!isNonEmptyString(id)) return false;
@@ -2536,11 +2566,11 @@ function readPairedBearer(opts = {}) {
 function readPairedToken(opts = {}) {
   return readPairedBearer(opts).token ?? void 0;
 }
-function scopeHeadersFor(scope, method, path4) {
+function scopeHeadersFor(scope, method, path5) {
   if (scope === "none") {
-    if (!isVaultLessEndpoint(method, path4)) {
+    if (!isVaultLessEndpoint(method, path5)) {
       throw new Error(
-        `controlRequest: scope "none" is only allowed for the vault-less endpoints (${VAULT_LESS_ENDPOINTS.join(", ")}); ${method.toUpperCase()} ${path4} is vault-scoped and must name { accountId, vaultId }.`
+        `controlRequest: scope "none" is only allowed for the vault-less endpoints (${VAULT_LESS_ENDPOINTS.join(", ")}); ${method.toUpperCase()} ${path5} is vault-scoped and must name { accountId, vaultId }.`
       );
     }
     return {};
@@ -2551,7 +2581,7 @@ function cloudRequestScope(scope) {
   const named = { accountId: scope.accountId, vaultId: scope.vaultId };
   return {
     ...named,
-    headersFor: (method, path4) => isVaultLessEndpoint(method, path4) ? {} : scopeHeadersFor(named, method, path4)
+    headersFor: (method, path5) => isVaultLessEndpoint(method, path5) ? {} : scopeHeadersFor(named, method, path5)
   };
 }
 function withCloudScope(deps, accountId2, vaultId) {
@@ -2562,8 +2592,8 @@ function withCloudScope(deps, accountId2, vaultId) {
 // scripts/lib/console-url-resolver.mjs
 init_heyspex_home();
 init_dev_mode();
-import { readFileSync as readFileSync8 } from "node:fs";
-import { homedir as homedir8 } from "node:os";
+import { readFileSync as readFileSync9 } from "node:fs";
+import { homedir as homedir9 } from "node:os";
 import { join as join9 } from "node:path";
 var DEFAULT_CONSOLE_URL = LOCAL_CONSOLE_URL;
 function trimTrailingSlash(url) {
@@ -2601,7 +2631,7 @@ function readCredentialsConsoleUrl({ homeDir = heyspexHome(), readFile: readFile
   }
 }
 function defaultReadFile2(p) {
-  return readFileSync8(p, "utf8");
+  return readFileSync9(p, "utf8");
 }
 function readDiscoveryFileConsoleUrl(repoRoot, { readDiscovery = defaultReadFile2 } = {}) {
   if (!repoRoot) return null;
@@ -2699,7 +2729,7 @@ var HELP = [
 
 // spex-console/src/lib/cli/install-identity.ts
 import { spawnSync } from "node:child_process";
-import { existsSync as existsSync5 } from "node:fs";
+import { existsSync as existsSync6 } from "node:fs";
 import { join as join10 } from "node:path";
 import { createInterface } from "node:readline/promises";
 init_credentials();
@@ -2707,7 +2737,7 @@ init_credentials();
 // vendor/heyspex-mcp/whoami.mjs
 init_heyspex_home();
 init_credentials();
-import { homedir as homedir9 } from "node:os";
+import { homedir as homedir10 } from "node:os";
 var SESSION_PATH = "/api/mcp/session";
 async function probeCredentialIdentity({ consoleUrl, token, fetchImpl = fetch } = {}) {
   if (!token) return { kind: "no_credential" };
@@ -2775,12 +2805,15 @@ var HELP2 = [
   "(spex-console/src/lib/cli/template-manifest.ts) \u2014 universal docs",
   "copied verbatim, template-shape docs written as author-prompt skeletons \u2014",
   "plus a generated CLAUDE.md, the kept-principles index, and the template_version",
-  "pin; with --git, one initial `git init` + commit. Rerunnable: a <dir> that already",
-  "holds heyspex.yaml and an empty/placeholder-only specs/ is accepted, existing",
-  "files are never overwritten (an existing CLAUDE.md gets a CLAUDE.md.template",
-  "beside it), and the result lists each manifest row as created or kept. Refuses a",
-  "non-empty <dir> without heyspex.yaml, or a specs/ holding managed specs.",
-  "See init.customer-vault.ts.",
+  "pin; with --git, one initial `git init` + commit. On an EXISTING vault (<dir>",
+  "holds heyspex.yaml with a vault_id) it is a REFRESH \u2014 the repair `hs doctor`'s",
+  "vault-template row names: only missing shipped files are added, template_version",
+  "is written/updated in heyspex.yaml (every other byte and the vault_id kept),",
+  "nothing existing is ever overwritten (an existing CLAUDE.md gets a",
+  "CLAUDE.md.template beside it), the result lists each manifest row as created or",
+  "kept, and a second run writes nothing. <dir> may be any path (a satellite repo",
+  "names its vault, e.g. `hs init --customer-vault ../my-specs`). Refuses only a",
+  "non-empty <dir> that has no heyspex.yaml. See init.customer-vault.ts.",
   "",
   "Flags:",
   "  --console-url <url>  console_url value (default: the mode-aware console --",
@@ -3048,7 +3081,7 @@ function isInteractiveTerminal() {
 }
 function defaultIdentityGateIo(opts) {
   const consoleUrl = opts.consoleUrl.trim().replace(/\/+$/, "");
-  const loginCli = [opts.platformRoot, resolveCodeRoot({})].filter((r) => Boolean(r && r.trim())).map((r) => join10(r, "vendor", "heyspex-mcp", "cli.mjs")).find((p) => existsSync5(p));
+  const loginCli = [opts.platformRoot, resolveCodeRoot({})].filter((r) => Boolean(r && r.trim())).map((r) => join10(r, "vendor", "heyspex-mcp", "cli.mjs")).find((p) => existsSync6(p));
   return {
     consoleUrl,
     interactive: opts.interactive ?? isInteractiveTerminal(),
@@ -3096,7 +3129,7 @@ function defaultIdentityGateIo(opts) {
 init_sql_orm_inert_cli_shim();
 
 // spex-console/src/lib/cli/vault-workspace-shared.ts
-import { readFileSync as readFileSync9 } from "node:fs";
+import { readFileSync as readFileSync10 } from "node:fs";
 
 // spex-console/src/lib/cli/default-workspace.ts
 function defaultWorkspaceId(accountId2) {
@@ -3109,7 +3142,7 @@ function resolveConfiguredAccountId(opts = {}) {
   return resolveSessionOwnerUncached({
     env: opts.env ?? process.env,
     homeDir: opts.homeDir ?? heyspexHome2(),
-    readFile: opts.readFile ?? ((p) => readFileSync9(p, "utf-8"))
+    readFile: opts.readFile ?? ((p) => readFileSync10(p, "utf-8"))
   });
 }
 var CLOUD_ACCOUNT_ID_REQUIRED_MESSAGE = "refusing -- no signed-in account (no HS_ACCOUNT_ID env var, and no account_id: in ~/.heyspex/config.yaml). Run `hs login` first; nothing was written.";
@@ -3130,10 +3163,10 @@ function classifyHttpFailureReason(res) {
   if (res.status === 401) return "unauthorized";
   return "server-error";
 }
-async function cloudHttpRequest(http, method, path4, body) {
-  const scopeHeaders = http.scope ? http.scope.headersFor(method, path4) : {};
+async function cloudHttpRequest(http, method, path5, body) {
+  const scopeHeaders = http.scope ? http.scope.headersFor(method, path5) : {};
   try {
-    const res = await http.fetchImpl(`${http.consoleUrl}${path4}`, {
+    const res = await http.fetchImpl(`${http.consoleUrl}${path5}`, {
       method,
       headers: {
         "content-type": "application/json",
@@ -3186,8 +3219,8 @@ async function classifyWorkspaceConflictHttp(id, conflictJson, http) {
   if (!Array.isArray(rows)) return { written: false, reason: "server-error" };
   return rows.some((w) => w.id === id) ? { written: true } : { written: false, reason: "owned-by-other-account" };
 }
-async function mutateHttp(http, method, path4, body, landed) {
-  const res = await cloudHttpRequest(http, method, path4, body);
+async function mutateHttp(http, method, path5, body, landed) {
+  const res = await cloudHttpRequest(http, method, path5, body);
   if (res.ok) return landed;
   if (res.status === 404) return "not_found";
   if (res.status === 403 && isOwnedByOtherAccountCode(errorCodeOf(res.json))) {
@@ -3436,7 +3469,7 @@ init_postgres_client_cli_shim();
 init_postgres();
 
 // spex-console/src/lib/vault-registry/repo-identity.ts
-import path2 from "node:path";
+import path3 from "node:path";
 
 // spex-console/src/lib/vault-registry/vault-workspace-store.ts
 function mapProbeFailureReason(reason) {
@@ -3778,7 +3811,7 @@ function buildCloseNotDestroyConfirm(kind, verb, displayName) {
 }
 
 // spex-console/src/lib/vault-registry/list.ts
-import { existsSync as existsSync6 } from "node:fs";
+import { existsSync as existsSync7 } from "node:fs";
 function pointerDeps2(deps) {
   return deps.accountPointer ?? { registryOpts: deps.registryOpts };
 }
@@ -4299,11 +4332,11 @@ function readLocalReceiptSide(subject, registryOpts = {}) {
     return unreadSide(`registry.json could not be read: ${message(err)}`);
   }
 }
-async function readList(http, path4, key) {
-  const res = await cloudHttpRequest(http, "GET", path4);
+async function readList(http, path5, key) {
+  const res = await cloudHttpRequest(http, "GET", path5);
   const rows = res.json?.[key];
   if (!res.ok || !Array.isArray(rows)) {
-    return { reason: `GET ${path4.split("?")[0]} answered HTTP ${res.status}` };
+    return { reason: `GET ${path5.split("?")[0]} answered HTTP ${res.status}` };
   }
   return { rows: rows.filter((r) => Boolean(r) && typeof r === "object") };
 }
@@ -4995,7 +5028,7 @@ function runEntry(name, main2, options = {}) {
 // spex-console/bin/hs-workspace.ts
 function readFile(p) {
   try {
-    return readFileSync10(p, "utf8");
+    return readFileSync11(p, "utf8");
   } catch {
     return null;
   }
@@ -5032,14 +5065,14 @@ async function main() {
     process4.exitCode = parsed.error.code;
     return;
   }
-  const vaultRoot = process4.env.HS_VAULT_ROOT ? path3.resolve(process4.env.HS_VAULT_ROOT) : process4.cwd();
+  const vaultRoot = process4.env.HS_VAULT_ROOT ? path4.resolve(process4.env.HS_VAULT_ROOT) : process4.cwd();
   const consoleUrl = resolveSpexConsoleUrl(vaultRoot, readFile);
   const gate = await gateWriteVerb({
     namespace: "hs workspace",
     sub: parsed.args.sub,
     writeVerbs: WORKSPACE_WRITE_VERBS,
     flags: identityArgv.flags,
-    io: defaultIdentityGateIo({ consoleUrl, platformRoot: path3.resolve(process4.cwd(), "..") })
+    io: defaultIdentityGateIo({ consoleUrl, platformRoot: path4.resolve(process4.cwd(), "..") })
   });
   if (gate && !gate.ok) {
     process4.stderr.write(