metheus-governance-mcp-cli 0.2.15 → 0.2.16

package/README.md

@@ -38,6 +38,25 @@ metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctx
 
 `project-id` can be omitted if your current folder (or parent) has `.metheus_ctxpack_sync.json`.
 
+Recommended for Codex/Claude multi-workspace sessions:
+
+```bash
+metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctxpack_key>" --base-url https://metheus.gesiaplatform.com --workspace-dir auto
+```
+
+Guardrail note:
+- By default, CLI blocks reading/writing ctxpack sync metadata when workspace root resolves to the home directory.
+- Override only when intentional: `METHEUS_ALLOW_HOME_WORKSPACE=1`.
+
+## Project ID behavior (verified)
+
+- `setup --project-id <A>` sets default proxy scope to project `A`.
+- Proxy forwards `project_id` to gateway query, and gateway sets `MCP_PROJECT_ID` for MCP runtime.
+- If a tool call includes `project_id` in its arguments, that value overrides setup-time default scope.
+- If tool arguments omit `project_id`, server falls back to `MCP_PROJECT_ID`.
+- If both are missing, the call fails with `project_id is required`.
+- For single-project sessions, keep one pinned `--project-id` and avoid sending a different `project_id` unless intentional.
+
 ## Doctor
 
 ```bash
@@ -74,7 +93,8 @@ These tools accept `project_id` and return:
 - missing local cache -> download
 - same version -> keep current
 - newer server version -> update local cache
-- workspace path -> follows active client workspace/root when provided by Codex/Claude
+- workspace path -> pinned to setup/proxy working directory by default
+- use `--workspace-dir auto` to follow active client workspace/root dynamically
 
 Ctxpack merge safety flow:
 - call `ctxpack.merge.brief` first
@@ -200,6 +220,8 @@ Actual publish:
 npm run publish:public
 ```
 
