heyspex 0.2.2 → 0.2.3

package/plugins/heyspex/bin/launch-mcp.mjs

@@ -83,13 +83,27 @@ if (!entry) {
   process.exit(1);
 }
 
-// The guessed "grandparent of vendor/heyspex-mcp" vault root only makes sense
-// for a source checkout, where that directory IS the vault. For the packaged
-// entry it resolves to node_modules/heyspex, which is never the customer's
-// vault — leave HEYSPEX_VAULT_ROOT alone in that case and let the server's own
-// multi-tier vault resolver (vault-resolve.mjs) find the real one.
-if (!process.env.HEYSPEX_VAULT_ROOT && entry !== packagedEntry) {
-  process.env.HEYSPEX_VAULT_ROOT = resolve(entry, "../../..");
+// No HEYSPEX_VAULT_ROOT guess here (HS-TYJA, owner ruling 2026-10-14). It used
+// to pin the "grandparent of vendor/heyspex-mcp" for a source checkout, which
+// since the repo split is the CODE repo, not a vault. HEYSPEX_VAULT_ROOT is now
+// a true override above the cwd walk, so a guess would beat the repo's own
+// heyspex.yaml `vault:` binding. The server's resolver (vault-resolve.mjs)
+// finds the vault from the folder it was launched in.
+
+// HS-C0NW: hosts that do not expand `${CLAUDE_PROJECT_DIR}` in a manifest `env` block (GitHub
+// Copilot CLI) hand the server the literal text. Drop HEYSPEX_VAULT_ROOT / CLAUDE_PROJECT_DIR /
+// CURSOR_PROJECT_DIR when they hold an unexpanded placeholder, a relative path or a missing dir,
+// so the server's resolver falls through to the folder it was launched in. The check lives in
+// the server tree (one helper shared with vault-resolve.mjs), next to the entry we just found.
+// A HEYSPEX_VAULT_ROOT naming an absolute path that does not exist locally is kept: it may be a
+// registered cloud-reliance vault, which the resolver validates itself.
+try {
+  const { scrubUnusableDirEnv } = await import(
+    pathToFileURL(resolve(dirname(entry), "usable-dir-env.mjs")).href
+  );
+  scrubUnusableDirEnv(process.env, { requireExisting: { HEYSPEX_VAULT_ROOT: false } });
+} catch {
+  // Older server tree without the helper: its own resolver is the only line of defence.
 }
 
 await import(pathToFileURL(entry).href);

package/plugins/heyspex/mcp.json

@@ -1,13 +1,12 @@
-{
-  "_comment": "Cursor plugin MCP declaration (HS-2HII). Boots through the plugin's own bin/launch-mcp.mjs, the same launcher .mcp.json uses for Claude Code. Cursor expands ${CURSOR_PLUGIN_ROOT} to the plugin's install path in command/args/env/cwd (cursor.com/docs/reference/plugins), so this works from a plain `npm install heyspex`: the launcher resolves node_modules/heyspex first, then CURSOR_PROJECT_DIR and the other source-checkout fallbacks. Never point this at vendor/heyspex-mcp/cli.mjs directly: that path exists only inside the platform checkout.",
-  "mcpServers": {
-    "heyspex": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["${CURSOR_PLUGIN_ROOT}/bin/launch-mcp.mjs"],
-      "env": {
-        "HEYSPEX_VAULT_ROOT": "${workspaceFolder}"
-      }
-    }
-  }
-}
+{
+  "_comment": "Cursor plugin MCP declaration (HS-2HII). Boots through the plugin's own bin/launch-mcp.mjs, the same launcher .mcp.json uses for Claude Code. Cursor expands ${CURSOR_PLUGIN_ROOT} to the plugin's install path in command/args/env/cwd (cursor.com/docs/reference/plugins), so this works from a plain `npm install heyspex`: the launcher resolves node_modules/heyspex first, then CURSOR_PROJECT_DIR and the other source-checkout fallbacks. Never point this at vendor/heyspex-mcp/cli.mjs directly: that path exists only inside the platform checkout. No HEYSPEX_VAULT_ROOT pin (HS-TYJA, owner ruling 2026-10-14): the server resolves its vault from the folder it is launched in (a heyspex.yaml vault: binding or a vault checkout); a pin here would override every repo binding.",
+  "mcpServers": {
+    "heyspex": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "${CURSOR_PLUGIN_ROOT}/bin/launch-mcp.mjs"
+      ]
+    }
+  }
+}

package/scripts/check-mcp-freshness.mjs

@@ -48,7 +48,8 @@
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+import { isMainModule } from './lib/shared-path-helpers.mjs';
 
 function defaultVaultRoot() {
   // Honor the same override the hs CLI / dev-server-status.mjs use; otherwise
@@ -342,8 +343,9 @@ export function checkFreshness({ vaultRoot, vendorDir, buildFile, buildsDir, pid
       status: 'unknown',
       message:
         'heyspex MCP server freshness: unknown freshness (no build record at ' +
-        '.heyspex/mcp-server-build.json — the running server predates the freshness ' +
-        'handshake, or the file is missing/corrupt). Restart the server to establish one.',
+        '.heyspex/mcp-server-build.json — no HeySpex MCP server has started for this vault yet; ' +
+        'the record is written at server start. If one is running, it predates the freshness ' +
+        'handshake or the file is missing/corrupt — restart it to establish one).',
       scope,
       current,
       recorded: null,
@@ -366,7 +368,7 @@ export function checkFreshness({ vaultRoot, vendorDir, buildFile, buildsDir, pid
 
 // ---- CLI entrypoint --------------------------------------------------------
 
-const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+const invokedDirectly = isMainModule(import.meta.url);
 if (invokedDirectly) {
   const argv = process.argv.slice(2);
   const asJson = argv.includes('--json');