@velaro/cli 1.2.0 → 1.4.8

package/lib/commands/routing.js

@@ -0,0 +1,304 @@
+import { messagingGet, messagingPut, messagingDel, get as adminGet } from '../api.js';
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+const RESET = '\x1b[0m';
+const BOLD  = '\x1b[1m';
+const DIM   = '\x1b[2m';
+const CYN   = '\x1b[36m';
+const YEL   = '\x1b[33m';
+const GRN   = '\x1b[32m';
+const RED   = '\x1b[31m';
+
+function fmtDate(iso) {
+  if (!iso) return '—';
+  return new Date(iso).toLocaleString('en-US', {
+    timeZone: 'America/Los_Angeles',
+    dateStyle: 'short',
+    timeStyle: 'short',
+  });
+}
+
+const TERMINAL_LABELS = {
+  0: 'Survey',
+  1: 'Create Ticket',
+  2: 'Survey + Create Ticket',
+  3: 'Queue',
+  4: 'Offline Message',
+  5: 'No Action',
+};
+
+// ── velaro routing engine get ─────────────────────────────────────────────────
+
+const engineGetCommand = {
+  command:  'get',
+  describe: 'Show the current routing engine version and circuit breaker status',
+  builder:  (y) => y,
+  handler:  async () => {
+    const data = await messagingGet('/RoutingEngine');
+
+    const ver   = data.engineVersion ?? 'unknown';
+    const cb    = data.circuitBreakerOpen ?? false;
+    const verColor = ver === 'modern' ? GRN : YEL;
+
+    console.log(`\n${BOLD}── Routing Engine ──────────────────────────────────────────────────────${RESET}`);
+    console.log(`  Engine version:     ${verColor}${ver}${RESET}`);
+    console.log(`  Circuit breaker:    ${cb ? `${RED}OPEN (auto-reverted to legacy)${RESET}` : `${GRN}closed${RESET}`}`);
+    console.log();
+
+    if (cb) {
+      console.log(`${YEL}  ⚠ Circuit breaker is open.${RESET}`);
+      console.log(`  Run ${CYN}velaro routing circuit-breaker reset${RESET} to re-enable smart routing.\n`);
+    }
+  },
+};
+
+// ── velaro routing engine set ─────────────────────────────────────────────────
+
+const engineSetCommand = {
+  command:  'set',
+  describe: 'Set the routing engine version',
+  builder:  (y) => y
+    .option('version', {
+      alias:    'v',
+      type:     'string',
+      describe: 'Engine version: legacy or modern',
+      choices:  ['legacy', 'modern'],
+      demandOption: true,
+    }),
+  handler:  async (argv) => {
+    const { version } = argv;
+    await messagingPut('/RoutingEngine', { engineVersion: version });
+    const color = version === 'modern' ? GRN : YEL;
+    console.log(`\n  ${GRN}✓${RESET} Routing engine set to ${color}${version}${RESET}\n`);
+  },
+};
+
+// ── velaro routing engine ─────────────────────────────────────────────────────
+
+const engineCommand = {
+  command:  'engine <subcommand>',
+  describe: 'Manage the routing engine version',
+  builder:  (y) => y
+    .command(engineGetCommand)
+    .command(engineSetCommand)
+    .demandCommand(1, 'Specify a subcommand: get, set')
+    .strict(),
+  handler:  () => {},
+};
+
+// ── velaro routing circuit-breaker reset ──────────────────────────────────────
+
+const cbResetCommand = {
+  command:  'reset',
+  describe: 'Reset the routing circuit breaker to re-enable smart routing',
+  builder:  (y) => y,
+  handler:  async () => {
+    await messagingDel('/RoutingEngine/circuit-breaker');
+    console.log(`\n  ${GRN}✓${RESET} Circuit breaker reset. Smart routing is active again.\n`);
+  },
+};
+
+const circuitBreakerCommand = {
+  command:  'circuit-breaker <subcommand>',
+  describe: 'Manage the routing circuit breaker',
+  builder:  (y) => y
+    .command(cbResetCommand)
+    .demandCommand(1, 'Specify a subcommand: reset')
+    .strict(),
+  handler:  () => {},
+};
+
+// ── velaro routing policy get ─────────────────────────────────────────────────
+
+const policyGetCommand = {
+  command:  'get',
+  describe: 'Show the site-wide auto-routing policy',
+  builder:  (y) => y,
+  handler:  async () => {
+    const p = await messagingGet('/AutoRoutingPolicy');
+
+    console.log(`\n${BOLD}── Auto-Routing Policy ─────────────────────────────────────────────────${RESET}`);
+    console.log(`  ${DIM}Enabled:                   ${RESET}${p.enabled ? `${GRN}yes${RESET}` : `${RED}no${RESET}`}`);
+    console.log(`  ${DIM}Initial response timeout:  ${RESET}${p.initialResponseTimeoutSeconds}s`);
+    console.log(`  ${DIM}Idle after response:       ${RESET}${p.idleAfterResponseTimeoutSeconds}s`);
+    console.log(`  ${DIM}Idle alert grace period:   ${RESET}${p.idleAlertGraceSeconds}s`);
+    console.log(`  ${DIM}Max reroute attempts:      ${RESET}${p.maxRerouteAttempts}`);
+    console.log(`  ${DIM}Allow bounceback:          ${RESET}${p.allowBounceBack ? `${YEL}yes${RESET}` : 'no'}`);
+    console.log(`  ${DIM}Prefer previous agent:     ${RESET}${p.preferPreviousAgentOnTimeout ? `${GRN}yes${RESET}` : 'no'}`);
+    console.log(`  ${DIM}Agent follow-up flag:      ${RESET}${p.agentFollowUpFlagEnabled ? `${GRN}yes${RESET}` : 'no'}`);
+    console.log(`  ${DIM}Queue unavailable grace:   ${RESET}${p.queueUnavailableGracePeriodSeconds}s`);
+
+    const terminalLabel = p.terminalActionOverride != null
+      ? (TERMINAL_LABELS[p.terminalActionOverride] ?? String(p.terminalActionOverride))
+      : 'Default (Survey)';
+    console.log(`  ${DIM}Terminal action:           ${RESET}${terminalLabel}`);
+    console.log();
+  },
+};
+
+// ── velaro routing policy set ─────────────────────────────────────────────────
+
+const policySetCommand = {
+  command:  'set',
+  describe: 'Update the site-wide auto-routing policy fields',
+  builder:  (y) => y
+    .option('initial-timeout', {
+      type:     'number',
+      describe: 'Initial response timeout in seconds (min 30)',
+    })
+    .option('idle-timeout', {
+      type:     'number',
+      describe: 'Idle after response timeout in seconds (min 30)',
+    })
+    .option('grace', {
+      type:     'number',
+      describe: 'Idle alert grace period in seconds',
+    })
+    .option('max-reroutes', {
+      type:     'number',
+      describe: 'Max reroute attempts (min 1)',
+    })
+    .option('allow-bounceback', {
+      type:     'boolean',
+      describe: 'Allow agent bounceback (true/false)',
+    })
+    .option('prefer-previous', {
+      type:     'boolean',
+      describe: 'Prefer previous agent on timeout (true/false)',
+    })
+    .option('terminal-action', {
+      type:     'number',
+      describe: 'Terminal action: 0=Survey 1=CreateTicket 2=SurveyAndCreateTicket 3=Queue 4=OfflineMessage 5=NoOp',
+    }),
+  handler:  async (argv) => {
+    // Load current policy first, then merge
+    const current = await messagingGet('/AutoRoutingPolicy');
+
+    const updated = {
+      ...current,
+      initialResponseTimeoutSeconds:  argv['initial-timeout']  ?? current.initialResponseTimeoutSeconds,
+      idleAfterResponseTimeoutSeconds: argv['idle-timeout']     ?? current.idleAfterResponseTimeoutSeconds,
+      idleAlertGraceSeconds:           argv['grace']            ?? current.idleAlertGraceSeconds,
+      maxRerouteAttempts:              argv['max-reroutes']     ?? current.maxRerouteAttempts,
+      allowBounceBack:                 argv['allow-bounceback'] ?? current.allowBounceBack,
+      preferPreviousAgentOnTimeout:    argv['prefer-previous']  ?? current.preferPreviousAgentOnTimeout,
+      terminalActionOverride:
+        argv['terminal-action'] !== undefined
+          ? argv['terminal-action']
+          : current.terminalActionOverride,
+    };
+
+    await messagingPut('/AutoRoutingPolicy', updated);
+    console.log(`\n  ${GRN}✓${RESET} Routing policy updated.\n`);
+  },
+};
+
+// ── velaro routing policy ─────────────────────────────────────────────────────
+
+const policyCommand = {
+  command:  'policy <subcommand>',
+  describe: 'Manage the site-wide auto-routing policy',
+  builder:  (y) => y
+    .command(policyGetCommand)
+    .command(policySetCommand)
+    .demandCommand(1, 'Specify a subcommand: get, set')
+    .strict(),
+  handler:  () => {},
+};
+
+// ── velaro routing decision-log ───────────────────────────────────────────────
+
+const decisionLogCommand = {
+  command:  'decision-log <conversationId>',
+  describe: 'Show the routing decision log for a conversation',
+  builder:  (y) => y
+    .positional('conversationId', {
+      type:     'string',
+      describe: 'Conversation ID',
+    }),
+  handler:  async (argv) => {
+    const { conversationId } = argv;
+    const data = await messagingGet(`/RoutingEngine/decision-log/${conversationId}`);
+    const items = Array.isArray(data) ? data : [];
+
+    console.log(`\n${BOLD}── Routing Decision Log — Conversation ${conversationId} ────────────────────${RESET}`);
+
+    if (!items.length) {
+      console.log(`  ${DIM}No routing events found for this conversation.${RESET}\n`);
+      return;
+    }
+
+    for (const ev of items) {
+      const ts  = fmtDate(ev.timestamp);
+      const type = (ev.eventType ?? '—').padEnd(24);
+      const source = ev.ruleSource ? `${DIM}[${ev.ruleSource}]${RESET} ` : '';
+      const agents = ev.fromAgentId
+        ? ` ${DIM}agent ${ev.fromAgentId}${ev.toAgentId ? ` → ${ev.toAgentId}` : ''}${RESET}`
+        : '';
+      const attempt = ev.rerouteAttemptNumber != null ? ` ${DIM}attempt #${ev.rerouteAttemptNumber}${RESET}` : '';
+      console.log(`  ${CYN}${ts}${RESET}  ${BOLD}${type}${RESET}  ${source}${ev.reason ?? ''}${agents}${attempt}`);
+    }
+    console.log();
+  },
+};
+
+// ── velaro routing explain ────────────────────────────────────────────────────
+
+const explainCommand = {
+  command:  'explain <conversationId>',
+  describe: 'Plain-English explanation of every routing decision for a conversation — agent names, policy settings, and timeline',
+  builder:  (y) => y
+    .positional('conversationId', {
+      type:     'string',
+      describe: 'Conversation ID',
+    }),
+  handler:  async (argv) => {
+    const { conversationId } = argv;
+    let result;
+    try {
+      result = await adminGet(`RoutingDiagnostics/explain/${conversationId}`);
+    } catch (err) {
+      console.error(`\n${RED}Error:${RESET} ${err.message}\n`);
+      process.exit(1);
+    }
+
+    console.log(`\n${BOLD}── Routing Explanation — Conversation ${conversationId} ─────────────────────${RESET}`);
+    console.log(`  Engine: ${result.engineVersion === 'modern' ? GRN : YEL}${result.engineVersion}${RESET}  ·  ${result.events?.length ?? 0} routing events\n`);
+
+    if (result.summary) {
+      const lines = result.summary.split('\n');
+      for (const line of lines) {
+        console.log(`  ${line}`);
+      }
+    }
+
+    if (result.policySnapshot) {
+      const p = result.policySnapshot;
+      console.log(`\n${DIM}  Policy settings:${RESET}`);
+      console.log(`  Initial timeout:    ${p.initialResponseTimeoutSeconds}s`);
+      console.log(`  Idle timeout:       ${p.idleAfterResponseTimeoutSeconds}s`);
+      console.log(`  Max reroutes:       ${p.maxRerouteAttempts}`);
+      console.log(`  Terminal action:    ${p.terminalActionOverride != null ? TERMINAL_LABELS[p.terminalActionOverride] ?? p.terminalActionOverride : 'default (Survey)'}`);
+      console.log(`  Anti-bounce:        ${!p.allowBounceBack ? `${GRN}ON${RESET}` : `${DIM}off${RESET}`}`);
+      console.log(`  Prefer prev agent:  ${p.preferPreviousAgentOnTimeout ? `${GRN}yes${RESET}` : 'no'}`);
+    }
+    console.log();
+  },
+};
+
+// ── top-level routing command ─────────────────────────────────────────────────
+
+export const routingCommand = {
+  command:  'routing <subcommand>',
+  describe: 'Manage smart routing engine, policy, and decision logs',
+  builder:  (y) => y
+    .command(engineCommand)
+    .command(circuitBreakerCommand)
+    .command(policyCommand)
+    .command(decisionLogCommand)
+    .command(explainCommand)
+    .demandCommand(1, 'Specify a subcommand: engine, circuit-breaker, policy, decision-log, explain')
+    .strict(),
+  handler:  () => {},
+};