+If npm returns `You cannot publish over the previously published versions`, bump `package.json` version and retry.
+
 If npm account uses 2FA, pass OTP:
 
 ```bash

package/cli.mjs

@@ -25,6 +25,7 @@ const SELF_UPDATE_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
 const SELF_UPDATE_TIMEOUT_SECONDS = 6;
 const SELF_UPDATE_ENV_KEY = "METHEUS_CLI_AUTO_UPDATE";
 const SELF_UPDATE_GUARD_ENV_KEY = "METHEUS_CLI_SELF_UPDATE_ATTEMPTED";
+const ALLOW_HOME_WORKSPACE_ENV_KEY = "METHEUS_ALLOW_HOME_WORKSPACE";
 const AUTO_CTXPACK_SYNC_INTERVAL_MS = 60 * 1000;
 const autoCtxpackSyncTracker = new Map();
 
@@ -50,6 +51,7 @@ function printUsage() {
       "Environment:",
       "  METHEUS_TOKEN or MCP_AUTH_TOKEN is used first for proxy requests.",
       `  ${SELF_UPDATE_ENV_KEY}=0 to disable startup auto-update check.`,
+      `  ${ALLOW_HOME_WORKSPACE_ENV_KEY}=1 to allow using home directory as workspace root (disabled by default).`,
       "  If env is missing, stored token file is used:",
       `    ${AUTH_STORE_RELATIVE_PATH}`,
       "",
@@ -423,6 +425,29 @@ function resolveWorkspaceDirForRequest(defaultWorkspaceDir, requestObj, toolArgs
   return resolveWorkspaceDir(process.cwd());
 }
 
+function normalizedPathForCompare(rawPath) {
+  const candidate = sanitizeWorkspaceCandidate(rawPath);
+  if (!candidate) return "";
+  const normalized = path.normalize(candidate);
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function homeWorkspaceRoot() {
+  return sanitizeWorkspaceCandidate(firstNonEmptyString([process.env.USERPROFILE, process.env.HOME]));
+}
+
+function isHomeWorkspaceRoot(workspaceDir) {
+  const home = normalizedPathForCompare(homeWorkspaceRoot());
+  if (!home) return false;
+  const current = normalizedPathForCompare(workspaceDir);
+  if (!current) return false;
+  return current === home;
+}
+
+function allowHomeWorkspaceRoot() {
+  return boolFromRaw(process.env[ALLOW_HOME_WORKSPACE_ENV_KEY], false);
+}
+
 function resolveProjectIDForRequest({
   toolArgs,
   args,
@@ -437,8 +462,8 @@ function resolveProjectIDForRequest({
     toolArgs?.projectID,
     responseProjectID,
     envelopeProjectID,
-    workspaceMeta.project_id,
     args?.projectID,
+    workspaceMeta.project_id,
   ]);
 }
 
@@ -1172,7 +1197,11 @@ function findSyncMetaFile(startDir) {
 }
 
 function loadWorkspaceMeta(startDir) {
-  const metaFile = findSyncMetaFile(startDir);
+  const resolvedStart = resolveWorkspaceDir(startDir || process.cwd());
+  if (isHomeWorkspaceRoot(resolvedStart) && !allowHomeWorkspaceRoot()) {
+    return {};
+  }
+  const metaFile = findSyncMetaFile(resolvedStart);
   if (!metaFile) return {};
   try {
     const raw = fs.readFileSync(metaFile, "utf8");
@@ -2418,6 +2447,17 @@ function syncCtxpackToLocalCache({ siteBaseURL, projectID, ctxpack, workspaceDir
   const metaPath = path.join(cacheDir, CTXPACK_META_FILENAME);
   const workspaceMetaPath = path.join(resolvedWorkspaceDir, CTXPACK_META_FILENAME);
 
+  if (isHomeWorkspaceRoot(resolvedWorkspaceDir) && !allowHomeWorkspaceRoot()) {
+    return {
+      sync_status: "guarded",
+      sync_message:
+        "Workspace root resolved to home directory. Guardrail blocked ctxpack local write. Use --workspace-dir <project_path> or --workspace-dir auto.",
+      local_path: cacheDir,
+      workspace_path: resolvedWorkspaceDir,
+      local_file_count: 0,
+    };
+  }
+
   if (!ctxpackID || !version || files.length === 0) {
     return {
       sync_status: "not_available",
@@ -3622,13 +3662,20 @@ async function appendCtxpackConflictHintToErrorResponse(responseObj, args, toolN
 }
 
 async function runProxy(flags) {
-  const explicitWorkspaceDirRaw = String(flags["workspace-dir"] || "").trim();
-  const explicitWorkspaceDir = explicitWorkspaceDirRaw ? resolveWorkspaceDir(explicitWorkspaceDirRaw) : "";
+  const workspaceDirRaw = String(flags["workspace-dir"] || "").trim();
+  const hasWorkspaceDirFlag = Object.prototype.hasOwnProperty.call(flags, "workspace-dir");
+  const workspaceAutoMode = hasWorkspaceDirFlag && workspaceDirRaw.length > 0 && isAutoWorkspaceMode(workspaceDirRaw);
+  const explicitPinnedWorkspace = hasWorkspaceDirFlag && !workspaceAutoMode;
+  // Keep pinned workspace only when user explicitly set --workspace-dir.
+  // If not explicitly set, resolve per-request from client metadata/env first.
+  const pinnedWorkspaceDir = explicitPinnedWorkspace ? resolveWorkspaceDir(workspaceDirRaw || process.cwd()) : "";
   const args = {
     baseURL: flags["base-url"] || DEFAULT_BASE_URL,
     projectID: String(flags["project-id"] || "").trim(),
     ctxpackKey: String(flags["ctxpack-key"] || "").trim(),
-    workspaceDir: explicitWorkspaceDir,
+    workspaceDir: pinnedWorkspaceDir,
+    workspaceAutoMode,
+    explicitPinnedWorkspace,
     includeDrafts: boolFromRaw(flags["include-drafts"], true),
     autoPullOnConflict: boolFromRaw(flags["auto-pull-on-conflict"], true),
     timeoutSeconds: intFromRaw(flags["timeout-seconds"], 30),
@@ -3694,18 +3741,22 @@ async function runProxy(flags) {
     }
 
     const { name: toolName, args: toolArgs } = extractToolCall(requestObj);
-    const requestWorkspaceCandidate = extractWorkspaceCandidateFromRequest(requestObj, toolArgs);
-    const envWorkspaceCandidate = extractWorkspaceCandidateFromEnv();
-    if (requestWorkspaceCandidate) {
-      sessionWorkspaceDir = requestWorkspaceCandidate;
-    } else if (envWorkspaceCandidate) {
-      sessionWorkspaceDir = envWorkspaceCandidate;
+    if (!args.explicitPinnedWorkspace) {
+      const requestWorkspaceCandidate = extractWorkspaceCandidateFromRequest(requestObj, toolArgs);
+      const envWorkspaceCandidate = extractWorkspaceCandidateFromEnv();
+      if (requestWorkspaceCandidate) {
+        sessionWorkspaceDir = requestWorkspaceCandidate;
+      } else if (envWorkspaceCandidate) {
+        sessionWorkspaceDir = envWorkspaceCandidate;
+      }
     }
-    const requestWorkspaceDir = resolveWorkspaceDirForRequest(
-      firstNonEmptyString([sessionWorkspaceDir, args.workspaceDir, process.cwd()]),
-      requestObj,
-      toolArgs,
-    );
+    const requestWorkspaceDir = args.explicitPinnedWorkspace
+      ? resolveWorkspaceDir(args.workspaceDir || process.cwd())
+      : resolveWorkspaceDirForRequest(
+          firstNonEmptyString([sessionWorkspaceDir, args.workspaceDir, process.cwd()]),
+          requestObj,
+          toolArgs,
+        );
     let autoSyncSummary = null;
     if (isJsonRpcMethod(requestObj, "tools/call")) {
       autoSyncSummary = await maybeAutoSyncCtxpackForCall({
@@ -4013,16 +4064,15 @@ function resolveSetupContext(flags) {
   const workspaceDirRaw = String(flags["workspace-dir"] || "").trim();
   const hasWorkspaceDirFlag = workspaceDirRaw.length > 0;
   const workspaceAutoMode = hasWorkspaceDirFlag && isAutoWorkspaceMode(workspaceDirRaw);
-  // Default: auto workspace detection at runtime.
-  // Pin only when user explicitly passes --workspace-dir <path>.
-  const shouldPinWorkspaceDir = hasWorkspaceDirFlag && !workspaceAutoMode;
+  // Default: pin to current working directory.
+  // Use --workspace-dir auto for dynamic runtime workspace detection.
+  const shouldPinWorkspaceDir = !workspaceAutoMode;
   const workspaceDir = resolveWorkspaceDir(
-    shouldPinWorkspaceDir ? workspaceDirRaw : process.cwd(),
+    shouldPinWorkspaceDir ? workspaceDirRaw || process.cwd() : process.cwd(),
   );
   const serverName = String(flags.name || DEFAULT_SERVER_NAME).trim() || DEFAULT_SERVER_NAME;
   const proxyArgs = ["--base-url", `${baseURL}/governance/mcp`];
-  // Runtime auto-detection is default.
-  // Use --workspace-dir <path> when deterministic pinning is preferred.
+  // Pin workspace by default to avoid spreading ctxpack cache across mixed client roots.
   if (shouldPinWorkspaceDir) {
     proxyArgs.push("--workspace-dir", workspaceDir);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metheus-governance-mcp-cli",
-  "version": "0.2.15",
+  "version": "0.2.16",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [