metheus-governance-mcp-cli 0.2.112 → 0.2.113

package/README.md

@@ -305,7 +305,7 @@ For direct Telegram adds, the CLI derives the local file name from the matched s
 
 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.
+For runner commands, routes are the executable unit. Use `--route-name` as the primary selector. `--bot-name` and `--bot-id` are convenience route aliases only when they identify one enabled route uniquely. Use `runner list` first if you are not sure which route belongs to which server bot, and use `runner show` to inspect the resolved route, server identity, workspace mapping, and execution profile together.
 
 Current support status:
 
@@ -388,6 +388,7 @@ Commands:
 
 ```bash
 metheus-governance-mcp-cli runner list
+metheus-governance-mcp-cli runner show --route-name telegram-monitor
 metheus-governance-mcp-cli runner once --route-name telegram-monitor
 metheus-governance-mcp-cli runner start --route-name telegram-monitor
 ```
@@ -399,9 +400,16 @@ metheus-governance-mcp-cli runner once --route-name telegram-monitor --dry-run-d
 metheus-governance-mcp-cli runner start --route-name telegram-monitor
 ```
 
+What `runner list` means:
+- `server_bot_name` may come from `route.server_bot_name` or be resolved from the Telegram bot env file by `server_bot_id`
+- `server_bot_name_source=route_config` means the route file already stores the name directly
+- `server_bot_name_source=telegram_env_lookup` means the CLI resolved the name from the local Telegram bot file
+- `route_alias_by_server_bot_name` is a convenience selector, not a separate execution target
+
 Debug/selection overrides:
 
 ```bash
+metheus-governance-mcp-cli runner show --bot-name <server_bot_name>
 metheus-governance-mcp-cli runner once --project-id <project_uuid> --provider telegram --role monitor
 metheus-governance-mcp-cli runner start --project-id <project_uuid> --provider telegram --role monitor --poll-interval-ms 5000
 metheus-governance-mcp-cli runner once --project-id <project_uuid> --provider telegram --role monitor --role-profile review

package/cli.mjs

@@ -255,8 +255,9 @@ function printUsage() {
       `  ${cmd} selftest [--json <true|false>]`,
       `  ${cmd} local-bot-bridge [--client <gpt|claude|gemini|sample>] [--cwd <path>] [--model <name>] [--permission-mode <read_only|workspace_write|danger_full_access>] [--reasoning-effort <low|medium|high>]`,
       `  ${cmd} runner list [--json <true|false>]`,
-      `  ${cmd} runner once [--route-name <name> | --bot-name <server_name> | --bot-id <uuid>] [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--role-profile <name>] [--mentions-only <true|false>] [--reply-to-bot-messages <true|false>] [--direct-messages <true|false>] [--ignore-edited-messages <true|false>] [--dry-run-delivery <true|false>] [--context-comments <n>] [--archive-replies <true|false>]`,
-      `  ${cmd} runner start [--route-name <name> | --bot-name <server_name> | --bot-id <uuid>] [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--role-profile <name>] [--mentions-only <true|false>] [--reply-to-bot-messages <true|false>] [--direct-messages <true|false>] [--ignore-edited-messages <true|false>] [--dry-run-delivery <true|false>] [--poll-interval-ms <n>] [--context-comments <n>] [--archive-replies <true|false>]`,
+      `  ${cmd} runner show [--route-name <name> | --bot-name <server_name> | --bot-id <uuid>] [--json <true|false>]`,
+      `  ${cmd} runner once [--route-name <name> | --bot-name <server_name when one enabled route matches> | --bot-id <uuid when one enabled route matches>] [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--role-profile <name>] [--mentions-only <true|false>] [--reply-to-bot-messages <true|false>] [--direct-messages <true|false>] [--ignore-edited-messages <true|false>] [--dry-run-delivery <true|false>] [--context-comments <n>] [--archive-replies <true|false>]`,
+      `  ${cmd} runner start [--route-name <name> | --bot-name <server_name when one enabled route matches> | --bot-id <uuid when one enabled route matches>] [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--role-profile <name>] [--mentions-only <true|false>] [--reply-to-bot-messages <true|false>] [--direct-messages <true|false>] [--ignore-edited-messages <true|false>] [--dry-run-delivery <true|false>] [--poll-interval-ms <n>] [--context-comments <n>] [--archive-replies <true|false>]`,
       `  ${cmd} ctxpack pull [--project-id <uuid>] [--base-url <url>] [--workspace-dir <path|auto>] [--paths <csv>] [--timeout-seconds <n>]`,
       `  ${cmd} auth status`,
       `  ${cmd} 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>]`,
@@ -2632,6 +2633,11 @@ function buildRunnerRouteListRows() {
         );
       })
       : null;
+    const botNameSource = route.botName
+      ? "route_config"
+      : matchedTelegramEntry?.serverBotName
+        ? "telegram_env_lookup"
+        : "unresolved";
     const resolvedBotName = firstNonEmptyString([
       route.botName,
       matchedTelegramEntry?.serverBotName,
@@ -2644,6 +2650,7 @@ function buildRunnerRouteListRows() {
       provider: route.provider || "-",
       projectID: route.projectID || "-",
       botName: resolvedBotName,
+      botNameSource,
       botID: route.botID || "-",
       role: route.role || "-",
       roleProfile: route.roleProfile || "-",
@@ -2661,6 +2668,7 @@ async function runRunnerList(flags) {
     return;
   }
   process.stdout.write("Runner routes\n");
+  process.stdout.write("  note: routes are the executable unit. --bot-name and --bot-id are convenience selectors that resolve one enabled route when the match is unique.\n");
   if (!rows.length) {
     process.stdout.write("  none configured\n");
     return;
@@ -2673,18 +2681,141 @@ async function runRunnerList(flags) {
         `    provider: ${row.provider}`,
         `    project_id: ${row.projectID}`,
         `    server_bot_name: ${row.botName}`,
+        `    server_bot_name_source: ${row.botNameSource}`,
         `    server_bot_id: ${row.botID}`,
         `    role: ${row.role}`,
         `    role_profile: ${row.roleProfile}`,
         `    destination_label: ${row.destinationLabel}`,
         `    poll_interval_ms: ${row.pollIntervalMs}`,
         `    run_once: ${CLI_NAME} runner once --route-name ${row.name}`,
-        row.botName ? `    run_once_by_server_bot_name: ${CLI_NAME} runner once --bot-name "${row.botName}"` : "",
+        row.botName && row.botNameSource !== "unresolved"
+          ? `    route_alias_by_server_bot_name: ${CLI_NAME} runner once --bot-name "${row.botName}"`
+          : "",
       ].join("\n") + "\n",
     );
   });
 }
 