package/lib/commands/rule.js

@@ -1,85 +1,85 @@
-import { get, post, del } from '../api.js';
-import { requireFeature }  from '../subscription.js';
-import { runCommand }      from '../run.js';
-
-export const ruleCommand = {
-  command:  'rule <subcommand>',
-  describe: 'Manage routing rules',
-  builder:  (yargs) =>
-    yargs
-      .command(ruleListCommand)
-      .command(ruleCreateCommand)
-      .command(ruleDeleteCommand)
-      .demandCommand(1, 'Specify a subcommand: list, create, delete'),
-  handler: () => {},
-};
-
-// ── list ───────────────────────────────────────────────────────────────────────
-
-const ruleListCommand = {
-  command:  'list',
-  describe: 'List all routing rules',
-  handler:  runCommand(async () => {
-    await requireFeature('enableWorkflowRules', 'Routing Rules');
-
-    const rules = await get('/Rules/List');
-    if (!rules?.length) { console.log('No routing rules found.'); return; }
-
-    const sorted = [...rules].sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
-    const idW    = Math.max(...sorted.map(r => String(r.id).length + 2));
-    const priW   = Math.max('pri'.length, ...sorted.map(r => String(r.priority ?? 0).length));
-    const nameW  = Math.max('name'.length, ...sorted.map(r => (r.name ?? r.trigger ?? '—').length));
-
-    console.log(`\n${'id'.padStart(idW)}  ${'pri'.padEnd(priW)}  ${'name'.padEnd(nameW)}  trigger`);
-    console.log(`${'-'.repeat(idW)}  ${'-'.repeat(priW)}  ${'-'.repeat(nameW)}  -------`);
-    for (const r of sorted) {
-      const id   = `[${r.id}]`.padStart(idW);
-      const pri  = String(r.priority ?? 0).padEnd(priW);
-      const name = (r.name ?? r.trigger ?? '—').padEnd(nameW);
-      console.log(`${id}  ${pri}  ${name}  ${r.trigger ?? '—'}`);
-    }
-    console.log(`\n${sorted.length} rule(s)`);
-  }),
-};
-
-// ── create ─────────────────────────────────────────────────────────────────────
-
-const ruleCreateCommand = {
-  command:  'create',
-  describe: 'Create a routing rule',
-  builder:  (y) =>
-    y
-      .option('name',       { type: 'string', demandOption: true, describe: 'Rule name' })
-      .option('trigger',    { type: 'string', demandOption: true, describe: 'Trigger type (e.g. pageUrl, country)' })
-      .option('value',      { type: 'string', demandOption: true, describe: 'Trigger value to match' })
-      .option('team-id',    { type: 'number', demandOption: true, describe: 'Team ID to route to' })
-      .option('priority',   { type: 'number', default: 0,         describe: 'Rule priority (lower = higher priority)' }),
-
-  handler: runCommand(async (argv) => {
-    await requireFeature('enableWorkflowRules', 'Routing Rules');
-
-    const result = await post('/Rules', {
-      name:      argv.name,
-      trigger:   argv.trigger,
-      value:     argv.value,
-      teamId:    argv['team-id'],
-      priority:  argv.priority,
-      isEnabled: true,
-    });
-
-    console.log(`Rule created: [${result.id}] ${result.name}`);
-  }),
-};
-
-// ── delete ─────────────────────────────────────────────────────────────────────
-
-const ruleDeleteCommand = {
-  command:  'delete <id>',
-  describe: 'Delete a routing rule',
-  builder:  (y) => y.positional('id', { type: 'number', describe: 'Rule ID' }),
-  handler:  runCommand(async (argv) => {
-    await requireFeature('enableWorkflowRules', 'Routing Rules');
-    await del(`/Rules/${argv.id}`);
-    console.log(`Rule ${argv.id} deleted.`);
-  }),
-};
+import { get, post, del } from '../api.js';
+import { requireFeature }  from '../subscription.js';
+import { runCommand }      from '../run.js';
+
+export const ruleCommand = {
+  command:  'rule <subcommand>',
+  describe: 'Manage routing rules',
+  builder:  (yargs) =>
+    yargs
+      .command(ruleListCommand)
+      .command(ruleCreateCommand)
+      .command(ruleDeleteCommand)
+      .demandCommand(1, 'Specify a subcommand: list, create, delete'),
+  handler: () => {},
+};
+
+// ── list ───────────────────────────────────────────────────────────────────────
+
+const ruleListCommand = {
+  command:  'list',
+  describe: 'List all routing rules',
+  handler:  runCommand(async () => {
+    await requireFeature('enableWorkflowRules', 'Routing Rules');
+
+    const rules = await get('/Rules/List');
+    if (!rules?.length) { console.log('No routing rules found.'); return; }
+
+    const sorted = [...rules].sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+    const idW    = Math.max(...sorted.map(r => String(r.id).length + 2));
+    const priW   = Math.max('pri'.length, ...sorted.map(r => String(r.priority ?? 0).length));
+    const nameW  = Math.max('name'.length, ...sorted.map(r => (r.name ?? r.trigger ?? '—').length));
+
+    console.log(`\n${'id'.padStart(idW)}  ${'pri'.padEnd(priW)}  ${'name'.padEnd(nameW)}  trigger`);
+    console.log(`${'-'.repeat(idW)}  ${'-'.repeat(priW)}  ${'-'.repeat(nameW)}  -------`);
+    for (const r of sorted) {
+      const id   = `[${r.id}]`.padStart(idW);
+      const pri  = String(r.priority ?? 0).padEnd(priW);
+      const name = (r.name ?? r.trigger ?? '—').padEnd(nameW);
+      console.log(`${id}  ${pri}  ${name}  ${r.trigger ?? '—'}`);
+    }
+    console.log(`\n${sorted.length} rule(s)`);
+  }),
+};
+
+// ── create ─────────────────────────────────────────────────────────────────────
+
+const ruleCreateCommand = {
+  command:  'create',
+  describe: 'Create a routing rule',
+  builder:  (y) =>
+    y
+      .option('name',       { type: 'string', demandOption: true, describe: 'Rule name' })
+      .option('trigger',    { type: 'string', demandOption: true, describe: 'Trigger type (e.g. pageUrl, country)' })
+      .option('value',      { type: 'string', demandOption: true, describe: 'Trigger value to match' })
+      .option('team-id',    { type: 'number', demandOption: true, describe: 'Team ID to route to' })
+      .option('priority',   { type: 'number', default: 0,         describe: 'Rule priority (lower = higher priority)' }),
+
+  handler: runCommand(async (argv) => {
+    await requireFeature('enableWorkflowRules', 'Routing Rules');
+
+    const result = await post('/Rules', {
+      name:      argv.name,
+      trigger:   argv.trigger,
+      value:     argv.value,
+      teamId:    argv['team-id'],
+      priority:  argv.priority,
+      isEnabled: true,
+    });
+
+    console.log(`Rule created: [${result.id}] ${result.name}`);
+  }),
+};
+
+// ── delete ─────────────────────────────────────────────────────────────────────
+
+const ruleDeleteCommand = {
+  command:  'delete <id>',
+  describe: 'Delete a routing rule',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Rule ID' }),
+  handler:  runCommand(async (argv) => {
+    await requireFeature('enableWorkflowRules', 'Routing Rules');
+    await del(`/Rules/${argv.id}`);
+    console.log(`Rule ${argv.id} deleted.`);
+  }),
+};

