outlook-cli 1.2.0

package/cli.js

@@ -0,0 +1,1349 @@
+#!/usr/bin/env node
+/**
+ * Production-oriented local CLI for outlook-cli.
+ *
+ * This CLI is designed for both human operators and automation/AI agents:
+ * - human friendly command groups (email/calendar/folder/rule/auth)
+ * - machine friendly JSON output mode
+ * - tokenless login helper that can start auth server and open browser
+ */
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+const chalk = require('chalk');
+
+const pkg = require('./package.json');
+const config = require('./config');
+const tokenManager = require('./auth/token-manager');
+const { listTools, getTool, invokeTool } = require('./tool-registry');
+
+const CLI_BIN_NAME = 'outlook-cli';
+const SPINNER_FRAMES = ['|', '/', '-', '\\'];
+const UI_STATE = {
+  plain: false,
+  color: false,
+  animate: false
+};
+
+function cliCommand(pathTail = '') {
+  return pathTail ? `${CLI_BIN_NAME} ${pathTail}` : CLI_BIN_NAME;
+}
+
+class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = 'CliError';
+    this.exitCode = exitCode;
+  }
+}
+
+class UsageError extends CliError {
+  constructor(message) {
+    super(message, 2);
+    this.name = 'UsageError';
+  }
+}
+
+function toCamelCase(value) {
+  return value.replace(/-([a-zA-Z])/g, (_, letter) => letter.toUpperCase());
+}
+
+function looksLikeOption(token) {
+  return /^--?[a-zA-Z]/.test(token);
+}
+
+function isNumericLiteral(value) {
+  return /^-?\d+(\.\d+)?$/.test(value);
+}
+
+function coerceValue(value) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (isNumericLiteral(value)) return Number(value);
+
+  if ((value.startsWith('{') && value.endsWith('}')) || (value.startsWith('[') && value.endsWith(']'))) {
+    try {
+      return JSON.parse(value);
+    } catch (_error) {
+      return value;
+    }
+  }
+
+  return value;
+}
+
+function pushOptionValue(options, key, value) {
+  const normalizedKey = toCamelCase(key);
+
+  if (!(normalizedKey in options)) {
+    options[normalizedKey] = value;
+    return;
+  }
+
+  if (!Array.isArray(options[normalizedKey])) {
+    options[normalizedKey] = [options[normalizedKey]];
+  }
+
+  options[normalizedKey].push(value);
+}
+
+function parseArgv(argv) {
+  const options = {};
+  const positional = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (token === '-commands' || token === '--commands') {
+      positional.push('commands');
+      continue;
+    }
+
+    if (token === '--') {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+
+    if (!token.startsWith('-') || token === '-') {
+      positional.push(token);
+      continue;
+    }
+
+    if (token.startsWith('--')) {
+      const long = token.slice(2);
+
+      if (long.includes('=')) {
+        const [rawKey, ...rest] = long.split('=');
+        pushOptionValue(options, rawKey, coerceValue(rest.join('=')));
+        continue;
+      }
+
+      if (long.startsWith('no-')) {
+        pushOptionValue(options, long.slice(3), false);
+        continue;
+      }
+
+      const next = argv[i + 1];
+      if (next !== undefined && !looksLikeOption(next)) {
+        pushOptionValue(options, long, coerceValue(next));
+        i += 1;
+      } else {
+        pushOptionValue(options, long, true);
+      }
+
+      continue;
+    }
+
+    const shorts = token.slice(1).split('');
+    shorts.forEach((shortFlag) => {
+      pushOptionValue(options, shortFlag, true);
+    });
+  }
+
+  return { options, positional };
+}
+
+function readOption(options, key, defaultValue) {
+  if (key in options) {
+    return options[key];
+  }
+
+  return defaultValue;
+}
+
+function requireOption(options, key, helpText) {
+  const value = readOption(options, key);
+  if (value === undefined || value === null || value === '') {
+    throw new UsageError(helpText || `Missing required option --${key}`);
+  }
+
+  return value;
+}
+
+function asBoolean(value, defaultValue = false) {
+  if (value === undefined) return defaultValue;
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') return value !== 0;
+
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) return false;
+
+  return defaultValue;
+}
+
+function asNumber(value, defaultValue, label) {
+  if (value === undefined || value === null || value === '') {
+    return defaultValue;
+  }
+
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new UsageError(`Expected ${label || 'a number'}, received: ${value}`);
+  }
+
+  return parsed;
+}
+
+function asCsv(value) {
+  if (value === undefined || value === null || value === '') {
+    return [];
+  }
+
+  if (Array.isArray(value)) {
+    return value
+      .flatMap((item) => String(item).split(','))
+      .map((item) => item.trim())
+      .filter(Boolean);
+  }
+
+  return String(value)
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function setUiState(options, outputMode) {
+  const plain = asBoolean(readOption(options, 'plain', false), false);
+  const colorOption = readOption(options, 'color');
+  const animateOption = readOption(options, 'animate');
+  const isTextMode = outputMode === 'text';
+  const isInteractive = isTextMode && process.stdout.isTTY;
+
+  UI_STATE.plain = plain;
+  UI_STATE.color = isInteractive && !plain && colorOption !== false;
+  UI_STATE.animate = isInteractive && !plain && animateOption !== false;
+
+  chalk.level = UI_STATE.color ? Math.max(chalk.level, 1) : 0;
+}
+
+function tone(text, kind) {
+  if (!UI_STATE.color) {
+    return text;
+  }
+
+  switch (kind) {
+    case 'title':
+      return chalk.bold.cyan(text);
+    case 'section':
+      return chalk.bold.blue(text);
+    case 'ok':
+      return chalk.green(text);
+    case 'warn':
+      return chalk.yellow(text);
+    case 'err':
+      return chalk.red(text);
+    case 'muted':
+      return chalk.gray(text);
+    case 'accent':
+      return chalk.magenta(text);
+    default:
+      return text;
+  }
+}
+
+function badge(kind) {
+  switch (kind) {
+    case 'ok':
+      return tone('[OK]', 'ok');
+    case 'warn':
+      return tone('[WARN]', 'warn');
+    case 'err':
+      return tone('[ERR]', 'err');
+    default:
+      return tone('[INFO]', 'accent');
+  }
+}
+
+function createSpinner(text, outputMode) {
+  const enabled = outputMode === 'text' && UI_STATE.animate;
+  let currentText = text;
+  let frameIndex = 0;
+  let timer = null;
+
+  function render() {
+    if (!enabled) {
+      return;
+    }
+
+    const frame = tone(SPINNER_FRAMES[frameIndex], 'accent');
+    process.stdout.write(`\r${frame} ${currentText}\x1b[K`);
+    frameIndex = (frameIndex + 1) % SPINNER_FRAMES.length;
+  }
+
+  return {
+    start() {
+      if (!enabled) {
+        return this;
+      }
+
+      render();
+      timer = setInterval(render, 90);
+      return this;
+    },
+    update(nextText) {
+      currentText = nextText;
+      if (enabled) {
+        render();
+      }
+      return this;
+    },
+    stop() {
+      if (enabled && timer) {
+        clearInterval(timer);
+        timer = null;
+        process.stdout.write('\r\x1b[2K');
+      }
+      return this;
+    }
+  };
+}
+
+function formatResultText(result) {
+  if (result && Array.isArray(result.content)) {
+    const textChunks = result.content
+      .filter((entry) => entry && entry.type === 'text' && typeof entry.text === 'string')
+      .map((entry) => entry.text.trim())
+      .filter(Boolean);
+
+    if (textChunks.length > 0) {
+      return textChunks.join('\n\n');
+    }
+  }
+
+  return JSON.stringify(result, null, 2);
+}
+
+function printSuccess(outputMode, payload) {
+  if (outputMode === 'json') {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+
+  if (typeof payload.message === 'string' && payload.message) {
+    process.stdout.write(`${badge('ok')} ${payload.message}\n`);
+  }
+
+  if (payload.result) {
+    process.stdout.write(`${tone('Result:', 'section')}\n${formatResultText(payload.result)}\n`);
+  }
+
+  if (payload.data && !payload.result) {
+    process.stdout.write(`${tone('Details:', 'section')}\n${JSON.stringify(payload.data, null, 2)}\n`);
+  }
+}
+
+function printError(outputMode, error) {
+  if (outputMode === 'json') {
+    process.stderr.write(`${JSON.stringify({
+      ok: false,
+      error: {
+        name: error.name,
+        message: error.message,
+        exitCode: error.exitCode || 1
+      }
+    }, null, 2)}\n`);
+    return;
+  }
+
+  process.stderr.write(`${badge('err')} ${error.message}\n`);
+  if (error instanceof UsageError) {
+    process.stderr.write(`${tone(`Run '${cliCommand('help')}' to see valid usage.`, 'muted')}\n`);
+  }
+}
+
+function buildOutputMode(options) {
+  const outputOption = readOption(options, 'output');
+  if (outputOption === 'json') {
+    return 'json';
+  }
+
+  if (asBoolean(readOption(options, 'json', false))) {
+    return 'json';
+  }
+
+  return 'text';
+}
+
+function parseKeyValueArgs(argOption) {
+  const pairs = Array.isArray(argOption) ? argOption : (argOption ? [argOption] : []);
+  const args = {};
+
+  pairs.forEach((pair) => {
+    const raw = String(pair);
+    const index = raw.indexOf('=');
+    if (index <= 0) {
+      throw new UsageError(`Invalid --arg value: ${pair}. Expected key=value.`);
+    }
+
+    const key = raw.slice(0, index).trim();
+    const value = raw.slice(index + 1).trim();
+    args[key] = coerceValue(value);
+  });
+
+  return args;
+}
+
+function parseArgsJson(argsJsonOption) {
+  if (!argsJsonOption) {
+    return {};
+  }
+
+  if (typeof argsJsonOption === 'object') {
+    return argsJsonOption;
+  }
+
+  try {
+    const parsed = JSON.parse(String(argsJsonOption));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('Value must be a JSON object');
+    }
+
+    return parsed;
+  } catch (error) {
+    throw new UsageError(`Invalid --args-json value: ${error.message}`);
+  }
+}
+
+async function callTool(toolName, args, outputMode, commandLabel) {
+  const result = await invokeTool(toolName, args);
+  printSuccess(outputMode, {
+    ok: true,
+    command: commandLabel,
+    tool: toolName,
+    args,
+    result
+  });
+}
+
+function printUsage() {
+  const usage = [
+    `${tone(CLI_BIN_NAME, 'title')} ${tone(`v${pkg.version}`, 'muted')}`,
+    '',
+    tone('Global install:', 'section'),
+    `  npm i -g ${pkg.name}`,
+    '',
+    tone('Usage:', 'section'),
+    `  ${cliCommand('<command> [subcommand] [options]')}`,
+    '',
+    tone('Global options:', 'section'),
+    '  --json                 Output machine-readable JSON',
+    '  --output text|json     Explicit output mode',
+    '  --plain                Disable rich colors and animations',
+    '  --no-color             Disable colors explicitly',
+    '  --no-animate           Disable spinner animations',
+    '  --help                 Show help',
+    '  --version              Show version',
+    '',
+    tone('Core commands:', 'section'),
+    '  commands               Show all command groups and tools',
+    '  tools list',
+    '  tools schema <tool-name>',
+    '  call <tool-name> [--args-json "{...}"] [--arg key=value]',
+    '  auth status|url|login|logout',
+    '  update [--run] [--to latest|x.y.z]',
+    '  doctor',
+    '',
+    tone('Human-friendly command groups:', 'section'),
+    '  email list|search|read|send|mark-read',
+    '  calendar list|create|decline|cancel|delete',
+    '  folder list|create|move',
+    '  rule list|create|sequence',
+    '',
+    tone('Examples:', 'section'),
+    `  ${cliCommand('auth login --open --start-server --wait --timeout 180')}`,
+    `  ${cliCommand('email list --folder inbox --count 15')}`,
+    `  ${cliCommand('call search-emails --arg query=invoice --arg unreadOnly=true --json')}`,
+    `  ${cliCommand('tools schema send-email')}`,
+    `  ${cliCommand('update --run')}`
+  ];
+
+  process.stdout.write(`${usage.join('\n')}\n`);
+}
+
+function getAuthUrl() {
+  if (!config.AUTH_CONFIG.clientId) {
+    throw new CliError('Client ID is missing. Set OUTLOOK_CLIENT_ID or MS_CLIENT_ID in your environment.', 1);
+  }
+
+  return `${config.AUTH_CONFIG.authServerUrl}/auth?client_id=${config.AUTH_CONFIG.clientId}`;
+}
+
+function buildCommandCatalog() {
+  const toolCatalog = listTools();
+
+  return {
+    commandGroups: {
+      auth: ['status', 'url', 'login', 'logout'],
+      email: ['list', 'search', 'read', 'send', 'mark-read'],
+      calendar: ['list', 'create', 'decline', 'cancel', 'delete'],
+      folder: ['list', 'create', 'move'],
+      rule: ['list', 'create', 'sequence'],
+      tools: ['list', 'schema'],
+      generic: ['call'],
+      system: ['doctor', 'update', 'version', 'help']
+    },
+    tools: toolCatalog
+  };
+}
+
+function printCommandCatalog(outputMode) {
+  const catalog = buildCommandCatalog();
+
+  printSuccess(outputMode, {
+    ok: true,
+    command: 'commands',
+    data: catalog,
+    message: outputMode === 'text'
+      ? [
+        `Command groups:`,
+        `- auth: ${catalog.commandGroups.auth.join(', ')}`,
+        `- email: ${catalog.commandGroups.email.join(', ')}`,
+        `- calendar: ${catalog.commandGroups.calendar.join(', ')}`,
+        `- folder: ${catalog.commandGroups.folder.join(', ')}`,
+        `- rule: ${catalog.commandGroups.rule.join(', ')}`,
+        `- tools: ${catalog.commandGroups.tools.join(', ')}`,
+        `- generic: ${catalog.commandGroups.generic.join(', ')}`,
+        `- system: ${catalog.commandGroups.system.join(', ')}`,
+        '',
+        `Available MCP tools (${catalog.tools.length}):`,
+        ...catalog.tools.map((tool) => `- ${tool.name}`)
+      ].join('\n')
+      : undefined
+  });
+}
+
+function parseBaseUrl(baseUrl) {
+  try {
+    return new URL(baseUrl);
+  } catch (_error) {
+    throw new CliError(`Invalid auth server URL: ${baseUrl}`, 1);
+  }
+}
+
+function httpProbe(baseUrl, timeoutMs = 1500) {
+  return new Promise((resolve) => {
+    const parsed = parseBaseUrl(baseUrl);
+    const transport = parsed.protocol === 'https:' ? https : http;
+
+    const req = transport.request(
+      {
+        hostname: parsed.hostname,
+        port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+        path: '/',
+        method: 'GET',
+        timeout: timeoutMs
+      },
+      (res) => {
+        res.resume();
+        resolve(true);
+      }
+    );
+
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(false);
+    });
+
+    req.end();
+  });
+}
+
+async function waitForProbe(baseUrl, timeoutMs, onTick) {
+  const start = Date.now();
+  let attempts = 0;
+
+  while ((Date.now() - start) < timeoutMs) {
+    attempts += 1;
+    if (onTick) {
+      onTick({
+        attempts,
+        elapsedMs: Date.now() - start,
+        remainingMs: Math.max(0, timeoutMs - (Date.now() - start))
+      });
+    }
+
+    // eslint-disable-next-line no-await-in-loop
+    if (await httpProbe(baseUrl)) {
+      return true;
+    }
+
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+
+  return false;
+}
+
+function openInBrowser(url) {
+  const platform = process.platform;
+
+  if (platform === 'win32') {
+    spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
+    return;
+  }
+
+  if (platform === 'darwin') {
+    spawn('open', [url], { detached: true, stdio: 'ignore' }).unref();
+    return;
+  }
+
+  spawn('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
+}
+
+function startAuthServer(outputMode) {
+  const scriptPath = path.join(__dirname, 'outlook-auth-server.js');
+
+  if (!fs.existsSync(scriptPath)) {
+    throw new CliError(`Auth server script not found: ${scriptPath}`, 1);
+  }
+
+  const child = spawn(process.execPath, [scriptPath], {
+    cwd: __dirname,
+    windowsHide: true,
+    stdio: 'ignore',
+    env: process.env
+  });
+
+  child.on('error', (error) => {
+    if (outputMode === 'text') {
+      process.stderr.write(`Auth server failed to start: ${error.message}\n`);
+    }
+  });
+
+  return child;
+}
+
+async function waitForValidToken(timeoutMs, onTick) {
+  const start = Date.now();
+  let attempts = 0;
+
+  while ((Date.now() - start) < timeoutMs) {
+    attempts += 1;
+    if (onTick) {
+      onTick({
+        attempts,
+        elapsedMs: Date.now() - start,
+        remainingMs: Math.max(0, timeoutMs - (Date.now() - start))
+      });
+    }
+
+    // eslint-disable-next-line no-await-in-loop
+    const accessToken = await tokenManager.getValidAccessToken();
+    if (accessToken) {
+      return true;
+    }
+
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((resolve) => setTimeout(resolve, 1500));
+  }
+
+  return false;
+}
+
+async function handleAuthCommand(action, options, outputMode) {
+  switch (action) {
+    case 'status': {
+      const accessToken = await tokenManager.getValidAccessToken();
+      const tokens = tokenManager.loadTokenCache();
+
+      printSuccess(outputMode, {
+        ok: true,
+        command: 'auth status',
+        data: {
+          authenticated: Boolean(accessToken),
+          tokenPath: config.AUTH_CONFIG.tokenStorePath,
+          expiresAt: tokens && tokens.expires_at ? new Date(tokens.expires_at).toISOString() : null,
+          authServerUrl: config.AUTH_CONFIG.authServerUrl
+        },
+        message: accessToken ? 'Authenticated and ready.' : 'Not authenticated.'
+      });
+      return;
+    }
+
+    case 'url': {
+      const authUrl = getAuthUrl();
+      printSuccess(outputMode, {
+        ok: true,
+        command: 'auth url',
+        data: { authUrl },
+        message: authUrl
+      });
+      return;
+    }
+
+    case 'logout': {
+      const removed = tokenManager.clearTokenCache();
+      printSuccess(outputMode, {
+        ok: true,
+        command: 'auth logout',
+        data: { removed, tokenPath: config.AUTH_CONFIG.tokenStorePath },
+        message: removed ? 'Token cache cleared.' : 'Unable to clear token cache.'
+      });
+      return;
+    }
+
+    case 'login': {
+      const force = asBoolean(readOption(options, 'force', false));
+      const shouldOpen = asBoolean(readOption(options, 'open', true), true);
+      const shouldStartServer = asBoolean(readOption(options, 'startServer', true), true);
+      const shouldWait = asBoolean(readOption(options, 'wait', true), true);
+      const timeoutSeconds = asNumber(readOption(options, 'timeout', 180), 180, 'timeout seconds');
+      const timeoutMs = Math.max(5, timeoutSeconds) * 1000;
+
+      if (force) {
+        tokenManager.clearTokenCache();
+      }
+
+      const existingToken = await tokenManager.getValidAccessToken();
+      if (existingToken && !force) {
+        printSuccess(outputMode, {
+          ok: true,
+          command: 'auth login',
+          data: { alreadyAuthenticated: true },
+          message: 'Already authenticated. Use --force to re-authenticate.'
+        });
+        return;
+      }
+
+      const authUrl = getAuthUrl();
+      let startedServer = null;
+      let startSpinner = null;
+      let waitSpinner = null;
+
+      try {
+        const runningBefore = await httpProbe(config.AUTH_CONFIG.authServerUrl);
+        if (!runningBefore && shouldStartServer) {
+          startSpinner = createSpinner('Starting auth server...', outputMode).start();
+          startedServer = startAuthServer(outputMode);
+          const ready = await waitForProbe(
+            config.AUTH_CONFIG.authServerUrl,
+            10000,
+            ({ remainingMs }) => {
+              if (startSpinner) {
+                startSpinner.update(`Starting auth server... ${Math.ceil(remainingMs / 1000)}s`);
+              }
+            }
+          );
+          if (startSpinner) {
+            startSpinner.stop();
+            startSpinner = null;
+          }
+
+          if (!ready) {
+            throw new CliError('Auth server did not become ready on time.', 1);
+          }
+
+          if (outputMode === 'text') {
+            process.stdout.write(`${badge('ok')} Auth server is ready.\n`);
+          }
+        }
+
+        if (!runningBefore && !shouldStartServer) {
+          throw new CliError('Auth server is not running. Start it with `npm run auth-server` or use --start-server.', 1);
+        }
+
+        if (shouldOpen) {
+          openInBrowser(authUrl);
+        }
+
+        if (!shouldWait) {
+          printSuccess(outputMode, {
+            ok: true,
+            command: 'auth login',
+            data: {
+              authUrl,
+              waiting: false,
+              serverStarted: Boolean(startedServer)
+            },
+            message: `Open this URL to authenticate: ${authUrl}`
+          });
+          return;
+        }
+
+        if (outputMode === 'text') {
+          process.stdout.write(`${badge('info')} Authenticate in browser: ${authUrl}\n`);
+        }
+
+        waitSpinner = createSpinner(`Waiting for token... ${Math.ceil(timeoutMs / 1000)}s left`, outputMode).start();
+        const authenticated = await waitForValidToken(
+          timeoutMs,
+          ({ remainingMs }) => {
+            if (waitSpinner) {
+              waitSpinner.update(`Waiting for token... ${Math.ceil(remainingMs / 1000)}s left`);
+            }
+          }
+        );
+        if (waitSpinner) {
+          waitSpinner.stop();
+          waitSpinner = null;
+        }
+
+        if (!authenticated) {
+          throw new CliError('Timed out waiting for authentication completion.', 1);
+        }
+
+        printSuccess(outputMode, {
+          ok: true,
+          command: 'auth login',
+          data: {
+            authenticated: true,
+            authUrl,
+            tokenPath: config.AUTH_CONFIG.tokenStorePath,
+            serverStarted: Boolean(startedServer)
+          },
+          message: 'Authentication completed successfully.'
+        });
+      } finally {
+        if (startSpinner) {
+          startSpinner.stop();
+        }
+        if (waitSpinner) {
+          waitSpinner.stop();
+        }
+        if (startedServer && !startedServer.killed) {
+          startedServer.kill('SIGTERM');
+        }
+      }
+
+      return;
+    }
+
+    default:
+      throw new UsageError('Unknown auth command. Use: auth status|url|login|logout');
+  }
+}
+
+function validateToolExists(toolName) {
+  if (!getTool(toolName)) {
+    throw new UsageError(`Unknown tool: ${toolName}. Use '${cliCommand('tools list')}' to view available tools.`);
+  }
+}
+
+async function handleToolsCommand(action, positional, outputMode) {
+  if (action === 'list' || !action) {
+    const tools = listTools();
+
+    printSuccess(outputMode, {
+      ok: true,
+      command: 'tools list',
+      data: { count: tools.length, tools },
+      message: outputMode === 'text'
+        ? tools.map((tool) => `- ${tool.name}: ${tool.description}`).join('\n')
+        : undefined
+    });
+    return;
+  }
+
+  if (action === 'schema') {
+    const toolName = positional[0];
+    if (!toolName) {
+      throw new UsageError(`Usage: ${cliCommand('tools schema <tool-name>')}`);
+    }
+
+    const tool = getTool(toolName);
+    if (!tool) {
+      throw new UsageError(`Unknown tool: ${toolName}`);
+    }
+
+    printSuccess(outputMode, {
+      ok: true,
+      command: 'tools schema',
+      data: {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema
+      },
+      message: outputMode === 'text'
+        ? `${tool.name}\n${tool.description}\n${JSON.stringify(tool.inputSchema, null, 2)}`
+        : undefined
+    });
+    return;
+  }
+
+  throw new UsageError('Unknown tools command. Use: tools list|schema <tool-name>');
+}
+
+async function handleGenericCall(positional, options, outputMode) {
+  const toolName = positional[0];
+  if (!toolName) {
+    throw new UsageError(`Usage: ${cliCommand('call <tool-name> [--args-json "{...}"] [--arg key=value]')}`);
+  }
+
+  validateToolExists(toolName);
+
+  const fromJson = parseArgsJson(readOption(options, 'argsJson'));
+  const fromPairs = parseKeyValueArgs(readOption(options, 'arg'));
+
+  const args = {
+    ...fromJson,
+    ...fromPairs
+  };
+
+  await callTool(toolName, args, outputMode, `call ${toolName}`);
+}
+
+function buildEventRange(value, timezone) {
+  if (!timezone) {
+    return value;
+  }
+
+  return {
+    dateTime: value,
+    timeZone: timezone
+  };
+}
+
+async function handleEmailCommand(action, options, outputMode) {
+  switch (action) {
+    case 'list': {
+      await callTool(
+        'list-emails',
+        {
+          folder: readOption(options, 'folder', 'inbox'),
+          count: asNumber(readOption(options, 'count', 10), 10, 'count')
+        },
+        outputMode,
+        'email list'
+      );
+      return;
+    }
+
+    case 'search': {
+      await callTool(
+        'search-emails',
+        {
+          query: readOption(options, 'query', ''),
+          folder: readOption(options, 'folder', 'inbox'),
+          from: readOption(options, 'from', ''),
+          to: readOption(options, 'to', ''),
+          subject: readOption(options, 'subject', ''),
+          hasAttachments: readOption(options, 'hasAttachments'),
+          unreadOnly: readOption(options, 'unreadOnly'),
+          count: asNumber(readOption(options, 'count', 10), 10, 'count')
+        },
+        outputMode,
+        'email search'
+      );
+      return;
+    }
+
+    case 'read': {
+      await callTool(
+        'read-email',
+        { id: requireOption(options, 'id', `Usage: ${cliCommand('email read --id <email-id>')}`) },
+        outputMode,
+        'email read'
+      );
+      return;
+    }
+
+    case 'send': {
+      await callTool(
+        'send-email',
+        {
+          to: requireOption(options, 'to', `Usage: ${cliCommand('email send --to <emails> --subject <subject> --body <body>')}`),
+          cc: readOption(options, 'cc'),
+          bcc: readOption(options, 'bcc'),
+          subject: requireOption(options, 'subject', `Usage: ${cliCommand('email send --to <emails> --subject <subject> --body <body>')}`),
+          body: requireOption(options, 'body', `Usage: ${cliCommand('email send --to <emails> --subject <subject> --body <body>')}`),
+          importance: readOption(options, 'importance', 'normal'),
+          saveToSentItems: asBoolean(readOption(options, 'saveToSentItems', true), true)
+        },
+        outputMode,
+        'email send'
+      );
+      return;
+    }
+
+    case 'mark-read': {
+      await callTool(
+        'mark-as-read',
+        {
+          id: requireOption(options, 'id', `Usage: ${cliCommand('email mark-read --id <email-id> [--is-read true|false]')}`),
+          isRead: asBoolean(readOption(options, 'isRead', true), true)
+        },
+        outputMode,
+        'email mark-read'
+      );
+      return;
+    }
+
+    default:
+      throw new UsageError('Unknown email command. Use: email list|search|read|send|mark-read');
+  }
+}
+
+async function handleCalendarCommand(action, options, outputMode) {
+  switch (action) {
+    case 'list': {
+      await callTool(
+        'list-events',
+        {
+          count: asNumber(readOption(options, 'count', 10), 10, 'count')
+        },
+        outputMode,
+        'calendar list'
+      );
+      return;
+    }
+
+    case 'create': {
+      const timezone = readOption(options, 'timezone');
+      const start = requireOption(options, 'start', `Usage: ${cliCommand('calendar create --subject <subject> --start <iso> --end <iso> [--timezone <tz>]')}`);
+      const end = requireOption(options, 'end', `Usage: ${cliCommand('calendar create --subject <subject> --start <iso> --end <iso> [--timezone <tz>]')}`);
+
+      await callTool(
+        'create-event',
+        {
+          subject: requireOption(options, 'subject', `Usage: ${cliCommand('calendar create --subject <subject> --start <iso> --end <iso>')}`),
+          start: buildEventRange(start, timezone),
+          end: buildEventRange(end, timezone),
+          attendees: asCsv(readOption(options, 'attendees')),
+          body: readOption(options, 'body', '')
+        },
+        outputMode,
+        'calendar create'
+      );
+      return;
+    }
+
+    case 'decline': {
+      await callTool(
+        'decline-event',
+        {
+          eventId: requireOption(options, 'eventId', `Usage: ${cliCommand('calendar decline --event-id <id> [--comment <text>]')}`),
+          comment: readOption(options, 'comment')
+        },
+        outputMode,
+        'calendar decline'
+      );
+      return;
+    }
+
+    case 'cancel': {
+      await callTool(
+        'cancel-event',
+        {
+          eventId: requireOption(options, 'eventId', `Usage: ${cliCommand('calendar cancel --event-id <id> [--comment <text>]')}`),
+          comment: readOption(options, 'comment')
+        },
+        outputMode,
+        'calendar cancel'
+      );
+      return;
+    }
+
+    case 'delete': {
+      await callTool(
+        'delete-event',
+        {
+          eventId: requireOption(options, 'eventId', `Usage: ${cliCommand('calendar delete --event-id <id>')}`)
+        },
+        outputMode,
+        'calendar delete'
+      );
+      return;
+    }
+
+    default:
+      throw new UsageError('Unknown calendar command. Use: calendar list|create|decline|cancel|delete');
+  }
+}
+
+async function handleFolderCommand(action, options, outputMode) {
+  switch (action) {
+    case 'list': {
+      await callTool(
+        'list-folders',
+        {
+          includeItemCounts: asBoolean(readOption(options, 'includeItemCounts', false), false),
+          includeChildren: asBoolean(readOption(options, 'includeChildren', false), false)
+        },
+        outputMode,
+        'folder list'
+      );
+      return;
+    }
+
+    case 'create': {
+      await callTool(
+        'create-folder',
+        {
+          name: requireOption(options, 'name', `Usage: ${cliCommand('folder create --name <folder-name> [--parent-folder <name>]')}`),
+          parentFolder: readOption(options, 'parentFolder', '')
+        },
+        outputMode,
+        'folder create'
+      );
+      return;
+    }
+
+    case 'move': {
+      await callTool(
+        'move-emails',
+        {
+          emailIds: requireOption(options, 'emailIds', `Usage: ${cliCommand('folder move --email-ids <id1,id2> --target-folder <name> [--source-folder <name>]')}`),
+          targetFolder: requireOption(options, 'targetFolder', `Usage: ${cliCommand('folder move --email-ids <id1,id2> --target-folder <name> [--source-folder <name>]')}`),
+          sourceFolder: readOption(options, 'sourceFolder', '')
+        },
+        outputMode,
+        'folder move'
+      );
+      return;
+    }
+
+    default:
+      throw new UsageError('Unknown folder command. Use: folder list|create|move');
+  }
+}
+
+async function handleRuleCommand(action, options, outputMode) {
+  switch (action) {
+    case 'list': {
+      await callTool(
+        'list-rules',
+        {
+          includeDetails: asBoolean(readOption(options, 'includeDetails', false), false)
+        },
+        outputMode,
+        'rule list'
+      );
+      return;
+    }
+
+    case 'create': {
+      await callTool(
+        'create-rule',
+        {
+          name: requireOption(options, 'name', `Usage: ${cliCommand('rule create --name <name> [rule options]')}`),
+          fromAddresses: readOption(options, 'fromAddresses'),
+          containsSubject: readOption(options, 'containsSubject'),
+          hasAttachments: readOption(options, 'hasAttachments'),
+          moveToFolder: readOption(options, 'moveToFolder'),
+          markAsRead: readOption(options, 'markAsRead'),
+          isEnabled: asBoolean(readOption(options, 'isEnabled', true), true),
+          sequence: readOption(options, 'sequence')
+        },
+        outputMode,
+        'rule create'
+      );
+      return;
+    }
+
+    case 'sequence': {
+      await callTool(
+        'edit-rule-sequence',
+        {
+          ruleName: requireOption(options, 'ruleName', `Usage: ${cliCommand('rule sequence --rule-name <name> --sequence <number>')}`),
+          sequence: asNumber(requireOption(options, 'sequence', `Usage: ${cliCommand('rule sequence --rule-name <name> --sequence <number>')}`), 1, 'sequence')
+        },
+        outputMode,
+        'rule sequence'
+      );
+      return;
+    }
+
+    default:
+      throw new UsageError('Unknown rule command. Use: rule list|create|sequence');
+  }
+}
+
+async function handleDoctorCommand(outputMode) {
+  const tokenPath = config.AUTH_CONFIG.tokenStorePath;
+  const tokenExists = fs.existsSync(tokenPath);
+  const authServerReachable = await httpProbe(config.AUTH_CONFIG.authServerUrl, 1000);
+  const hasClientId = Boolean(config.AUTH_CONFIG.clientId);
+  const hasClientSecret = Boolean(config.AUTH_CONFIG.clientSecret);
+  const accessToken = await tokenManager.getValidAccessToken();
+
+  const status = {
+    runtime: {
+      node: process.version,
+      platform: process.platform,
+      cwd: process.cwd()
+    },
+    auth: {
+      hasClientId,
+      hasClientSecret,
+      authenticated: Boolean(accessToken),
+      tokenPath,
+      tokenFileExists: tokenExists,
+      authServerUrl: config.AUTH_CONFIG.authServerUrl,
+      authServerReachable
+    },
+    mode: {
+      testMode: config.USE_TEST_MODE,
+      debugLogs: config.DEBUG_LOGS
+    }
+  };
+
+  const warnings = [];
+  if (!hasClientId) warnings.push('Missing client ID. Set OUTLOOK_CLIENT_ID or MS_CLIENT_ID.');
+  if (!hasClientSecret) warnings.push('Missing client secret. Set OUTLOOK_CLIENT_SECRET or MS_CLIENT_SECRET.');
+  if (!tokenExists) warnings.push(`Token file not found at ${tokenPath}. Run '${cliCommand('auth login')}'.`);
+  if (!authServerReachable) warnings.push(`Auth server is not reachable at ${config.AUTH_CONFIG.authServerUrl}.`);
+
+  printSuccess(outputMode, {
+    ok: true,
+    command: 'doctor',
+    data: {
+      ...status,
+      warnings
+    },
+    message: outputMode === 'text'
+      ? [
+        `Node: ${status.runtime.node}`,
+        `Platform: ${status.runtime.platform}`,
+        `Authenticated: ${status.auth.authenticated ? 'yes' : 'no'}`,
+        `Token file: ${status.auth.tokenFileExists ? 'found' : 'missing'} (${tokenPath})`,
+        `Auth server reachable: ${status.auth.authServerReachable ? 'yes' : 'no'}`,
+        warnings.length ? `Warnings:\n- ${warnings.join('\n- ')}` : 'No warnings detected.'
+      ].join('\n')
+      : undefined
+  });
+}
+
+async function handleUpdateCommand(options, outputMode) {
+  const target = String(readOption(options, 'to', 'latest'));
+  const installArg = `${pkg.name}@${target}`;
+  const updateCommand = `npm i -g ${installArg}`;
+  const shouldRun = asBoolean(readOption(options, 'run', false), false);
+
+  if (!shouldRun) {
+    printSuccess(outputMode, {
+      ok: true,
+      command: 'update',
+      data: {
+        packageName: pkg.name,
+        target,
+        command: updateCommand
+      },
+      message: `Run this to update globally: ${updateCommand}`
+    });
+    return;
+  }
+
+  if (outputMode === 'text') {
+    process.stdout.write(`${badge('info')} Running: ${updateCommand}\n`);
+  }
+
+  const result = spawnSync('npm', ['i', '-g', installArg], {
+    shell: process.platform === 'win32',
+    encoding: 'utf8',
+    stdio: outputMode === 'text' ? 'inherit' : 'pipe'
+  });
+
+  if (result.status !== 0) {
+    const details = outputMode === 'json'
+      ? `${result.stdout || ''}${result.stderr || ''}`.trim()
+      : '';
+
+    throw new CliError(`Global update failed${details ? `: ${details}` : '.'}`, 1);
+  }
+
+  printSuccess(outputMode, {
+    ok: true,
+    command: 'update',
+    data: {
+      packageName: pkg.name,
+      target,
+      command: updateCommand
+    },
+    message: `Updated successfully to ${installArg}.`
+  });
+}
+
+async function run() {
+  const parsed = parseArgv(process.argv.slice(2));
+  const { options, positional } = parsed;
+  const outputMode = buildOutputMode(options);
+  setUiState(options, outputMode);
+
+  const wantsHelp = asBoolean(readOption(options, 'help', false), false) || asBoolean(readOption(options, 'h', false), false);
+  const wantsVersion = asBoolean(readOption(options, 'version', false), false) || asBoolean(readOption(options, 'v', false), false);
+
+  if (wantsVersion) {
+    printSuccess(outputMode, {
+      ok: true,
+      command: 'version',
+      data: { version: pkg.version },
+      message: pkg.version
+    });
+    return;
+  }
+
+  if (wantsHelp || positional.length === 0 || positional[0] === 'help') {
+    printUsage();
+    return;
+  }
+
+  const command = positional[0];
+  const action = positional[1];
+  const rest = positional.slice(2);
+
+  switch (command) {
+    case 'version':
+      printSuccess(outputMode, {
+        ok: true,
+        command: 'version',
+        data: { version: pkg.version },
+        message: pkg.version
+      });
+      return;
+
+    case 'tools':
+      await handleToolsCommand(action, rest, outputMode);
+      return;
+
+    case 'commands':
+      printCommandCatalog(outputMode);
+      return;
+
+    case 'call':
+      await handleGenericCall(positional.slice(1), options, outputMode);
+      return;
+
+    case 'auth':
+      await handleAuthCommand(action, options, outputMode);
+      return;
+
+    case 'email':
+      await handleEmailCommand(action, options, outputMode);
+      return;
+
+    case 'calendar':
+      await handleCalendarCommand(action, options, outputMode);
+      return;
+
+    case 'folder':
+      await handleFolderCommand(action, options, outputMode);
+      return;
+
+    case 'rule':
+      await handleRuleCommand(action, options, outputMode);
+      return;
+
+    case 'doctor':
+      await handleDoctorCommand(outputMode);
+      return;
+
+    case 'update':
+      await handleUpdateCommand(options, outputMode);
+      return;
+
+    default:
+      throw new UsageError(`Unknown command: ${command}. Run '${cliCommand('help')}' for usage.`);
+  }
+}
+
+run().catch((error) => {
+  const parsed = parseArgv(process.argv.slice(2));
+  const outputMode = buildOutputMode(parsed.options);
+  setUiState(parsed.options, outputMode);
+  printError(outputMode, error);
+  process.exit(error.exitCode || 1);
+});