@velaro/cli 1.4.99 → 1.4.101

package/bin/velaro.js

@@ -15,6 +15,7 @@ import { knowledgeAdvisorCommand } from '../lib/commands/knowledge-advisor.js';
 import { productCommand }    from '../lib/commands/product.js';
 import { mcpKeyCommand }     from '../lib/commands/mcp-key.js';
 import { opsCommand }        from '../lib/commands/ops.js';
+import { cobrowseCommand }   from '../lib/commands/cobrowse.js';
 import { deployStateCommand } from '../lib/commands/deploy-state.js';
 import { checkCommand }      from '../lib/commands/check.js';
 import { logsCommand }       from '../lib/commands/logs.js';
@@ -151,6 +152,7 @@ await yargs(hideBin(process.argv))
   .command(productCommand)
   .command(mcpKeyCommand)
   .command(opsCommand)
+  .command(cobrowseCommand)
   .command(deployStateCommand)
   .command(checkCommand)
   .command(logsCommand)

package/lib/cobrowse-settings.js

@@ -0,0 +1,90 @@
+// Pure helpers for `velaro cobrowse ...` (kept free of I/O so they are unit-testable).
+//
+// The platform API (messaging: GET/PUT superadmin/sites/{siteId}/cobrowse...) has REPLACE semantics: every setting
+// that is not sent goes back to the platform default. For a CLI that is a footgun, so `set` first reads the current
+// raw settings and only overwrites what the operator named on the command line.
+
+export const TRI_FIELDS = [
+  ['cues', 'cuesEnabled'],
+  ['formFill', 'formFillEnabled'],
+  ['strictMask', 'strictMaskMode'],
+  ['disableMobile', 'disableOnMobile'],
+];
+
+/** "on" / "off" / "default" (also true/false) -> true / false / null. Throws on anything else. */
+export function parseTri(value, flag) {
+  if (value === undefined) return undefined;
+  const v = String(value).trim().toLowerCase();
+  if (['on', 'true', 'yes', '1'].includes(v)) return true;
+  if (['off', 'false', 'no', '0'].includes(v)) return false;
+  if (['default', 'inherit', 'null', ''].includes(v)) return null;
+  throw new Error(`--${flag} must be on, off or default (got "${value}")`);
+}
+
+function parseIntOrDefault(value, flag) {
+  if (value === undefined) return undefined;
+  const v = String(value).trim().toLowerCase();
+  if (v === 'default' || v === '') return null;
+  const n = Number(v);
+  if (!Number.isInteger(n)) throw new Error(`--${flag} must be a whole number of minutes or "default" (got "${value}")`);
+  return n;
+}
+
+function parseTextOrDefault(value) {
+  if (value === undefined) return undefined;
+  return String(value).trim().toLowerCase() === 'default' ? null : String(value);
+}
+
+/**
+ * Merge operator flags over the site's current raw settings. Returns the full request body to PUT.
+ * Protected pages: "default" -> platform list, "none" -> no protected pages, otherwise a newline/comma list.
+ */
+export function buildCobrowseUpdate(current, args) {
+  const body = { ...(current ?? {}) };
+  delete body.updatedAt;
+
+  for (const [flag, field] of TRI_FIELDS) {
+    const v = parseTri(args[flag], flag);
+    if (v !== undefined) body[field] = v;
+  }
+
+  if (args.protectedPages !== undefined) {
+    const raw = String(args.protectedPages).trim();
+    const lower = raw.toLowerCase();
+    body.blockedUrlPatterns = lower === 'default' ? null : lower === 'none' ? '' : raw.split(/[\n,]/).map(s => s.trim()).filter(Boolean).join('\n');
+  }
+
+  const max = parseIntOrDefault(args.maxMinutes, 'max-minutes');
+  if (max !== undefined) body.maxSessionMinutes = max;
+  const idle = parseIntOrDefault(args.idleMinutes, 'idle-minutes');
+  if (idle !== undefined) body.idleStopMinutes = idle;
+
+  const title = parseTextOrDefault(args.consentTitle);
+  if (title !== undefined) body.consentTitle = title;
+  const message = parseTextOrDefault(args.consentMessage);
+  if (message !== undefined) body.consentMessage = message;
+  const allow = parseTextOrDefault(args.consentAllow);
+  if (allow !== undefined) body.consentAllowLabel = allow;
+
+  const teams = parseTextOrDefault(args.teams);
+  if (teams !== undefined) body.allowedTeamIds = teams === 'none' ? null : teams;
+  const roles = parseTextOrDefault(args.roles);
+  if (roles !== undefined) body.allowedRoles = roles === 'none' ? null : roles;
+
+  return body;
+}
+
+export function describeEffective(e) {
+  if (!e) return [];
+  return [
+    ['Agent cues', e.cuesEnabled ? 'on' : 'off'],
+    ['Guided form fill', e.formFillEnabled ? 'on' : 'off'],
+    ['Strict mask mode', e.strictMask ? 'on' : 'off'],
+    ['Off on mobile', e.disableOnMobile ? 'yes' : 'no'],
+    ['Protected pages', (e.blockedUrlPatterns ?? []).length ? e.blockedUrlPatterns.join('  ') : 'none'],
+    ['Max session / idle stop', `${e.maxSessionMinutes} min / ${e.idleStopMinutes} min`],
+    ['Who can start', (e.allowedTeamIds ?? []).length || (e.allowedRoles ?? []).length
+      ? `teams [${(e.allowedTeamIds ?? []).join(', ')}] roles [${(e.allowedRoles ?? []).join(', ')}]`
+      : 'everyone with a seat'],
+  ];
+}

