metheus-governance-mcp-cli 0.2.17 → 0.2.19

package/README.md

@@ -37,6 +37,8 @@ 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`.
+`setup` defaults to `--workspace-dir auto` (dynamic workspace detection).
+Use an explicit path only when you intentionally want a fixed workspace.
 
 Recommended for Codex/Claude multi-workspace sessions:
 
@@ -44,6 +46,15 @@ Recommended for Codex/Claude multi-workspace sessions:
 metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctxpack_key>" --base-url https://metheus.gesiaplatform.com --workspace-dir auto
 ```
 
+When a client does not send workspace metadata (for example some Codex sessions),
+set a stable fallback root once:
+
+```bash
+metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctxpack_key>" --base-url https://metheus.gesiaplatform.com --workspace-dir auto --workspace-fallback-dir C:\code_test
+```
+
+This registers `METHEUS_WORKSPACE_DIR` for Codex MCP so ctxpack sync still resolves safely.
+
 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`.
@@ -93,8 +104,8 @@ These tools accept `project_id` and return:
 - missing local cache -> download
 - same version -> keep current
 - newer server version -> update local cache
-- workspace path -> pinned to setup/proxy working directory by default
-- use `--workspace-dir auto` to follow active client workspace/root dynamically
+- workspace path -> auto-detected from client metadata/env by default
+- use `--workspace-fallback-dir <path>` when client metadata is unavailable
 
 Ctxpack merge safety flow:
 - call `ctxpack.merge.brief` first

package/cli.mjs

@@ -38,7 +38,7 @@ function printUsage() {
       "Usage:",
       `  ${cmd} [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path|auto>] [--flow <auto|device|callback|manual>]`,
       `  ${cmd} init [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--flow <auto|device|callback|manual>]`,
-      `  ${cmd} setup [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path|auto>] [--name <server_name>]`,
+      `  ${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} ctxpack pull [--project-id <uuid>] [--base-url <url>] [--workspace-dir <path|auto>] [--paths <csv>] [--timeout-seconds <n>]`,
@@ -365,7 +365,7 @@ function extractWorkspaceCandidateFromFolders(rawFolders) {
   return "";
 }
 
-function extractWorkspaceCandidateFromRequest(requestObj, toolArgs) {
+function extractStrongWorkspaceCandidateFromRequest(requestObj, toolArgs) {
   const params = safeObject(requestObj?.params);
   const meta = safeObject(params._meta);
   const workspaceFromFolders = firstNonEmptyString([
@@ -381,13 +381,28 @@ function extractWorkspaceCandidateFromRequest(requestObj, toolArgs) {
     args.workspaceDir,
     params.workspace_dir,
     params.workspaceDir,
+    meta.workspace_dir,
+    meta.workspaceDir,
+  ]);
+  return sanitizeWorkspaceCandidate(rawCandidate);
+}
+
+function extractWorkspaceCandidateFromRequest(requestObj, toolArgs) {
+  return firstNonEmptyString([
+    extractStrongWorkspaceCandidateFromRequest(requestObj, toolArgs),
+    extractWeakWorkspaceCandidateFromRequest(requestObj),
+  ]);
+}
+
+function extractWeakWorkspaceCandidateFromRequest(requestObj) {
+  const params = safeObject(requestObj?.params);
+  const meta = safeObject(params._meta);
+  const rawCandidate = firstNonEmptyString([
     params.cwd,
     params.root_path,
     params.rootPath,
     params.root_uri,
     params.rootUri,
-    meta.workspace_dir,
-    meta.workspaceDir,
     meta.cwd,
     meta.root_path,
     meta.rootPath,
@@ -397,13 +412,28 @@ function extractWorkspaceCandidateFromRequest(requestObj, toolArgs) {
   return sanitizeWorkspaceCandidate(rawCandidate);
 }
 
-function extractWorkspaceCandidateFromEnv() {
+function extractStrongWorkspaceCandidateFromEnv() {
   const rawCandidate = firstNonEmptyString([
     process.env.METHEUS_WORKSPACE_DIR,
+    process.env.METHEUS_WORKSPACE_URI,
+    process.env.CODEX_WORKSPACE_DIR,
+    process.env.CODEX_WORKSPACE_URI,
     process.env.CLAUDE_WORKSPACE_DIR,
     process.env.CLAUDE_WORKSPACE_URI,
     process.env.CLAUDE_PROJECT_DIR,
-    process.env.CODEX_WORKSPACE_DIR,
+  ]);
+  return sanitizeWorkspaceCandidate(rawCandidate);
+}
+
+function extractWorkspaceCandidateFromEnv() {
+  return firstNonEmptyString([
+    extractStrongWorkspaceCandidateFromEnv(),
+    extractWeakWorkspaceCandidateFromEnv(),
+  ]);
+}
+
+function extractWeakWorkspaceCandidateFromEnv() {
+  const rawCandidate = firstNonEmptyString([
     process.env.WORKSPACE_DIR,
     process.env.WORKSPACE_FOLDER,
     process.env.VSCODE_WORKSPACE_FOLDER,
@@ -415,10 +445,20 @@ function extractWorkspaceCandidateFromEnv() {
 }
 
 function resolveWorkspaceDirForRequest(defaultWorkspaceDir, requestObj, toolArgs) {
-  const requestCandidate = extractWorkspaceCandidateFromRequest(requestObj, toolArgs);
-  const envCandidate = extractWorkspaceCandidateFromEnv();
+  const strongRequestCandidate = extractStrongWorkspaceCandidateFromRequest(requestObj, toolArgs);
+  const strongEnvCandidate = extractStrongWorkspaceCandidateFromEnv();
+  const weakRequestCandidate = extractWeakWorkspaceCandidateFromRequest(requestObj);
+  const weakEnvCandidate = extractWeakWorkspaceCandidateFromEnv();
   const homeCandidate = firstNonEmptyString([process.env.USERPROFILE, process.env.HOME]);
-  for (const rawCandidate of [requestCandidate, envCandidate, defaultWorkspaceDir, process.cwd(), homeCandidate]) {
+  for (const rawCandidate of [
+    strongRequestCandidate,
+    strongEnvCandidate,
+    weakRequestCandidate,
+    weakEnvCandidate,
+    defaultWorkspaceDir,
+    process.cwd(),
+    homeCandidate,
+  ]) {
     const resolved = sanitizeWorkspaceCandidate(rawCandidate);
     if (resolved) return resolved;
   }
@@ -2436,7 +2476,13 @@ function hasAllCtxpackFiles(baseDir, files) {
   return true;
 }
 
-function syncCtxpackToLocalCache({ siteBaseURL, projectID, ctxpack, workspaceDir }) {
+function syncCtxpackToLocalCache({
+  siteBaseURL,
+  projectID,
+  ctxpack,
+  workspaceDir,
+  workspaceSignalTrusted = true,
+}) {
   const ctxpackID = String(ctxpack?.ctxpack_id || "").trim();
   const version = String(ctxpack?.version || "").trim();
   const versionID = String(ctxpack?.version_id || ctxpack?.current_version_id || "").trim();
@@ -2458,6 +2504,17 @@ function syncCtxpackToLocalCache({ siteBaseURL, projectID, ctxpack, workspaceDir
     };
   }
 
+  if (!workspaceSignalTrusted) {
+    return {
+      sync_status: "guarded",
+      sync_message:
+        "Workspace signal is missing in auto mode. Guardrail blocked ctxpack local write to avoid wrong folder sync.",
+      local_path: cacheDir,
+      workspace_path: resolvedWorkspaceDir,
+      local_file_count: 0,
+    };
+  }
+
   if (!ctxpackID || !version || files.length === 0) {
     return {
       sync_status: "not_available",
@@ -2542,6 +2599,7 @@ async function loadProjectSummaryForTool({
   syncCtxpackLocal,
   workspaceDir,
   ctxpackPaths,
+  workspaceSignalTrusted = true,
 }) {
   const encodedProjectID = encodeURIComponent(projectID);
   let projectRaw = null;
@@ -2607,6 +2665,7 @@ async function loadProjectSummaryForTool({
           projectID,
           ctxpack,
           workspaceDir,
+          workspaceSignalTrusted,
         });
         ctxpackSyncStatus = syncResult.sync_status || "error";
         ctxpackSyncMessage = String(syncResult.sync_message || "").trim();
@@ -3267,6 +3326,7 @@ async function maybeAutoSyncCtxpackForCall({
   args,
   token,
   workspaceDir,
+  workspaceSignalTrusted = true,
 }) {
   if (!isJsonRpcMethod(requestObj, "tools/call")) return null;
   if (!token) return null;
@@ -3298,6 +3358,7 @@ async function maybeAutoSyncCtxpackForCall({
       includeCtxpack: true,
       syncCtxpackLocal: true,
       workspaceDir: workspacePath,
+      workspaceSignalTrusted,
     });
   } catch {
     return null;
@@ -3329,7 +3390,7 @@ function appendAutoCtxpackSyncHint(responseObj, summary) {
   return responseObj;
 }
 
-async function appendWorkitemListHints(responseObj, args, toolArgs, token) {
+async function appendWorkitemListHints(responseObj, args, toolArgs, token, workspaceSignalTrusted = true) {
   const result = safeObject(responseObj.result);
   const content = ensureArray(result.content);
   if (!content.length) return responseObj;
@@ -3388,6 +3449,7 @@ async function appendWorkitemListHints(responseObj, args, toolArgs, token) {
         includeCtxpack: isEmptyBody,
         syncCtxpackLocal: isEmptyBody,
         workspaceDir: args.workspaceDir,
+        workspaceSignalTrusted,
       });
       if (String(summary.access || "") === "granted") {
         nextLines.push("Project context:");
@@ -3425,7 +3487,7 @@ async function appendWorkitemListHints(responseObj, args, toolArgs, token) {
   return responseObj;
 }
 
-function appendCtxpackEnsureSyncHints(responseObj, args, toolArgs, requestObj) {
+function appendCtxpackEnsureSyncHints(responseObj, args, toolArgs, requestObj, workspaceSignalTrusted = true) {
   const result = safeObject(responseObj.result);
   const content = ensureArray(result.content);
   if (!content.length) return responseObj;
@@ -3459,6 +3521,7 @@ function appendCtxpackEnsureSyncHints(responseObj, args, toolArgs, requestObj) {
     projectID,
     ctxpack: body,
     workspaceDir,
+    workspaceSignalTrusted,
   });
   const baseVersionID = firstNonEmptyString([body.base_version_id, body.version_id, body.current_version_id]);
   const currentVersionID = firstNonEmptyString([body.current_version_id, body.version_id, body.base_version_id]);
@@ -3616,7 +3679,15 @@ async function injectCtxpackPreflightToken(requestObj, toolName, toolArgs, args,
   }
 }
 
-async function appendCtxpackConflictHintToErrorResponse(responseObj, args, toolName, toolArgs, token, workspaceDir) {
+async function appendCtxpackConflictHintToErrorResponse(
+  responseObj,
+  args,
+  toolName,
+  toolArgs,
+  token,
+  workspaceDir,
+  workspaceSignalTrusted = true,
+) {
   const out = safeObject(responseObj);
   const errObj = safeObject(out.error);
   const message = String(errObj.message || "").trim();
@@ -3648,6 +3719,7 @@ async function appendCtxpackConflictHintToErrorResponse(responseObj, args, toolN
         projectID: projectIDHint,
         ctxpack: safeObject(ctxpackRaw),
         workspaceDir,
+        workspaceSignalTrusted,
       });
       autoPullHint = ` auto-pull: ${String(syncResult.sync_status || "error")}${
         syncResult.local_path ? ` (${String(syncResult.local_path)})` : ""
@@ -3684,6 +3756,7 @@ async function runProxy(flags) {
   let lastRefreshAttemptAtMs = 0;
   let lastRefreshError = "";
   let sessionWorkspaceDir = "";
+  let sessionWorkspaceTrusted = false;
 
   const rl = readline.createInterface({
     input: process.stdin,
@@ -3741,15 +3814,31 @@ async function runProxy(flags) {
     }
 
     const { name: toolName, args: toolArgs } = extractToolCall(requestObj);
+    let strongRequestWorkspaceCandidate = "";
+    let weakRequestWorkspaceCandidate = "";
+    let strongEnvWorkspaceCandidate = "";
+    let weakEnvWorkspaceCandidate = "";
     if (!args.explicitPinnedWorkspace) {
-      const requestWorkspaceCandidate = extractWorkspaceCandidateFromRequest(requestObj, toolArgs);
-      const envWorkspaceCandidate = extractWorkspaceCandidateFromEnv();
-      if (requestWorkspaceCandidate) {
-        sessionWorkspaceDir = requestWorkspaceCandidate;
-      } else if (envWorkspaceCandidate) {
-        sessionWorkspaceDir = envWorkspaceCandidate;
+      strongRequestWorkspaceCandidate = extractStrongWorkspaceCandidateFromRequest(requestObj, toolArgs);
+      weakRequestWorkspaceCandidate = extractWeakWorkspaceCandidateFromRequest(requestObj);
+      strongEnvWorkspaceCandidate = extractStrongWorkspaceCandidateFromEnv();
+      weakEnvWorkspaceCandidate = extractWeakWorkspaceCandidateFromEnv();
+      if (strongRequestWorkspaceCandidate) {
+        sessionWorkspaceDir = strongRequestWorkspaceCandidate;
+        sessionWorkspaceTrusted = true;
+      } else if (strongEnvWorkspaceCandidate) {
+        sessionWorkspaceDir = strongEnvWorkspaceCandidate;
+        sessionWorkspaceTrusted = true;
+      } else if (weakRequestWorkspaceCandidate) {
+        sessionWorkspaceDir = weakRequestWorkspaceCandidate;
+      } else if (weakEnvWorkspaceCandidate) {
+        sessionWorkspaceDir = weakEnvWorkspaceCandidate;
       }
     }
+    const workspaceSignalTrusted =
+      args.explicitPinnedWorkspace ||
+      sessionWorkspaceTrusted ||
+      Boolean(strongRequestWorkspaceCandidate || strongEnvWorkspaceCandidate);
     const requestWorkspaceDir = args.explicitPinnedWorkspace
       ? resolveWorkspaceDir(args.workspaceDir || process.cwd())
       : resolveWorkspaceDirForRequest(
@@ -3766,6 +3855,7 @@ async function runProxy(flags) {
         args,
         token,
         workspaceDir: requestWorkspaceDir,
+        workspaceSignalTrusted,
       });
     }
     if (isJsonRpcMethod(requestObj, "tools/call") && LOCAL_PROJECT_TOOL_NAMES.includes(toolName)) {
@@ -3809,6 +3899,7 @@ async function runProxy(flags) {
           includeCtxpack,
           syncCtxpackLocal,
           workspaceDir: requestWorkspaceDir,
+          workspaceSignalTrusted,
         });
         const text = buildProjectSummaryText(summary);
         process.stdout.write(
@@ -3962,6 +4053,7 @@ async function runProxy(flags) {
               toolArgs,
               token,
               requestWorkspaceDir,
+              workspaceSignalTrusted,
             );
             process.stdout.write(`${JSON.stringify(patched)}\n`);
             return;
@@ -3971,9 +4063,15 @@ async function runProxy(flags) {
           } else if (isJsonRpcMethod(requestObj, "initialize")) {
             patched = appendProjectHintToInitialize(patched, args);
           } else if (isJsonRpcMethod(requestObj, "tools/call") && toolName === "workitem.list") {
-            patched = await appendWorkitemListHints(patched, args, toolArgs, token);
+            patched = await appendWorkitemListHints(patched, args, toolArgs, token, workspaceSignalTrusted);
           } else if (isJsonRpcMethod(requestObj, "tools/call") && toolName === "ctxpack.ensure") {
-            patched = appendCtxpackEnsureSyncHints(patched, args, toolArgs, requestObj);
+            patched = appendCtxpackEnsureSyncHints(
+              patched,
+              args,
+              toolArgs,
+              requestObj,
+              workspaceSignalTrusted,
+            );
           }
           if (autoSyncSummary) {
             patched = appendAutoCtxpackSyncHint(patched, autoSyncSummary);
@@ -4070,18 +4168,23 @@ function resolveSetupContext(flags) {
   const ctxpackKey = String(flags["ctxpack-key"] || buildCtxpackKeyFromMeta(workspaceMeta) || "").trim();
   const baseURL = String(flags["base-url"] || DEFAULT_SITE_URL).trim().replace(/\/+$/, "");
   const workspaceDirRaw = String(flags["workspace-dir"] || "").trim();
-  const hasWorkspaceDirFlag = workspaceDirRaw.length > 0;
-  const workspaceAutoMode = hasWorkspaceDirFlag && isAutoWorkspaceMode(workspaceDirRaw);
-  // Default: pin to current working directory.
-  // Use --workspace-dir auto for dynamic runtime workspace detection.
-  const shouldPinWorkspaceDir = !workspaceAutoMode;
+  const workspaceFallbackDirRaw = String(flags["workspace-fallback-dir"] || "").trim();
+  const hasWorkspaceDirFlag = Object.prototype.hasOwnProperty.call(flags, "workspace-dir");
+  // Default to auto workspace mode for safer multi-project Codex sessions.
+  const workspaceAutoMode = !hasWorkspaceDirFlag || isAutoWorkspaceMode(workspaceDirRaw);
+  // Pin only when user explicitly set a non-auto workspace-dir.
+  const shouldPinWorkspaceDir = hasWorkspaceDirFlag && !workspaceAutoMode;
+  const workspaceFallbackDir = workspaceFallbackDirRaw
+    ? resolveWorkspaceDir(workspaceFallbackDirRaw)
+    : "";
   const workspaceDir = resolveWorkspaceDir(
     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`];
-  // Pin workspace by default to avoid spreading ctxpack cache across mixed client roots.
-  if (shouldPinWorkspaceDir) {
+  if (workspaceAutoMode) {
+    proxyArgs.push("--workspace-dir", "auto");
+  } else if (shouldPinWorkspaceDir) {
     proxyArgs.push("--workspace-dir", workspaceDir);
   }
   if (projectID) proxyArgs.push("--project-id", projectID);
@@ -4091,6 +4194,7 @@ function resolveSetupContext(flags) {
     ctxpackKey,
     baseURL,
     workspaceDir,
+    workspaceFallbackDir,
     shouldPinWorkspaceDir,
     workspaceAutoMode,
     serverName,
@@ -4111,7 +4215,9 @@ function runSetupInternal(flags, options = {}) {
       runRemove(cliBin, context.serverName);
     }
     const ok = tryRegister(cliBin, context.serverName, context.proxyArgs, {
-      workspaceDir: context.workspaceDir,
+      workspaceDir: context.shouldPinWorkspaceDir
+        ? context.workspaceDir
+        : context.workspaceFallbackDir,
     });
     const action = ensureOnly
       ? alreadyRegistered
@@ -4127,6 +4233,9 @@ function runSetupInternal(flags, options = {}) {
   process.stdout.write(`Server:    ${context.serverName}\n`);
   process.stdout.write(`Gateway:   ${context.baseURL}/governance/mcp\n`);
   process.stdout.write(`Workspace: ${context.shouldPinWorkspaceDir ? context.workspaceDir : "auto (client current folder)"}\n`);
+  if (!context.shouldPinWorkspaceDir && context.workspaceFallbackDir) {
+    process.stdout.write(`Fallback:  ${context.workspaceFallbackDir} (METHEUS_WORKSPACE_DIR)\n`);
+  }
   process.stdout.write(`Project:   ${context.projectID || "auto-detect from .metheus_ctxpack_sync.json"}\n`);
   if (context.ctxpackKey) {
     process.stdout.write(`Ctxpack:   ${context.ctxpackKey}\n`);

package/package.json

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