@velaro/cli 1.4.102 → 1.4.103

package/lib/commands/logs.js

@@ -1,5 +1,6 @@
 import { getCredentials }          from '../api.js';
 import { readConfig, ENVS }        from '../config.js';
+import { logsInsightsCommand }  from './logs-insights.js';
 import { completeLogSearch, describeCompleteness, describeRawMeta, fetchJsonRetry } from '../log-search.js';
 
 // ── helpers ──────────────────────────────────────────────────────────────────
@@ -64,6 +65,10 @@ async function searchLogsInner(argv) {
   const creds   = await getCredentials();
   await requireAdmin(creds);
   const msgBase = await getMsgBase(argv);
+  // Always say WHICH environment is searched. The CLI defaults to prod, and a staging problem searched
+  // there looks identical to "nothing was logged" (cost days on 2026-10-21).
+  const searchedEnv = /staging|stg/i.test(msgBase) ? 'staging' : 'prod';
+  console.log(`${DIM}environment: ${searchedEnv} (${msgBase})${searchedEnv === 'prod' ? ' - add --env staging for staging logs' : ''}${RESET}`);
 
   const to   = argv.to   ? new Date(argv.to)   : new Date();
   const from = argv.from ? new Date(argv.from) : new Date(to.getTime() - parseDuration(argv.last ?? '2h'));
@@ -112,7 +117,10 @@ async function searchLogsInner(argv) {
     wanted: argv.take ?? 50,
   });
   console.log(`${result.complete ? DIM : YEL}${describeCompleteness(result)}${RESET}`);
-  if (!result.entries.length) { console.log('No results.'); return; }
+  if (!result.entries.length) {
+    console.log(searchedEnv === 'prod' ? 'No results in PROD. If you meant staging, re-run with --env staging.' : 'No results.');
+    return;
+  }
   const shown = result.entries.slice(0, argv.take ?? 50);
   console.log(`\n${DIM}showing ${shown.length} of ${result.entries.length} (newest first) from ${from.toISOString().slice(0, 16)} UTC${RESET}\n`);
   for (const e of shown) printEntry(e);
@@ -343,20 +351,53 @@ function parsePositiveIntFlag(flagName, rawValue, { max } = {}) {
   return { ok: true, value: n };
 }
 
-// A rule with none of the four notification channels fires into the void —
+// A rule with none of the five 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/teams, which that component's check omits).
+// NOTE: a blank emails/sms does NOT necessarily mean "no one" any more --
+// LogAlertEvaluationService.ResolveRecipients falls back to global-default
+// AlertContacts when a rule leaves those blank. Callers should pass
+// hasGlobalDefaultContacts (from fetchHasGlobalDefaultContacts) so a blank
+// emails/sms isn't wrongly flagged as "fires into the void" when defaults
+// actually cover it.
+function hasAnyRecipient({ emails, sms, webhook, teams, mobileUserIds, hasGlobalDefaultContacts }) {
 // also cover webhook, which that component's check omits).
 function hasAnyRecipient({ emails, sms, webhook, mobileUserIds, teams }) {
   return Boolean(
     (emails && String(emails).trim()) ||
     (sms && String(sms).trim()) ||
     (webhook && String(webhook).trim()) ||
+    teams ||
+    (mobileUserIds && String(mobileUserIds).trim()) ||
+    // Blank emails AND blank sms both fall back to global defaults together (see
+    // ResolveRecipients) -- if there's at least one global-default contact with a phone or
+    // email, a rule with both blank is NOT actually silent, even though neither field is set.
+    ((!emails || !String(emails).trim()) && (!sms || !String(sms).trim()) && hasGlobalDefaultContacts)
     (mobileUserIds && String(mobileUserIds).trim()) ||
     teams
   );
 }
 
+// Fetches whether at least one global-default AlertContact exists with a phone or email --
+// used only to soften the "fires into the void" guard above, never cached across CLI
+// invocations, so a stale answer can't cause a false pass. Returns false (fail toward the
+// stricter behavior) on any fetch error rather than silently skipping the guard.
+async function fetchHasGlobalDefaultContacts(creds, msgBase) {
+  try {
+    const res = await fetch(`${msgBase}/superadmin/log-alerts/contacts`, {
+      headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
+      signal: AbortSignal.timeout(15000),
+    });
+    if (!res.ok) return false;
+    const contacts = await res.json();
+    return Array.isArray(contacts) && contacts.some(c =>
+      c.isGlobalDefault && ((c.phoneNumber && c.phoneNumber.trim()) || (c.email && c.email.trim())));
+  } catch {
+    return false;
+  }
+}
+
 function printAlertRule(r) {
   const state = r.enabled === false ? `${DIM}paused${RESET}` : `${CYN}active${RESET}`;
   const bits = [`>=${r.thresholdCount} in ${r.windowMinutes}m`];
@@ -365,9 +406,12 @@ function printAlertRule(r) {
   if (r.integration) bits.push(`tag=${r.integration}`);
   if (r.siteId)      bits.push(`site=${r.siteId}`);
   if (r.notifyPhoneNumbers)  bits.push('SMS');
+  else if (!r.notifyEmails)  bits.push('SMS+email (global defaults)');
   if (r.notifyEmails)        bits.push('email');
   if (r.notifyWebhookUrl)    bits.push('webhook');
+  if (r.notifyTeams)         bits.push('Teams');
   if (r.notifyMobileUserIds) bits.push('mobile push');
+  if (r.excludeContactNames) bits.push(`excl:${r.excludeContactNames}`);
   if (r.notifyTeams)         bits.push('Teams');
   bits.push(`cooldown ${r.minRefireMinutes}m`);
   console.log(`${DIM}[${r.id}]${RESET} ${r.name}  ${state}`);
@@ -481,11 +525,19 @@ async function createAlertRule(argv) {
   }
   const [thresholdCheck, windowCheck, cooldownCheck] = checks;
 
+  // HIGH: a rule with zero notification channels fires into the void. A blank --emails/--sms
+  // may still be covered by global-default AlertContacts (see hasAnyRecipient docs), so check
+  // those before failing.
+  const hasDefaults = await fetchHasGlobalDefaultContacts(creds, msgBase);
+  if (!hasAnyRecipient({ emails: argv.emails, sms: argv.sms, webhook: argv.webhook, teams: argv.teams, mobileUserIds: argv.mobileUserIds, hasGlobalDefaultContacts: hasDefaults })
+      && !argv.noRecipientsOk) {
+    console.error('No notification channel given (--emails, --sms, --webhook, --teams, or --mobile-user-ids), and no global-default contact exists to fall back to — this rule would fire but notify no one.');
   // 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, teams: argv.teams })
       && !argv.noRecipientsOk) {
     console.error('No notification channel given (--emails, --sms, --webhook, --teams, 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.');
+    console.error('To set up global defaults so a blank --emails/--sms is covered automatically: velaro logs contacts add --name alex --phone +1... --email alex@velaro.com --global');
     process.exit(1);
   }
 
@@ -500,7 +552,9 @@ async function createAlertRule(argv) {
     notifyEmails:         argv.emails,
     notifyPhoneNumbers:   argv.sms,
     notifyWebhookUrl:     argv.webhook,
+    notifyTeams:          Boolean(argv.teams),
     notifyMobileUserIds:  argv.mobileUserIds,
+    excludeContactNames:  argv.excludeContacts,
     notifyTeams:          Boolean(argv.teams),
     enabled:              true,
   };
@@ -590,7 +644,9 @@ async function updateAlertRule(argv) {
     notifyEmails:        argv.emails            ?? target.notifyEmails,
     notifyPhoneNumbers:  argv.sms               ?? target.notifyPhoneNumbers,
     notifyWebhookUrl:    argv.webhook           ?? target.notifyWebhookUrl,
+    notifyTeams:         argv.teams !== undefined ? Boolean(argv.teams) : target.notifyTeams,
     notifyMobileUserIds: argv.mobileUserIds     ?? target.notifyMobileUserIds,
+    excludeContactNames: argv.excludeContacts   ?? target.excludeContactNames,
     notifyTeams:         argv.teams !== undefined ? Boolean(argv.teams) : Boolean(target.notifyTeams),
     enabled:             argv.enabled !== undefined ? argv.enabled : target.enabled,
   };
@@ -598,6 +654,10 @@ async function updateAlertRule(argv) {
   // HIGH: same "fires into the void" guard as create -- an update that strips
   // every notification channel (or a rule that already had none, being
   // re-enabled without adding one) silently produces an alert nobody sees.
+  const hasDefaults = await fetchHasGlobalDefaultContacts(creds, msgBase);
+  if (!hasAnyRecipient({ emails: body.notifyEmails, sms: body.notifyPhoneNumbers, webhook: body.notifyWebhookUrl, teams: body.notifyTeams, mobileUserIds: body.notifyMobileUserIds, hasGlobalDefaultContacts: hasDefaults })
+      && !argv.noRecipientsOk) {
+    console.error('This update would leave the rule with no notification channel (--emails, --sms, --webhook, --teams, or --mobile-user-ids), and no global-default contact exists to fall back to — it would fire but notify no one.');
   if (!hasAnyRecipient({ emails: body.notifyEmails, sms: body.notifyPhoneNumbers, webhook: body.notifyWebhookUrl, mobileUserIds: body.notifyMobileUserIds, teams: body.notifyTeams })
       && !argv.noRecipientsOk) {
     console.error('This update would leave the rule with no notification channel (--emails, --sms, --webhook, --teams, or --mobile-user-ids) — it would fire but notify no one.');
@@ -704,6 +764,198 @@ async function deleteAlertRule(argv) {
   console.log(`\nDeleted rule ${argv.id}.\n`);
 }
 
+// ── Alert contacts ───────────────────────────────────────────────────────────
+
+function printAlertContact(c) {
+  const scope = c.isGlobalDefault ? `${CYN}global default${RESET}` : `${DIM}not global${RESET}`;
+  const bits = [];
+  if (c.phoneNumber) bits.push(`SMS ${c.phoneNumber}`);
+  if (c.email)       bits.push(`email ${c.email}`);
+  console.log(`${DIM}[${c.id}]${RESET} ${c.name}${c.displayName ? ` (${c.displayName})` : ''}  ${scope}`);
+  console.log(`    ${bits.join('  ') || '(no phone/email set)'}`);
+}
+
+async function listAlertContacts(argv) {
+  const creds   = await getCredentials();
+  await requireAdmin(creds);
+  const msgBase = await getMsgBase(argv);
+
+  const res = await fetch(`${msgBase}/superadmin/log-alerts/contacts`, {
+    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 contacts = await res.json();
+  if (!Array.isArray(contacts) || !contacts.length) {
+    console.log('No alert contacts yet. Add one with: velaro logs contacts add --name alex --phone +1... --email alex@velaro.com');
+    return;
+  }
+  console.log(`\n${DIM}${contacts.length} alert contact(s)${RESET}\n`);
+  for (const c of contacts) printAlertContact(c);
+  console.log('');
+}
+
+async function addAlertContact(argv) {
+  const creds   = await getCredentials();
+  await requireAdmin(creds);
+  const msgBase = await getMsgBase(argv);
+
+  if (!argv.name) {
+    console.error('--name is required. Example: velaro logs contacts add --name alex --phone +14436295872 --email alex@velaro.com');
+    process.exit(1);
+  }
+  if (!argv.phone && !argv.email) {
+    console.error('At least one of --phone or --email is required.');
+    process.exit(1);
+  }
+
+  const body = {
+    name:            argv.name,
+    displayName:     argv.displayName,
+    phoneNumber:     argv.phone,
+    email:           argv.email,
+    isGlobalDefault: argv.global,
+  };
+
+  if (!argv.yes) {
+    console.log(`\n${DIM}About to create this contact (dry run — nothing sent yet):${RESET}\n`);
+    printAlertContact({ ...body, id: '(new)' });
+    console.log(`\nRe-run with --yes to actually create it.\n`);
+    return;
+  }
+
+  const res = await fetch(`${msgBase}/superadmin/log-alerts/contacts`, {
+    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 contact [${data.id}] "${data.name}"\n`);
+  printAlertContact(data);
+  console.log('');
+}
+
+async function updateAlertContact(argv) {
+  const creds   = await getCredentials();
+  await requireAdmin(creds);
+  const msgBase = await getMsgBase(argv);
+
+  if (!argv.id) {
+    console.error('Contact id is required. Example: velaro logs contacts update 1 --phone +1...');
+    process.exit(1);
+  }
+
+  const listRes = await fetch(`${msgBase}/superadmin/log-alerts/contacts`, {
+    headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
+    signal: AbortSignal.timeout(15000),
+  });
+  if (!listRes.ok) {
+    console.error(`HTTP ${listRes.status}: ${await listRes.text().catch(() => '')}`);
+    process.exit(1);
+  }
+  const contacts = await listRes.json().catch(() => []);
+  const target   = Array.isArray(contacts) ? contacts.find(c => String(c.id) === String(argv.id)) : null;
+  if (!target) {
+    console.error(`No contact with id ${argv.id} found. Run 'velaro logs contacts list' to see current ids.`);
+    process.exit(1);
+  }
+
+  const body = {
+    ...target,
+    displayName:     argv.displayName     ?? target.displayName,
+    phoneNumber:     argv.phone           ?? target.phoneNumber,
+    email:           argv.email           ?? target.email,
+    isGlobalDefault: argv.global !== undefined ? argv.global : target.isGlobalDefault,
+  };
+
+  if (!argv.yes) {
+    console.log(`\n${DIM}Current contact:${RESET}\n`);
+    printAlertContact(target);
+    console.log(`\n${DIM}About to update to (dry run — nothing sent yet):${RESET}\n`);
+    printAlertContact(body);
+    console.log(`\nRe-run with --yes to actually apply this update.\n`);
+    return;
+  }
+
+  const res = await fetch(`${msgBase}/superadmin/log-alerts/contacts/${argv.id}`, {
+    method:  'PUT',
+    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} Updated contact [${data.id}] "${data.name}"\n`);
+  printAlertContact(data);
+  console.log('');
+}
+
+async function removeAlertContact(argv) {
+  const creds   = await getCredentials();
+  await requireAdmin(creds);
+  const msgBase = await getMsgBase(argv);
+
+  if (!argv.id) {
+    console.error('Contact id is required. Example: velaro logs contacts remove 1');
+    process.exit(1);
+  }
+
+  const listRes = await fetch(`${msgBase}/superadmin/log-alerts/contacts`, {
+    headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
+    signal: AbortSignal.timeout(15000),
+  });
+  let target = null;
+  if (listRes.ok) {
+    const contacts = await listRes.json().catch(() => []);
+    target = Array.isArray(contacts) ? contacts.find(c => String(c.id) === String(argv.id)) : null;
+  }
+
+  if (target) {
+    console.log(`\n${DIM}About to delete this contact:${RESET}\n`);
+    printAlertContact(target);
+    if (target.isGlobalDefault) {
+      console.log(`${YEL}This is a global-default contact -- removing it stops it from covering any rule that leaves --emails/--sms blank.${RESET}`);
+    }
+  } else {
+    console.log(`\n${YEL}Could not fetch contact ${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/contacts/${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 contact ${argv.id}.\n`);
+}
+
 // ── command export ────────────────────────────────────────────────────────────
 
 export const logsCommand = {
@@ -797,6 +1049,11 @@ export const logsCommand = {
             .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. Leave blank to fall back to global-default contacts (see: velaro logs contacts list)', type: 'string' })
+            .option('sms',              { describe: 'Comma-separated E.164 phone numbers for SMS. Leave blank to fall back to global-default contacts', type: 'string' })
+            .option('webhook',          { describe: 'Custom webhook URL for a generic JSON POST on fire (Slack, PagerDuty, etc). NOT for Teams -- use --teams instead, which posts a properly formatted Adaptive Card through Velaro\'s existing Teams pipeline', type: 'string' })
+            .option('teams',            { describe: 'Post fired/resolved notifications to the velaro-alerts-to-teams Teams channel', type: 'boolean' })
+            .option('exclude-contacts', { describe: 'Comma-separated global-default contact names to exclude from this rule (e.g. "andrea") -- only relevant when --emails/--sms are left blank', type: 'string' })
             .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' })
@@ -819,6 +1076,11 @@ export const logsCommand = {
             .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. Leave blank to fall back to global-default contacts (see: velaro logs contacts list)', type: 'string' })
+            .option('sms',              { describe: 'Comma-separated E.164 phone numbers for SMS. Leave blank to fall back to global-default contacts', type: 'string' })
+            .option('webhook',          { describe: 'Custom webhook URL for a generic JSON POST on fire (Slack, PagerDuty, etc). NOT for Teams -- use --teams instead, which posts a properly formatted Adaptive Card through Velaro\'s existing Teams pipeline', type: 'string' })
+            .option('teams',            { describe: 'Post fired/resolved notifications to the velaro-alerts-to-teams Teams channel', type: 'boolean' })
+            .option('exclude-contacts', { describe: 'Comma-separated global-default contact names to exclude from this rule (e.g. "andrea") -- only relevant when --emails/--sms are left blank', type: 'string' })
             .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' })
@@ -849,5 +1111,53 @@ export const logsCommand = {
         })
         .demandCommand(1, 'Specify a subcommand: list, suggest, create, update, toggle, or delete'),
     })
-    .demandCommand(1, 'Specify a subcommand: search, tail, diagnose, digest-recipients, set-digest-recipients, or alerts'),
+    .command({
+      command:  'contacts <subcommand>',
+      describe: 'Manage global-default notification contacts for alert rules (Velaro staff only)',
+      builder:  y => y
+        .command({
+          command:  'list',
+          describe: 'List all alert contacts',
+          builder:  yy => yy.option('env', { describe: 'staging or prod', type: 'string' }),
+          handler:  listAlertContacts,
+        })
+        .command({
+          command:  'add',
+          describe: 'Add a new alert contact',
+          builder:  yy => yy
+            .option('name',    { describe: 'Short unique handle, e.g. "alex" -- used in --exclude-contacts', type: 'string', demandOption: true })
+            .option('display-name', { describe: 'Human-readable label, e.g. "Alex Bloom"', type: 'string' })
+            .option('phone',   { describe: 'E.164 phone number for SMS, e.g. +14436295872', type: 'string' })
+            .option('email',   { describe: 'Email address', type: 'string' })
+            .option('global',  { describe: 'Include this contact in every rule that leaves --emails/--sms blank (the normal case)', type: 'boolean', default: true })
+            .option('yes',     { describe: 'Skip the dry-run preview and actually create the contact', type: 'boolean', default: false })
+            .option('env',     { describe: 'staging or prod', type: 'string' }),
+          handler:  addAlertContact,
+        })
+        .command({
+          command:  'update <id>',
+          describe: 'Change an existing contact\'s phone/email/global-default flag',
+          builder:  yy => yy
+            .positional('id', { describe: 'Contact id (from: velaro logs contacts list)', type: 'number' })
+            .option('display-name', { describe: 'Human-readable label', type: 'string' })
+            .option('phone',   { describe: 'E.164 phone number for SMS', type: 'string' })
+            .option('email',   { describe: 'Email address', type: 'string' })
+            .option('global',  { describe: 'Include/exclude this contact from global defaults', type: 'boolean' })
+            .option('yes',     { describe: 'Skip the dry-run preview and actually apply the update', type: 'boolean', default: false })
+            .option('env',     { describe: 'staging or prod', type: 'string' }),
+          handler:  updateAlertContact,
+        })
+        .command({
+          command:  'remove <id>',
+          describe: 'Delete an alert contact',
+          builder:  yy => yy
+            .positional('id', { describe: 'Contact 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:  removeAlertContact,
+        })
+        .demandCommand(1, 'Specify a subcommand: list, add, update, or remove'),
+    })
+    .command(logsInsightsCommand)
+    .demandCommand(1, 'Specify a subcommand: search, tail, diagnose, digest-recipients, set-digest-recipients, alerts, contacts, or insights'),
 };

package/lib/commands/magento.js

@@ -40,6 +40,21 @@ async function listHandler() {
 // ── test ──────────────────────────────────────────────────────────────────────
 
 async function testHandler(argv) {
+  if (argv.id) {
+    try {
+      const r = await request('POST', `/Magento/Configs/${encodeURIComponent(argv.id)}/Test`);
+      if (r && r.valid === false) throw new Error(r.error);
+      console.log(`
+${GRN}✓ Connected${RST} to "${r.storeName}" (${r.edition} ${r.version})
+`);
+    } catch (e) {
+      console.error(`
+${RED}✗ Connection failed: ${e.message}${RST}
+`);
+      process.exitCode = 1;
+    }
+    return;
+  }
   if (!argv.url || !argv.token) {
     console.error(`${RED}✗ --url and --token are required${RST}`);
     process.exitCode = 1;
@@ -189,6 +204,7 @@ export const magentoCommand = {
       command:  'test',
       describe: 'Test a Magento store connection',
       builder: yy => yy
+        .option('id',    { describe: 'Test a connected store by config id (stored token)', type: 'number' })
         .option('url',   { describe: 'Magento store URL', type: 'string' })
         .option('token', { describe: 'Admin API bearer token', type: 'string' }),
       handler: testHandler,

package/lib/commands/mcp-key.js

@@ -31,7 +31,12 @@ const mcpKeyListCommand = {
   command:  'list',
   describe: 'List MCP API keys for your site',
   handler:  runCommand(async () => {
-    const keys = normalizeMcpKeysResponse(await get('/McpApiKeys'));
+    const response = await get('/McpApiKeys');
+    if (response?.entitled === false) {
+      console.log('MCP keys are included with the Professional plan and above. Contact support@velaro.com to upgrade.');
+      return;
+    }
+    const keys = normalizeMcpKeysResponse(response);
     if (!keys.length) { console.log('No MCP keys found.'); return; }
     console.log(`Found ${keys.length} key(s):\n`);
     for (const k of keys) {
@@ -101,6 +106,21 @@ const mcpKeyInstallCommand = {
     const result  = await request('POST', '/McpApiKeys', payload, env);
     const rawKey  = result.rawKey;
 
+    // Claude Code reads user-scope MCP server definitions from the
+    // top-level "mcpServers" key in ~/.claude.json — NOT from
+    // ~/.claude/settings.json (that file is for permissions/hooks/env,
+    // and any mcpServers entry written there is silently ignored).
+    // prod  → entry named "velaro"
+    // staging → entry named "velaro-staging"
+    const serverName    = env === 'prod' ? 'velaro' : `velaro-${env}`;
+    const claudeJsonPath = path.join(os.homedir(), '.claude.json');
+    let claudeJson = {};
+    if (fs.existsSync(claudeJsonPath)) {
+      try { claudeJson = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf8')); } catch {}
+    }
+
+    claudeJson.mcpServers = claudeJson.mcpServers || {};
+    claudeJson.mcpServers[serverName] = {
     // Claude Code reads MCP server definitions from the top-level "mcpServers" key
     // in ~/.claude.json (NOT ~/.claude/settings.json — that file has no effect here).
     // This is the same shape `claude mcp add` itself writes.
@@ -132,6 +152,8 @@ const mcpKeyInstallCommand = {
       },
     };
 
+    fs.mkdirSync(path.dirname(claudeJsonPath), { recursive: true });
+    fs.writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
     // Claude Code itself writes ~/.claude.json continuously (history, project state),
     // so this must never be a plain in-place write: write to a temp file and rename,
     // which is atomic on the same filesystem — a crash or concurrent write mid-save

package/lib/commands/netsuite.js

@@ -9,7 +9,7 @@
  * (velaro-messaging). Site is resolved server-side from the auth context — never caller-supplied.
  */
 
-import { messagingGet, messagingPost } from '../api.js';
+import { messagingGet, messagingPost, messagingDel } from '../api.js';
 
 const GRN  = '\x1b[32m';
 const DIM  = '\x1b[2m';
@@ -84,6 +84,42 @@ async function m2mVerifyHandler(argv) {
   printChecks(await messagingPost('/NetSuite/M2M/Verify', { id: Number(argv.configId) }));
 }
 
+async function suiteappHandler(argv) {
+  const includeKey = argv['include-key'] !== false;
+  const r = await messagingGet(`/api/v1/CrmEmbed/suiteapp-package?includeKey=${includeKey}&format=json`);
+  const d = r?.data ?? r;
+  if (!d?.contentBase64) throw new Error('SuiteApp package was not returned.');
+  const { writeFileSync } = await import('node:fs');
+  const out = argv.out || d.fileName || 'velaro-netsuite-screenpop-suiteapp.zip';
+  writeFileSync(out, Buffer.from(d.contentBase64, 'base64'));
+  console.log(`\n  ${GRN}Saved${RST} ${out}`);
+  if (d.keyIncluded) console.log('  Your Velaro key is already inside: no NetSuite API Secret, nothing to paste. Keep the zip private.\n');
+  else console.log(`  Key-less zip. In NetSuite create an API Secret: type ID ${d.secretFormId} (NetSuite adds the prefix, giving ${d.secretFullId}), paste your crm_embed_ key as Password.\n`);
+}
+
+async function configDeleteHandler(argv) {
+  await messagingDel(`/Netsuite/Integrations/${Number(argv.configId)}`);
+  console.log(`
+  ${GRN}Deleted${RST} NetSuite config ${argv.configId}.
+`);
+}
+
+async function m2mClearLegacyHandler(argv) {
+  const r = await messagingPost('/NetSuite/M2M/ClearLegacy', { id: Number(argv.configId) });
+  console.log(`
+  ${GRN}Legacy consumer secret/token cleared${RST} for config ${r?.id ?? argv.configId}.
+`);
+}
+
+async function embedStatusHandler() {
+  const r = await messagingGet('/api/v1/CrmEmbed/embed-status');
+  const d = r?.data ?? r;
+  console.log(`\n${BOLD}NetSuite call-pop (CRM embed) status${RST}`);
+  if (!d?.hasEmbedKey) { console.log(`  ${DIM}No crm_embed API key set for this site.${RST}\n`); return; }
+  if (d.connected) console.log(`  ${GRN}SuiteApp connected${RST}, last polled ${d.lastPolledAt}\n`);
+  else console.log(`  ${DIM}Embed key exists; SuiteApp not connected (last polled: ${d.lastPolledAt ?? 'never'})${RST}\n`);
+}
+
 export const netsuiteCommand = {
   command:  'netsuite <subcommand>',
   describe: 'NetSuite integration setup (click-to-dial / CTI)',
@@ -111,6 +147,30 @@ export const netsuiteCommand = {
         .strict(),
       handler: () => {},
     })
+    .command({
+      command:  'suiteapp',
+      describe: 'Download the screen-pop SuiteApp zip (key included by default: no API Secret to create)',
+      builder: a => a.option('include-key', { type: 'boolean', default: true }).option('out', { type: 'string' }),
+      handler: suiteappHandler,
+    })
+    .command({
+      command:  'config <action>',
+      describe: 'NetSuite connection (config) management',
+      builder: yy => yy
+        .command({ command: 'delete <configId>', describe: 'Delete a NetSuite connection from the site', handler: configDeleteHandler })
+        .demandCommand(1, 'Specify a config action: delete.')
+        .strict(),
+      handler: () => {},
+    })
+    .command({
+      command:  'embed <action>',
+      describe: 'NetSuite call-pop (CRM embed) SuiteApp',
+      builder: yy => yy
+        .command({ command: 'status', describe: 'Is the crm_embed key set, and last heartbeat', handler: embedStatusHandler })
+        .demandCommand(1, 'Specify an embed action: status.')
+        .strict(),
+      handler: () => {},
+    })
     .command({
       command:  'm2m <action>',
       describe: 'NetSuite machine-to-machine (OAuth 2.0 Client Credentials) setup',
@@ -132,7 +192,12 @@ export const netsuiteCommand = {
           describe: 'Run the per-check verification (token, REST, customer read)',
           handler: m2mVerifyHandler,
         })
-        .demandCommand(1, 'Specify an m2m action: init, save, or verify.')
+        .command({
+          command: 'clear-legacy <configId>',
+          describe: 'Disconnect the old consumer-key/token credentials (requires M2M saved)',
+          handler: m2mClearLegacyHandler,
+        })
+        .demandCommand(1, 'Specify an m2m action: init, save, verify, or clear-legacy.')
         .strict(),
       handler: () => {},
     })

package/lib/commands/notifications.js

@@ -1,4 +1,12 @@
-import { messagingGet, messagingPost } from '../api.js';
+import { messagingGet, messagingPost, messagingPut } from '../api.js';
+
+// Alert routing: Channel x Handling x Kind (+ ivrBotAlerts). Backend: GET/PUT /api/v1/alert-routing.
+const ROUTING_GROUPS = {
+  channel:  ['channels', ['web', 'sms', 'whatsapp', 'appleMessages', 'email', 'phone']],
+  handling: ['handling', ['mine', 'unassigned', 'bot', 'teammates']],
+  kind:     ['kinds',    ['conversations', 'tickets', 'calls', 'visitors']],
+};
+const csv = (v) => String(v).split(',').map((x) => x.trim()).filter(Boolean);
 
 const FLAGS = [
   ['new-conversations',    'newConversations',    'NewConversations'],
@@ -24,6 +32,15 @@ const getCommand = {
     }
     console.log(`  ${'sticky-duration'.padEnd(28)} ${s.stickyDuration}ms`);
     console.log(`  ${'sms-alert-phone'.padEnd(28)} ${s.smsAlertPhone ?? '(none)'}`);
+    try {
+      const r = (await messagingGet('/api/v1/alert-routing')).data;
+      console.log('\n\x1b[1mAlert routing\x1b[0m (alert fires only if channel, handling and kind all match)');
+      for (const [label, [group]] of Object.entries(ROUTING_GROUPS)) {
+        const on = Object.entries(r[group] ?? {}).filter(([, v]) => v).map(([k]) => k);
+        console.log(`  ${label.padEnd(28)} ${on.join(', ') || '(none)'}`);
+      }
+      console.log(`  ${'ivr-bot-alerts'.padEnd(28)} ${r.ivrBotAlerts ? '\x1b[32mon\x1b[0m' : '\x1b[90moff\x1b[0m'}`);
+    } catch { /* older server without alert routing */ }
     console.log('');
   },
 };
@@ -35,6 +52,10 @@ const setCommand = {
     for (const [flag] of FLAGS) {
       y.option(flag, { type: 'boolean', describe: `Turn ${flag.replace(/-/g, ' ')} on/off` });
     }
+    y.option('channel',  { type: 'string', describe: 'Channels to alert on, comma list of: web,sms,whatsapp,appleMessages,email,phone (others turned off)' });
+    y.option('handling', { type: 'string', describe: 'Handling to alert on, comma list of: mine,unassigned,bot,teammates (others turned off)' });
+    y.option('kind',     { type: 'string', describe: 'Kinds to alert on, comma list of: conversations,tickets,calls,visitors (others turned off)' });
+    y.option('ivr-bot-alerts', { type: 'boolean', describe: 'Alert for inbound IVR / phone bot chats' });
     y.option('sms-alert-phone', { type: 'string', describe: 'Phone number for SMS alerts (E.164, e.g. +14155551234)' });
     return y;
   },
@@ -47,6 +68,18 @@ const setCommand = {
     if (argv['sms-alert-phone'] !== undefined) current.smsAlertPhone = argv['sms-alert-phone'];
 
     await messagingPost('/NotificationSettings', current);
+
+    const patch = {};
+    for (const [flag, [group, keys]] of Object.entries(ROUTING_GROUPS)) {
+      if (argv[flag] === undefined) continue;
+      const wanted = csv(argv[flag]);
+      const bad = wanted.filter((k) => !keys.includes(k));
+      if (bad.length) { console.error(`Unknown ${flag}: ${bad.join(', ')}. Valid: ${keys.join(', ')}`); process.exit(1); }
+      patch[group] = Object.fromEntries(keys.map((k) => [k, wanted.includes(k)]));
+    }
+    if (argv['ivr-bot-alerts'] !== undefined) patch.ivrBotAlerts = argv['ivr-bot-alerts'];
+    if (Object.keys(patch).length) await messagingPut('/api/v1/alert-routing', patch);
+
     console.log('\x1b[32m✓ Notification settings updated.\x1b[0m Run `velaro notifications get` to review.');
   },
 };