package/lib/cobrowse-settings.test.js

@@ -0,0 +1,45 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { buildCobrowseUpdate, parseTri, describeEffective } from './cobrowse-settings.js';
+
+test('parseTri maps on/off/default and rejects anything else', () => {
+  assert.equal(parseTri('on', 'cues'), true);
+  assert.equal(parseTri('OFF', 'cues'), false);
+  assert.equal(parseTri('default', 'cues'), null);
+  assert.equal(parseTri(undefined, 'cues'), undefined);
+  assert.throws(() => parseTri('maybe', 'cues'), /--cues must be on, off or default/);
+});
+
+test('set only changes the flags named; everything else is preserved (the API itself replaces)', () => {
+  const current = { cuesEnabled: true, strictMaskMode: true, maxSessionMinutes: 30, blockedUrlPatterns: '/a\n/b', updatedAt: '2026-10-15T00:00:00Z' };
+  const body = buildCobrowseUpdate(current, { formFill: 'on', maxMinutes: '60' });
+  assert.deepEqual(body, { cuesEnabled: true, strictMaskMode: true, maxSessionMinutes: 60, blockedUrlPatterns: '/a\n/b', formFillEnabled: true });
+});
+
+test('default clears a setting back to the platform default', () => {
+  const body = buildCobrowseUpdate({ cuesEnabled: false, maxSessionMinutes: 30 }, { cues: 'default', maxMinutes: 'default' });
+  assert.equal(body.cuesEnabled, null);
+  assert.equal(body.maxSessionMinutes, null);
+});
+
+test('protected pages: default / none / explicit list', () => {
+  assert.equal(buildCobrowseUpdate({}, { protectedPages: 'default' }).blockedUrlPatterns, null);
+  assert.equal(buildCobrowseUpdate({}, { protectedPages: 'none' }).blockedUrlPatterns, '');
+  assert.equal(buildCobrowseUpdate({}, { protectedPages: '/checkout, /portal/pay ' }).blockedUrlPatterns, '/checkout\n/portal/pay');
+});
+
+test('teams and roles accept "none"', () => {
+  const body = buildCobrowseUpdate({ allowedTeamIds: '1,2', allowedRoles: 'Manager' }, { teams: 'none', roles: 'Agent' });
+  assert.equal(body.allowedTeamIds, null);
+  assert.equal(body.allowedRoles, 'Agent');
+});
+
+test('non-integer minutes are rejected before anything is sent', () => {
+  assert.throws(() => buildCobrowseUpdate({}, { maxMinutes: 'soon' }), /whole number/);
+});
+
+test('describeEffective renders a readable summary', () => {
+  const rows = describeEffective({ cuesEnabled: true, formFillEnabled: false, strictMask: false, disableOnMobile: false, blockedUrlPatterns: ['/checkout'], maxSessionMinutes: 120, idleStopMinutes: 15, allowedTeamIds: [], allowedRoles: [] });
+  assert.ok(rows.some(([k, v]) => k === 'Protected pages' && v === '/checkout'));
+  assert.ok(rows.some(([k, v]) => k === 'Who can start' && v === 'everyone with a seat'));
+});

package/lib/commands/cobrowse.js

@@ -0,0 +1,99 @@
+import { messagingGet, messagingPut } from '../api.js';
+import { buildCobrowseUpdate, describeEffective } from '../cobrowse-settings.js';
+
+// velaro cobrowse show|set|reset|sessions <siteId>
+//
+// Staff view and control of a site's Co-Browse configuration (what the plan entitles it to, what the site switched
+// on, the effective values after platform defaults and hard caps, and recent session metadata). Goes through the
+// messaging SuperAdmin endpoints, which share ONE validated service with the customer admin UI and the MCP tools,
+// so the CLI cannot store anything the UI cannot, and every change lands in the site's Activity Log.
+
+const RESET = '\x1b[0m';
+const BOLD  = '\x1b[1m';
+const DIM   = '\x1b[2m';
+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 siteArg = (y) => y.positional('siteId', { type: 'number', describe: 'Site id' });
+
+function printSite(data) {
+  const ent = data.entitlements ?? {};
+  const chip = (on) => (on ? `${GRN}yes${RESET}` : `${RED}no${RESET}`);
+  console.log(`\n${BOLD}Co-Browse - site ${data.siteId}${RESET}`);
+  console.log(`  Entitled:  Co-Browse ${chip(ent.coBrowse)}   Plus cues ${chip(ent.cues)}   Plus form fill ${chip(ent.formFill)}   Plus redaction ${chip(ent.enhancedPiiRedaction)}`);
+  console.log(`\n${BOLD}Effective settings${RESET} ${DIM}(null in the raw settings = platform default)${RESET}`);
+  for (const [k, v] of describeEffective(data.effective)) console.log(`  ${k.padEnd(26)} ${v}`);
+}
+
+const showCommand = {
+  command: 'show <siteId>',
+  describe: 'Show entitlement, settings and recent sessions for a site',
+  builder: siteArg,
+  handler: async (argv) => {
+    const data = await messagingGet(`/superadmin/sites/${argv.siteId}/cobrowse`);
+    if (argv.json) return console.log(JSON.stringify(data, null, 2));
+    printSite(data);
+    console.log(`\n${BOLD}Recent sessions${RESET} ${DIM}(metadata only, Pacific time)${RESET}`);
+    const rows = data.recentSessions ?? [];
+    if (rows.length === 0) console.log('  none');
+    for (const s of rows) {
+      console.log(`  ${fmtDate(s.startedAt).padEnd(18)} conv #${String(s.conversationId).padEnd(8)} agent ${String(s.initiatedByUserId ?? '-').padEnd(7)} ${String(s.durationSeconds ?? '-').padStart(5)}s  ${s.outcome ?? '-'}${s.endReason ? ` (${s.endReason})` : ''}`);
+    }
+  },
+};
+
+const setCommand = {
+  command: 'set <siteId>',
+  describe: 'Change Co-Browse settings for a site (only the flags you pass change)',
+  builder: (y) => siteArg(y)
+    .option('cues',            { type: 'string', describe: 'Agent pointer/highlight/annotation (Plus): on | off | default' })
+    .option('form-fill',       { type: 'string', describe: 'Guided form fill (Plus): on | off | default', alias: 'formFill' })
+    .option('strict-mask',     { type: 'string', describe: 'Strict mask mode: on | off | default', alias: 'strictMask' })
+    .option('disable-mobile',  { type: 'string', describe: 'Turn off on mobile: on | off | default', alias: 'disableMobile' })
+    .option('protected-pages', { type: 'string', describe: 'URL patterns (newline/comma separated), "default" or "none"', alias: 'protectedPages' })
+    .option('max-minutes',     { type: 'string', describe: 'Max session minutes (5-240) or default', alias: 'maxMinutes' })
+    .option('idle-minutes',    { type: 'string', describe: 'Idle auto-stop minutes (2-60) or default', alias: 'idleMinutes' })
+    .option('consent-title',   { type: 'string', alias: 'consentTitle' })
+    .option('consent-message', { type: 'string', alias: 'consentMessage' })
+    .option('consent-allow',   { type: 'string', alias: 'consentAllow' })
+    .option('teams',           { type: 'string', describe: 'Comma separated team ids allowed to start, or "none"' })
+    .option('roles',           { type: 'string', describe: 'Comma separated roles allowed to start (Administrator, Manager, Agent), or "none"' }),
+  handler: async (argv) => {
+    const current = await messagingGet(`/superadmin/sites/${argv.siteId}/cobrowse`);
+    const body = buildCobrowseUpdate(current.settings, argv);
+    const saved = await messagingPut(`/superadmin/sites/${argv.siteId}/cobrowse-settings`, body);
+    if (argv.json) return console.log(JSON.stringify(saved, null, 2));
+    console.log(`${GRN}Saved.${RESET} Effective settings now:`);
+    for (const [k, v] of describeEffective(saved.effective)) console.log(`  ${k.padEnd(26)} ${v}`);
+  },
+};
+
+const resetCommand = {
+  command: 'reset <siteId>',
+  describe: 'Reset every Co-Browse setting for a site to the platform defaults',
+  builder: siteArg,
+  handler: async (argv) => {
+    const saved = await messagingPut(`/superadmin/sites/${argv.siteId}/cobrowse-settings`, {});
+    if (argv.json) return console.log(JSON.stringify(saved, null, 2));
+    console.log(`${GRN}Reset to platform defaults.${RESET}`);
+    for (const [k, v] of describeEffective(saved.effective)) console.log(`  ${k.padEnd(26)} ${v}`);
+  },
+};
+
+export const cobrowseCommand = {
+  command: 'cobrowse <subcommand>',
+  describe: 'View and control a site\'s Co-Browse settings and session history',
+  builder: (y) => y
+    .option('json', { type: 'boolean', describe: 'Print raw JSON' })
+    .command(showCommand)
+    .command(setCommand)
+    .command(resetCommand)
+    .demandCommand(1, 'Specify a subcommand: show, set, reset')
+    .strict(),
+  handler: () => {},
+};

package/lib/commands/migrate.js

@@ -12,7 +12,8 @@ export const migrateCommand = {
       .command(migrateTeamsCommand)
       .command(migrateWorkflowsCommand)
       .command(migrateRulesCommand)
-      .demandCommand(1, 'Specify a subcommand: export, livefluence, url-rules, teams, workflows, rules'),
+      .command(migrateAdviseCommand)
+      .demandCommand(1, 'Specify a subcommand: export, livefluence, url-rules, teams, workflows, rules, advise'),
   handler: () => {},
 };
 
@@ -321,3 +322,52 @@ const migrateRulesCommand = {
       .demandCommand(1, 'Specify: list, set-enabled'),
   handler: () => {},
 };
+
+// ── conversion advisor: consolidated v20 design from a v10 site or an intent list ──
+
+const migrateAdviseCommand = {
+  command:  'advise',
+  describe: 'Livefluence conversion advisor: recommend (dry run, default) or build (--apply) a consolidated v20 routing design. Staff only.',
+  builder:  (y) =>
+    y
+      .option('v10-site-id', { type: 'number', alias: 'v', describe: 'V10 (Livefluence) site to read (omit when using --intents)' })
+      .option('v20-site-id', { type: 'number', alias: 's', describe: 'V20 destination site ID', demandOption: true })
+      .option('intents',     { type: 'string', describe: 'JSON array (or @file.json) of intents: [{"intent":"support","paths":["/support"],"device":"any","target":"Service team + troubleshooting AI node"}]' })
+      .option('apply',       { type: 'boolean', default: false, describe: 'Create missing teams and DISABLED workflows (default: dry run + diff)' })
+      .option('include-non-routing', { type: 'boolean', default: false, describe: 'Also read v10 rules with IsRouting=false (group-assignment rules)' }),
+  handler:  runCommand(async (argv) => {
+    let intents = null;
+    if (argv.intents) {
+      const raw = argv.intents.startsWith('@')
+        ? (await import('node:fs')).readFileSync(argv.intents.slice(1), 'utf8')
+        : argv.intents;
+      intents = JSON.parse(raw);
+    }
+    if (!intents && !argv['v10-site-id']) throw new Error('Give -v <v10 site> or --intents.');
+
+    const result = await post('/DatabaseTool/ConversionAdvisor', {
+      v10SiteId: intents ? null : argv['v10-site-id'],
+      v20SiteId: argv['v20-site-id'],
+      apply: argv.apply,
+      includeNonRouting: argv['include-non-routing'],
+      intents,
+    });
+
+    console.log(`\n${'─'.repeat(60)}`);
+    console.log(`  Conversion advisor (${result.source}) -> V20 site ${result.v20SiteId}  ${result.dryRun ? 'DRY RUN' : 'APPLIED (all workflows disabled)'}`);
+    if (result.v10RuleCount) console.log(`  ${result.v10RuleCount} v10 rule(s) -> ${result.consolidatedWorkflows} workflow(s)`);
+    console.log(`${'─'.repeat(60)}\n`);
+    for (const t of result.teams ?? [])
+      console.log(`  team  ${t.status.padEnd(8)} ${t.name}${t.v10Members ? ` (${t.v10Members} v10 members, assign v20 agents by hand)` : ''}`);
+    console.log('');
+    for (const w of result.workflows ?? []) {
+      console.log(`  [${w.status}] #${w.priority} ${w.name}  mode=${w.mode}${w.device !== 'any' ? `  device=${w.device}` : ''}`);
+      console.log(`       team: ${w.teamName ?? '-'}   AI node: ${w.aiNodeName ?? '-'}   condition groups (OR): ${w.conditionGroups}`);
+      if (w.statusReason) console.log(`       ${w.statusReason}`);
+      for (const x of w.warnings ?? []) console.log(`       ! ${x}`);
+    }
+    if (result.existingNotInPlan?.length) console.log(`\n  Already on the v20 site, not in this plan: ${result.existingNotInPlan.join(', ')}`);
+    for (const n of result.notes ?? []) console.log(`  note: ${n}`);
+    console.log(`\n  ${result.message}\n`);
+  }),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/cli",
-  "version": "1.4.99",
+  "version": "1.4.101",
   "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, MCP API keys, search indexes, and ops health.",
   "type": "module",
   "bin": {