@tronsfey/ucli 0.4.3 → 0.5.1

package/dist/index.js

@@ -154,23 +154,71 @@ var ServerClient = class {
   }
 };
 
+// src/lib/exit-codes.ts
+var ExitCode = {
+  SUCCESS: 0,
+  GENERAL_ERROR: 1,
+  USAGE_ERROR: 2,
+  CONFIG_ERROR: 3,
+  AUTH_ERROR: 4,
+  CONNECTIVITY_ERROR: 5,
+  NOT_FOUND: 6,
+  SERVER_ERROR: 7
+};
+
+// src/lib/output.ts
+var currentMode = "text";
+function setOutputMode(mode) {
+  currentMode = mode;
+}
+function isJsonOutput() {
+  return currentMode === "json";
+}
+function outputSuccess(data) {
+  if (currentMode === "json") {
+    console.log(JSON.stringify({ success: true, data }, null, 2));
+  }
+}
+function outputError(code, message, hint) {
+  if (currentMode === "json") {
+    const envelope = {
+      success: false,
+      error: { code, message, ...hint ? { hint } : {} }
+    };
+    console.log(JSON.stringify(envelope, null, 2));
+    process.exit(code);
+  }
+  console.error(`
+\u2716 Error: ${message}`);
+  if (hint) console.error(`  Hint: ${hint}`);
+  process.exit(code);
+}
+
 // src/commands/configure.ts
 function registerConfigure(program2) {
   program2.command("configure").description("Configure the OAS Gateway server URL and authentication token").requiredOption("--server <url>", "OAS Gateway server URL (e.g. https://oas.example.com)").requiredOption("--token <jwt>", "Group JWT token issued by the server admin").action(async (opts) => {
     const serverUrl = opts.server.replace(/\/$/, "");
     const token = opts.token;
-    console.log(`Connecting to ${serverUrl}...`);
+    if (!isJsonOutput()) {
+      console.log(`Connecting to ${serverUrl}...`);
+    }
     const client = new ServerClient({ serverUrl, token });
     try {
       await client.listOAS();
       saveConfig({ serverUrl, token });
+      if (isJsonOutput()) {
+        outputSuccess({ serverUrl, configured: true });
+        return;
+      }
       console.log("\u2713 Configuration saved successfully.");
       console.log(`  Server: ${serverUrl}`);
       console.log(`  Token:  ${token.slice(0, 20)}...`);
     } catch (err) {
-      console.error("Connection failed:", err.message);
-      console.error("Please check the server URL and token.");
-      process.exit(1);
+      outputError(
+        ExitCode.CONNECTIVITY_ERROR,
+        `Connection failed: ${err.message}`,
+        "Check the server URL and token"
+      );
     }
   });
 }
@@ -374,6 +422,68 @@ async function getServiceHelp(entry) {
   });
 }
 
