heyspex 0.2.2 → 0.2.4

package/plugins/heyspex/assets/heyspex-glyph.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512" role="img" aria-label="HeySpex">
+  <title>HeySpex</title>
+  <rect width="512" height="512" rx="112" fill="#1c1c1c"/>
+  <g fill="#00fa8e" transform="translate(97.5 78) scale(0.62)">
+<g>
+    <path d="M492.09,442.88c-65.92,38.17-133.04,85.08-200.61,119.86-22.67,11.67-37.56,16.13-62.07,4.5-61.39-39.16-127.24-71.73-188.76-110.57-18.29-11.55-32.09-22.94-34.82-46.35-1.61-13.78-2.31-66.54.21-78.91,4.31-21.18,37.08-24.95,45.67-5.85,7.53,16.75.59,54.94,2.95,74.84.62,5.21,2.18,7.48,5.88,11.03l184.72,109.54c13.76,9.11,26.71-2.74,38.87-9.54,51.46-28.76,113.11-63.02,161.72-95.32,15-9.97,20.67-18.96,10.78-36.34-28.71-21.71-67.83-35.99-96.42-56.61-23.64-17.06-12.01-47.51,14.98-45.36,1.83.15,8.91,2.25,10.53,3.14,33.32,18.24,63.31,34.57,93.3,55.33,37.69,26.08,43.46,72.24,13.08,106.64Z"/>
+    <path d="M243.69.85c12.8-1.85,26.6-.86,38.25,4.84,62.2,41.11,135.65,72.85,197.08,114.09,17.62,11.83,30.42,26.6,32.33,48.84.94,10.91,1.45,52.76-1.36,61.33-5.34,16.31-28.33,21.56-40.21,8.99-14.65-15.5,2.93-59.4-11.75-74.5l-191.41-111.29c-13.78-6.07-14.69-3.43-27.04,2.78-61.47,30.91-118.4,69.68-179.46,102.42-2.08,1.12-6.61,6.79-7.92,8.75-4.63,6.91-5.05,15.42-1.49,23.04,1.11,2.38,6.69,10.57,16.31,18.03,9.62,7.47,79.88,43.77,79.88,43.77,0,0,8.04,5.6,11.22,9.33,32.8,38.48,78.67,72.23,109.62,110.4,9.39,11.58,16.25,24.24,3.26,36.99-4.39,4.31-19.18,8.74-26.16,3.21-52.15-41.35-104.86-107.39-115.17-115.21-34.22-25.96-113.6-51.84-126.21-93.64-8.65-28.69-1.2-62.67,24.3-79.87C92.85,88.7,155.73,43.65,220.97,10.27c7.03-3.6,14.88-8.28,22.72-9.42Z"/>
+    <path d="M288.09,263.38l63.24-63.56c17.83-21.25-3.94-49.23-28.94-35.71-17.77,9.61-44.6,47.97-63.02,62.12-.73.56-15.17,15.68-26.6,26.29-6.28,5.83-8.03,13.22-1.96,19.27,3.26,3.25,7.75,7.71,11.01,10.96,6.72,6.68,18.09,6.17,25.39.12,8.5-7.04,16.82-16.05,20.89-19.49Z"/>
+    <path d="M273.49,316.01c-37.73-38.63-74.58-78.18-113-116.16-14.21-20.09-.54-43.95,24.53-38.05,17.67,4.16,54.53,53.37,70.29,66.79,2.42,2.43,32.78,34.79,32.78,34.79l86.21,87.95c17.85,24.27-9.57,53.48-38.08,29.63-19.24-16.1-44.11-45.89-62.72-64.94Z"/>
+  </g>
+  </g>
+</svg>

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');