+function resolveRunnerShowSelection(flags) {
+  const routes = resolveRunnerRoutes(flags, "once");
+  if (!routes.length) {
+    throw new Error("no runner route matched the provided filters");
+  }
+  if (routes.length > 1) {
+    const names = routes.map((route) => normalizeRunnerRoute(route).name || runnerRouteKey(route)).join(", ");
+    throw new Error(`Multiple enabled runner routes matched. Narrow with --route-name, --bot-name, or --bot-id. Matches: ${names}`);
+  }
+  return normalizeRunnerRoute(routes[0]);
+}
+
+function findRunnerTelegramEntryForRoute(route, telegramEntries) {
+  const normalizedRoute = normalizeRunnerRoute(route);
+  if (normalizedRoute.provider !== "telegram") return null;
+  return ensureArray(telegramEntries).find((entry) => {
+    const current = safeObject(entry);
+    return (
+      (normalizedRoute.botID && current.serverBotID && current.serverBotID === normalizedRoute.botID)
+      || (normalizedRoute.botName && current.serverBotName && current.serverBotName === normalizedRoute.botName)
+    );
+  }) || null;
+}
+
+function buildRunnerShowPayload(route, flags = {}) {
+  const normalizedRoute = normalizeRunnerRoute(route);
+  const runnerConfig = loadBotRunnerConfig({ persistIfNeeded: true });
+  const diagnostics = collectRunnerRouteDiagnostics(normalizedRoute, runnerConfig);
+  const telegramState = readTelegramEnvState();
+  const telegramEntries = ensureArray(telegramState.entries);
+  const matchedTelegramEntry = findRunnerTelegramEntryForRoute(normalizedRoute, telegramEntries);
+  const botNameSource = normalizedRoute.botName
+    ? "route_config"
+    : matchedTelegramEntry?.serverBotName
+      ? "telegram_env_lookup"
+      : "unresolved";
+  const resolvedServerBotName = firstNonEmptyString([
+    normalizedRoute.botName,
+    matchedTelegramEntry?.serverBotName,
+    "-",
+  ]);
+  const envConfig = normalizedRoute.provider
+    ? loadProviderEnvConfig(normalizedRoute.provider, {
+      botID: normalizedRoute.botID,
+      botName: resolvedServerBotName !== "-" ? resolvedServerBotName : "",
+      route: normalizedRoute,
+    })
+    : null;
+  return {
+    ok: diagnostics.errors.length === 0,
+    route_name: normalizedRoute.name || runnerRouteKey(normalizedRoute),
+    route_key: runnerRouteKey(normalizedRoute),
+    route_config_file: runnerConfig.filePath,
+    route_config: serializeRunnerRoute(normalizedRoute),
+    resolved_server_identity: {
+      server_bot_name: resolvedServerBotName,
+      server_bot_name_source: botNameSource,
+      server_bot_id: normalizedRoute.botID || "-",
+      telegram_entry_file: String(envConfig?.entryFilePath || "").trim() || "-",
+    },
+    workspace_mapping: {
+      workspace_dir: diagnostics.workspaceDir || "-",
+      workspace_source: diagnostics.workspaceSource || "-",
+    },
+    execution_profile: {
+      route_role: normalizedRoute.role || "-",
+      role_profile_name: diagnostics.roleProfileName || "-",
+      client: String(diagnostics.roleProfile?.client || "").trim() || "-",
+      model: String(diagnostics.roleProfile?.model || "").trim() || "-",
+      permission_mode: String(diagnostics.roleProfile?.permissionMode || "").trim() || "-",
+      reasoning_effort: String(diagnostics.roleProfile?.reasoningEffort || "").trim() || "-",
+    },
+    route_selection_note: "Routes are the executable unit. --bot-name and --bot-id are convenience selectors that resolve one enabled route when the match is unique.",
+    warnings: diagnostics.warnings,
+    errors: diagnostics.errors,
+  };
+}
+
+async function runRunnerShow(flags) {
+  const route = resolveRunnerShowSelection(flags);
+  const payload = buildRunnerShowPayload(route, flags);
+  if (boolFromRaw(flags.json, false)) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write("Runner route details\n");
+  process.stdout.write("  note: routes are the executable unit. --bot-name and --bot-id are convenience selectors that resolve one enabled route when the match is unique.\n");
+  process.stdout.write(
+    [
+      `  route_name: ${payload.route_name}`,
+      `  route_key: ${payload.route_key}`,
+      `  route_config_file: ${payload.route_config_file}`,
+      "  route_config:",
+      `    provider: ${payload.route_config.provider || "-"}`,
+      `    project_id: ${payload.route_config.project_id || "-"}`,
+      `    role: ${payload.route_config.role || "-"}`,
+      `    role_profile: ${payload.route_config.role_profile || "-"}`,
+      `    destination_label: ${payload.route_config.destination_label || "-"}`,
+      `    poll_interval_ms: ${payload.route_config.poll_interval_ms || 0}`,
+      "  resolved_server_identity:",
+      `    server_bot_name: ${payload.resolved_server_identity.server_bot_name}`,
+      `    server_bot_name_source: ${payload.resolved_server_identity.server_bot_name_source}`,
+      `    server_bot_id: ${payload.resolved_server_identity.server_bot_id}`,
+      `    telegram_entry_file: ${payload.resolved_server_identity.telegram_entry_file}`,
+      "  workspace_mapping:",
+      `    workspace_dir: ${payload.workspace_mapping.workspace_dir}`,
+      `    workspace_source: ${payload.workspace_mapping.workspace_source}`,
+      "  execution_profile:",
+      `    route_role: ${payload.execution_profile.route_role}`,
+      `    role_profile_name: ${payload.execution_profile.role_profile_name}`,
+      `    client: ${payload.execution_profile.client}`,
+      `    model: ${payload.execution_profile.model}`,
+      `    permission_mode: ${payload.execution_profile.permission_mode}`,
+      `    reasoning_effort: ${payload.execution_profile.reasoning_effort}`,
+      payload.warnings.length ? `  warnings: ${payload.warnings.join("; ")}` : "  warnings: -",
+      payload.errors.length ? `  errors: ${payload.errors.join("; ")}` : "  errors: -",
+    ].join("\n") + "\n",
+  );
+}
+
 async function runRunnerStart(flags) {
   const jsonMode = boolFromRaw(flags.json, false);
   const routes = resolveRunnerRoutes(flags, "start");
@@ -2749,6 +2880,10 @@ async function runRunner(argv) {
     await runRunnerList(flags);
     return;
   }
+  if (subcommand === "show") {
+    await runRunnerShow(flags);
+    return;
+  }
   if (subcommand === "once") {
     await runRunnerOnce(flags);
     return;

package/package.json

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