+// src/lib/yaml.ts
+function toYaml(value, indent = 0) {
+  if (value === null || value === void 0) {
+    return "null";
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  if (typeof value === "number") {
+    return String(value);
+  }
+  if (typeof value === "string") {
+    if (needsQuoting(value)) {
+      return JSON.stringify(value);
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    const prefix = " ".repeat(indent);
+    return value.map((item) => {
+      const serialised = toYaml(item, indent + 2);
+      if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+        const firstNewline = serialised.indexOf("\n");
+        if (firstNewline === -1) {
+          return `${prefix}- ${serialised.trimStart()}`;
+        }
+        const firstLine = serialised.slice(0, firstNewline);
+        const rest = serialised.slice(firstNewline + 1);
+        return `${prefix}- ${firstLine.trimStart()}
+${rest}`;
+      }
+      return `${prefix}- ${serialised}`;
+    }).join("\n");
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return "{}";
+    const prefix = " ".repeat(indent);
+    return entries.map(([key, val]) => {
+      if (val === null || val === void 0) {
+        return `${prefix}${key}: null`;
+      }
+      if (typeof val === "object") {
+        const nested = toYaml(val, indent + 2);
+        return `${prefix}${key}:
+${nested}`;
+      }
+      return `${prefix}${key}: ${toYaml(val, indent)}`;
+    }).join("\n");
+  }
+  return String(value);
+}
+function needsQuoting(s) {
+  if (s === "") return true;
+  if (s === "true" || s === "false" || s === "null") return true;
+  if (/^\d/.test(s)) return true;
+  if (/[:{}\[\],&*#?|<>=!%@`'"\\\n\r\t]/.test(s)) return true;
+  if (s.startsWith(" ") || s.endsWith(" ")) return true;
+  return false;
+}
+
 // src/commands/services.ts
 function registerServices(program2) {
   const services = program2.command("services").description("Manage and inspect available OAS services");
@@ -392,19 +502,27 @@ function registerServices(program2) {
         await writeOASListCache(entries, maxTtl);
       }
     }
+    const safe = entries.map(({ authConfig, ...rest }) => ({
+      ...rest,
+      authConfig: { type: authConfig["type"] ?? rest.authType }
+    }));
+    if (isJsonOutput()) {
+      outputSuccess(safe);
+      return;
+    }
     const format = (opts.format ?? "table").toLowerCase();
     if (entries.length === 0) {
       console.log("No services registered in this group.");
       return;
     }
     if (format === "json") {
-      const safe = entries.map(({ authConfig, ...rest }) => ({
-        ...rest,
-        authConfig: { type: authConfig["type"] ?? rest.authType }
-      }));
       console.log(JSON.stringify(safe, null, 2));
       return;
     }
+    if (format === "yaml") {
+      console.log(toYaml(safe));
+      return;
+    }
     const nameWidth = Math.max(10, ...entries.map((e) => e.name.length));
     console.log(`
 ${"SERVICE".padEnd(nameWidth)}  AUTH      DESCRIPTION`);
@@ -422,23 +540,33 @@ ${"SERVICE".padEnd(nameWidth)}  AUTH      DESCRIPTION`);
     let entry;
     try {
       entry = await client.getOAS(name);
-    } catch (err) {
-      console.error(`Service not found: ${name}`);
-      console.error("Run `ucli services list` to see available services.");
-      process.exit(1);
+    } catch {
+      outputError(
+        ExitCode.NOT_FOUND,
+        `Service not found: ${name}`,
+        "Run: ucli services list  to see available services"
+      );
     }
     const help = await getServiceHelp(entry);
+    const { authConfig, ...rest } = entry;
+    const safe = {
+      ...rest,
+      authConfig: { type: authConfig["type"] ?? rest.authType },
+      operationsHelp: help
+    };
+    if (isJsonOutput()) {
+      outputSuccess(safe);
+      return;
+    }
     const format = (opts.format ?? "table").toLowerCase();
     if (format === "json") {
-      const { authConfig, ...rest } = entry;
-      const safe = {
-        ...rest,
-        authConfig: { type: authConfig["type"] ?? rest.authType },
-        operationsHelp: help
-      };
       console.log(JSON.stringify(safe, null, 2));
       return;
     }
+    if (format === "yaml") {
+      console.log(toYaml(safe));
+      return;
+    }
     console.log(`
 Service: ${entry.name}`);
     console.log(`Description: ${entry.description || "(none)"}`);
@@ -456,13 +584,18 @@ Service: ${entry.name}`);
 function registerRun(program2) {
   program2.command("run [service] [args...]").description("Execute an operation on a service").option("--service <name>", "Service name (from `services list`)").option("--operation <id>", "OperationId to execute").option("--params <json>", "JSON string of operation parameters").option("--format <fmt>", "Output format: json | table | yaml", "json").option("--query <jmespath>", "Filter response with JMESPath expression").option("--data <json>", "Request body (JSON string or @filename)").allowUnknownOption(true).action(async (serviceArg, args, opts) => {
     if (serviceArg && opts.service && serviceArg !== opts.service) {
-      console.error(`Conflicting service values: positional "${serviceArg}" and --service "${opts.service}". Use either the positional argument or --service flag, not both.`);
-      process.exit(1);
+      outputError(
+        ExitCode.USAGE_ERROR,
+        `Conflicting service values: positional "${serviceArg}" and --service "${opts.service}". Use either the positional argument or --service flag, not both.`
+      );
     }
     const service = opts.service ?? serviceArg;
     if (!service) {
-      console.error("Missing service name. Use positional <service> or --service <name>.");
-      process.exit(1);
+      outputError(
+        ExitCode.USAGE_ERROR,
+        "Missing service name. Use positional <service> or --service <name>.",
+        "Run: ucli services list  to see available services"
+      );
     }
     const cfg = getConfig();
     const client = new ServerClient(cfg);
@@ -470,9 +603,11 @@ function registerRun(program2) {
     try {
       entry = await client.getOAS(service);
     } catch {
-      console.error(`Unknown service: ${service}`);
-      console.error("Run `ucli services list` to see available services.");
-      process.exit(1);
+      outputError(
+        ExitCode.NOT_FOUND,
+        `Unknown service: ${service}`,
+        "Run: ucli services list  to see available services"
+      );
     }
     const extraArgs = opts.args ?? [];
     const operationArgs = [...args, ...extraArgs];
@@ -484,8 +619,11 @@ function registerRun(program2) {
       try {
         parsed = JSON.parse(opts.params);
       } catch {
-        console.error(`Invalid --params JSON. Example: --params '{"petId": 1}'`);
-        process.exit(1);
+        outputError(
+          ExitCode.USAGE_ERROR,
+          "Invalid --params JSON.",
+          `Example: --params '{"petId": 1}'`
+        );
       }
       if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
         for (const [k, v] of Object.entries(parsed)) {
@@ -508,8 +646,10 @@ function registerRun(program2) {
         ...query !== void 0 ? { query } : {}
       });
     } catch (err) {
-      console.error("Operation failed:", err.message);
-      process.exit(1);
+      outputError(
+        ExitCode.GENERAL_ERROR,
+        `Operation failed: ${err.message}`
+      );
     }
   });
 }
@@ -519,7 +659,9 @@ function registerRefresh(program2) {
   program2.command("refresh").description("Force-refresh the local OAS cache from the server").option("--service <name>", "Refresh only a specific service").action(async (opts) => {
     const cfg = getConfig();
     const client = new ServerClient(cfg);
-    console.log("Refreshing OAS list from server...");
+    if (!isJsonOutput()) {
+      console.log("Refreshing OAS list from server...");
+    }
     if (opts.service) {
       await clearOASCache(opts.service);
     } else {
@@ -530,6 +672,10 @@ function registerRefresh(program2) {
       const maxTtl = Math.min(...entries.map((e) => e.cacheTtl));
       await writeOASListCache(entries, maxTtl);
     }
+    if (isJsonOutput()) {
+      outputSuccess({ refreshed: entries.length });
+      return;
+    }
     console.log(`\u2713 Refreshed ${entries.length} service(s).`);
   });
 }
@@ -570,7 +716,7 @@ function registerHelp(program2) {
     } catch {
       console.error(`Unknown service: ${service}`);
       console.error("Run `ucli services list` to see available services.");
-      process.exit(1);
+      process.exit(ExitCode.NOT_FOUND);
     }
     console.log(`
 === ${entry.name} ===`);
@@ -604,6 +750,10 @@ DISCOVERY
   ucli services info <service>
       Show detailed service info and all available operations.
 
+  ucli introspect
+      Return complete capability manifest in a single call (JSON).
+      Ideal for AI agents: includes services, MCP servers, and command reference.
+
   ucli help [service]
       Show this guide, or service-specific operations.
 
@@ -616,15 +766,44 @@ EXECUTION
         --query <jmespath>         Filter response with JMESPath
         --data <json|@file>        Request body for POST/PUT/PATCH
 
+MCP SERVERS
+  ucli mcp list
+      List all MCP servers in your group.
+
+  ucli mcp tools <server>
+      List tools available on a MCP server.
+
+  ucli mcp run <server> <tool> [key=value ...]
+      Call a tool on a MCP server.
+
 MAINTENANCE
   ucli refresh
       Force-refresh the local OAS cache from the server.
 
+  ucli doctor
+      Check configuration, server connectivity, and token validity.
+
+SHELL COMPLETIONS
+  eval "$(ucli completions bash)"
+  eval "$(ucli completions zsh)"
+  ucli completions fish | source
+
+GLOBAL FLAGS
+  --debug                          Enable verbose debug logging
+  --output json                    Wrap ALL output in structured JSON envelopes
+                                   (for agent/automation consumption)
+  -v, --version                    Show version number
+
 ERRORS
   401 Unauthorized  \u2192 Run: ucli configure --server <url> --token <jwt>
   404 Not Found     \u2192 Check service name: ucli services list
   4xx Client Error  \u2192 Check operation args: ucli services info <service>
   5xx Server Error  \u2192 Retry or run: ucli refresh
+
+AI AGENT QUICK START
+  1. ucli introspect               # discover everything in one call
+  2. ucli run <svc> <op> [args]    # execute operations
+  3. Use --output json globally    # get structured { success, data/error } envelopes
 `);
 }
 
@@ -635,8 +814,8 @@ function resolve(mod, name) {
   throw new Error(`Cannot resolve export "${name}" from module`);
 }
 async function getMcp2cli() {
-  const clientMod = await import("./client-3I7XBDJU.js");
-  const runnerMod = await import("./runner-GVYIJNHN.js");
+  const clientMod = await import("./client-LCWUZRZX.js");
+  const runnerMod = await import("./runner-HH357SRR.js");
   return {
     createMcpClient: resolve(clientMod, "createMcpClient"),
     getTools: resolve(runnerMod, "getTools"),
@@ -706,19 +885,27 @@ function registerMcp(program2) {
     const cfg = getConfig();
     const client = new ServerClient(cfg);
     const entries = await client.listMCP();
+    const safe = entries.map(({ authConfig, ...rest }) => ({
+      ...rest,
+      authConfig: { type: authConfig.type }
+    }));
+    if (isJsonOutput()) {
+      outputSuccess(safe);
+      return;
+    }
     if (entries.length === 0) {
       console.log("No MCP servers registered in this group.");
       return;
     }
     const format = (opts.format ?? "table").toLowerCase();
     if (format === "json") {
-      const safe = entries.map(({ authConfig, ...rest }) => ({
-        ...rest,
-        authConfig: { type: authConfig.type }
-      }));
       console.log(JSON.stringify(safe, null, 2));
       return;
     }
+    if (format === "yaml") {
+      console.log(toYaml(safe));
+      return;
+    }
     const nameWidth = Math.max(10, ...entries.map((e) => e.name.length));
     console.log(`
 ${"SERVER".padEnd(nameWidth)}  TRANSPORT  DESCRIPTION`);
@@ -729,23 +916,28 @@ ${"SERVER".padEnd(nameWidth)}  TRANSPORT  DESCRIPTION`);
     }
     console.log();
   });
-  mcp.command("tools <server>").description("List tools available on a MCP server").option("--format <fmt>", "Output format: table | json", "table").action(async (serverName, opts) => {
+  mcp.command("tools <server>").description("List tools available on a MCP server").option("--format <fmt>", "Output format: table | json | yaml", "table").action(async (serverName, opts) => {
     const cfg = getConfig();
     const client = new ServerClient(cfg);
     let entry;
     try {
       entry = await client.getMCP(serverName);
     } catch {
-      console.error(`Unknown MCP server: ${serverName}`);
-      console.error("Run `ucli mcp list` to see available servers.");
-      process.exit(1);
+      outputError(
+        ExitCode.NOT_FOUND,
+        `Unknown MCP server: ${serverName}`,
+        "Run: ucli mcp list  to see available servers"
+      );
     }
     let tools;
     try {
       tools = await listMcpTools(entry);
     } catch (err) {
-      console.error("Failed to fetch tools:", err.message);
-      process.exit(1);
+      outputError(ExitCode.GENERAL_ERROR, `Failed to fetch tools: ${err.message}`);
+    }
+    if (isJsonOutput()) {
+      outputSuccess(tools);
+      return;
     }
     if (tools.length === 0) {
       console.log(`No tools found on MCP server "${serverName}".`);
@@ -756,6 +948,10 @@ ${"SERVER".padEnd(nameWidth)}  TRANSPORT  DESCRIPTION`);
       console.log(JSON.stringify(tools, null, 2));
       return;
     }
+    if (format === "yaml") {
+      console.log(toYaml(tools));
+      return;
+    }
     console.log(`
 Tools on "${serverName}":`);
     console.log("\u2500".repeat(60));
@@ -772,29 +968,441 @@ Tools on "${serverName}":`);
     try {
       entry = await client.getMCP(serverName);
     } catch {
-      console.error(`Unknown MCP server: ${serverName}`);
-      console.error("Run `ucli mcp list` to see available servers.");
-      process.exit(1);
+      outputError(
+        ExitCode.NOT_FOUND,
+        `Unknown MCP server: ${serverName}`,
+        "Run: ucli mcp list  to see available servers"
+      );
     }
     try {
       await runMcpTool(entry, toolName, args);
     } catch (err) {
-      console.error("Tool execution failed:", err.message);
-      process.exit(1);
+      outputError(ExitCode.GENERAL_ERROR, `Tool execution failed: ${err.message}`);
     }
   });
 }
 
+// src/lib/errors.ts
+var debugEnabled = false;
+function setDebugMode(enabled) {
+  debugEnabled = enabled;
+}
+function debug(message) {
+  if (debugEnabled) {
+    console.error(`[DEBUG] ${message}`);
+  }
+}
+var HINT_MAP = {
+  [ExitCode.CONFIG_ERROR]: "Run: ucli configure --server <url> --token <jwt>",
+  [ExitCode.AUTH_ERROR]: "Your token may be expired or revoked. Run: ucli configure --server <url> --token <jwt>",
+  [ExitCode.CONNECTIVITY_ERROR]: "Check that the server URL is correct and the server is running. Run: ucli doctor",
+  [ExitCode.NOT_FOUND]: "Check the resource name. Run: ucli services list  or  ucli mcp list",
+  [ExitCode.SERVER_ERROR]: "The server returned an unexpected error. Try again or run: ucli doctor"
+};
+
+// src/commands/doctor.ts
+import axios2 from "axios";
+function registerDoctor(program2) {
+  program2.command("doctor").description("Check configuration, server connectivity, and token validity").action(async () => {
+    const results = [];
+    debug("Checking configuration...");
+    if (!isConfigured()) {
+      results.push({
+        name: "Configuration",
+        ok: false,
+        detail: "Not configured. Run: ucli configure --server <url> --token <jwt>"
+      });
+      outputError(
+        ExitCode.CONFIG_ERROR,
+        "Not configured",
+        "Run: ucli configure --server <url> --token <jwt>"
+      );
+    }
+    let cfg;
+    try {
+      cfg = getConfig();
+      results.push({
+        name: "Configuration",
+        ok: true,
+        detail: `Server: ${cfg.serverUrl}`
+      });
+    } catch (err) {
+      results.push({
+        name: "Configuration",
+        ok: false,
+        detail: `Failed to read config: ${err.message}`
+      });
+      outputError(
+        ExitCode.CONFIG_ERROR,
+        `Failed to read config: ${err.message}`,
+        "Run: ucli configure --server <url> --token <jwt>"
+      );
+    }
+    debug(`Checking connectivity to ${cfg.serverUrl}...`);
+    try {
+      const healthUrl = `${cfg.serverUrl}/api/v1/health`;
+      const resp = await axios2.get(healthUrl, { timeout: 1e4 });
+      results.push({
+        name: "Server connectivity",
+        ok: resp.status === 200,
+        detail: resp.status === 200 ? `Health endpoint OK (${cfg.serverUrl})` : `Unexpected status: ${resp.status}`
+      });
+    } catch (err) {
+      const msg = axios2.isAxiosError(err) ? err.code ?? err.message : err.message;
+      results.push({
+        name: "Server connectivity",
+        ok: false,
+        detail: `Cannot reach server: ${msg}`
+      });
+    }
+    debug("Validating JWT token...");
+    try {
+      const client = new ServerClient(cfg);
+      await client.listOAS();
+      results.push({
+        name: "Authentication",
+        ok: true,
+        detail: "Token accepted by server"
+      });
+    } catch (err) {
+      const msg = err.message;
+      results.push({
+        name: "Authentication",
+        ok: false,
+        detail: `Token rejected: ${msg}`
+      });
+    }
+    const allOk = results.every((r) => r.ok);
+    if (isJsonOutput()) {
+      outputSuccess({
+        healthy: allOk,
+        checks: results
+      });
+      process.exit(allOk ? ExitCode.SUCCESS : ExitCode.GENERAL_ERROR);
+    }
+    printResults(results);
+    process.exit(allOk ? ExitCode.SUCCESS : ExitCode.GENERAL_ERROR);
+  });
+}
+function printResults(results) {
+  console.log("\nucli doctor\n" + "\u2550".repeat(40));
+  for (const r of results) {
+    const icon = r.ok ? "\u2713" : "\u2716";
+    console.log(`  ${icon} ${r.name}: ${r.detail}`);
+  }
+  console.log();
+}
+
+// src/commands/completions.ts
+function registerCompletions(program2) {
+  program2.command("completions <shell>").description("Generate shell completion script (bash | zsh | fish)").action((shell) => {
+    const normalized = shell.toLowerCase().trim();
+    switch (normalized) {
+      case "bash":
+        console.log(bashCompletions());
+        break;
+      case "zsh":
+        console.log(zshCompletions());
+        break;
+      case "fish":
+        console.log(fishCompletions());
+        break;
+      default:
+        console.error(`Unsupported shell: ${shell}. Supported: bash, zsh, fish`);
+        process.exit(ExitCode.USAGE_ERROR);
+    }
+  });
+}
+function bashCompletions() {
+  return `# ucli bash completions \u2014 eval "$(ucli completions bash)"
+_ucli_completions() {
+  local cur prev commands
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  commands="configure services run refresh help mcp doctor completions introspect"
+
+  case "\${COMP_WORDS[1]}" in
+    services)
+      COMPREPLY=( $(compgen -W "list info" -- "$cur") )
+      return 0
+      ;;
+    mcp)
+      COMPREPLY=( $(compgen -W "list tools run" -- "$cur") )
+      return 0
+      ;;
+    completions)
+      COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") )
+      return 0
+      ;;
+    run|help)
+      # dynamic completions would require server calls; skip for now
+      return 0
+      ;;
+  esac
+
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+  fi
+
+  return 0
+}
+complete -F _ucli_completions ucli`;
+}
+function zshCompletions() {
+  return `# ucli zsh completions \u2014 eval "$(ucli completions zsh)"
+#compdef ucli
+
+_ucli() {
+  local -a commands
+  commands=(
+    'configure:Configure server URL and authentication token'
+    'services:Manage and inspect available OAS services'
+    'run:Execute an operation on a service'
+    'refresh:Force-refresh the local OAS cache'
+    'help:Show usage guide'
+    'mcp:Interact with MCP servers'
+    'doctor:Check configuration and connectivity'
+    'completions:Generate shell completion script'
+    'introspect:Return complete capability manifest for AI agents'
+  )
+
+  _arguments -C \\
+    '1: :->command' \\
+    '*::arg:->args'
+
+  case $state in
+    command)
+      _describe -t commands 'ucli commands' commands
+      ;;
+    args)
+      case $words[1] in
+        services)
+          _values 'subcommand' 'list[List all OAS services]' 'info[Show service details]'
+          ;;
+        mcp)
+          _values 'subcommand' 'list[List MCP servers]' 'tools[List tools]' 'run[Call a tool]'
+          ;;
+        completions)
+          _values 'shell' bash zsh fish
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_ucli "$@"`;
+}
+function fishCompletions() {
+  return `# ucli fish completions \u2014 ucli completions fish | source
+complete -c ucli -e
+
+# Top-level commands
+complete -c ucli -n __fish_use_subcommand -a configure -d 'Configure server URL and token'
+complete -c ucli -n __fish_use_subcommand -a services -d 'Manage OAS services'
+complete -c ucli -n __fish_use_subcommand -a run -d 'Execute a service operation'
+complete -c ucli -n __fish_use_subcommand -a refresh -d 'Refresh local cache'
+complete -c ucli -n __fish_use_subcommand -a help -d 'Show usage guide'
+complete -c ucli -n __fish_use_subcommand -a mcp -d 'Interact with MCP servers'
+complete -c ucli -n __fish_use_subcommand -a doctor -d 'Check config and connectivity'
+complete -c ucli -n __fish_use_subcommand -a completions -d 'Generate shell completions'
+
+complete -c ucli -n __fish_use_subcommand -a introspect -d 'Return capability manifest for AI agents'
+
+# services subcommands
+complete -c ucli -n '__fish_seen_subcommand_from services' -a list -d 'List services'
+complete -c ucli -n '__fish_seen_subcommand_from services' -a info -d 'Show service details'
+
+# mcp subcommands
+complete -c ucli -n '__fish_seen_subcommand_from mcp' -a list -d 'List MCP servers'
+complete -c ucli -n '__fish_seen_subcommand_from mcp' -a tools -d 'List tools'
+complete -c ucli -n '__fish_seen_subcommand_from mcp' -a run -d 'Call a tool'
+
+# completions subcommands
+complete -c ucli -n '__fish_seen_subcommand_from completions' -a 'bash zsh fish' -d 'Shell type'`;
+}
+
+// src/commands/introspect.ts
+function registerIntrospect(program2) {
+  program2.command("introspect").description("Return a complete capability manifest for AI agent discovery (services, MCP servers, commands)").option("--format <fmt>", "Output format: json | yaml", "json").action(async (opts) => {
+    const cfg = getConfig();
+    const client = new ServerClient(cfg);
+    let oasEntries = [];
+    let mcpEntries = [];
+    try {
+      ;
+      [oasEntries, mcpEntries] = await Promise.all([
+        client.listOAS(),
+        client.listMCP()
+      ]);
+    } catch (err) {
+      const message = err.message;
+      outputError(
+        ExitCode.CONNECTIVITY_ERROR,
+        `Failed to fetch capabilities: ${message}`,
+        "Check server connectivity with: ucli doctor"
+      );
+    }
+    const manifest = {
+      version: "1",
+      services: oasEntries.map(toIntrospectService),
+      mcpServers: mcpEntries.map(toIntrospectMcpServer),
+      commands: getCommandReference()
+    };
+    const format = (opts.format ?? "json").toLowerCase();
+    if (isJsonOutput()) {
+      outputSuccess(manifest);
+      return;
+    }
+    if (format === "json") {
+      console.log(JSON.stringify(manifest, null, 2));
+      return;
+    }
+    if (format === "yaml") {
+      console.log(toYaml(manifest));
+      return;
+    }
+    console.log(JSON.stringify(manifest, null, 2));
+  });
+}
+function toIntrospectService(e) {
+  return {
+    name: e.name,
+    description: e.description,
+    authType: e.authType,
+    remoteUrl: e.remoteUrl,
+    baseEndpoint: e.baseEndpoint,
+    cacheTtl: e.cacheTtl
+  };
+}
+function toIntrospectMcpServer(e) {
+  return {
+    name: e.name,
+    description: e.description,
+    transport: e.transport,
+    enabled: e.enabled
+  };
+}
+function getCommandReference() {
+  return [
+    {
+      name: "services list",
+      description: "List all OAS services available in the current group",
+      usage: "ucli services list [--format json|table|yaml] [--refresh]",
+      examples: [
+        "ucli services list",
+        "ucli services list --format json",
+        "ucli services list --refresh"
+      ]
+    },
+    {
+      name: "services info",
+      description: "Show detailed information and available operations for a service",
+      usage: "ucli services info <name> [--format json|table|yaml]",
+      examples: [
+        "ucli services info payments",
+        "ucli services info payments --format json"
+      ]
+    },
+    {
+      name: "run",
+      description: "Execute an operation on an OAS service",
+      usage: "ucli run <service> <operation> [--format json|table|yaml] [--query <jmespath>] [--data <json|@file>] [--params <json>]",
+      examples: [
+        "ucli run payments listTransactions",
+        "ucli run payments getTransaction --transactionId txn_123",
+        `ucli run payments createCharge --data '{"amount": 5000, "currency": "USD"}'`,
+        'ucli run inventory listProducts --query "items[?stock > `0`].name"'
+      ]
+    },
+    {
+      name: "mcp list",
+      description: "List all MCP servers available in the current group",
+      usage: "ucli mcp list [--format json|table|yaml]",
+      examples: [
+        "ucli mcp list",
+        "ucli mcp list --format json"
+      ]
+    },
+    {
+      name: "mcp tools",
+      description: "List tools available on a MCP server",
+      usage: "ucli mcp tools <server> [--format json|table|yaml]",
+      examples: [
+        "ucli mcp tools weather",
+        "ucli mcp tools weather --format json"
+      ]
+    },
+    {
+      name: "mcp run",
+      description: "Call a tool on a MCP server",
+      usage: "ucli mcp run <server> <tool> [key=value ...]",
+      examples: [
+        'ucli mcp run weather get_forecast location="New York"',
+        'ucli mcp run search web_search query="ucli docs" limit=5'
+      ]
+    },
+    {
+      name: "introspect",
+      description: "Return complete capability manifest (this command)",
+      usage: "ucli introspect [--format json|yaml]",
+      examples: [
+        "ucli introspect",
+        "ucli introspect --format yaml"
+      ]
+    },
+    {
+      name: "refresh",
+      description: "Force-refresh the local OAS cache from the server",
+      usage: "ucli refresh [--service <name>]",
+      examples: [
+        "ucli refresh",
+        "ucli refresh --service payments"
+      ]
+    },
+    {
+      name: "doctor",
+      description: "Check configuration, server connectivity, and token validity",
+      usage: "ucli doctor",
+      examples: ["ucli doctor"]
+    },
+    {
+      name: "configure",
+      description: "Configure the server URL and authentication token",
+      usage: "ucli configure --server <url> --token <jwt>",
+      examples: ["ucli configure --server https://oas.example.com --token eyJ..."]
+    }
+  ];
+}
+
 // src/index.ts
 var require3 = createRequire2(import.meta.url);
 var pkg = require3("../package.json");
 var program = new Command();
-program.name("ucli").description(pkg.description).version(pkg.version, "-v, --version").addHelpCommand(false);
+program.name("ucli").description(pkg.description).version(pkg.version, "-v, --version").option("--debug", "Enable verbose debug logging").option("--output <mode>", "Output mode: text | json (json wraps every result in a structured envelope for agent consumption)", "text").addHelpCommand(false).hook("preAction", (_thisCommand, actionCommand) => {
+  let cmd = actionCommand;
+  while (cmd) {
+    const opts = cmd.opts();
+    if (opts.debug) {
+      setDebugMode(true);
+    }
+    if (opts.output && typeof opts.output === "string") {
+      const mode = opts.output.toLowerCase();
+      if (mode === "json" || mode === "text") {
+        setOutputMode(mode);
+      }
+    }
+    cmd = cmd.parent;
+  }
+});
 registerConfigure(program);
 registerServices(program);
 registerRun(program);
 registerRefresh(program);
 registerMcp(program);
+registerDoctor(program);
+registerCompletions(program);
+registerIntrospect(program);
 registerHelp(program);
 program.parse(process.argv);
 //# sourceMappingURL=index.js.map