@velaro/cli 0.7.0 → 1.4.8

package/lib/commands/logs.js

@@ -0,0 +1,680 @@
+import { getCredentials }          from '../api.js';
+import { readConfig, ENVS }        from '../config.js';
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+const RESET = '\x1b[0m';
+const DIM   = '\x1b[2m';
+const RED   = '\x1b[31m';
+const YEL   = '\x1b[33m';
+const CYN   = '\x1b[36m';
+
+function parseDuration(s) {
+  const m = /^(\d+)(m|h|d)$/i.exec(String(s).trim());
+  if (!m) return 2 * 3600 * 1000;
+  const n = parseInt(m[1], 10);
+  if (m[2] === 'm') return n * 60 * 1000;
+  if (m[2] === 'h') return n * 3600 * 1000;
+  return n * 24 * 3600 * 1000;
+}
+
+function printEntry(e) {
+  const ts      = new Date(e.timestamp ?? e.LogTimestamp).toISOString().replace('T', ' ').slice(0, 19);
+  const lvl     = (e.Level ?? e.level ?? '?').padEnd(5);
+  const color   = (e.Level ?? e.level) === 'ERROR' ? RED : (e.Level ?? e.level) === 'WARN' ? YEL : RESET;
+  const tag     = (e.IntegrationTag ?? e.integrationTag) ? ` ${CYN}[${e.IntegrationTag ?? e.integrationTag}]${RESET}` : '';
+  const site    = (e.siteId ?? e.SiteId) ? ` ${DIM}(site ${e.siteId ?? e.SiteId})${RESET}` : '';
+  const logger  = (e.Logger ?? e.logger ?? '').split('.').pop() ?? '';
+  const msg     = e.Message ?? e.message ?? '';
+  console.log(`${DIM}${ts}${RESET} ${color}${lvl}${RESET} ${DIM}${logger}${RESET}${tag}${site}  ${msg}`);
+}
+
+async function getMsgBase(argv) {
+  const cfg = readConfig();
+  const env = argv.env || cfg.env || 'staging';
+  return cfg.envs?.[env]?.messagingApiBase ?? ENVS[env]?.messagingApiBase
+    ?? 'https://velaro-messaging-api-staging.azurewebsites.net';
+}
+
+async function requireAdmin(creds) {
+  if (creds.siteId !== 1032) {
+    console.error('velaro logs is only available to Velaro staff (site 1032).');
+    process.exit(1);
+  }
+}
+
+// ── search handler ────────────────────────────────────────────────────────────
+
+async function searchLogs(argv) {
+  const creds   = await getCredentials();
+  await requireAdmin(creds);
+  const msgBase = await getMsgBase(argv);
+
+  const from = new Date(Date.now() - parseDuration(argv.last ?? '2h'));
+  const params = new URLSearchParams({ from: from.toISOString(), take: String(argv.take ?? 50) });
+  if (argv.query)       params.set('q',           argv.query);
+  if (argv.level)       params.set('level',        argv.level.toUpperCase());
+  if (argv.integration) params.set('integration',  argv.integration);
+  if (argv.site)        params.set('siteId',        String(argv.site));
+  if (argv.source)      params.set('source',        argv.source);
+  if (argv.regex)       params.set('regex',         'true');
+
+  const res = await fetch(`${msgBase}/superadmin/logs/search?${params}`, {
+    headers: {
+      Authorization:       `Bearer ${creds.velaroToken}`,
+      'X-Internal-SiteId': String(creds.siteId),
+    },
+    signal: AbortSignal.timeout(20000),
+  });
+
+  if (!res.ok) {
+    console.error(`HTTP ${res.status}: ${await res.text().catch(() => '')}`);
+    process.exit(1);
+  }
+
+  const entries = await res.json();
+  if (!Array.isArray(entries) || !entries.length) {
+    console.log('No results.');
+    return;
+  }
+
+  console.log(`\n${DIM}${entries.length} result(s) from ${from.toISOString().slice(0, 16)} UTC${RESET}\n`);
+  for (const e of entries) printEntry(e);
+  console.log('');
+}
+
+// ── tail handler (SSE stream) ─────────────────────────────────────────────────
+
+async function tailLogs(argv) {
+  const creds   = await getCredentials();
+  await requireAdmin(creds);
+  const msgBase = await getMsgBase(argv);
+
+  const url = new URL(`${msgBase}/superadmin/logs/stream`);
+  if (argv.level)       url.searchParams.set('level',       argv.level.toUpperCase());
+  if (argv.integration) url.searchParams.set('integration', argv.integration);
+  if (argv.site)        url.searchParams.set('siteId',      String(argv.site));
+  if (argv.source)      url.searchParams.set('source',      argv.source);
+
+  const envLabel = argv.env || readConfig().env || 'staging';
+  console.log(`\n${DIM}Streaming from ${envLabel} — Ctrl+C to stop${RESET}\n`);
+
+  const res = await fetch(url.toString(), {
+    headers: {
+      Authorization:       `Bearer ${creds.velaroToken}`,
+      'X-Internal-SiteId': String(creds.siteId),
+    },
+    signal: AbortSignal.timeout(660_000),
+  });
+
+  if (!res.ok) {
+    console.error(`HTTP ${res.status}: could not connect to log stream`);
+    process.exit(1);
+  }
+
+  const decoder = new TextDecoder();
+  for await (const chunk of res.body) {
+    const text = decoder.decode(chunk, { stream: true });
+    for (const line of text.split('\n')) {
+      if (!line.startsWith('data: ')) continue;
+      const json = line.slice(6).trim();
+      if (!json || json.startsWith('{"status"')) continue;
+      try { printEntry(JSON.parse(json)); } catch { /* malformed line */ }
+    }
+  }
+}
+
+// ── digest-recipients handlers ────────────────────────────────────────────────
+
+async function getAdminBase(argv) {
+  const cfg = readConfig();
+  const env = argv.env || cfg.env || 'staging';
+  return cfg.envs?.[env]?.adminApiBase ?? ENVS[env]?.adminApiBase
+    ?? 'https://velaro-admin-staging.azurewebsites.net';
+}
+
+async function getDigestRecipients(argv) {
+  const creds    = await getCredentials();
+  await requireAdmin(creds);
+  const adminBase = await getAdminBase(argv);
+
+  const res = await fetch(`${adminBase}/superadmin/logs/digest-recipients`, {
+    headers: {
+      Authorization:       `Bearer ${creds.velaroToken}`,
+      'X-Internal-SiteId': String(creds.siteId),
+    },
+    signal: AbortSignal.timeout(15000),
+  });
+
+  if (!res.ok) {
+    console.error(`HTTP ${res.status}: ${await res.text().catch(() => '')}`);
+    process.exit(1);
+  }
+
+  const data = await res.json();
+  console.log(`\nLog digest recipients: ${data.recipients}`);
+  console.log(`\nTo persist changes: set LOG_DIGEST_RECIPIENTS in Azure App Settings.`);
+  console.log(`Digest job runs every 4h (Hangfire job: log-digest-4h, queue: low).\n`);
+}
+
+async function setDigestRecipients(argv) {
+  const creds    = await getCredentials();
+  await requireAdmin(creds);
+  const adminBase = await getAdminBase(argv);
+
+  if (!argv.emails) {
+    console.error('--emails is required. Example: velaro logs set-digest-recipients --emails "noc@velaro.com;alex@velaro.com"');
+    process.exit(1);
+  }
+
+  const res = await fetch(`${adminBase}/superadmin/logs/digest-recipients`, {
+    method:  'POST',
+    headers: {
+      Authorization:       `Bearer ${creds.velaroToken}`,
+      'X-Internal-SiteId': String(creds.siteId),
+      'Content-Type':      'application/json',
+    },
+    body:   JSON.stringify({ recipients: argv.emails }),
+    signal: AbortSignal.timeout(15000),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    console.error(`HTTP ${res.status}: ${body}`);
+    process.exit(1);
+  }
+
+  const data = await res.json();
+  console.log(`\n✓ Recipients validated: ${data.recipients}`);
+  console.log(`Note: ${data.note}\n`);
+}
+
+// ── diagnose handler ──────────────────────────────────────────────────────────
+
+async function diagnoseLogs(argv) {
+  const creds   = await getCredentials();
+  await requireAdmin(creds);
+  const msgBase = await getMsgBase(argv);
+  const window  = argv.last ?? '1h';
+  const from    = new Date(Date.now() - parseDuration(window));
+
+  const BOLD = '\x1b[1m'; const RESET2 = '\x1b[0m'; const GREEN = '\x1b[32m';
+
+  console.log(`\n${BOLD}── Bot Diagnostic — last ${window} ──────────────────────────────${RESET2}`);
+
+  // Run error search and perf/routing search in parallel
+  async function search(q) {
+    const p = new URLSearchParams({ q, from: from.toISOString(), take: '50' });
+    const r = await fetch(`${msgBase}/superadmin/logs/search?${p}`, {
+      headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
+      signal: AbortSignal.timeout(15000),
+    });
+    if (!r.ok) return [];
+    const d = await r.json();
+    return Array.isArray(d) ? d : [];
+  }
+
+  const [errors, perfAndRouting] = await Promise.all([
+    search('level:ERROR'),
+    search('WF-AI-ROUTE OR PERF-SLOW'),
+  ]);
+
+  // ── Errors ──
+  console.log(`\n${BOLD}Errors${RESET2}`);
+  if (!errors.length) {
+    console.log(`  ${GREEN}✓${RESET2}  No errors`);
+  } else {
+    for (const e of errors) printEntry(e);
+  }
+
+  // ── Perf ──
+  const perfEntries   = perfAndRouting.filter(e => (e.Message ?? e.message ?? '').includes('PERF-SLOW'));
+  const routeEntries  = perfAndRouting.filter(e => (e.Message ?? e.message ?? '').includes('WF-AI-ROUTE'));
+
+  console.log(`\n${BOLD}Perf  [WF-PERF-SLOW] [AI-PERF-SLOW]${RESET2}`);
+  if (!perfEntries.length) {
+    console.log(`  ${GREEN}✓${RESET2}  No slow responses`);
+  } else {
+    for (const e of perfEntries) printEntry(e);
+  }
+
+  // ── AI Routing ──
+  console.log(`\n${BOLD}AI Intent Routing  [WF-AI-ROUTE]${RESET2}`);
+  if (!routeEntries.length) {
+    console.log(`  ${GREEN}✓${RESET2}  No AI routing events`);
+  } else {
+    const matched  = routeEntries.filter(e => (e.Message ?? e.message ?? '').includes('AI matched'));
+    const timeouts = routeEntries.filter(e => (e.Message ?? e.message ?? '').includes('timed out'));
+    const failed   = routeEntries.filter(e => (e.Message ?? e.message ?? '').includes('failed'));
+    console.log(`  Matched: ${matched.length}  Timeouts: ${timeouts.length}  Errors: ${failed.length}`);
+    for (const e of routeEntries.slice(0, 10)) printEntry(e);
+    if (routeEntries.length > 10) console.log(`  ... and ${routeEntries.length - 10} more`);
+  }
+
+  // ── Summary ──
+  const status = errors.length   ? '\x1b[31m⚠ ERRORS FOUND\x1b[0m'
+    : perfEntries.length         ? '\x1b[33m⚠ SLOW RESPONSES\x1b[0m'
+    : routeEntries.length        ? '\x1b[36m🤖 AI ROUTING ACTIVE\x1b[0m'
+    : `${GREEN}✅ ALL CLEAR\x1b[0m`;
+  console.log(`\n${BOLD}Summary:${RESET2} ${status}  (${errors.length} errors, ${perfEntries.length} slow, ${routeEntries.length} ai-routes)\n`);
+  console.log(`Velaro Logger presaved filter: "AI Intent Routing + Perf"\n`);
+}
+
+// ── alert rule helpers ───────────────────────────────────────────────────────
+
+const ALERT_RULE_DEFAULTS = {
+  windowMinutes:    5,
+  thresholdCount:   1,
+  minRefireMinutes: 60,
+};
+
+// Strips ANSI/control characters from AI-generated text before it ever reaches
+// the terminal (not just the copy-pasteable command line below) — an AI
+// suggestion is untrusted text and should never be able to inject escape
+// sequences into the user's terminal.
+function sanitizeForTerminal(s) {
+  if (typeof s !== 'string') return s;
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
+}
+
+// POSIX-safe single-quote wrapping for interpolating untrusted values into a
+// printed shell command line (standard 'wrap, escape embedded quotes' trick).
+function shellQuote(value) {
+  const s = String(value ?? '');
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+// Validates a value is meant to be a positive (>=1) finite integer for a
+// numeric alert-rule flag. Returns the parsed integer, or null if invalid.
+// `argv[flag]` from yargs with `type: 'number'` is already a number (or NaN
+// if the user passed something non-numeric like `--threshold abc`), but we
+// re-parse defensively since a flag can also arrive as a string in some
+// invocation paths.
+function parsePositiveIntFlag(flagName, rawValue, { max } = {}) {
+  if (rawValue === undefined || rawValue === null) return { ok: true, value: undefined };
+  const n = typeof rawValue === 'number' ? rawValue : Number(rawValue);
+  if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1) {
+    return { ok: false, error: `--${flagName} must be a whole number >= 1 (got ${JSON.stringify(rawValue)}).` };
+  }
+  if (max !== undefined && n > max) {
+    return { ok: false, error: `--${flagName} must be <= ${max} (got ${n}).` };
+  }
+  return { ok: true, value: n };
+}
+
+// A rule with none of the four notification channels fires into the void —
+// it's pure log noise that pages no one. Mirrors the same guard in
+// client/src/pages/Messaging/Integrations/AlertRules.tsx (extended here to
+// also cover webhook, which that component's check omits).
+function hasAnyRecipient({ emails, sms, webhook, mobileUserIds }) {
+  return Boolean(
+    (emails && String(emails).trim()) ||
+    (sms && String(sms).trim()) ||
+    (webhook && String(webhook).trim()) ||
+    (mobileUserIds && String(mobileUserIds).trim())
+  );
+}
+
+function printAlertRule(r) {
+  const state = r.enabled === false ? `${DIM}paused${RESET}` : `${CYN}active${RESET}`;
+  const bits = [`>=${r.thresholdCount} in ${r.windowMinutes}m`];
+  if (r.level)       bits.push(`level=${r.level}`);
+  if (r.queryText)   bits.push(`q="${r.queryText}"`);
+  if (r.integration) bits.push(`tag=${r.integration}`);
+  if (r.siteId)      bits.push(`site=${r.siteId}`);
+  if (r.notifyPhoneNumbers)  bits.push('SMS');
+  if (r.notifyEmails)        bits.push('email');
+  if (r.notifyWebhookUrl)    bits.push('webhook');
+  if (r.notifyMobileUserIds) bits.push('mobile push');
+  bits.push(`cooldown ${r.minRefireMinutes}m`);
+  console.log(`${DIM}[${r.id}]${RESET} ${r.name}  ${state}`);
+  console.log(`    ${bits.join('  ')}`);
+}
+
+async function listAlertRules(argv) {
+  const creds   = await getCredentials();
+  await requireAdmin(creds);
+  const msgBase = await getMsgBase(argv);
+
+  const res = await fetch(`${msgBase}/superadmin/log-alerts/rules`, {
+    headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
+    signal: AbortSignal.timeout(15000),
+  });
+  if (!res.ok) {
+    console.error(`HTTP ${res.status}: ${await res.text().catch(() => '')}`);
+    process.exit(1);
+  }
+  const rules = await res.json();
+  if (!Array.isArray(rules) || !rules.length) {
+    console.log('No alert rules yet. Create one with: velaro logs alerts create --name "..." --query "..."');
+    return;
+  }
+  console.log(`\n${DIM}${rules.length} alert rule(s)${RESET}\n`);
+  for (const r of rules) printAlertRule(r);
+  console.log('');
+}
+
+async function suggestAlertRule(argv) {
+  const creds   = await getCredentials();
+  await requireAdmin(creds);
+  const msgBase = await getMsgBase(argv);
+
+  if (!argv.description) {
+    console.error('--description is required. Example: velaro logs alerts suggest --description "text me if NetSuite errors 3+ times in 10 min"');
+    process.exit(1);
+  }
+
+  const res = await fetch(`${msgBase}/superadmin/log-alerts/suggest`, {
+    method:  'POST',
+    headers: {
+      Authorization:       `Bearer ${creds.velaroToken}`,
+      'X-Internal-SiteId': String(creds.siteId),
+      'Content-Type':      'application/json',
+    },
+    body:   JSON.stringify({ description: argv.description }),
+    signal: AbortSignal.timeout(30000),
+  });
+
+  if (!res.ok) {
+    console.error(`HTTP ${res.status}: ${await res.text().catch(() => '')}`);
+    process.exit(1);
+  }
+
+  const data = await res.json();
+  if (data.error) {
+    console.error(`Could not generate a suggestion: ${sanitizeForTerminal(String(data.error))}`);
+    console.log('You can still create a rule manually with: velaro logs alerts create --name "..." --query "..."');
+    process.exit(1);
+  }
+
+  // Every AI-generated field is untrusted text — strip control/ANSI escapes
+  // before it ever reaches the terminal, not just in the copy-paste line below.
+  const name       = sanitizeForTerminal(data.name ?? '');
+  const queryText  = sanitizeForTerminal(data.queryText ?? '');
+  const level      = sanitizeForTerminal(data.level ?? '');
+  const integration = sanitizeForTerminal(data.integration ?? '');
+  const reasoning  = data.reasoning ? sanitizeForTerminal(String(data.reasoning)) : null;
+  const windowMinutes    = data.windowMinutes    ?? ALERT_RULE_DEFAULTS.windowMinutes;
+  const thresholdCount   = data.thresholdCount   ?? ALERT_RULE_DEFAULTS.thresholdCount;
+  const minRefireMinutes = data.minRefireMinutes ?? ALERT_RULE_DEFAULTS.minRefireMinutes;
+
+  console.log(`\n${DIM}Suggested rule (preview only — not created; pass to 'create' to save):${RESET}\n`);
+  console.log(`  name:              ${name}`);
+  console.log(`  queryText:         ${queryText}`);
+  console.log(`  level:             ${level || '(any)'}`);
+  console.log(`  integration:       ${integration || '(any)'}`);
+  console.log(`  windowMinutes:     ${windowMinutes}`);
+  console.log(`  thresholdCount:    ${thresholdCount}`);
+  console.log(`  minRefireMinutes:  ${minRefireMinutes}`);
+  if (reasoning) console.log(`\n${DIM}Why:${RESET} ${reasoning}`);
+  console.log(`\nNote: this suggestion has no notification channels — add --emails/--sms/--webhook when you create it, or the rule will fire into the void.`);
+  console.log(`\nTo create it:\n  velaro logs alerts create --name ${shellQuote(name)} --query ${shellQuote(queryText)}${level ? ` --level ${shellQuote(level)}` : ''} --window-minutes ${windowMinutes} --threshold ${thresholdCount} --cooldown-minutes ${minRefireMinutes} --emails "..." --yes\n`);
+}
+
+async function createAlertRule(argv) {
+  const creds   = await getCredentials();
+  await requireAdmin(creds);
+  const msgBase = await getMsgBase(argv);
+
+  if (!argv.name || !argv.query) {
+    console.error('--name and --query are required. Example: velaro logs alerts create --name "NetSuite errors" --query "exception"');
+    process.exit(1);
+  }
+
+  // HIGH: LogAlertDecisionEngine evaluates `count >= effectiveThreshold`, so a
+  // threshold of 0 (or negative, or NaN from a bad --threshold value) fires on
+  // every single evaluation tick — a permanently-firing, unresolvable alert.
+  // The backend's CreateRule endpoint (unlike UpdateRule/PatchRuleByName) does
+  // not clamp this, so the CLI must validate before sending the request.
+  const checks = [
+    parsePositiveIntFlag('threshold',        argv.threshold),
+    parsePositiveIntFlag('window-minutes',   argv.windowMinutes, { max: 1440 }),
+    parsePositiveIntFlag('cooldown-minutes', argv.cooldownMinutes),
+  ];
+  const failed = checks.find(c => !c.ok);
+  if (failed) {
+    console.error(failed.error);
+    process.exit(1);
+  }
+  const [thresholdCheck, windowCheck, cooldownCheck] = checks;
+
+  // HIGH: a rule with zero notification channels fires into the void.
+  if (!hasAnyRecipient({ emails: argv.emails, sms: argv.sms, webhook: argv.webhook, mobileUserIds: argv.mobileUserIds })
+      && !argv.noRecipientsOk) {
+    console.error('No notification channel given (--emails, --sms, --webhook, or --mobile-user-ids) — this rule would fire but notify no one.');
+    console.error('If that\'s intentional (e.g. you only want it visible in Alert History), pass --no-recipients-ok to proceed anyway.');
+    process.exit(1);
+  }
+
+  const body = {
+    name:                 argv.name,
+    queryText:            argv.query,
+    level:                argv.level ? argv.level.toUpperCase() : undefined,
+    integration:          argv.integration,
+    windowMinutes:        windowCheck.value   ?? ALERT_RULE_DEFAULTS.windowMinutes,
+    thresholdCount:       thresholdCheck.value ?? ALERT_RULE_DEFAULTS.thresholdCount,
+    minRefireMinutes:     cooldownCheck.value ?? ALERT_RULE_DEFAULTS.minRefireMinutes,
+    notifyEmails:         argv.emails,
+    notifyPhoneNumbers:   argv.sms,
+    notifyWebhookUrl:     argv.webhook,
+    notifyMobileUserIds:  argv.mobileUserIds,
+    enabled:              true,
+  };
+
+  // HIGH: create is a real, live write with no undo from the CLI — preview
+  // before sending, require --yes to actually proceed. Mirrors the
+  // `kb swap-connection` confirmation pattern in cli/lib/commands/kb.js.
+  if (!argv.yes) {
+    console.log(`\n${DIM}About to create this alert rule (dry run — nothing sent yet):${RESET}\n`);
+    printAlertRule({ ...body, id: '(new)' });
+    console.log(`\nRe-run with --yes to actually create it.\n`);
+    return;
+  }
+
+  const res = await fetch(`${msgBase}/superadmin/log-alerts/rules`, {
+    method:  'POST',
+    headers: {
+      Authorization:       `Bearer ${creds.velaroToken}`,
+      'X-Internal-SiteId': String(creds.siteId),
+      'Content-Type':      'application/json',
+    },
+    body:   JSON.stringify(body),
+    signal: AbortSignal.timeout(15000),
+  });
+
+  if (!res.ok) {
+    console.error(`HTTP ${res.status}: ${await res.text().catch(() => '')}`);
+    process.exit(1);
+  }
+
+  const data = await res.json();
+  console.log(`\n${CYN}✓${RESET} Created rule [${data.id}] "${data.name}"\n`);
+  printAlertRule(data);
+  console.log('');
+}
+
+async function toggleAlertRule(argv) {
+  const creds   = await getCredentials();
+  await requireAdmin(creds);
+  const msgBase = await getMsgBase(argv);
+
+  if (!argv.id) {
+    console.error('Rule id is required. Example: velaro logs alerts toggle 42');
+    process.exit(1);
+  }
+
+  const res = await fetch(`${msgBase}/superadmin/log-alerts/rules/${argv.id}/toggle`, {
+    method:  'POST',
+    headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
+    signal: AbortSignal.timeout(15000),
+  });
+  if (!res.ok) {
+    console.error(`HTTP ${res.status}: ${await res.text().catch(() => '')}`);
+    process.exit(1);
+  }
+  const data = await res.json();
+  console.log(`Rule ${argv.id} is now ${data.enabled ? 'active' : 'paused'}.`);
+}
+
+async function deleteAlertRule(argv) {
+  const creds   = await getCredentials();
+  await requireAdmin(creds);
+  const msgBase = await getMsgBase(argv);
+
+  if (!argv.id) {
+    console.error('Rule id is required. Example: velaro logs alerts delete 42');
+    process.exit(1);
+  }
+
+  // HIGH: delete is a real, live, irreversible write — fetch and print the
+  // rule being deleted (name, query, recipients) before doing anything.
+  // There's no single-rule GET endpoint, so pull the list and find it there.
+  const listRes = await fetch(`${msgBase}/superadmin/log-alerts/rules`, {
+    headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
+    signal: AbortSignal.timeout(15000),
+  });
+  let target = null;
+  if (listRes.ok) {
+    const rules = await listRes.json().catch(() => []);
+    target = Array.isArray(rules) ? rules.find(r => String(r.id) === String(argv.id)) : null;
+  }
+
+  if (target) {
+    console.log(`\n${DIM}About to delete this alert rule:${RESET}\n`);
+    printAlertRule(target);
+  } else {
+    console.log(`\n${YEL}Could not fetch rule ${argv.id} to preview it (it may already be gone) — proceeding on id alone.${RESET}`);
+  }
+
+  if (!argv.yes) {
+    console.log(`\nRe-run with --yes to actually delete it.\n`);
+    return;
+  }
+
+  const res = await fetch(`${msgBase}/superadmin/log-alerts/rules/${argv.id}`, {
+    method:  'DELETE',
+    headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
+    signal: AbortSignal.timeout(15000),
+  });
+  if (!res.ok) {
+    console.error(`HTTP ${res.status}: ${await res.text().catch(() => '')}`);
+    process.exit(1);
+  }
+  console.log(`\nDeleted rule ${argv.id}.\n`);
+}
+
+// ── command export ────────────────────────────────────────────────────────────
+
+export const logsCommand = {
+  command:  'logs <subcommand>',
+  describe: 'Search and stream Velaro Logger (Velaro staff only)',
+  builder: yargs => yargs
+    .command({
+      command:  'search [query]',
+      describe: 'Search application logs',
+      builder:  y => y
+        .positional('query', { describe: 'Text to search for (or regex with --regex)', type: 'string' })
+        .option('level',       { describe: 'Filter by level: ERROR, WARN, INFO, DEBUG', type: 'string' })
+        .option('integration', { describe: 'Integration tag (HubSpot, NetSuite, [Skill], etc.)', type: 'string' })
+        .option('site',        { describe: 'Filter by site ID', type: 'number' })
+        .option('source',      { describe: 'App source (velaro-messaging-Staging, etc.)', type: 'string' })
+        .option('last',        { describe: 'Time window: 30m, 2h, 1d', default: '2h', type: 'string' })
+        .option('regex',       { describe: 'Treat query as regex', boolean: true, default: false })
+        .option('take',        { describe: 'Max results (max 500)', default: 50, type: 'number' })
+        .option('env',         { describe: 'staging or prod', type: 'string' }),
+      handler: searchLogs,
+    })
+    .command({
+      command:  'tail',
+      describe: 'Stream new log entries in real-time via SSE',
+      builder:  y => y
+        .option('level',       { describe: 'Filter by level: ERROR, WARN, INFO, DEBUG', type: 'string' })
+        .option('integration', { describe: 'Integration tag', type: 'string' })
+        .option('site',        { describe: 'Filter by site ID', type: 'number' })
+        .option('source',      { describe: 'App source', type: 'string' })
+        .option('env',         { describe: 'staging or prod', type: 'string' }),
+      handler: tailLogs,
+    })
+    .command({
+      command:  'digest-recipients',
+      describe: 'Show current log digest email recipients (Velaro staff only)',
+      builder:  y => y
+        .option('env', { describe: 'staging or prod', type: 'string' }),
+      handler: getDigestRecipients,
+    })
+    .command({
+      command:  'set-digest-recipients',
+      describe: 'Update log digest email recipients (Velaro staff only)',
+      builder:  y => y
+        .option('emails', { describe: 'Semicolon-separated email list, e.g. "noc@velaro.com;alex@velaro.com"', type: 'string', demandOption: true })
+        .option('env',    { describe: 'staging or prod', type: 'string' }),
+      handler: setDigestRecipients,
+    })
+    .command({
+      command:  'diagnose',
+      describe: 'Run combined bot diagnostic: errors + [WF-PERF-SLOW] + [AI-PERF-SLOW] + [WF-AI-ROUTE]',
+      builder:  y => y
+        .option('last', { describe: 'Time window: 30m, 1h, 2h, 1d', default: '1h', type: 'string' })
+        .option('env',  { describe: 'staging or prod', type: 'string' }),
+      handler: diagnoseLogs,
+    })
+    .command({
+      command:  'alerts <subcommand>',
+      describe: 'Manage Velaro Logger alert rules (Velaro staff only)',
+      builder:  y => y
+        .command({
+          command:  'list',
+          describe: 'List current alert rules',
+          builder:  yy => yy.option('env', { describe: 'staging or prod', type: 'string' }),
+          handler:  listAlertRules,
+        })
+        .command({
+          command:  'suggest',
+          describe: 'Preview an AI-suggested rule config from a plain-English description (does not create it)',
+          builder:  yy => yy
+            .option('description', { describe: 'Plain-English description of what to alert on', type: 'string', demandOption: true })
+            .option('env',         { describe: 'staging or prod', type: 'string' }),
+          handler:  suggestAlertRule,
+        })
+        .command({
+          command:  'create',
+          describe: 'Create a new alert rule',
+          builder:  yy => yy
+            .option('name',             { describe: 'Rule name', type: 'string', demandOption: true })
+            .option('query',            { describe: 'Message-contains text to match', type: 'string', demandOption: true })
+            .option('level',            { describe: 'ERROR, WARN, INFO, or DEBUG', type: 'string' })
+            .option('integration',      { describe: 'Integration tag to match', type: 'string' })
+            .option('window-minutes',   { describe: 'Rolling window in minutes', type: 'number' })
+            .option('threshold',        { describe: 'Fire when count >= this within the window', type: 'number' })
+            .option('cooldown-minutes', { describe: 'Minimum minutes between re-fires', type: 'number' })
+            .option('emails',           { describe: 'Comma-separated notification email addresses', type: 'string' })
+            .option('sms',              { describe: 'Comma-separated E.164 phone numbers for SMS', type: 'string' })
+            .option('webhook',          { describe: 'Webhook URL (Slack/Teams) to POST on fire', type: 'string' })
+            .option('mobile-user-ids',  { describe: 'Comma-separated Velaro workspace user IDs for mobile push', type: 'string' })
+            .option('no-recipients-ok', { describe: 'Allow creating a rule with zero notification channels (visible in Alert History only)', type: 'boolean', default: false })
+            .option('yes',              { describe: 'Skip the dry-run preview and actually create the rule', type: 'boolean', default: false })
+            .option('env',              { describe: 'staging or prod', type: 'string' }),
+          handler:  createAlertRule,
+        })
+        .command({
+          command:  'toggle <id>',
+          describe: 'Enable/pause an alert rule',
+          builder:  yy => yy
+            .positional('id', { describe: 'Rule id', type: 'number' })
+            .option('env', { describe: 'staging or prod', type: 'string' }),
+          handler:  toggleAlertRule,
+        })
+        .command({
+          command:  'delete <id>',
+          describe: 'Delete an alert rule',
+          builder:  yy => yy
+            .positional('id', { describe: 'Rule id', type: 'number' })
+            .option('yes', { describe: 'Skip the confirmation preview and actually delete', type: 'boolean', default: false })
+            .option('env', { describe: 'staging or prod', type: 'string' }),
+          handler:  deleteAlertRule,
+        })
+        .demandCommand(1, 'Specify a subcommand: list, suggest, create, toggle, or delete'),
+    })
+    .demandCommand(1, 'Specify a subcommand: search, tail, diagnose, digest-recipients, set-digest-recipients, or alerts'),
+};