metheus-governance-mcp-cli 0.2.37 → 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();
@@ -5099,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();
@@ -5159,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.37",
+  "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"