metheus-governance-mcp-cli 0.2.47 → 0.2.49

package/README.md

@@ -20,6 +20,27 @@ Compatibility note: legacy command alias `metheus-governance-mcp` is still suppo
 npm install -g metheus-governance-mcp-cli@latest
 ```
 
+Install creates a local Telegram settings template here:
+
+- `~/.metheus/telegram.env`
+
+This file is for local bot secrets only.
+
+- Store locally:
+  - `TELEGRAM_BOT_TOKEN`
+- Server-side Metheus stores project Telegram destination metadata separately:
+  - `chat_id`
+  - label / active state
+
+Example template:
+
+```env
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_DEFAULT_CHAT_ID=
+TELEGRAM_ALLOWED_CHAT_IDS=
+TELEGRAM_DEFAULT_PARSE_MODE=
+```
+
 ## One command bootstrap (recommended)
 
 Run in your project folder:
@@ -36,31 +57,34 @@ If auth is not ready, login starts automatically, then MCP registration is compl
 metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctxpack_key>" --base-url https://metheus.gesiaplatform.com
 ```
 
-`project-id` can be omitted if your current folder (or parent) has `.metheus_ctxpack_sync.json`.
+Technical fallback: `project-id` can be auto-detected 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.
 
+Ops policy (recommended):
+- Always pass explicit `--project-id <project_uuid>` during setup.
+- Omit `--project-id` only in advanced cases where `.metheus_ctxpack_sync.json` is already present and verified.
+
 Recommended for Codex/Claude/Gemini/Antigravity/Cursor 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
 ```
 
+`setup` also ensures the local Telegram template exists:
+
+- `~/.metheus/telegram.env`
+
+Fill only the bot token locally. Project Telegram `chat_id` destinations should be managed on the Metheus server.
+
 Gemini CLI note:
 - `gemini mcp` commands require Gemini auth to be configured first (`GEMINI_API_KEY` or `~/.gemini/settings.json` auth).
 - `setup` registers Gemini in both `user` and `project` scopes to improve auto-discovery across folders.
 
-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 sets fallback workspace context for clients that do not pass workspace metadata:
-- Codex/Antigravity/Cursor: `METHEUS_WORKSPACE_DIR` env
-- Gemini: pinned `--workspace-dir <fallback>` and `METHEUS_WORKSPACE_DIR` in MCP registration
-- fallback env is used only when workspace cannot be resolved (or resolves to home); when current `cwd` is a real project folder, sync uses that folder.
+Workspace signal guardrail:
+- default recommendation is `--workspace-dir auto` with no fixed fallback path.
+- if a client session does not provide trusted workspace signals (`workspaceFolders` / `rootUri` / `cwd`), ctxpack local write is blocked (`sync_status=guarded`, `local_file_count=0`).
+- use `--workspace-fallback-dir` only when you intentionally want a shared fallback root.
 
 Guardrail note:
 - By default, CLI blocks reading/writing ctxpack sync metadata when workspace root resolves to the home directory.
@@ -83,6 +107,7 @@ metheus-governance-mcp-cli doctor --project-id <project_uuid> --base-url https:/
 
 Checks:
 - auth token status (+ auto refresh attempt)
+- local Telegram env template presence
 - codex/claude/gemini/antigravity/cursor registration state
 - gateway `tools/list` reachability
 - `project.summary` access
@@ -105,8 +130,8 @@ Cursor note:
 
 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.
+- Cursor/Antigravity sessions use safe aliases only (`project_summary`, `ctxpack_merge_brief`, ...).
+- Proxy maps safe alias calls back to canonical names automatically.
 
 Local bootstrap tools exposed by proxy:
 
@@ -127,7 +152,13 @@ These tools accept `project_id` and return:
 - same version -> keep current
 - newer server version -> update local cache
 - workspace path -> auto-detected from client metadata/env by default
-- use `--workspace-fallback-dir <path>` when client metadata is unavailable
+- if workspace signal is missing in auto mode, sync is guarded (no local write)
+- use `--workspace-fallback-dir <path>` only when you intentionally want fallback writes
+
+Project-ID first-call rule:
+- when user gives only `Project ID`, call `project.summary` first.
+- call `ctxpack.ensure` after `project.summary` only when extra ctxpack refresh/export context is needed.
+- for support/ops workflows, do not run ctxpack sync/download before a successful `project.summary`.
 
 Ctxpack merge safety flow:
 - call `ctxpack.merge.brief` first

package/cli.mjs

@@ -15,6 +15,7 @@ const DEFAULT_SITE_URL = "https://metheus.gesiaplatform.com";
 const DEFAULT_BASE_URL = `${DEFAULT_SITE_URL}/governance/mcp`;
 const DEFAULT_SERVER_NAME = "metheus-governance-mcp";
 const AUTH_STORE_RELATIVE_PATH = path.join(".metheus", "governance-mcp-auth.json");
+const TELEGRAM_ENV_RELATIVE_PATH = path.join(".metheus", "telegram.env");
 const SELF_UPDATE_STATE_RELATIVE_PATH = path.join(".metheus", "governance-mcp-cli-update.json");
 const CTXPACK_CACHE_RELATIVE_DIR = path.join(".metheus", "ctxpack-cache");
 const CTXPACK_META_FILENAME = ".metheus_ctxpack_sync.json";
@@ -57,6 +58,8 @@ function printUsage() {
       `  ${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}`,
+      "  Local Telegram bot token template is stored at:",
+      `    ${TELEGRAM_ENV_RELATIVE_PATH}`,
       "",
     ].join("\n"),
   );
@@ -66,7 +69,7 @@ function loadCLIMeta() {
   try {
     const dir = path.dirname(fileURLToPath(import.meta.url));
     const raw = fs.readFileSync(path.join(dir, "package.json"), "utf8");
-    const parsed = JSON.parse(raw);
+    const parsed = JSON.parse(stripUTF8BOM(raw));
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return {};
     }
@@ -80,6 +83,12 @@ function printVersion() {
   process.stdout.write(`${CLI_NAME} ${CLI_VERSION}\n`);
 }
 
+function stripUTF8BOM(rawText) {
+  const text = String(rawText || "");
+  if (!text) return "";
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
 function resolveHomeFilePath(relativePath) {
   const home = String(process.env.USERPROFILE || process.env.HOME || "").trim();
   if (!home) {
@@ -284,7 +293,7 @@ function loadSelfUpdateState() {
   const filePath = updateStateFilePath();
   try {
     const raw = fs.readFileSync(filePath, "utf8");
-    const parsed = JSON.parse(raw);
+    const parsed = JSON.parse(stripUTF8BOM(raw));
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return { filePath, checkedAt: "", latestVersion: "", installedVersion: "", updatedAt: "" };
     }
@@ -470,6 +479,41 @@ function authStoreFilePath() {
   return resolveHomeFilePath(AUTH_STORE_RELATIVE_PATH);
 }
 
+function telegramEnvFilePath() {
+  return resolveHomeFilePath(TELEGRAM_ENV_RELATIVE_PATH);
+}
+
+function telegramEnvTemplate() {
+  return [
+    "# Metheus local Telegram bot settings",
+    "# Keep this file on your machine only. Do not commit it.",
+    "# Server-side project Telegram destinations store chat_id metadata separately.",
+    "",
+    "TELEGRAM_BOT_TOKEN=",
+    "# Optional local default for quick tests. Project chat_id is normally resolved from Metheus server.",
+    "TELEGRAM_DEFAULT_CHAT_ID=",
+    "# Optional CSV allowlist to avoid accidental sends to the wrong chats.",
+    "TELEGRAM_ALLOWED_CHAT_IDS=",
+    "# Optional parse mode: Markdown, MarkdownV2, HTML",
+    "TELEGRAM_DEFAULT_PARSE_MODE=",
+    "",
+  ].join("\n");
+}
+
+function ensureTelegramEnvTemplate() {
+  const filePath = telegramEnvFilePath();
+  try {
+    if (fs.existsSync(filePath)) {
+      return { filePath, created: false, existed: true };
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, telegramEnvTemplate(), "utf8");
+    return { filePath, created: true, existed: false };
+  } catch (err) {
+    return { filePath, created: false, existed: false, error: String(err?.message || err) };
+  }
+}
+
 function resolveWorkspaceDir(rawPath) {
   const input = String(rawPath || "").trim();
   if (input) {
@@ -757,9 +801,9 @@ function resolveProjectIDForRequest({
 }) {
   const resolvedWorkspaceDir = resolveWorkspaceDir(workspaceDir || process.cwd());
   const workspaceMeta = loadWorkspaceMeta(resolvedWorkspaceDir);
+  const toolProjectID = resolveProjectIDFromToolArgs(toolArgs);
   return firstNonEmptyString([
-    toolArgs?.project_id,
-    toolArgs?.projectID,
+    toolProjectID,
     responseProjectID,
     envelopeProjectID,
     args?.projectID,
@@ -795,7 +839,7 @@ function loadStoredAuth() {
       return { filePath, token: "", refreshToken: "", baseURL: "", updatedAt: "" };
     }
     const raw = fs.readFileSync(filePath, "utf8");
-    const parsed = JSON.parse(raw);
+    const parsed = JSON.parse(stripUTF8BOM(raw));
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return { filePath, token: "", refreshToken: "", baseURL: "", updatedAt: "" };
     }
@@ -1461,7 +1505,7 @@ function currentAccessTokenSource() {
 
 function tryJsonParse(raw) {
   try {
-    return JSON.parse(raw);
+    return JSON.parse(stripUTF8BOM(raw));
   } catch {
     return null;
   }
@@ -1505,7 +1549,7 @@ function loadWorkspaceMeta(startDir) {
   if (!metaFile) return {};
   try {
     const raw = fs.readFileSync(metaFile, "utf8");
-    const parsed = JSON.parse(raw);
+    const parsed = JSON.parse(stripUTF8BOM(raw));
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       return parsed;
     }
@@ -1552,6 +1596,40 @@ function isUUID(raw) {
   return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
 }
 
+function extractUUIDFromText(raw) {
+  const text = String(raw || "").trim();
+  if (!text) return "";
+  const match = text.match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i);
+  return String(match?.[0] || "").trim();
+}
+
+function resolveProjectIDFromToolArgs(rawToolArgs) {
+  const toolArgs = safeObject(rawToolArgs);
+  const direct = firstNonEmptyString([
+    toolArgs.project_id,
+    toolArgs.projectID,
+    toolArgs.projectId,
+    toolArgs["project-id"],
+    toolArgs.project_uuid,
+    toolArgs.projectUUID,
+    toolArgs.projectUuid,
+  ]);
+  if (isUUID(direct)) return direct;
+
+  const hinted = firstNonEmptyString([
+    extractUUIDFromText(toolArgs.project),
+    extractUUIDFromText(toolArgs.project_id_text),
+    extractUUIDFromText(toolArgs.projectIdText),
+    extractUUIDFromText(toolArgs.input),
+    extractUUIDFromText(toolArgs.text),
+    extractUUIDFromText(toolArgs.query),
+    extractUUIDFromText(toolArgs.prompt),
+  ]);
+  if (isUUID(hinted)) return hinted;
+
+  return "";
+}
+
 async function runAuthStatus() {
   const resolved = resolveCurrentAccessToken();
   const token = resolved.token;
@@ -2067,6 +2145,18 @@ async function runDoctor(flags) {
   });
   const rows = [];
 
+  const telegramEnv = ensureTelegramEnvTemplate();
+  if (telegramEnv.error) {
+    addDoctorCheck(rows, "warn", "local telegram env", `unavailable (${telegramEnv.error})`);
+  } else {
+    addDoctorCheck(
+      rows,
+      telegramEnv.created ? "warn" : "ok",
+      "local telegram env",
+      `${telegramEnv.created ? "created template" : "ready"} (${telegramEnv.filePath})`,
+    );
+  }
+
   const resolved = await resolveAccessTokenForCommand(context.baseURL, timeoutSeconds);
   const token = resolved.token;
   if (!token) {
@@ -2720,7 +2810,7 @@ function loadCtxpackMeta(metaPath) {
   try {
     if (!fs.existsSync(metaPath)) return null;
     const raw = fs.readFileSync(metaPath, "utf8");
-    const parsed = JSON.parse(raw);
+    const parsed = JSON.parse(stripUTF8BOM(raw));
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
     return parsed;
   } catch {
@@ -3730,6 +3820,7 @@ function appendProjectHintToInitialize(responseObj, args, options = {}) {
         ]
       : []),
     `- MUST call \`${projectSummaryTool}\` first when the user provides only a Project ID or asks project overview/agenda.`,
+    `- If user enters a Project ID in text (e.g., "Project ID <uuid>"), pass that exact UUID as \`project_id\` argument when calling \`${projectSummaryTool}\`.`,
     `- \`${projectDescribeTool}\` and \`${projectGetTool}\` are aliases of \`${projectSummaryTool}\`.`,
     `- Never handle a bare Project ID by local file/transcript search before \`${projectSummaryTool}\` succeeds.`,
     `- Run \`${ctxpackEnsureTool}\` only after \`${projectSummaryTool}\`, and only when additional ctxpack refresh/export context is needed.`,
@@ -4505,7 +4596,13 @@ async function runProxy(flags) {
         }),
       ).trim();
       if (!projectID) {
-        writeProxyJson(jsonRpcError(requestObj, -32001, "project_id is required (or set --project-id during setup)"));
+        writeProxyJson(
+          jsonRpcError(
+            requestObj,
+            -32001,
+            'project_id is required. Enter a valid UUID (e.g., {"project_id":"00000000-0000-0000-0000-000000000000"}) or set --project-id during setup.',
+          ),
+        );
         return;
       }
       if (!isUUID(projectID)) {
@@ -4561,7 +4658,13 @@ async function runProxy(flags) {
         }),
       ).trim();
       if (!projectID) {
-        writeProxyJson(jsonRpcError(requestObj, -32001, "project_id is required (or set --project-id during setup)"));
+        writeProxyJson(
+          jsonRpcError(
+            requestObj,
+            -32001,
+            'project_id is required. Enter a valid UUID (e.g., {"project_id":"00000000-0000-0000-0000-000000000000"}) or set --project-id during setup.',
+          ),
+        );
         return;
       }
       if (!isUUID(projectID)) {
@@ -5198,6 +5301,7 @@ function runSetupInternal(flags, options = {}) {
   const context = resolveSetupContext(flags);
   const clients = [...MCP_CLIENTS];
   const results = [];
+  const telegramEnv = ensureTelegramEnvTemplate();
 
   for (const cliBin of clients) {
     if (!commandExists(cliBin)) continue;
@@ -5247,6 +5351,13 @@ function runSetupInternal(flags, options = {}) {
     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 (telegramEnv.error) {
+    process.stdout.write(`Telegram:  template unavailable (${telegramEnv.error})\n`);
+  } else {
+    process.stdout.write(
+      `Telegram:  ${telegramEnv.created ? "template created" : "template ready"} (${telegramEnv.filePath})\n`,
+    );
+  }
   if (context.ctxpackKey) {
     process.stdout.write(`Ctxpack:   ${context.ctxpackKey}\n`);
   }

package/package.json

@@ -1,21 +1,23 @@
 {
   "name": "metheus-governance-mcp-cli",
-  "version": "0.2.47",
+  "version": "0.2.49",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [
     "bin/metheus-governance-mcp.js",
     "cli.mjs",
+    "postinstall.mjs",
     "README.md",
     ".env.npm.local.example"
   ],
   "scripts": {
-    "check": "node --check cli.mjs && node --check release.mjs",
+    "check": "node --check cli.mjs && node --check postinstall.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"
+    "publish:public": "node release.mjs",
+    "postinstall": "node postinstall.mjs"
   },
   "bin": {
     "metheus-governance-mcp": "bin/metheus-governance-mcp.js",

package/postinstall.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const RELATIVE_PATH = path.join(".metheus", "telegram.env");
+
+function resolveTargetPath() {
+  const home = String(process.env.USERPROFILE || process.env.HOME || os.homedir() || "").trim();
+  if (!home) return "";
+  return path.join(home, RELATIVE_PATH);
+}
+
+function template() {
+  return [
+    "# Metheus local Telegram bot settings",
+    "# Keep this file on your machine only. Do not commit it.",
+    "# Server-side project Telegram destinations store chat_id metadata separately.",
+    "",
+    "TELEGRAM_BOT_TOKEN=",
+    "# Optional local default for quick tests. Project chat_id is normally resolved from Metheus server.",
+    "TELEGRAM_DEFAULT_CHAT_ID=",
+    "# Optional CSV allowlist to avoid accidental sends to the wrong chats.",
+    "TELEGRAM_ALLOWED_CHAT_IDS=",
+    "# Optional parse mode: Markdown, MarkdownV2, HTML",
+    "TELEGRAM_DEFAULT_PARSE_MODE=",
+    "",
+  ].join("\n");
+}
+
+function main() {
+  const filePath = resolveTargetPath();
+  if (!filePath) return;
+  try {
+    if (fs.existsSync(filePath)) return;
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, template(), "utf8");
+    process.stdout.write(`[metheus-governance-mcp-cli] created ${filePath}\n`);
+  } catch (err) {
+    process.stderr.write(
+      `[metheus-governance-mcp-cli] could not create ${filePath}: ${String(err?.message || err)}\n`,
+    );
+  }
+}
+
+main();