metheus-governance-mcp-cli 0.2.16 → 0.2.18

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,23 @@ function extractWorkspaceCandidateFromRequest(requestObj, toolArgs) {
     args.workspaceDir,
     params.workspace_dir,
     params.workspaceDir,
+    meta.workspace_dir,
+    meta.workspaceDir,
+  ]);
+  return sanitizeWorkspaceCandidate(rawCandidate);
+}
+
+function extractWorkspaceCandidateFromRequest(requestObj, toolArgs) {
+  const strongCandidate = extractStrongWorkspaceCandidateFromRequest(requestObj, toolArgs);
+  if (strongCandidate) return strongCandidate;
+  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 +407,22 @@ 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() {
+  const rawCandidate = firstNonEmptyString([
+    extractStrongWorkspaceCandidateFromEnv(),
     process.env.WORKSPACE_DIR,
     process.env.WORKSPACE_FOLDER,
     process.env.VSCODE_WORKSPACE_FOLDER,
@@ -2436,7 +2455,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 +2483,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 +2578,7 @@ async function loadProjectSummaryForTool({
   syncCtxpackLocal,
   workspaceDir,
   ctxpackPaths,
+  workspaceSignalTrusted = true,
 }) {
   const encodedProjectID = encodeURIComponent(projectID);
   let projectRaw = null;
@@ -2607,6 +2644,7 @@ async function loadProjectSummaryForTool({
           projectID,
           ctxpack,
           workspaceDir,
+          workspaceSignalTrusted,
         });
         ctxpackSyncStatus = syncResult.sync_status || "error";
         ctxpackSyncMessage = String(syncResult.sync_message || "").trim();
@@ -3267,6 +3305,7 @@ async function maybeAutoSyncCtxpackForCall({
   args,
   token,
   workspaceDir,
+  workspaceSignalTrusted = true,
 }) {
   if (!isJsonRpcMethod(requestObj, "tools/call")) return null;
   if (!token) return null;
@@ -3298,6 +3337,7 @@ async function maybeAutoSyncCtxpackForCall({
       includeCtxpack: true,
       syncCtxpackLocal: true,
       workspaceDir: workspacePath,
+      workspaceSignalTrusted,
     });
   } catch {
     return null;
@@ -3329,7 +3369,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 +3428,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 +3466,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 +3500,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 +3658,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 +3698,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 +3735,7 @@ async function runProxy(flags) {
   let lastRefreshAttemptAtMs = 0;
   let lastRefreshError = "";
   let sessionWorkspaceDir = "";
+  let sessionWorkspaceTrusted = false;
 
   const rl = readline.createInterface({
     input: process.stdin,
@@ -3741,15 +3793,36 @@ async function runProxy(flags) {
     }
 
     const { name: toolName, args: toolArgs } = extractToolCall(requestObj);
+    let requestWorkspaceCandidate = "";
+    let strongRequestWorkspaceCandidate = "";
+    let strongEnvWorkspaceCandidate = "";
     if (!args.explicitPinnedWorkspace) {
-      const requestWorkspaceCandidate = extractWorkspaceCandidateFromRequest(requestObj, toolArgs);
-      const envWorkspaceCandidate = extractWorkspaceCandidateFromEnv();
+      strongRequestWorkspaceCandidate = extractStrongWorkspaceCandidateFromRequest(requestObj, toolArgs);
+      requestWorkspaceCandidate = firstNonEmptyString([
+        strongRequestWorkspaceCandidate,
+        extractWorkspaceCandidateFromRequest(requestObj, toolArgs),
+      ]);
+      strongEnvWorkspaceCandidate = extractStrongWorkspaceCandidateFromEnv();
+      const envWorkspaceCandidate = firstNonEmptyString([
+        strongEnvWorkspaceCandidate,
+        extractWorkspaceCandidateFromEnv(),
+      ]);
       if (requestWorkspaceCandidate) {
         sessionWorkspaceDir = requestWorkspaceCandidate;
+        if (strongRequestWorkspaceCandidate) {
+          sessionWorkspaceTrusted = true;
+        }
       } else if (envWorkspaceCandidate) {
         sessionWorkspaceDir = envWorkspaceCandidate;
+        if (strongEnvWorkspaceCandidate) {
+          sessionWorkspaceTrusted = true;
+        }
       }
     }
+    const workspaceSignalTrusted =
+      args.explicitPinnedWorkspace ||
+      sessionWorkspaceTrusted ||
+      Boolean(strongRequestWorkspaceCandidate || strongEnvWorkspaceCandidate);
     const requestWorkspaceDir = args.explicitPinnedWorkspace
       ? resolveWorkspaceDir(args.workspaceDir || process.cwd())
       : resolveWorkspaceDirForRequest(
@@ -3766,6 +3839,7 @@ async function runProxy(flags) {
         args,
         token,
         workspaceDir: requestWorkspaceDir,
+        workspaceSignalTrusted,
       });
     }
     if (isJsonRpcMethod(requestObj, "tools/call") && LOCAL_PROJECT_TOOL_NAMES.includes(toolName)) {
@@ -3809,6 +3883,7 @@ async function runProxy(flags) {
           includeCtxpack,
           syncCtxpackLocal,
           workspaceDir: requestWorkspaceDir,
+          workspaceSignalTrusted,
         });
         const text = buildProjectSummaryText(summary);
         process.stdout.write(
@@ -3962,6 +4037,7 @@ async function runProxy(flags) {
               toolArgs,
               token,
               requestWorkspaceDir,
+              workspaceSignalTrusted,
             );
             process.stdout.write(`${JSON.stringify(patched)}\n`);
             return;
@@ -3971,9 +4047,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);
@@ -4017,16 +4099,24 @@ function commandExists(bin) {
   return check.status === 0;
 }
 
-function tryRegister(cliBin, serverName, proxyArgs) {
+function tryRegister(cliBin, serverName, proxyArgs, options = {}) {
   const selfPath = fileURLToPath(import.meta.url);
   const baseAddArgs =
     cliBin === "claude"
       ? ["mcp", "add", "--scope", "user", serverName]
       : ["mcp", "add", serverName];
-  const attempts = [
-    [...baseAddArgs, "--", process.execPath, selfPath, "proxy", ...proxyArgs],
-    [...baseAddArgs, process.execPath, selfPath, "proxy", ...proxyArgs],
-  ];
+  const workspaceEnv = String(options.workspaceDir || "").trim();
+  const codexEnvArgs =
+    cliBin === "codex" && workspaceEnv
+      ? ["--env", `METHEUS_WORKSPACE_DIR=${workspaceEnv}`]
+      : [];
+  const attempts = [];
+  if (codexEnvArgs.length > 0) {
+    attempts.push([...baseAddArgs, ...codexEnvArgs, "--", process.execPath, selfPath, "proxy", ...proxyArgs]);
+    attempts.push([...baseAddArgs, ...codexEnvArgs, process.execPath, selfPath, "proxy", ...proxyArgs]);
+  }
+  attempts.push([...baseAddArgs, "--", process.execPath, selfPath, "proxy", ...proxyArgs]);
+  attempts.push([...baseAddArgs, process.execPath, selfPath, "proxy", ...proxyArgs]);
   for (const args of attempts) {
     const run = runCLICommand(cliBin, args, { stdio: "inherit" });
     if (run.status === 0) return true;
@@ -4062,18 +4152,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);
@@ -4083,6 +4178,7 @@ function resolveSetupContext(flags) {
     ctxpackKey,
     baseURL,
     workspaceDir,
+    workspaceFallbackDir,
     shouldPinWorkspaceDir,
     workspaceAutoMode,
     serverName,
@@ -4102,7 +4198,11 @@ function runSetupInternal(flags, options = {}) {
     if (!ensureOnly || alreadyRegistered) {
       runRemove(cliBin, context.serverName);
     }
-    const ok = tryRegister(cliBin, context.serverName, context.proxyArgs);
+    const ok = tryRegister(cliBin, context.serverName, context.proxyArgs, {
+      workspaceDir: context.shouldPinWorkspaceDir
+        ? context.workspaceDir
+        : context.workspaceFallbackDir,
+    });
     const action = ensureOnly
       ? alreadyRegistered
         ? "updated"
@@ -4117,6 +4217,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.16",
+  "version": "0.2.18",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [