@velaro/cli 1.2.0 → 1.4.9

package/lib/commands/migrate.js

@@ -0,0 +1,134 @@
+import { get, post, request } from '../api.js';
+import { runCommand }         from '../run.js';
+
+export const migrateCommand = {
+  command:  'migrate <subcommand>',
+  describe: 'Migrate customer setups between Velaro platforms',
+  builder:  (yargs) =>
+    yargs
+      .command(migrateExportCommand)
+      .command(migrateLivefluenceCommand)
+      .demandCommand(1, 'Specify a subcommand: export, livefluence'),
+  handler: () => {},
+};
+
+// ── export V10 routing rules for a site ───────────────────────────────────────
+
+const migrateExportCommand = {
+  command:  'export <v10SiteId>',
+  describe: 'Export V10 (Livefluence) routing rules for a site and preview V20 migration',
+  builder:  (y) =>
+    y
+      .positional('v10SiteId', { type: 'number', describe: 'V10 site ID to export from' })
+      .option('v20-site-id',   { type: 'number', alias: 's', describe: 'V20 site ID for auto-matching teams/AI configs' }),
+  handler:  runCommand(async (argv) => {
+    const qs = argv['v20-site-id'] ? `?v20SiteId=${argv['v20-site-id']}` : '';
+    const data = await get(`/DatabaseTool/V10Export/${argv.v10SiteId}${qs}`);
+
+    console.log(`\n${'─'.repeat(60)}`);
+    console.log(`  V10 Site ${data.v10SiteId} — Livefluence Routing Rules`);
+    console.log(`  ${data.ruleCount} rule(s) across ${data.groupCount} group(s)`);
+    console.log(`${'─'.repeat(60)}\n`);
+
+    for (const r of data.rules) {
+      const resolved = r.canAutoResolve ? '✅' : '⚠';
+      console.log(`  ${resolved} [#${r.priority}] ${r.name}`);
+      console.log(`       Group: ${r.groupName} → ${r.action}`);
+      console.log(`       V10 expression: ${r.v10Expression}`);
+      if (r.canAutoResolve) {
+        if (r.suggestedAiConfigName)
+          console.log(`       → AI Config: "${r.suggestedAiConfigName}" (id=${r.suggestedAiConfigId})`);
+        if (r.suggestedTeamName)
+          console.log(`       → Team: "${r.suggestedTeamName}" (id=${r.suggestedTeamId})`);
+      } else {
+        if (r.hasBot)
+          console.log(`       ⚠ No V20 AI config named "${r.groupName}" — create it first`);
+        else
+          console.log(`       ⚠ No V20 team named "${r.groupName}" — create it first`);
+      }
+      console.log('');
+    }
+
+    console.log(`  Auto-resolvable: ${data.autoResolvable}/${data.ruleCount}`);
+    if (data.needsManualMapping > 0) {
+      console.log(`  Needs manual mapping: ${data.needsManualMapping} rule(s)`);
+      console.log(`  Create matching V20 teams/AI configs by name, then re-run.`);
+    }
+
+    if (data.v20Teams?.length) {
+      console.log(`\n  V20 Teams on site ${data.v20SiteId}: ${data.v20Teams.map(t => t.name).join(', ')}`);
+    }
+    if (data.v20AiConfigs?.length) {
+      console.log(`  V20 AI Configs: ${data.v20AiConfigs.map(a => a.name).join(', ')}`);
+    }
+
+    console.log(`\n  Run: velaro migrate livefluence --v10-site-id ${argv.v10SiteId} --v20-site-id <id> --dry-run`);
+    console.log(`${'─'.repeat(60)}\n`);
+  }),
+};
+
+// ── migrate Livefluence → V20 canvas workflows ────────────────────────────────
+
+const migrateLivefluenceCommand = {
+  command:  'livefluence',
+  describe: 'Migrate a Livefluence site\'s routing rules to V20 canvas workflows',
+  builder:  (y) =>
+    y
+      .option('v10-site-id',  { type: 'number',  alias: 'v', describe: 'V10 (Livefluence) site ID', demandOption: true })
+      .option('v20-site-id',  { type: 'number',  alias: 's', describe: 'V20 destination site ID', demandOption: true })
+      .option('dry-run',      { type: 'boolean', default: false, describe: 'Preview without creating' })
+      .option('enable',       { type: 'boolean', default: false, describe: 'Enable created workflows immediately (default: disabled)' })
+      .option('team-map',     { type: 'string',  describe: 'JSON: [{"v10GroupId":1,"v20TeamId":5},...]  override auto-resolution for teams' })
+      .option('ai-config-map',{ type: 'string',  describe: 'JSON: [{"v10GroupId":2,"v20AiConfigId":3},...] override auto-resolution for AI configs' }),
+  handler:  runCommand(async (argv) => {
+    const v10SiteId = argv['v10-site-id'];
+    const v20SiteId = argv['v20-site-id'];
+
+    const body = {
+      v10SiteId,
+      v20SiteId,
+      dryRun: argv['dry-run'],
+      enable: argv.enable,
+      teamMappings:     argv['team-map']      ? JSON.parse(argv['team-map'])       : [],
+      aiConfigMappings: argv['ai-config-map'] ? JSON.parse(argv['ai-config-map'])  : [],
+    };
+
+    console.log(`\n${'─'.repeat(60)}`);
+    console.log(`  Livefluence → V20 Canvas Workflow Migration`);
+    console.log(`  V10 site: ${v10SiteId} → V20 site: ${v20SiteId}`);
+    console.log(`  Mode: ${argv['dry-run'] ? 'DRY RUN (no changes)' : 'LIVE'}`);
+    console.log(`${'─'.repeat(60)}\n`);
+
+    const result = await post('/DatabaseTool/V10Migrate', body);
+
+    if (result.createdItems?.length) {
+      console.log(`  Workflows ${argv['dry-run'] ? '(would create)' : 'created'}:\n`);
+      for (const item of result.createdItems) {
+        const id = item.workflowId ? ` [id=${item.workflowId}]` : '';
+        console.log(`  + [#${item.priority}] ${item.ruleName}${id}`);
+        console.log(`       Action: ${item.action}`);
+        if (item.v2AiConfigId)  console.log(`       → AI Config id=${item.v2AiConfigId}`);
+        if (item.v2TeamId)      console.log(`       → Team id=${item.v2TeamId}`);
+        if (item.v10Expression) console.log(`       V10 expression: ${item.v10Expression}`);
+        console.log('');
+      }
+    }
+
+    if (result.skippedItems?.length) {
+      console.log(`  Skipped (unresolvable):\n`);
+      for (const item of result.skippedItems) {
+        console.log(`  ⚠ ${item.name}: ${item.reason}`);
+      }
+      console.log('');
+    }
+
+    console.log(`${'─'.repeat(60)}`);
+    console.log(`  ${result.message}`);
+    if (!argv['dry-run'] && result.created > 0) {
+      console.log(`\n  ⚠ All workflows created DISABLED — review conditions in the canvas then enable.`);
+      console.log(`    Note: V10 routing expressions were NOT auto-converted.`);
+      console.log(`    Add conditions manually in the Workflows canvas (Phase 3 trigger node).`);
+    }
+    console.log(`${'─'.repeat(60)}\n`);
+  }),
+};

package/lib/commands/migration-status.js

@@ -0,0 +1,66 @@
+import { get }        from '../api.js';
+import { runCommand } from '../run.js';
+
+// Reads AdminStartupDiagnostics (SuperAdmin/StartupDiagnostics) — the dependency-free canary
+// table StartupMigrationRunner.WriteCanary writes on every startup, one row per DbContext per
+// restart. Built 2026-08-23: no CLI/MCP/REST surface previously existed to read this table, so
+// every prior round of the MessagingContext production migration investigation
+// (docs/architecture/postmortems.md, 2026-07-14 through 2026-08-19) had to guess at the real
+// Database.Migrate()/SchemaDriftChecker outcome instead of just reading it directly.
+export const migrationStatusCommand = {
+  command:  'migration-status [contextLabel]',
+  describe: 'Show recent StartupMigrationRunner/SchemaDriftChecker outcomes (AdminStartupDiagnostics canary table)',
+  builder:  (y) =>
+    y
+      .positional('contextLabel', { type: 'string', describe: 'Filter to one DbContext label, e.g. Messaging, Marketing, Billing' })
+      .option('count', { type: 'number', alias: 'n', default: 20, describe: 'Max rows to show (1-200)' }),
+  handler:  runCommand(async (argv) => {
+    const qs = new URLSearchParams();
+    if (argv.contextLabel) qs.set('contextLabel', argv.contextLabel);
+    if (argv.count) qs.set('count', String(argv.count));
+
+    const data = await get(`/SuperAdmin/StartupDiagnostics?${qs.toString()}`);
+
+    if (data.note) {
+      console.log(`\n  ${data.note}\n`);
+      return;
+    }
+
+    if (!data.rows?.length) {
+      console.log(`\n  No AdminStartupDiagnostics rows${argv.contextLabel ? ` for '${argv.contextLabel}'` : ''}.\n`);
+      return;
+    }
+
+    console.log(`\n${'─'.repeat(70)}`);
+    console.log(`  Startup Migration Diagnostics${argv.contextLabel ? ` — ${argv.contextLabel}` : ''}`);
+    console.log(`${'─'.repeat(70)}\n`);
+
+    for (const row of data.rows) {
+      const outcomeIcon =
+        row.outcome === 'Success' ? '✅' :
+        row.outcome === 'PendingAfterMigrate_HistoryOnly' ? '🟡' :
+        row.outcome?.startsWith('PendingAfterMigrate_RealDrift') ? '🔴' :
+        row.outcome === 'PendingAfterMigrate_Unchecked' ? '⚠️' :
+        row.outcome === 'MigrateThrew' || row.outcome === 'DriftCheckThrew' ? '❌' :
+        '·';
+
+      console.log(`  ${outcomeIcon} [${row.contextLabel}] ${row.outcome}  —  ${new Date(row.createdAtUtc).toISOString()}`);
+      if (row.pendingCount > 0) {
+        console.log(`       Pending (${row.pendingCount}): ${row.pendingMigrationIds}`);
+      }
+      if (row.exceptionType) {
+        console.log(`       Exception: ${row.exceptionType}`);
+        console.log(`       Detail: ${(row.exceptionDetail || '').slice(0, 400)}${(row.exceptionDetail || '').length > 400 ? '…' : ''}`);
+      }
+      console.log('');
+    }
+
+    console.log(`${'─'.repeat(70)}`);
+    console.log('  Outcomes: Success | PendingAfterMigrate_HistoryOnly (safe, Degraded) |');
+    console.log('  PendingAfterMigrate_RealDrift* (real missing schema, Critical) |');
+    console.log('  PendingAfterMigrate_Unchecked (drift check never ran, fail-safe Critical) |');
+    console.log('  MigrateThrew (Database.Migrate() itself threw) |');
+    console.log('  DriftCheckThrew (SchemaDriftChecker itself threw after a successful Migrate())');
+    console.log(`${'─'.repeat(70)}\n`);
+  }),
+};

package/lib/commands/monday.js

@@ -0,0 +1,137 @@
+/**
+ * velaro monday - Monday.com board/column field mapping + CRM search
+ *
+ *   velaro monday columns              List a board's real columns (status/people/dropdown/date/numbers/text)
+ *   velaro monday mapping              Show the site's saved field mapping
+ *   velaro monday mapping-set          Set a single field's mapping to a column id
+ *   velaro monday search               Freeform CRM search across a board's items
+ */
+
+import { request } from '../api.js';
+
+const GRN  = '\x1b[32m';
+const RED  = '\x1b[31m';
+const CYN  = '\x1b[36m';
+const DIM  = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RST  = '\x1b[0m';
+
+async function resolveBoardId(argv) {
+  if (argv.board) return argv.board;
+  const cfg = await request('GET', '/Monday');
+  return cfg?.defaultBoardId ?? null;
+}
+
+// -- columns ---------------------------------------------------------------
+
+async function columnsHandler(argv) {
+  const boardId = await resolveBoardId(argv);
+  if (!boardId) {
+    console.error(`${RED}No board ID given and no default board configured. Use --board or set a default board first.${RST}`);
+    process.exitCode = 1;
+    return;
+  }
+  const columns = await request('GET', `/Monday/boards/${encodeURIComponent(boardId)}/columns`);
+  if (!Array.isArray(columns) || columns.length === 0) {
+    console.log(`\nNo columns found for board ${boardId}.\n`);
+    return;
+  }
+  console.log(`\n${BOLD}Columns on board ${boardId} (${columns.length})${RST}\n`);
+  for (const c of columns) {
+    console.log(`  ${CYN}${(c.id ?? '').padEnd(20)}${RST} ${BOLD}${c.title}${RST}  ${DIM}(${c.type})${RST}`);
+    if (Array.isArray(c.options) && c.options.length) {
+      console.log(`      ${DIM}options: ${c.options.map(o => o.label).join(', ')}${RST}`);
+    }
+  }
+  console.log('');
+}
+
+// -- mapping -----------------------------------------------------------------
+
+async function mappingHandler() {
+  const result = await request('GET', '/Monday/FieldMapping');
+  const entries = Object.entries(result?.mapping ?? {});
+  if (entries.length === 0) {
+    console.log(`\nNo field mapping saved yet${result?.boardId ? ` for board ${result.boardId}` : ''}.\n`);
+    return;
+  }
+  console.log(`\n${BOLD}Field mapping${result?.boardId ? ` (board ${result.boardId})` : ''}${RST}\n`);
+  for (const [k, v] of entries) console.log(`  ${k.padEnd(16)} -> ${GRN}${v}${RST}`);
+  console.log('');
+}
+
+// -- mapping-set ---------------------------------------------------------------
+
+async function mappingSetHandler(argv) {
+  if (!argv.field || !argv.column) {
+    console.error(`${RED}--field and --column are required (e.g. --field contactEmail --column email_mkjy)${RST}`);
+    process.exitCode = 1;
+    return;
+  }
+  const current = await request('GET', '/Monday/FieldMapping');
+  const mapping = { ...(current?.mapping ?? {}), [argv.field]: argv.column };
+  const result = await request('PUT', '/Monday/FieldMapping', { mapping });
+  console.log(`\n${GRN}Mapped${RST} ${argv.field} -> ${result?.mapping?.[argv.field]}\n`);
+}
+
+// -- search --------------------------------------------------------------------
+
+async function searchHandler(argv) {
+  if (!argv.q) {
+    console.error(`${RED}--q (search text) is required${RST}`);
+    process.exitCode = 1;
+    return;
+  }
+  const qs = new URLSearchParams({ q: argv.q });
+  if (argv.board) qs.set('boardId', argv.board);
+  const results = await request('GET', `/Monday/Data/Contacts/Search?${qs.toString()}`);
+  if (!Array.isArray(results) || results.length === 0) {
+    console.log(`\nNo Monday.com items matched "${argv.q}".\n`);
+    return;
+  }
+  console.log(`\n${BOLD}${results.length} match(es) for "${argv.q}"${RST}\n`);
+  for (const r of results) {
+    console.log(`  [${r.id}] ${BOLD}${r.name}${RST}`);
+    const bits = [r.email, r.phone, r.company].filter(Boolean);
+    if (bits.length) console.log(`       ${DIM}${bits.join(' | ')}${RST}`);
+  }
+  console.log('');
+}
+
+// -- command export --------------------------------------------------------------
+
+export const mondayCommand = {
+  command:  'monday <subcommand>',
+  describe: 'Monday.com board/column field mapping + CRM search',
+  builder: y => y
+    .command({
+      command:  'columns',
+      describe: "List a board's real columns (status/people/dropdown/date/numbers/text)",
+      builder: yy => yy
+        .option('board', { describe: "Board ID (default: site's configured default board)", type: 'string' }),
+      handler: columnsHandler,
+    })
+    .command({
+      command:  'mapping',
+      describe: "Show the site's saved Velaro field to Monday column mapping",
+      handler: mappingHandler,
+    })
+    .command({
+      command:  'mapping-set',
+      describe: 'Map a single Velaro field to a Monday.com column id',
+      builder: yy => yy
+        .option('field',  { describe: 'Velaro field key (contactName, contactEmail, contactPhone, company, leadSource, status)', type: 'string' })
+        .option('column', { describe: 'Monday.com column id (from velaro monday columns)', type: 'string' }),
+      handler: mappingSetHandler,
+    })
+    .command({
+      command:  'search',
+      describe: 'Freeform CRM search (name/email/phone/company) across a board',
+      builder: yy => yy
+        .option('q',     { describe: 'Search text', type: 'string' })
+        .option('board', { describe: "Board ID (default: site's configured default board)", type: 'string' }),
+      handler: searchHandler,
+    })
+    .demandCommand(1, 'Specify a subcommand. Try: velaro monday --help'),
+  handler: () => {},
+};

package/lib/commands/netsuite.js

@@ -0,0 +1,87 @@
+/**
+ * velaro netsuite - NetSuite click-to-dial (CTI) setup
+ *
+ *   velaro netsuite cti list                 List NetSuite config IDs for the site
+ *   velaro netsuite cti urls <configId>       Show the current CTI setup URLs (or null if never generated)
+ *   velaro netsuite cti generate <configId>   Generate/rotate the CTI URL token
+ *
+ * Backend contract: server/Velaro.Messaging/Controllers/CRMs/NetsuiteIntegrationsController.cs
+ * (velaro-messaging). Site is resolved server-side from the auth context — never caller-supplied.
+ */
+
+import { messagingGet, messagingPost } from '../api.js';
+
+const GRN  = '\x1b[32m';
+const DIM  = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RST  = '\x1b[0m';
+
+function printConfigs(configs) {
+  if (!Array.isArray(configs) || !configs.length) {
+    console.log(`\n  ${DIM}No NetSuite configurations found for this site.${RST}\n`);
+    return;
+  }
+  console.log(`\n${BOLD}NetSuite configurations${RST}`);
+  for (const c of configs) console.log(`  [${c.id}] ${c.displayName} (${c.company})`);
+  console.log('');
+}
+
+function printUrls(urls) {
+  console.log(`\n${BOLD}NetSuite CTI setup — config ${urls.id}${RST}`);
+  if (!urls.ctiUrlToken) {
+    console.log(`  ${DIM}No CTI URL generated yet. Run "velaro netsuite cti generate ${urls.id}".${RST}\n`);
+    return;
+  }
+  console.log(`  ${GRN}Dial URL${RST} (paste into NetSuite Home > Set Preferences > Telephony > CTI URL):`);
+  console.log(`    ${urls.dialUrlTemplate}`);
+  console.log(`  ${GRN}Screen-pop URL${RST} (optional, unconfirmed automatic by NetSuite):`);
+  console.log(`    ${urls.screenPopUrl}\n`);
+}
+
+async function listHandler() {
+  const configs = await messagingGet('/NetSuite/Integrations/List');
+  printConfigs(configs);
+}
+
+async function urlsHandler(argv) {
+  const urls = await messagingGet(`/NetSuite/Integrations/${argv.configId}/CtiUrls`);
+  printUrls(urls);
+}
+
+async function generateHandler(argv) {
+  const urls = await messagingPost(`/NetSuite/Integrations/${argv.configId}/GenerateCtiToken`, {});
+  console.log(`\n  ${GRN}✓${RST} CTI token generated/rotated.`);
+  printUrls(urls);
+}
+
+export const netsuiteCommand = {
+  command:  'netsuite <subcommand>',
+  describe: 'NetSuite integration setup (click-to-dial / CTI)',
+  builder: y => y
+    .command({
+      command:  'cti <action>',
+      describe: 'NetSuite click-to-dial (CTI URL) setup',
+      builder: yy => yy
+        .command({
+          command: 'list',
+          describe: 'List NetSuite config IDs for the site',
+          handler: listHandler,
+        })
+        .command({
+          command: 'urls <configId>',
+          describe: 'Show the current CTI setup URLs for a config',
+          handler: argv => urlsHandler({ configId: argv.configId }),
+        })
+        .command({
+          command: 'generate <configId>',
+          describe: 'Generate (or rotate) the CTI URL token for a config',
+          handler: argv => generateHandler({ configId: argv.configId }),
+        })
+        .demandCommand(1, 'Specify a cti action: list, urls, or generate.')
+        .strict(),
+      handler: () => {},
+    })
+    .demandCommand(1, 'Specify a netsuite subcommand.')
+    .strict(),
+  handler: () => {},
+};

package/lib/commands/notifications.js

@@ -0,0 +1,63 @@
+import { messagingGet, messagingPost } from '../api.js';
+
+const FLAGS = [
+  ['new-conversations',    'newConversations',    'NewConversations'],
+  ['conversation-assigned','conversationAssigned','ConversationAssigned'],
+  ['new-messages',         'newMessages',          'NewMessages'],
+  ['unassign-warning',     'unassignWarning',      'UnassignWarning'],
+  ['text-alerts',          'textAlerts',           'TextAlerts'],
+  ['sticky-alerts',        'stickyAlerts',         'StickyAlerts'],
+  ['sms-on-new-conversation',  'smsOnNewConversation',  'SmsOnNewConversation'],
+  ['sms-on-missed-chat',       'smsOnMissedChat',       'SmsOnMissedChat'],
+  ['sms-on-unassign-warning',  'smsOnUnassignWarning',  'SmsOnUnassignWarning'],
+  ['use-profile-phone',        'useProfilePhone',       'UseProfilePhone'],
+];
+
+const getCommand = {
+  command:  'get',
+  describe: 'Show your current notification/alert settings (new conversations, SMS alerts, etc.)',
+  handler:  async () => {
+    const s = await messagingGet('/NotificationSettings');
+    console.log('\n\x1b[1mNotification settings\x1b[0m');
+    for (const [flag, jsonKey] of FLAGS) {
+      console.log(`  ${flag.padEnd(28)} ${s[jsonKey] ? '\x1b[32mon\x1b[0m' : '\x1b[90moff\x1b[0m'}`);
+    }
+    console.log(`  ${'sticky-duration'.padEnd(28)} ${s.stickyDuration}ms`);
+    console.log(`  ${'sms-alert-phone'.padEnd(28)} ${s.smsAlertPhone ?? '(none)'}`);
+    console.log('');
+  },
+};
+
+const setCommand = {
+  command:  'set',
+  describe: 'Update your notification/alert settings (only the flags you pass are changed)',
+  builder:  (y) => {
+    for (const [flag] of FLAGS) {
+      y.option(flag, { type: 'boolean', describe: `Turn ${flag.replace(/-/g, ' ')} on/off` });
+    }
+    y.option('sms-alert-phone', { type: 'string', describe: 'Phone number for SMS alerts (E.164, e.g. +14155551234)' });
+    return y;
+  },
+  handler: async (argv) => {
+    const current = await messagingGet('/NotificationSettings');
+
+    for (const [flag, jsonKey] of FLAGS) {
+      if (argv[flag] !== undefined) current[jsonKey] = argv[flag];
+    }
+    if (argv['sms-alert-phone'] !== undefined) current.smsAlertPhone = argv['sms-alert-phone'];
+
+    await messagingPost('/NotificationSettings', current);
+    console.log('\x1b[32m✓ Notification settings updated.\x1b[0m Run `velaro notifications get` to review.');
+  },
+};
+
+export const notificationsCommand = {
+  command:  'notifications <subcommand>',
+  describe: 'View and update your own notification/SMS alert settings',
+  builder:  (yargs) =>
+    yargs
+      .command(getCommand)
+      .command(setCommand)
+      .demandCommand(1, 'Specify a subcommand: get | set'),
+  handler: () => {},
+};

package/lib/commands/notion.js

@@ -0,0 +1,70 @@
+/**
+ * velaro notion - Notion workspace connection status + connectivity test
+ *
+ *   velaro notion status         Show the site's connected Notion workspace + config
+ *   velaro notion test           Test a Notion integration token without saving it
+ */
+
+import { request } from '../api.js';
+
+const GRN  = '\x1b[32m';
+const RED  = '\x1b[31m';
+const DIM  = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RST  = '\x1b[0m';
+
+// -- status ------------------------------------------------------------------
+
+async function statusHandler() {
+  const configs = await request('GET', '/Notion/Configs');
+  if (!Array.isArray(configs) || configs.length === 0) {
+    console.log(`\n${RED}Notion is not connected.${RST} Visit Integration Settings -> Notion to connect a workspace.\n`);
+    return;
+  }
+  const cfg = configs[0];
+  console.log(`\n${BOLD}Notion${RST} ${cfg.isEnabled ? `${GRN}connected${RST}` : `${RED}disabled${RST}`}`);
+  console.log(`  Workspace:            ${cfg.workspaceName || DIM + '(unknown)' + RST}`);
+  console.log(`  Workspace ID:         ${cfg.workspaceId || DIM + '(none)' + RST}`);
+  console.log(`  Knowledge base pages: ${cfg.knowledgeBasePageIds || DIM + 'entire workspace' + RST}`);
+  console.log(`  Leads database:       ${cfg.leadsDatabaseId || DIM + '(not configured)' + RST}`);
+  console.log('');
+}
+
+// -- test ----------------------------------------------------------------------
+
+async function testHandler(argv) {
+  if (!argv.token) {
+    console.error(`${RED}--token (Notion internal integration token) is required${RST}`);
+    process.exitCode = 1;
+    return;
+  }
+  const result = await request('POST', '/Notion/Configs/Test', { accessToken: argv.token });
+  if (!result?.valid) {
+    console.log(`\n${RED}Invalid token${RST}${result?.error ? `: ${result.error}` : '.'}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`\n${GRN}Valid${RST} — workspace: ${BOLD}${result.workspaceName}${RST} (${result.workspaceId})\n`);
+}
+
+// -- command export --------------------------------------------------------------
+
+export const notionCommand = {
+  command:  'notion <subcommand>',
+  describe: 'Notion workspace connection status + connectivity test',
+  builder: y => y
+    .command({
+      command:  'status',
+      describe: "Show the site's connected Notion workspace and configuration",
+      handler: statusHandler,
+    })
+    .command({
+      command:  'test',
+      describe: 'Test a Notion integration token without saving it',
+      builder: yy => yy
+        .option('token', { describe: 'Notion internal integration token (secret_...)', type: 'string' }),
+      handler: testHandler,
+    })
+    .demandCommand(1, 'Specify a subcommand. Try: velaro notion --help'),
+  handler: () => {},
+};