metheus-governance-mcp-cli 0.2.36 → 0.2.38

package/README.md

@@ -103,6 +103,11 @@ Antigravity note:
 Cursor note:
 - this CLI manages MCP registration via Cursor global MCP config (`~/.cursor/mcp.json`).
 
+Tool naming compatibility:
+- Claude/Codex/Gemini keep canonical MCP tool names (`project.summary`, `ctxpack.merge.brief`, ...).
+- Cursor/Antigravity sessions may receive safe aliases (`project_summary`, `ctxpack_merge_brief`, ...).
+- Proxy maps alias calls back to canonical names automatically.
+
 Local bootstrap tools exposed by proxy:
 
 - `project.summary`
@@ -239,6 +244,7 @@ npm publish --access public
 
 ```bash
 npm run check
+npm run test:compat
 npm run publish:dry
 ```
 
@@ -255,3 +261,25 @@ If npm account uses 2FA, pass OTP:
 ```bash
 node release.mjs --otp <6-digit-code>
 ```
+
+## Regression and smoke checks
+
+Local compatibility selftest (no network):
+
+```bash
+npm run test:compat
+```
+
+Proxy smoke test (initialize -> tools/list -> project summary -> ctxpack local sync):
+
+```bash
+npm run smoke:proxy -- --project-id <project_uuid> --ctxpack-key "<ctxpack_key>" --workspace-dir <workspace_path>
+```
+
+Optional:
+- `--client cursor-vscode` (default) or `--client antigravity`
+- `--base-url https://metheus.gesiaplatform.com/governance/mcp`
+
+Workspace fallback guardrail:
+- If `METHEUS_WORKSPACE_DIR` is accidentally set to a non-existing boolean suffix path like `C:\code_test\true`,
+  proxy now recovers to the parent workspace (`C:\code_test`) instead of pinning to the bad path.

package/cli.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import readline from "node:readline";
@@ -42,6 +43,7 @@ function printUsage() {
       `  ${cmd} setup [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path|auto>] [--workspace-fallback-dir <path>] [--name <server_name>]`,
       `  ${cmd} doctor [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--timeout-seconds <n>]`,
       `  ${cmd} proxy [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path|auto>] [--include-drafts <true|false>] [--auto-pull-on-conflict <true|false>] [--timeout-seconds <n>]`,
+      `  ${cmd} selftest [--json <true|false>]`,
       `  ${cmd} ctxpack pull [--project-id <uuid>] [--base-url <url>] [--workspace-dir <path|auto>] [--paths <csv>] [--timeout-seconds <n>]`,
       `  ${cmd} auth status`,
       `  ${cmd} auth login [--base-url <url>] [--flow <auto|device|callback|manual>] [--keycloak-url <url>] [--realm <name>] [--client-id <id>] [--open-browser <true|false>] [--callback-port <n>] [--timeout-seconds <n>] [--manual <true|false>]`,
@@ -604,7 +606,7 @@ function extractWeakWorkspaceCandidateFromRequest(requestObj) {
 }
 
 function extractStrongWorkspaceCandidateFromEnv() {
-  const rawCandidate = firstNonEmptyString([
+  const rawCandidates = [
     process.env.METHEUS_WORKSPACE_DIR,
     process.env.METHEUS_WORKSPACE_URI,
     process.env.CODEX_WORKSPACE_DIR,
@@ -612,8 +614,12 @@ function extractStrongWorkspaceCandidateFromEnv() {
     process.env.CLAUDE_WORKSPACE_DIR,
     process.env.CLAUDE_WORKSPACE_URI,
     process.env.CLAUDE_PROJECT_DIR,
-  ]);
-  return sanitizeWorkspaceCandidate(rawCandidate);
+  ];
+  for (const rawCandidate of rawCandidates) {
+    const normalized = sanitizeWorkspaceFallbackEnvCandidate(rawCandidate);
+    if (normalized) return normalized;
+  }
+  return "";
 }
 
 function extractWorkspaceCandidateFromEnv() {
@@ -635,6 +641,35 @@ function extractWeakWorkspaceCandidateFromEnv() {
   return sanitizeWorkspaceCandidate(rawCandidate);
 }
 
+function sanitizeWorkspaceFallbackEnvCandidate(rawCandidate) {
+  const input = String(rawCandidate || "").trim();
+  if (!input) return "";
+
+  const direct = sanitizeWorkspaceCandidate(input);
+  if (direct && fs.existsSync(direct)) {
+    return direct;
+  }
+
+  const fileCandidate = fileURIToLocalPath(input);
+  const candidate = firstNonEmptyString([fileCandidate, input]);
+  if (!candidate) return direct;
+
+  const resolved = resolveWorkspaceDir(candidate);
+  if (!resolved || isEditorInstallDirectory(resolved)) {
+    return direct;
+  }
+
+  const leaf = path.basename(resolved).trim().toLowerCase();
+  if ((leaf === "true" || leaf === "false") && !fs.existsSync(resolved)) {
+    const parent = sanitizeWorkspaceCandidate(path.dirname(resolved));
+    if (parent && fs.existsSync(parent)) {
+      return parent;
+    }
+  }
+
+  return direct;
+}
+
 function resolveWorkspaceDirForRequest(defaultWorkspaceDir, requestObj, toolArgs) {
   const strongRequestCandidate = extractStrongWorkspaceCandidateFromRequest(requestObj, toolArgs);
   const strongEnvCandidate = extractStrongWorkspaceCandidateFromEnv();
@@ -3491,6 +3526,83 @@ function ensureArray(value) {
   return Array.isArray(value) ? value : [];
 }
 
+function normalizeSafeToolAliasName(rawName) {
+  const base = String(rawName || "")
+    .trim()
+    .replace(/[^a-zA-Z0-9_]/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  if (!base) return "";
+  if (/^[0-9]/.test(base)) return `tool_${base}`;
+  return base;
+}
+
+function buildToolAliasMaps(tools) {
+  const canonicalNames = new Set(
+    ensureArray(tools)
+      .map((tool) => String(tool?.name || "").trim())
+      .filter(Boolean),
+  );
+  const aliasToCanonical = new Map();
+  const canonicalToAlias = new Map();
+  const reserved = new Set(canonicalNames);
+
+  for (const canonicalName of canonicalNames) {
+    const aliasBase = normalizeSafeToolAliasName(canonicalName);
+    if (!aliasBase || aliasBase === canonicalName) continue;
+    let alias = aliasBase;
+    let counter = 2;
+    while (reserved.has(alias) || aliasToCanonical.has(alias)) {
+      alias = `${aliasBase}_${counter}`;
+      counter += 1;
+    }
+    aliasToCanonical.set(alias, canonicalName);
+    canonicalToAlias.set(canonicalName, alias);
+    reserved.add(alias);
+  }
+  return { aliasToCanonical, canonicalToAlias };
+}
+
+function applyToolAliasesToToolsListResponse(responseObj, canonicalToAlias) {
+  const result = safeObject(responseObj.result);
+  const tools = ensureArray(result.tools);
+  result.tools = tools.map((tool) => {
+    const safeTool = safeObject(tool);
+    const currentName = String(safeTool.name || "").trim();
+    const aliasName = canonicalToAlias.get(currentName);
+    if (!aliasName) return safeTool;
+    return { ...safeTool, name: aliasName };
+  });
+  responseObj.result = result;
+  return responseObj;
+}
+
+function rewriteAliasedToolCallToCanonical(requestObj, aliasToCanonical) {
+  if (!isJsonRpcMethod(requestObj, "tools/call")) return requestObj;
+  const params = safeObject(requestObj.params);
+  const currentName = String(params.name ?? params.tool_name ?? params.toolName ?? "").trim();
+  if (!currentName) return requestObj;
+  const canonicalName = String(aliasToCanonical.get(currentName) || "").trim();
+  if (!canonicalName) return requestObj;
+
+  const nextParams = { ...params, name: canonicalName };
+  if (Object.prototype.hasOwnProperty.call(nextParams, "tool_name")) {
+    nextParams.tool_name = canonicalName;
+  }
+  if (Object.prototype.hasOwnProperty.call(nextParams, "toolName")) {
+    nextParams.toolName = canonicalName;
+  }
+  return { ...requestObj, params: nextParams };
+}
+
+function shouldUseSafeToolAliasesForClient(initParamsRaw) {
+  const initParams = safeObject(initParamsRaw);
+  const clientInfo = safeObject(initParams.clientInfo);
+  const name = String(clientInfo.name || "").trim().toLowerCase();
+  if (!name) return false;
+  return name.includes("cursor") || name.includes("antigravity");
+}
+
 function injectWorkspaceDirIntoToolSchemas(tools) {
   const workspaceDirProp = {
     type: "string",
@@ -4044,6 +4156,9 @@ async function runProxy(flags) {
   let lastRefreshError = "";
   let sessionWorkspaceDir = "";
   let sessionWorkspaceTrusted = false;
+  let sessionUseSafeToolAliases = false;
+  let sessionToolAliasToCanonical = new Map();
+  let sessionToolCanonicalToAlias = new Map();
 
   // Proxy-initiated requests (e.g., roots/list) pending client responses.
   const pendingProxyRequests = new Map(); // id → callback(responseObj)
@@ -4122,7 +4237,7 @@ async function runProxy(flags) {
     const line = String(lineRaw || "").trim();
     if (!line) return;
 
-    const requestObj = tryJsonParse(line);
+    let requestObj = tryJsonParse(line);
     if (requestObj == null) {
       writeProxyJson(jsonRpcError(null, -32700, "parse error"));
       return;
@@ -4175,6 +4290,13 @@ async function runProxy(flags) {
       return;
     }
 
+    if (isJsonRpcMethod(requestObj, "initialize") && shouldUseSafeToolAliasesForClient(requestObj?.params)) {
+      sessionUseSafeToolAliases = true;
+    }
+    if (sessionUseSafeToolAliases) {
+      requestObj = rewriteAliasedToolCallToCanonical(requestObj, sessionToolAliasToCanonical);
+    }
+
     const { name: toolName, args: toolArgs } = extractToolCall(requestObj);
     let strongRequestWorkspaceCandidate = "";
     let weakRequestWorkspaceCandidate = "";
@@ -4430,6 +4552,13 @@ async function runProxy(flags) {
           }
           if (isJsonRpcMethod(requestObj, "tools/list")) {
             patched = appendLocalToolToToolsList(patched);
+            if (sessionUseSafeToolAliases) {
+              const tools = ensureArray(safeObject(patched.result).tools);
+              const aliasMaps = buildToolAliasMaps(tools);
+              sessionToolAliasToCanonical = aliasMaps.aliasToCanonical;
+              sessionToolCanonicalToAlias = aliasMaps.canonicalToAlias;
+              patched = applyToolAliasesToToolsListResponse(patched, sessionToolCanonicalToAlias);
+            }
           } else if (isJsonRpcMethod(requestObj, "initialize")) {
             patched = appendProjectHintToInitialize(patched, args);
             // Log initialize params for workspace debugging.
@@ -5005,6 +5134,102 @@ function runSetup(flags) {
   runSetupInternal(flags, { ensureOnly: false });
 }
 
+function runSelftest(flags = {}) {
+  const jsonMode = boolFromRaw(flags.json, false);
+  const checks = [];
+  const push = (name, ok, detail = "") => checks.push({ name, ok: Boolean(ok), detail: String(detail || "") });
+
+  const aliasMaps = buildToolAliasMaps([
+    { name: "project.summary" },
+    { name: "ctxpack.merge.brief" },
+    { name: "workitem.list" },
+  ]);
+  const summaryAlias = String(aliasMaps.canonicalToAlias.get("project.summary") || "");
+  const roundTrip = rewriteAliasedToolCallToCanonical(
+    {
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: {
+        name: summaryAlias,
+        arguments: {},
+      },
+    },
+    aliasMaps.aliasToCanonical,
+  );
+  const roundTripOk = summaryAlias === "project_summary" && String(roundTrip?.params?.name || "") === "project.summary";
+  push(
+    "alias_roundtrip_project_summary",
+    roundTripOk,
+    `alias=${summaryAlias || "(none)"} canonical=${String(roundTrip?.params?.name || "(none)")}`,
+  );
+
+  const collisionMaps = buildToolAliasMaps([{ name: "a.b" }, { name: "a_b" }]);
+  const aliasDot = String(collisionMaps.canonicalToAlias.get("a.b") || "");
+  const aliasUnderscore = String(collisionMaps.canonicalToAlias.get("a_b") || "");
+  const collisionOk = aliasDot === "a_b_2" && aliasUnderscore === "";
+  push(
+    "alias_collision_safe_suffix",
+    collisionOk,
+    `a.b->${aliasDot || "(none)"} a_b->${aliasUnderscore || "(none)"}`,
+  );
+
+  let tempRoot = "";
+  try {
+    tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-selftest-"));
+    const parent = path.join(tempRoot, "workspace");
+    fs.mkdirSync(parent, { recursive: true });
+    const suspicious = path.join(parent, "true");
+    const recovered = sanitizeWorkspaceFallbackEnvCandidate(suspicious);
+    const recoveredOk = normalizedPathForCompare(recovered) === normalizedPathForCompare(parent);
+    push(
+      "workspace_env_true_suffix_recovery",
+      recoveredOk,
+      `input=${suspicious} recovered=${recovered || "(none)"}`,
+    );
+
+    fs.mkdirSync(suspicious, { recursive: true });
+    const keptExisting = sanitizeWorkspaceFallbackEnvCandidate(suspicious);
+    const keptExistingOk = normalizedPathForCompare(keptExisting) === normalizedPathForCompare(suspicious);
+    push(
+      "workspace_env_existing_true_dir_kept",
+      keptExistingOk,
+      `input=${suspicious} recovered=${keptExisting || "(none)"}`,
+    );
+  } catch (err) {
+    push("workspace_env_guard_test_setup", false, String(err?.message || err));
+  } finally {
+    if (tempRoot) {
+      try {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+      } catch {
+        // ignore selftest cleanup error
+      }
+    }
+  }
+
+  const failed = checks.filter((row) => !row.ok);
+  const payload = {
+    ok: failed.length === 0,
+    pass_count: checks.length - failed.length,
+    fail_count: failed.length,
+    checks,
+  };
+
+  if (jsonMode) {
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+  } else {
+    process.stdout.write(`Selftest: ${payload.ok ? "PASS" : "FAIL"} (${payload.pass_count}/${checks.length})\n`);
+    for (const row of checks) {
+      process.stdout.write(`- ${row.ok ? "PASS" : "FAIL"} ${row.name}${row.detail ? ` :: ${row.detail}` : ""}\n`);
+    }
+  }
+
+  if (!payload.ok) {
+    process.exitCode = 1;
+  }
+}
+
 async function runBootstrap(flags) {
   process.stdout.write("Bootstrap start.\n");
   let resolved = resolveCurrentAccessToken();
@@ -5065,6 +5290,10 @@ async function main() {
     await runDoctor(flags);
     return;
   }
+  if (command === "selftest") {
+    runSelftest(flags);
+    return;
+  }
   if (command === "auth") {
     await runAuth(rest);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metheus-governance-mcp-cli",
-  "version": "0.2.36",
+  "version": "0.2.38",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [
@@ -11,6 +11,8 @@
   ],
   "scripts": {
     "check": "node --check cli.mjs && node --check release.mjs",
+    "test:compat": "node cli.mjs selftest --json",
+    "smoke:proxy": "node scripts/smoke-proxy.mjs",
     "pack:dry": "npm pack --dry-run",
     "publish:dry": "node release.mjs --dry-run",
     "publish:public": "node release.mjs"