package/lib/commands/sharepoint.js

@@ -0,0 +1,167 @@
+/**
+ * velaro sharepoint — SharePoint / tracker access commands
+ *
+ *   velaro sharepoint login          One-time device-code auth against nocvelaro M365 tenant
+ *   velaro sharepoint read-tracker   Download + parse the Integrations Status Tracker Excel file
+ *   velaro sharepoint whoami         Show the currently logged-in M365 account
+ */
+
+import { readConfig, writeConfig } from '../config.js';
+import { spRequestDeviceCode, spPollForToken, getSpAccessToken, downloadSharePointFile } from '../sharepoint-auth.js';
+
+// The tracker file. Update the URL here if SharePoint ever moves it.
+const TRACKER_URL = 'https://nocvelaro.sharepoint.com/sites/DevOps/Shared%20Documents/DevOps/Integrations%20and%20Partnerships/Velaro%20Integrations%20Status%20Tracker.xlsx';
+
+// ── login ─────────────────────────────────────────────────────────────────────
+
+const loginCommand = {
+  command:  'login',
+  describe: 'Authenticate with SharePoint (nocvelaro M365 tenant). Run once.',
+  handler: async () => {
+    const deviceData = await spRequestDeviceCode();
+    console.log('\n\x1b[1mSign in to access the Velaro SharePoint tracker\x1b[0m');
+    console.log(`\n  Go to: \x1b[36m${deviceData.verification_uri}\x1b[0m`);
+    console.log(`  Enter code: \x1b[33m${deviceData.user_code}\x1b[0m`);
+    console.log('\nWaiting for sign-in...');
+
+    const tokenData = await spPollForToken(deviceData.device_code, deviceData.interval || 5);
+
+    const sp = {
+      accessToken:  tokenData.access_token,
+      refreshToken: tokenData.refresh_token,
+      expiresAt:    new Date(Date.now() + tokenData.expires_in * 1000).toISOString(),
+    };
+
+    const cfg = readConfig();
+    cfg.sharepoint = sp;
+    writeConfig(cfg);
+
+    // Get display name via Graph
+    try {
+      const meRes = await fetch('https://graph.microsoft.com/v1.0/me', {
+        headers: { Authorization: `Bearer ${tokenData.access_token}` },
+      });
+      const me = await meRes.json();
+      console.log(`\n\x1b[32m✓ Logged in as ${me.displayName} (${me.userPrincipalName})\x1b[0m`);
+    } catch {
+      console.log('\n\x1b[32m✓ SharePoint login saved.\x1b[0m');
+    }
+    console.log('  Run: velaro sharepoint read-tracker\n');
+  },
+};
+
+// ── whoami ────────────────────────────────────────────────────────────────────
+
+const whoamiCommand = {
+  command:  'whoami',
+  describe: 'Show the M365 account currently logged into SharePoint',
+  handler: async () => {
+    const cfg = readConfig();
+    let token;
+    try {
+      const result = await getSpAccessToken(cfg);
+      token = result.accessToken;
+      if (result.refreshed) { cfg.sharepoint = { ...cfg.sharepoint, ...result.refreshed }; writeConfig(cfg); }
+    } catch (e) {
+      console.error(`\x1b[31m✗ ${e.message}\x1b[0m`);
+      process.exit(1);
+    }
+
+    const res = await fetch('https://graph.microsoft.com/v1.0/me', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const me = await res.json();
+    console.log(`\n  \x1b[1m${me.displayName}\x1b[0m  (${me.userPrincipalName})`);
+    console.log(`  Token expires: ${cfg.sharepoint?.expiresAt ?? 'unknown'}\n`);
+  },
+};
+
+// ── read-tracker ──────────────────────────────────────────────────────────────
+
+const readTrackerCommand = {
+  command:  'read-tracker',
+  describe: 'Download and parse the Velaro Integrations Status Tracker spreadsheet',
+  builder:  (y) =>
+    y
+      .option('sheet', { type: 'string', describe: 'Sheet name to show (default: all)' })
+      .option('json',  { type: 'boolean', describe: 'Output raw JSON instead of formatted table' }),
+  handler: async (argv) => {
+    const cfg = readConfig();
+    let accessToken;
+    try {
+      const result = await getSpAccessToken(cfg);
+      accessToken = result.accessToken;
+      if (result.refreshed) { cfg.sharepoint = { ...cfg.sharepoint, ...result.refreshed }; writeConfig(cfg); }
+    } catch (e) {
+      console.error(`\x1b[31m✗ ${e.message}\x1b[0m`);
+      process.exit(1);
+    }
+
+    console.log('Downloading tracker...');
+    let buf;
+    try {
+      buf = await downloadSharePointFile(TRACKER_URL, accessToken);
+    } catch (e) {
+      console.error(`\x1b[31m✗ ${e.message}\x1b[0m`);
+      process.exit(1);
+    }
+
+    // Dynamically import xlsx (ESM-compatible)
+    let XLSX;
+    try {
+      XLSX = (await import('xlsx')).default;
+    } catch {
+      console.error('\x1b[31m✗ xlsx package not installed. Run: npm install xlsx --prefix cli\x1b[0m');
+      process.exit(1);
+    }
+
+    const workbook = XLSX.read(buf, { type: 'buffer', cellDates: true });
+    const targetSheets = argv.sheet
+      ? workbook.SheetNames.filter(n => n.toLowerCase().includes(argv.sheet.toLowerCase()))
+      : workbook.SheetNames;
+
+    if (!targetSheets.length) {
+      console.error(`\x1b[31m✗ No sheet matching "${argv.sheet}". Available: ${workbook.SheetNames.join(', ')}\x1b[0m`);
+      process.exit(1);
+    }
+
+    for (const sheetName of targetSheets) {
+      const ws = workbook.Sheets[sheetName];
+      const rows = XLSX.utils.sheet_to_json(ws, { defval: '' });
+
+      if (argv.json) {
+        console.log(JSON.stringify({ sheet: sheetName, rows }, null, 2));
+        continue;
+      }
+
+      console.log(`\n\x1b[1m━━ ${sheetName} \x1b[0m(${rows.length} rows)\n`);
+      if (!rows.length) { console.log('  (empty)\n'); continue; }
+
+      // Print as simple key: value blocks — avoids terminal width issues with wide tables
+      for (const [i, row] of rows.entries()) {
+        const keys = Object.keys(row).filter(k => row[k] !== '');
+        if (!keys.length) continue;
+        console.log(`  \x1b[36m[${i + 1}]\x1b[0m`);
+        for (const k of keys) {
+          const val = String(row[k]).replace(/\n/g, ' ↵ ').slice(0, 200);
+          console.log(`    \x1b[33m${k}\x1b[0m: ${val}`);
+        }
+        console.log('');
+      }
+    }
+  },
+};
+
+// ── export ────────────────────────────────────────────────────────────────────
+
+export const sharepointCommand = {
+  command:  'sharepoint <subcommand>',
+  describe: 'Access the Velaro SharePoint tracker and M365 files',
+  builder:  (yargs) =>
+    yargs
+      .command(loginCommand)
+      .command(whoamiCommand)
+      .command(readTrackerCommand)
+      .demandCommand(1, 'Specify a subcommand: login, whoami, read-tracker'),
+  handler: () => {},
+};