metheus-governance-mcp-cli 0.2.4 → 0.2.6

package/cli.mjs

@@ -26,12 +26,12 @@ function printUsage() {
       "Metheus Governance MCP CLI",
       "",
       "Usage:",
-      "  metheus-governance-mcp [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--flow <auto|device|callback|manual>]",
+      "  metheus-governance-mcp [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path>] [--flow <auto|device|callback|manual>]",
       "  metheus-governance-mcp init [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--flow <auto|device|callback|manual>]",
-      "  metheus-governance-mcp setup [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--name <server_name>]",
+      "  metheus-governance-mcp setup [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path>] [--name <server_name>]",
       "  metheus-governance-mcp doctor [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--timeout-seconds <n>]",
-      "  metheus-governance-mcp proxy [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--include-drafts <true|false>] [--timeout-seconds <n>]",
-      "  metheus-governance-mcp ctxpack pull [--project-id <uuid>] [--base-url <url>] [--timeout-seconds <n>]",
+      "  metheus-governance-mcp proxy [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path>] [--include-drafts <true|false>] [--timeout-seconds <n>]",
+      "  metheus-governance-mcp ctxpack pull [--project-id <uuid>] [--base-url <url>] [--workspace-dir <path>] [--timeout-seconds <n>]",
       "  metheus-governance-mcp auth status",
       "  metheus-governance-mcp 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>]",
       "  metheus-governance-mcp auth set --token <jwt> [--refresh-token <token>] [--base-url <url>]",
@@ -101,7 +101,15 @@ function authStoreFilePath() {
   return path.join(home, AUTH_STORE_RELATIVE_PATH);
 }
 
-function ctxpackCacheRootDir() {
+function resolveWorkspaceDir(rawPath) {
+  const input = String(rawPath || "").trim();
+  if (input) {
+    return path.resolve(input);
+  }
+  return path.resolve(process.cwd());
+}
+
+function homeCtxpackCacheRootDir() {
   const home = String(process.env.USERPROFILE || process.env.HOME || "").trim();
   if (!home) {
     return path.resolve(process.cwd(), CTXPACK_CACHE_RELATIVE_DIR);
@@ -109,6 +117,14 @@ function ctxpackCacheRootDir() {
   return path.join(home, CTXPACK_CACHE_RELATIVE_DIR);
 }
 
+function ctxpackCacheRootDir(workspaceDir) {
+  const root = resolveWorkspaceDir(workspaceDir);
+  if (!root) {
+    return homeCtxpackCacheRootDir();
+  }
+  return path.join(root, CTXPACK_CACHE_RELATIVE_DIR);
+}
+
 function ensureParentDir(filePath) {
   const parent = path.dirname(filePath);
   fs.mkdirSync(parent, { recursive: true });
@@ -1241,6 +1257,7 @@ async function resolveAccessTokenForCommand(baseURL, timeoutSeconds) {
 async function runCtxpackPull(flags) {
   const workspaceMeta = loadWorkspaceMeta(process.cwd());
   const projectID = String(flags["project-id"] || workspaceMeta.project_id || "").trim();
+  const workspaceDir = resolveWorkspaceDir(flags["workspace-dir"] || process.cwd());
   if (!projectID) {
     process.stderr.write("Missing project_id. Use --project-id <uuid> or run inside a synced ctxpack workspace.\n");
     process.exitCode = 1;
@@ -1271,6 +1288,7 @@ async function runCtxpackPull(flags) {
     timeoutSeconds,
     includeCtxpack: true,
     syncCtxpackLocal: true,
+    workspaceDir,
   });
   process.stdout.write(`${buildProjectSummaryText(summary)}\n`);
 
@@ -1457,6 +1475,7 @@ async function runDoctor(flags) {
     timeoutSeconds,
     includeCtxpack: true,
     syncCtxpackLocal: true,
+    workspaceDir: context.workspaceDir,
   });
   if (String(summary.access || "") !== "granted") {
     addDoctorCheck(
@@ -1832,19 +1851,22 @@ function hasAllCtxpackFiles(baseDir, files) {
   return true;
 }
 
-function syncCtxpackToLocalCache({ siteBaseURL, projectID, ctxpack }) {
+function syncCtxpackToLocalCache({ siteBaseURL, projectID, ctxpack, workspaceDir }) {
   const ctxpackID = String(ctxpack?.ctxpack_id || "").trim();
   const version = String(ctxpack?.version || "").trim();
   const status = String(ctxpack?.status || "").trim() || "draft";
   const files = normalizeCtxpackFiles(ctxpack?.files);
-  const cacheDir = path.join(ctxpackCacheRootDir(), projectID);
+  const resolvedWorkspaceDir = resolveWorkspaceDir(workspaceDir);
+  const cacheDir = path.join(ctxpackCacheRootDir(resolvedWorkspaceDir), projectID);
   const metaPath = path.join(cacheDir, CTXPACK_META_FILENAME);
+  const workspaceMetaPath = path.join(resolvedWorkspaceDir, CTXPACK_META_FILENAME);
 
   if (!ctxpackID || !version || files.length === 0) {
     return {
       sync_status: "not_available",
       sync_message: "Ctxpack is missing or has no files on server.",
       local_path: cacheDir,
+      workspace_path: resolvedWorkspaceDir,
       local_file_count: 0,
     };
   }
@@ -1854,12 +1876,28 @@ function syncCtxpackToLocalCache({ siteBaseURL, projectID, ctxpack }) {
   const previousSig = previousMeta
     ? `${String(previousMeta.ctxpack_id || "").trim()}|${String(previousMeta.version || "").trim()}|${String(previousMeta.status || "").trim()}|${Number.parseInt(String(previousMeta.files_count || 0), 10) || 0}`
     : "";
+  const payload = {
+    project_id: projectID,
+    ctxpack_id: ctxpackID,
+    version,
+    status,
+    files_count: files.length,
+    files: files.map((f) => ({ path: f.path, doc_type: f.docType || "" })),
+    source: `${String(siteBaseURL || "").replace(/\/+$/, "")}/api/v1/projects/${encodeURIComponent(projectID)}/ctxpack`,
+    synced_at: new Date().toISOString(),
+  };
 
   if (previousSig === remoteSig && hasAllCtxpackFiles(cacheDir, files)) {
+    try {
+      fs.writeFileSync(workspaceMetaPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    } catch {
+      // Best-effort metadata refresh for workspace-root auto-detection.
+    }
     return {
       sync_status: "current",
       sync_message: "Local ctxpack cache is up to date.",
       local_path: cacheDir,
+      workspace_path: resolvedWorkspaceDir,
       local_file_count: files.length,
     };
   }
@@ -1874,17 +1912,8 @@ function syncCtxpackToLocalCache({ siteBaseURL, projectID, ctxpack }) {
       fs.writeFileSync(target, file.content, "utf8");
     }
 
-    const payload = {
-      project_id: projectID,
-      ctxpack_id: ctxpackID,
-      version,
-      status,
-      files_count: files.length,
-      files: files.map((f) => ({ path: f.path, doc_type: f.docType || "" })),
-      source: `${String(siteBaseURL || "").replace(/\/+$/, "")}/api/v1/projects/${encodeURIComponent(projectID)}/ctxpack`,
-      synced_at: new Date().toISOString(),
-    };
     fs.writeFileSync(metaPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    fs.writeFileSync(workspaceMetaPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
 
     return {
       sync_status: previousMeta ? "updated" : "downloaded",
@@ -1892,6 +1921,7 @@ function syncCtxpackToLocalCache({ siteBaseURL, projectID, ctxpack }) {
         ? "Ctxpack updated to latest server version."
         : "Ctxpack downloaded to local cache.",
       local_path: cacheDir,
+      workspace_path: resolvedWorkspaceDir,
       local_file_count: files.length,
     };
   } catch (err) {
@@ -1899,6 +1929,7 @@ function syncCtxpackToLocalCache({ siteBaseURL, projectID, ctxpack }) {
       sync_status: "error",
       sync_message: String(err?.message || err),
       local_path: cacheDir,
+      workspace_path: resolvedWorkspaceDir,
       local_file_count: 0,
     };
   }
@@ -1911,6 +1942,7 @@ async function loadProjectSummaryForTool({
   timeoutSeconds,
   includeCtxpack,
   syncCtxpackLocal,
+  workspaceDir,
 }) {
   const encodedProjectID = encodeURIComponent(projectID);
   let projectRaw = null;
@@ -1968,6 +2000,7 @@ async function loadProjectSummaryForTool({
           siteBaseURL,
           projectID,
           ctxpack,
+          workspaceDir,
         });
         ctxpackSyncStatus = syncResult.sync_status || "error";
         ctxpackSyncMessage = String(syncResult.sync_message || "").trim();
@@ -2008,6 +2041,7 @@ async function loadProjectSummaryForTool({
     ctxpack_sync_message: ctxpackSyncMessage,
     ctxpack_local_path: ctxpackLocalPath,
     ctxpack_local_file_count: ctxpackLocalFileCount,
+    ctxpack_workspace_path: String(workspaceDir || "").trim(),
     agenda,
     agenda_source: agendaSource,
   };
@@ -2149,6 +2183,7 @@ async function appendWorkitemListHints(responseObj, args, toolArgs, token) {
         timeoutSeconds: args.timeoutSeconds,
         includeCtxpack: isEmptyBody,
         syncCtxpackLocal: isEmptyBody,
+        workspaceDir: args.workspaceDir,
       });
       if (String(summary.access || "") === "granted") {
         nextLines.push("Project context:");
@@ -2186,12 +2221,66 @@ async function appendWorkitemListHints(responseObj, args, toolArgs, token) {
   return responseObj;
 }
 
+function appendCtxpackEnsureSyncHints(responseObj, args, toolArgs) {
+  const result = safeObject(responseObj.result);
+  const content = ensureArray(result.content);
+  if (!content.length) return responseObj;
+
+  const first = safeObject(content[0]);
+  if (String(first.type || "") !== "text") return responseObj;
+  const text = String(first.text || "").trim();
+  if (!text) return responseObj;
+
+  const envelope = parseToolEnvelopeFromRPCResult(result);
+  if (!envelope) return responseObj;
+  if (String(envelope.tool || "").trim() !== "ctxpack.ensure") return responseObj;
+  if (!Boolean(envelope.ok) || Number(envelope.status || 0) !== 200) return responseObj;
+
+  const body = safeObject(envelope.body);
+  if (!Object.keys(body).length) return responseObj;
+
+  const projectID = String(
+    toolArgs?.project_id || toolArgs?.projectID || envelope.project_id || args.projectID || "",
+  ).trim();
+  if (!projectID || !isUUID(projectID)) return responseObj;
+
+  const syncResult = syncCtxpackToLocalCache({
+    siteBaseURL: normalizeSiteBaseURL(args.baseURL),
+    projectID,
+    ctxpack: body,
+    workspaceDir: args.workspaceDir,
+  });
+
+  const lines = [
+    "",
+    `ctxpack_local_sync_status: ${String(syncResult.sync_status || "error")}`,
+  ];
+  if (syncResult.sync_message) {
+    lines.push(`ctxpack_local_sync_message: ${String(syncResult.sync_message)}`);
+  }
+  if (syncResult.local_path) {
+    lines.push(`ctxpack_local_path: ${String(syncResult.local_path)}`);
+  }
+  if (syncResult.workspace_path) {
+    lines.push(`ctxpack_workspace_path: ${String(syncResult.workspace_path)}`);
+  }
+
+  content[0] = {
+    ...first,
+    text: `${text}\n${lines.join("\n")}`,
+  };
+  result.content = content;
+  responseObj.result = result;
+  return responseObj;
+}
+
 async function runProxy(flags) {
   const workspaceMeta = loadWorkspaceMeta(process.cwd());
   const args = {
     baseURL: flags["base-url"] || DEFAULT_BASE_URL,
     projectID: String(flags["project-id"] || workspaceMeta.project_id || "").trim(),
     ctxpackKey: String(flags["ctxpack-key"] || buildCtxpackKeyFromMeta(workspaceMeta) || "").trim(),
+    workspaceDir: resolveWorkspaceDir(flags["workspace-dir"] || process.cwd()),
     includeDrafts: boolFromRaw(flags["include-drafts"], true),
     timeoutSeconds: intFromRaw(flags["timeout-seconds"], 30),
   };
@@ -2289,6 +2378,7 @@ async function runProxy(flags) {
           timeoutSeconds: args.timeoutSeconds,
           includeCtxpack,
           syncCtxpackLocal,
+          workspaceDir: args.workspaceDir,
         });
         const text = buildProjectSummaryText(summary);
         process.stdout.write(
@@ -2324,6 +2414,8 @@ async function runProxy(flags) {
             patched = appendProjectHintToInitialize(patched, args);
           } else if (isJsonRpcMethod(requestObj, "tools/call") && toolName === "workitem.list") {
             patched = await appendWorkitemListHints(patched, args, toolArgs, token);
+          } else if (isJsonRpcMethod(requestObj, "tools/call") && toolName === "ctxpack.ensure") {
+            patched = appendCtxpackEnsureSyncHints(patched, args, toolArgs);
           }
           process.stdout.write(`${JSON.stringify(patched)}\n`);
           return;
@@ -2408,11 +2500,27 @@ function resolveSetupContext(flags) {
   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 workspaceDirRaw = String(flags["workspace-dir"] || "").trim();
+  const hasExplicitWorkspaceDir = workspaceDirRaw.length > 0;
+  const workspaceDir = resolveWorkspaceDir(hasExplicitWorkspaceDir ? workspaceDirRaw : process.cwd());
   const serverName = String(flags.name || DEFAULT_SERVER_NAME).trim() || DEFAULT_SERVER_NAME;
   const proxyArgs = ["--base-url", `${baseURL}/governance/mcp`];
+  // Default mode: do not pin workspace path in MCP registration.
+  // Let client runtime cwd resolve per open folder/workspace.
+  if (hasExplicitWorkspaceDir) {
+    proxyArgs.push("--workspace-dir", workspaceDir);
+  }
   if (projectID) proxyArgs.push("--project-id", projectID);
   if (ctxpackKey) proxyArgs.push("--ctxpack-key", ctxpackKey);
-  return { projectID, ctxpackKey, baseURL, serverName, proxyArgs };
+  return {
+    projectID,
+    ctxpackKey,
+    baseURL,
+    workspaceDir,
+    hasExplicitWorkspaceDir,
+    serverName,
+    proxyArgs,
+  };
 }
 
 function runSetupInternal(flags, options = {}) {
@@ -2424,20 +2532,26 @@ function runSetupInternal(flags, options = {}) {
   for (const cliBin of clients) {
     if (!commandExists(cliBin)) continue;
     const alreadyRegistered = isRegistered(cliBin, context.serverName);
-    if (ensureOnly && alreadyRegistered) {
-      results.push({ cliBin, ok: true, action: "already-registered" });
-      continue;
-    }
-    if (!ensureOnly) {
+    if (!ensureOnly || alreadyRegistered) {
       runRemove(cliBin, context.serverName);
     }
     const ok = tryRegister(cliBin, context.serverName, context.proxyArgs);
-    results.push({ cliBin, ok, action: alreadyRegistered ? "re-registered" : "registered" });
+    const action = ensureOnly
+      ? alreadyRegistered
+        ? "updated"
+        : "registered"
+      : alreadyRegistered
+        ? "re-registered"
+        : "registered";
+    results.push({ cliBin, ok, action });
   }
 
   process.stdout.write(ensureOnly ? "\nEnsure complete.\n" : "\nInstall complete.\n");
   process.stdout.write(`Server:    ${context.serverName}\n`);
   process.stdout.write(`Gateway:   ${context.baseURL}/governance/mcp\n`);
+  process.stdout.write(
+    `Workspace: ${context.hasExplicitWorkspaceDir ? context.workspaceDir : "auto (client current folder)"}\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.4",
+  "version": "0.2.6",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [