metheus-governance-mcp-cli 0.2.106 → 0.2.108

package/README.md

@@ -248,7 +248,7 @@ Behavior:
 
 - `bot setup` asks for `Telegram / Slack / KakaoTalk` first, then prompts with numbered actions.
 - `bot add` without flags now uses the shortest practical guided flow: provider -> token -> verify -> optional save-anyway only when verify fails -> optional username fallback only when verify cannot discover it -> optional AI model selection when the resolved defaults leave it blank -> optional default bot.
-- In the normal Telegram path, `bot add` does not ask for an advanced local selector, a server bot UUID, or an approval / worker / review / monitor choice.
+- In the normal Telegram path, `bot add` does not ask for a local selector, a server bot UUID, or an approval / worker / review / monitor choice.
 - For Telegram, the local bot file stem is auto-generated from the matched server bot name or verified username, so you do not have to invent a separate local nickname first.
 - For Telegram, the CLI tries to match the verified bot identity against the server `me/bots` list first. If the server exposes one logical bot name with multiple roles such as `approval`, `worker`, `review`, and `monitor`, the CLI does not ask you to choose one UUID. It binds by server bot name and keeps the local role/AI fields empty so runtime can use the server bot role for each route.
 - When the Telegram username matches exactly one server bot role, the CLI still auto-fills the local `role_profile` and blank AI defaults from your local `bot-runner.json` `role_profiles` mapping.
@@ -285,7 +285,7 @@ Behavior:
 - `bot show` prints one local bot entry in detail, including grouped role summaries when one server bot name expands to multiple roles and any linked local runner routes.
 - In `bot show` and `bot verify`, `saved_local_file` means the values already stored on disk under `~/.metheus/telegram-bots/*.env`, while `current_server_protocol` means the fresh `/api/v1/me/bots` response from the server right now.
 - `bot global` edits Telegram-wide local settings such as API base URL, allowed updates, and the default Telegram bot selector.
-- `bot set-default` updates `TELEGRAM_DEFAULT_BOT_KEY`.
+- `bot set-default` changes the default Telegram bot selection.
 - `bot migrate` moves legacy `TELEGRAM_BOT_TOKEN` into a named Telegram bot entry.
 
 Non-interactive examples:
@@ -301,9 +301,9 @@ metheus-governance-mcp-cli bot remove --provider telegram --bot-name <server_bot
 metheus-governance-mcp-cli bot verify --provider telegram --bot-name <server_bot_name> --json true
 ```
 
-For direct Telegram adds, the CLI derives the local file name from the matched server bot name. You normally do not need `--bot-key` or `--username`. Treat `--bot-key` as an advanced compatibility selector only when you intentionally need to target an older local selector directly.
+For direct Telegram adds, the CLI derives the local file name from the matched server bot name. You normally do not need `--bot-key` or `--username`. Treat `--bot-key` as a legacy compatibility selector only when you intentionally need to target an older local selector directly.
 
-For direct Telegram edits, prefer `--bot-name` or `--bot-id` because server bot identity is the source of truth. Use `--bot-key` only when you intentionally need the advanced local selector. If one server bot name expands to multiple roles such as `approval / worker / review / monitor`, prefer the guided `bot edit` flow so you can keep the current grouped settings, edit one role only, or walk every role in sequence instead of forcing one entry-level AI override.
+For direct Telegram edits, prefer `--bot-name` or `--bot-id` because server bot identity is the source of truth. Use `--bot-key` only when you intentionally need the legacy local selector. If one server bot name expands to multiple roles such as `approval / worker / review / monitor`, prefer the guided `bot edit` flow so you can keep the current grouped settings, edit one role only, or walk every role in sequence instead of forcing one entry-level AI override.
 
 For runner commands, you can still use `--route-name` directly, but normal operator workflows can also use `--bot-name` or `--bot-id` when those identify one enabled route uniquely. Use `runner list` first if you are not sure which route belongs to which server bot.
 

package/cli.mjs

@@ -249,7 +249,7 @@ function printUsage() {
       `  ${cmd} bot set-default --provider telegram [--bot-name <server_name>] [--bot-id <uuid>]`,
       `  ${cmd} bot migrate --provider telegram [--bot-name <server_name>] [--bot-id <uuid>]`,
       `  ${cmd} bot verify [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--timeout-seconds <n>] [--json <true|false>]`,
-      `  ${cmd} bot global --provider telegram [--api-base-url <url>] [--auto-clear-webhook <true|false>] [--allowed-updates <csv>] [--default-bot-key <key>]`,
+      `  ${cmd} bot global --provider telegram [--api-base-url <url>] [--auto-clear-webhook <true|false>] [--allowed-updates <csv>] [--default-bot-name <server_name>] [--default-bot-id <uuid>]`,
       `  ${cmd} doctor [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--timeout-seconds <n>] [--strict <true|false>]`,
       `  ${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} selftest [--json <true|false>]`,
@@ -4285,10 +4285,9 @@ async function runDoctor(flags) {
           continue;
         }
         const detailParts = [];
-        if (envConfig.botKey) detailParts.push(`bot=${envConfig.botKey}`);
-      if (envConfig.botUsername) detailParts.push(`@${envConfig.botUsername}`);
-      if (envConfig.serverBotID) detailParts.push(`server_bot_id=${envConfig.serverBotID}`);
-        else if (envConfig.botKey) detailParts.push(`server_name=${envConfig.botKey}`);
+        if (envConfig.serverBotName) detailParts.push(`server_bot_name=${envConfig.serverBotName}`);
+        if (envConfig.serverBotID) detailParts.push(`server_bot_id=${envConfig.serverBotID}`);
+        if (envConfig.botUsername) detailParts.push(`fallback_username=@${envConfig.botUsername}`);
         if (envConfig.client) detailParts.push(`ai=${envConfig.client}`);
         addDoctorCheck(
           rows,
@@ -4316,8 +4315,8 @@ async function runDoctor(flags) {
               "ok",
               `runner route ${routeLabel} server bot`,
               envConfig.botUsername
-                ? `resolved by bot username @${envConfig.botUsername}`
-                : `resolved by server bot name ${envConfig.botKey}`,
+                ? `resolved by fallback username @${envConfig.botUsername}`
+                : `resolved by server bot name ${envConfig.serverBotName || envConfig.botKey}`,
             );
           } else {
             addDoctorCheck(

package/lib/bot-commands.mjs

@@ -223,18 +223,18 @@ function printBotUsage(deps) {
       `  ${cliName} bot set-default --provider telegram [--bot-name <server_name>] [--bot-id <uuid>] [--non-interactive <true|false>]`,
       `  ${cliName} bot migrate --provider telegram [--bot-name <server_name>] [--bot-id <uuid>] [--keep-legacy-token <true|false>] [--non-interactive <true|false>]`,
       `  ${cliName} bot verify [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--timeout-seconds <n>] [--json <true|false>]`,
-      `  ${cliName} bot global --provider telegram [--non-interactive <true|false>] [--api-base-url <url>] [--auto-clear-webhook <true|false>] [--allowed-updates <csv>] [--default-bot-key <advanced_key>]`,
+      `  ${cliName} bot global --provider telegram [--non-interactive <true|false>] [--api-base-url <url>] [--auto-clear-webhook <true|false>] [--allowed-updates <csv>] [--default-bot-name <server_name>] [--default-bot-id <uuid>]`,
       "",
       `Behavior:`,
       `  - bot setup asks for provider first, then shows a numbered action menu.`,
       `  - bot add without flags uses the shortest practical guided flow: provider -> token -> verify -> optional username fallback -> optional default bot.`,
-      `  - in the normal Telegram path, bot add does not ask for an advanced local selector or a server role/profile choice.`,
-      `  - server bot name/UUID is the source of truth; --bot-key is an advanced compatibility selector only.`,
+      `  - in the normal Telegram path, bot add does not ask for a local selector or a server role/profile choice.`,
+      `  - server bot name/UUID is the source of truth; --bot-key remains only as a legacy compatibility selector.`,
       `  - runner commands can auto-select by --bot-name or --bot-id when one enabled route matches. Use runner list first if you are unsure.`,
       `  - bot edit without flags asks for provider, existing entry, then walks field-by-field in a numbered flow.`,
       `  - in the normal Telegram edit path, the CLI keeps or re-resolves the server bot binding automatically instead of asking you to pick a server role/profile UUID first.`,
       `  - bot set-default / bot verify / bot remove also support guided numbered selection when run without flags.`,
-      `  - advanced selectors: --bot-key is still supported for compatibility, but prefer --bot-name or --bot-id in normal operator workflows.`,
+      `  - legacy compatibility: prefer --bot-name or --bot-id in normal operator workflows; use --bot-key only when you must target an older local selector directly.`,
       "",
     ].join("\n"),
   );
@@ -858,7 +858,7 @@ function findTelegramEntryByFlags(parsedEnv, flags, deps) {
   if (requestedKey) {
     const match = entries.find((entry) => entry.key === requestedKey);
     if (!match) {
-      throw new Error(`Telegram bot entry "${requestedKey}" was not found`);
+      throw new Error(`Telegram bot entry with legacy local selector "${requestedKey}" was not found`);
     }
     return match;
   }
@@ -895,7 +895,7 @@ function saveTelegramBotEdit(parsed, selected, current, deps) {
     nextParsed.TELEGRAM_DEFAULT_BOT_KEY = current.key;
   }
   const filePath = writeProviderEnvState("telegram", nextParsed, deps);
-  process.stdout.write(`Saved Telegram bot entry "${current.key}" to ${filePath}\n`);
+  process.stdout.write(`Saved Telegram bot file for "${telegramEntryDisplayName(current)}" to ${filePath}\n`);
   return filePath;
 }
 
@@ -1129,7 +1129,7 @@ async function editTelegramBotGuided(ui, parsed, selected, current, flags, deps)
     parsed.TELEGRAM_DEFAULT_BOT_KEY = "";
   }
 
-  if (!await promptYesNo(ui, `Save changes for "${current.key}" now?`, true)) {
+  if (!await promptYesNo(ui, `Save changes for "${telegramEntryDisplayName(current)}" now?`, true)) {
     process.stdout.write("Cancelled.\n");
     return;
   }
@@ -1306,11 +1306,9 @@ function printBotList(provider, state, deps) {
       process.stdout.write("  entries: none\n");
       return;
     }
-    process.stdout.write(`  default: ${String(state.parsed.TELEGRAM_DEFAULT_BOT_KEY || "").trim() || "-"}\n`);
+    const defaultEntry = entries.find((entry) => entry.isDefault) || null;
+    process.stdout.write(`  default: ${defaultEntry ? telegramEntryDisplayName(defaultEntry) : "-"}\n`);
     entries.forEach((entry) => {
-      const advancedSelectorLine = entry.key
-        ? `    advanced_local_selector: ${entry.key} (compatibility only)`
-        : "";
       process.stdout.write(
         [
           `  - ${telegramEntryDisplayName(entry)}${entry.isDefault ? " [default]" : ""}`,
@@ -1325,7 +1323,6 @@ function printBotList(provider, state, deps) {
           `    model: ${entry.model || "-"}`,
           `    permission_mode: ${entry.permissionMode || "-"}`,
           `    reasoning_effort: ${entry.reasoningEffort || "-"}`,
-          advancedSelectorLine,
         ].join("\n") + "\n",
       );
     });
@@ -1361,7 +1358,6 @@ function printBotShow(provider, state, entry, deps, extras = {}) {
       `ai_model: ${selectedEntry.model || "-"}`,
       `permission_mode: ${selectedEntry.permissionMode || "-"}`,
       `reasoning_effort: ${selectedEntry.reasoningEffort || "-"}`,
-      selectedEntry.key ? `advanced_local_selector: ${selectedEntry.key} (compatibility only)` : "",
     ]);
     if (Object.keys(serverBinding).length) {
       const liveLines = [
@@ -1441,7 +1437,7 @@ async function resolveTelegramEntryForShow(ui, parsedEnv, flags, deps) {
   }
   const nonInteractive = boolFromRaw(flags["non-interactive"] ?? flags.yes ?? flags.json, false);
   if (nonInteractive) {
-    throw new Error("Telegram bot selector is required when multiple entries exist; pass --bot-key, --bot-id, or --bot-name");
+    throw new Error("Telegram bot selector is required when multiple entries exist; pass --bot-name or --bot-id (legacy --bot-key is still supported)");
   }
   return chooseTelegramEntry(ui, parsedEnv, deps, "Select Telegram bot entry", flags);
 }
@@ -2270,7 +2266,6 @@ async function buildTelegramEntrySelectionRows(entries, flags, deps) {
     const descriptionParts = [
       current.serverBotID ? `stored_server_bot_id:${current.serverBotID}` : "",
       current.client ? `ai_client:${displayLocalAIClientName(current.client)}` : "",
-      current.key ? `advanced_selector:${current.key}` : "",
     ].filter(Boolean);
     return {
       value: current.key,
@@ -2430,7 +2425,7 @@ async function addTelegramBot(ui, flags, deps) {
     defaultKeyHint,
   );
   if (nonInteractive && existingKeys.has(botKey)) {
-    throw new Error(`Telegram local selector "${botKey}" already exists`);
+    throw new Error(`Telegram legacy local selector "${botKey}" already exists`);
   }
   const serverGroupMatched = serverBot.matchMode === "group";
   if (serverGroupMatched && !nonInteractive) {
@@ -2530,7 +2525,7 @@ async function addTelegramBot(ui, flags, deps) {
   if (
     boolFromRaw(flags.default, false)
     || (nonInteractive && !hasCurrentDefault)
-    || (!nonInteractive && !hasCurrentDefault && await promptYesNo(ui, "Set this bot as TELEGRAM_DEFAULT_BOT_KEY?", true))
+    || (!nonInteractive && !hasCurrentDefault && await promptYesNo(ui, "Set this bot as the default Telegram bot?", true))
   ) {
     nextParsed.TELEGRAM_DEFAULT_BOT_KEY = botKey;
   }
@@ -2543,6 +2538,12 @@ async function editTelegramGlobalSettings(ui, flags, deps) {
   const state = loadProviderEnvState("telegram", deps);
   const parsed = { ...state.parsed };
   const nonInteractive = boolFromRaw(flags["non-interactive"] ?? flags.yes, false);
+  const defaultSelectorFlags = {
+    ...flags,
+    "bot-name": firstNonEmptyString([flags["default-bot-name"], flags["bot-name"]]),
+    "bot-id": firstNonEmptyString([flags["default-bot-id"], flags["bot-id"]]),
+    "bot-key": firstNonEmptyString([flags["default-bot-key"], flags["bot-key"]]),
+  };
   if (nonInteractive) {
     if (Object.prototype.hasOwnProperty.call(flags, "api-base-url")) {
       parsed.TELEGRAM_API_BASE_URL = String(flags["api-base-url"] || "").trim();
@@ -2553,8 +2554,16 @@ async function editTelegramGlobalSettings(ui, flags, deps) {
     if (Object.prototype.hasOwnProperty.call(flags, "allowed-updates")) {
       parsed.TELEGRAM_ALLOWED_UPDATES = String(flags["allowed-updates"] || "").trim();
     }
-    if (Object.prototype.hasOwnProperty.call(flags, "default-bot-key")) {
-      parsed.TELEGRAM_DEFAULT_BOT_KEY = String(flags["default-bot-key"] || "").trim();
+    if (
+      Object.prototype.hasOwnProperty.call(flags, "default-bot-name")
+      || Object.prototype.hasOwnProperty.call(flags, "default-bot-id")
+      || Object.prototype.hasOwnProperty.call(flags, "default-bot-key")
+    ) {
+      const selectedDefault = findTelegramEntryByFlags(parsed, defaultSelectorFlags, deps);
+      if (!selectedDefault) {
+        throw new Error("Telegram default bot selector was not found");
+      }
+      parsed.TELEGRAM_DEFAULT_BOT_KEY = selectedDefault.key;
     }
     const filePath = writeProviderEnvState("telegram", parsed, deps);
     process.stdout.write(`Saved Telegram global settings to ${filePath}\n`);
@@ -2567,7 +2576,13 @@ async function editTelegramGlobalSettings(ui, flags, deps) {
       { value: "api", label: "API base URL", description: String(parsed.TELEGRAM_API_BASE_URL || "").trim() || "(empty)" },
       { value: "webhook", label: "Auto clear webhook", description: boolFromRaw(parsed.TELEGRAM_AUTO_CLEAR_WEBHOOK, true) ? "true" : "false" },
       { value: "updates", label: "Allowed updates", description: String(parsed.TELEGRAM_ALLOWED_UPDATES || "message,edited_message").trim() },
-      { value: "default", label: "Default Telegram bot", description: String(parsed.TELEGRAM_DEFAULT_BOT_KEY || "").trim() || "(empty)" },
+      {
+        value: "default",
+        label: "Default Telegram bot",
+        description: telegramEntryDisplayName(
+          telegramEntriesForDisplay(parsed, deps).find((entry) => entry.isDefault) || {},
+        ) || "(empty)",
+      },
     ],
     { defaultIndex: 0 },
   );
@@ -2599,7 +2614,7 @@ async function editTelegramBot(ui, flags, deps) {
     ? findTelegramEntryByFlags(parsed, flags, deps)
     : await chooseTelegramEntry(ui, parsed, deps, "Select Telegram bot entry", flags);
   if (!selected) {
-    throw new Error("Telegram bot selector is required for non-interactive edit");
+    throw new Error("Telegram bot selector is required for non-interactive edit; pass --bot-name or --bot-id (legacy --bot-key is still supported)");
   }
   let current = { ...selected };
   if (nonInteractive) {
@@ -2661,11 +2676,11 @@ async function removeTelegramBot(ui, flags, deps) {
   const parsed = { ...state.parsed };
   const selected = await chooseTelegramEntry(ui, parsed, deps, "Select Telegram bot entry to remove", flags);
   if (!selected) return;
-  if (!await promptConfirmChoice(ui, `Remove Telegram bot "${selected.key}"?`, {
+  if (!await promptConfirmChoice(ui, `Remove Telegram bot "${telegramEntryDisplayName(selected)}"?`, {
     confirmLabel: "Remove bot",
-    confirmDescription: "delete this local Telegram bot entry",
+    confirmDescription: "delete this local Telegram bot file",
     cancelLabel: "Cancel",
-    cancelDescription: "keep the current local bot entry",
+    cancelDescription: "keep the current local Telegram bot file",
     defaultValue: "cancel",
   })) {
     process.stdout.write("Cancelled.\n");
@@ -2698,7 +2713,7 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
       selectors = {
         botKey: selected.key,
         botID: selected.serverBotID,
-        botName: selected.username,
+        botName: selected.serverBotName || selected.username,
       };
     }
   }
@@ -2848,7 +2863,6 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
         `ai_model: ${envConfig.model || "-"}`,
         `permission_mode: ${envConfig.permissionMode || "-"}`,
         `reasoning_effort: ${envConfig.reasoningEffort || "-"}`,
-        envConfig.botKey ? `advanced_local_selector: ${envConfig.botKey} (compatibility only)` : "",
       ]);
     }
     if (provider === "telegram" && serverBinding) {
@@ -3105,7 +3119,7 @@ async function runBotRemove(ui, flags, deps) {
       const state = loadProviderEnvState("telegram", deps);
       const selected = findTelegramEntryByFlags(state.parsed, flags, deps);
       if (!selected) {
-        throw new Error("Telegram bot selector is required for non-interactive remove");
+        throw new Error("Telegram bot selector is required for non-interactive remove; pass --bot-name or --bot-id (legacy --bot-key is still supported)");
       }
       const nextParsed = removeTelegramEntry(state.parsed, selected.key);
       if (String(state.parsed.TELEGRAM_DEFAULT_BOT_KEY || "").trim() === selected.key) {
@@ -3145,11 +3159,11 @@ async function runBotSetDefault(ui, flags, deps) {
     ? findTelegramEntryByFlags(parsed, flags, deps)
     : await chooseTelegramEntry(ui, parsed, deps, "Select default Telegram bot", flags);
   if (!selected) {
-    throw new Error("Telegram bot selector is required for set-default");
+    throw new Error("Telegram bot selector is required for set-default; pass --bot-name or --bot-id (legacy --bot-key is still supported)");
   }
-  if (!nonInteractive && !await promptConfirmChoice(ui, `Set "${selected.key}" as TELEGRAM_DEFAULT_BOT_KEY?`, {
+  if (!nonInteractive && !await promptConfirmChoice(ui, `Set "${telegramEntryDisplayName(selected)}" as the default Telegram bot?`, {
     confirmLabel: "Set default bot",
-    confirmDescription: "make this the default local Telegram bot entry",
+    confirmDescription: "make this the default Telegram bot for local delivery and fallback selection",
     cancelLabel: "Cancel",
     cancelDescription: "leave the current default unchanged",
     defaultValue: "confirm",
@@ -3159,7 +3173,7 @@ async function runBotSetDefault(ui, flags, deps) {
   }
   parsed.TELEGRAM_DEFAULT_BOT_KEY = selected.key;
   const filePath = writeProviderEnvState("telegram", parsed, deps);
-  process.stdout.write(`Set TELEGRAM_DEFAULT_BOT_KEY=${selected.key} in ${filePath}\n`);
+  process.stdout.write(`Set default Telegram bot to "${telegramEntryDisplayName(selected)}" in ${filePath}\n`);
 }
 
 async function runBotMigrate(ui, flags, deps) {
@@ -3186,11 +3200,11 @@ async function runBotMigrate(ui, flags, deps) {
   const botKey = normalizeBotKey(
     nonInteractive
       ? String(flags["bot-key"] || defaultKeyHint).trim()
-      : await promptRequiredLine(ui, "Advanced local selector for migrated entry", defaultKeyHint),
+      : await promptRequiredLine(ui, "Legacy local selector for migrated entry", defaultKeyHint),
     defaultKeyHint,
   );
   if (existingKeys.has(botKey)) {
-    throw new Error(`Telegram local selector "${botKey}" already exists`);
+    throw new Error(`Telegram legacy local selector "${botKey}" already exists`);
   }
   const nextParsed = upsertTelegramEntry(parsed, {
     key: botKey,

package/lib/doctor-checks.mjs

@@ -62,11 +62,11 @@ export async function runDoctorProjectDestinationChecks({
         continue;
       }
       const tokenDetailParts = [`configured (${envConfig.filePath})`];
-      if (envConfig.botKey) {
-        tokenDetailParts.push(`local_selector=${envConfig.botKey}`);
+      if (envConfig.serverBotName) {
+        tokenDetailParts.push(`server_bot_name=${envConfig.serverBotName}`);
       }
       if (envConfig.botUsername) {
-        tokenDetailParts.push(`@${envConfig.botUsername}`);
+        tokenDetailParts.push(`fallback_username=@${envConfig.botUsername}`);
       }
       if (envConfig.roleProfile) {
         tokenDetailParts.push(`role_profile=${envConfig.roleProfile}`);

package/package.json

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