metheus-governance-mcp-cli 0.2.37 → 0.2.39

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();
@@ -3568,6 +3603,14 @@ function shouldUseSafeToolAliasesForClient(initParamsRaw) {
   return name.includes("cursor") || name.includes("antigravity");
 }
 
+function displayToolNameForClient(canonicalName, useSafeToolAliases = false) {
+  const canonical = String(canonicalName || "").trim();
+  if (!canonical) return "";
+  if (!useSafeToolAliases) return canonical;
+  const alias = normalizeSafeToolAliasName(canonical);
+  return alias || canonical;
+}
+
 function injectWorkspaceDirIntoToolSchemas(tools) {
   const workspaceDirProp = {
     type: "string",
@@ -3598,14 +3641,25 @@ function appendLocalToolToToolsList(responseObj) {
   return responseObj;
 }
 
-function appendProjectHintToInitialize(responseObj, args) {
+function appendProjectHintToInitialize(responseObj, args, options = {}) {
+  const useSafeToolAliases = Boolean(options.useSafeToolAliases);
   const result = safeObject(responseObj.result);
+  const projectSummaryTool = displayToolNameForClient("project.summary", useSafeToolAliases);
+  const projectDescribeTool = displayToolNameForClient("project.describe", useSafeToolAliases);
+  const projectGetTool = displayToolNameForClient("project.get", useSafeToolAliases);
+  const ctxpackMergeBriefTool = displayToolNameForClient("ctxpack.merge.brief", useSafeToolAliases);
+  const ctxpackMergeExecuteTool = displayToolNameForClient("ctxpack.merge.execute", useSafeToolAliases);
   const hintLines = [
     "High-priority project bootstrap rule:",
-    "- MUST call `project.summary` first when the user provides only a Project ID or asks project overview/agenda.",
-    "- `project.describe` and `project.get` are aliases of `project.summary`.",
+    ...(useSafeToolAliases
+      ? [
+          "- This session uses safe MCP tool aliases (underscore format). Use `project_summary` / `ctxpack_ensure` / `workitem_list` style names, not dotted names.",
+        ]
+      : []),
+    `- MUST call \`${projectSummaryTool}\` first when the user provides only a Project ID or asks project overview/agenda.`,
+    `- \`${projectDescribeTool}\` and \`${projectGetTool}\` are aliases of \`${projectSummaryTool}\`.`,
     "- After project summary, use workitem/evidence/decision tools as follow-up.",
-    "- Before any ctxpack merge, call `ctxpack.merge.brief` first, share recommendation to owner, get explicit owner confirmation, then call `ctxpack.merge.execute`.",
+    `- Before any ctxpack merge, call \`${ctxpackMergeBriefTool}\` first, share recommendation to owner, get explicit owner confirmation, then call \`${ctxpackMergeExecuteTool}\`.`,
     "- IMPORTANT: When calling ANY tool, always include your current working directory / project folder path as the `workspace_dir` argument. This enables ctxpack files to be synced to the correct workspace location.",
   ];
   if (args.projectID) {
@@ -3732,7 +3786,16 @@ function appendAutoCtxpackSyncHint(responseObj, summary) {
   return responseObj;
 }
 
-async function appendWorkitemListHints(responseObj, args, toolArgs, token, workspaceSignalTrusted = true) {
+async function appendWorkitemListHints(
+  responseObj,
+  args,
+  toolArgs,
+  token,
+  workspaceSignalTrusted = true,
+  options = {},
+) {
+  const useSafeToolAliases = Boolean(options.useSafeToolAliases);
+  const projectSummaryTool = displayToolNameForClient("project.summary", useSafeToolAliases);
   const result = safeObject(responseObj.result);
   const content = ensureArray(result.content);
   if (!content.length) return responseObj;
@@ -3742,7 +3805,7 @@ async function appendWorkitemListHints(responseObj, args, toolArgs, token, works
 
   const text = String(first.text || "");
   if (!text) return responseObj;
-  if (text.includes("Call `project.summary`")) return responseObj;
+  if (text.includes(`Call \`${projectSummaryTool}\``) || text.includes("Call `project.summary`")) return responseObj;
 
   const parsed = parseGatewayResponseText(text);
   if (!parsed) return responseObj;
@@ -3759,7 +3822,7 @@ async function appendWorkitemListHints(responseObj, args, toolArgs, token, works
   const nextLines = [""];
   if (isEmptyBody) {
     nextLines.push("No work items found for this project.");
-    nextLines.push("- Call `project.summary` to confirm project context/agenda and access state first.");
+    nextLines.push(`- Call \`${projectSummaryTool}\` to confirm project context/agenda and access state first.`);
   }
 
   let responseProjectID = "";
@@ -4525,7 +4588,9 @@ async function runProxy(flags) {
               patched = applyToolAliasesToToolsListResponse(patched, sessionToolCanonicalToAlias);
             }
           } else if (isJsonRpcMethod(requestObj, "initialize")) {
-            patched = appendProjectHintToInitialize(patched, args);
+            patched = appendProjectHintToInitialize(patched, args, {
+              useSafeToolAliases: sessionUseSafeToolAliases,
+            });
             // Log initialize params for workspace debugging.
             try {
               const _diagDir = path.join(String(process.env.USERPROFILE || process.env.HOME || "."), ".metheus");
@@ -4542,7 +4607,14 @@ async function runProxy(flags) {
               setImmediate(() => sendRootsListProbe());
             }
           } else if (isJsonRpcMethod(requestObj, "tools/call") && toolName === "workitem.list") {
-            patched = await appendWorkitemListHints(patched, args, toolArgs, token, workspaceSignalTrusted);
+            patched = await appendWorkitemListHints(
+              patched,
+              args,
+              toolArgs,
+              token,
+              workspaceSignalTrusted,
+              { useSafeToolAliases: sessionUseSafeToolAliases },
+            );
           } else if (isJsonRpcMethod(requestObj, "tools/call") && toolName === "ctxpack.ensure") {
             patched = appendCtxpackEnsureSyncHints(
               patched,
@@ -4984,7 +5056,7 @@ function resolveSetupContext(flags) {
   const workspaceMeta = loadWorkspaceMeta(process.cwd());
   const projectID = String(flags["project-id"] || workspaceMeta.project_id || "").trim();
   const ctxpackKey = String(flags["ctxpack-key"] || buildCtxpackKeyFromMeta(workspaceMeta) || "").trim();
-  const baseURL = String(flags["base-url"] || DEFAULT_SITE_URL).trim().replace(/\/+$/, "");
+  const baseURL = normalizeSiteBaseURL(flags["base-url"] || DEFAULT_SITE_URL);
   const workspaceDirRaw = String(flags["workspace-dir"] || "").trim();
   const workspaceFallbackDirRaw = String(flags["workspace-fallback-dir"] || "").trim();
   const hasWorkspaceDirFlag = Object.prototype.hasOwnProperty.call(flags, "workspace-dir");
@@ -5099,6 +5171,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();
@@ -5159,6 +5327,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.37",
+  "version": "0.2.39",
   "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"