@velaro/cli 1.4.77 → 1.4.78

package/bin/velaro.js

@@ -10,6 +10,7 @@ import { botCommand }        from '../lib/commands/bot.js';
 import { indexCommand }      from '../lib/commands/index.js';
 import { ingestCommand }     from '../lib/commands/ingest.js';
 import { indexMoveCommand }  from '../lib/commands/index-move.js';
+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';
@@ -56,6 +57,8 @@ import { focusCommand }       from '../lib/commands/focus.js';
 import { triageCommand }      from '../lib/commands/triage.js';
 import { automationDraftCommand } from '../lib/commands/automation-draft.js';
 import { magentoCommand }       from '../lib/commands/magento.js';
+import { sapCommand }           from '../lib/commands/sap.js';
+import { actionsCommand }       from '../lib/commands/actions.js';
 import { mondayCommand }        from '../lib/commands/monday.js';
 import { notionCommand }        from '../lib/commands/notion.js';
 import { callrailCommand }      from '../lib/commands/callrail.js';
@@ -122,6 +125,7 @@ await yargs(hideBin(process.argv))
   .command(indexCommand)
   .command(ingestCommand)
   .command(indexMoveCommand)
+  .command(knowledgeAdvisorCommand)
   .command(productCommand)
   .command(mcpKeyCommand)
   .command(opsCommand)
@@ -170,6 +174,8 @@ await yargs(hideBin(process.argv))
   .command(triageCommand)
   .command(automationDraftCommand)
   .command(magentoCommand)
+  .command(sapCommand)
+  .command(actionsCommand)
   .command(mondayCommand)
   .command(notionCommand)
   .command(callrailCommand)

package/lib/api.js

@@ -60,7 +60,7 @@ export const post = (path, body) => request('POST',   path, body);
 export const put  = (path, body) => request('PUT',    path, body);
 export const del  = (path)       => request('DELETE', path);
 
-export async function messagingRequest(method, path, body, envOverride) {
+export async function messagingRequest(method, path, body, envOverride, extraHeaders = {}) {
   const creds = await getCredentials(envOverride);
   const res = await fetch(joinUrl(creds.messagingApiBase, path), {
     method,
@@ -72,6 +72,7 @@ export async function messagingRequest(method, path, body, envOverride) {
       // trust boundary override. Still required: every messaging* CLI command was silently
       // 401ing with "missing_site_id" until this was added.
       ...(creds.siteId ? { 'vmsg-siteId': String(creds.siteId) } : {}),
+      ...extraHeaders,
     },
     body: body !== undefined ? JSON.stringify(body) : undefined,
   });

package/lib/commands/actions.js

@@ -0,0 +1,105 @@
+/**
+ * velaro actions — shared business actions (one definition, many surfaces)
+ *
+ *   velaro actions list                              Registered business actions + their AI skill tool names
+ *   velaro actions route "<text>"                    Which action does this request mean? (deterministic)
+ *   velaro actions run <name> --json '<request>'     Execute an action as the signed-in agent
+ *                          [--idempotency-key K]     (writes: same key => same result, never a duplicate)
+ *
+ * Calls messaging GET /BusinessActions, POST /BusinessActions/Route and POST /BusinessActions/{name}/Execute.
+ * Site scope always comes from the signed-in identity, never from a flag.
+ */
+
+import { messagingRequest } from '../api.js';
+
+const GRN  = '\x1b[32m';
+const RED  = '\x1b[31m';
+const DIM  = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RST  = '\x1b[0m';
+
+async function listHandler(argv) {
+  try {
+    const rows = await messagingRequest('GET', '/BusinessActions');
+    if (argv.json) { console.log(JSON.stringify(rows, null, 2)); return; }
+    console.log(`\n${BOLD}${rows.length} business action(s)${RST}\n`);
+    for (const a of rows) {
+      const kind = a.isWrite ? `${RED}write${RST}` : `${GRN}read${RST}`;
+      console.log(`  ${BOLD}${a.name}${RST}  ${DIM}${a.displayName} | ${kind} | ${a.dataClass} | cache ${a.freshnessSeconds}s${RST}`);
+      if (a.skillToolNames?.length) console.log(`      ${DIM}AI skills: ${a.skillToolNames.join(', ')}${RST}`);
+    }
+    console.log('');
+  } catch (e) {
+    console.error(`\n${RED}✗ ${e.message}${RST}\n`);
+    process.exitCode = 1;
+  }
+}
+
+async function routeHandler(argv) {
+  const text = argv.text;
+  try {
+    const r = await messagingRequest('POST', '/BusinessActions/Route', { text, max: argv.max });
+    if (argv.json) { console.log(JSON.stringify(r, null, 2)); return; }
+    if (!r.matches?.length) { console.log('\nNo business action matches that request.\n'); return; }
+    console.log('');
+    for (const m of r.matches) {
+      console.log(`  ${BOLD}${m.actionName}${RST}  score ${m.score}  ${DIM}matched: ${(m.matchedTerms ?? []).join(', ')}${RST}`);
+    }
+    console.log('');
+  } catch (e) {
+    console.error(`\n${RED}✗ ${e.message}${RST}\n`);
+    process.exitCode = 1;
+  }
+}
+
+async function runHandler(argv) {
+  let body;
+  try {
+    body = argv.json ? JSON.parse(argv.json) : {};
+  } catch (e) {
+    console.error(`${RED}✗ --json is not valid JSON: ${e.message}${RST}`);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const headers = argv['idempotency-key'] ? { 'Idempotency-Key': argv['idempotency-key'] } : {};
+    const r = await messagingRequest('POST', `/BusinessActions/${encodeURIComponent(argv.name)}/Execute`, body, undefined, headers);
+    console.log(JSON.stringify(r, null, 2));
+    if (!r.success) process.exitCode = 1;
+  } catch (e) {
+    console.error(`\n${RED}✗ ${e.message}${RST}\n`);
+    process.exitCode = 1;
+  }
+}
+
+export const actionsCommand = {
+  command:  'actions <subcommand>',
+  describe: 'Shared business actions (pricing, quotes, ... served by Velaro catalog or a connected ERP)',
+  builder: y => y
+    .command({
+      command:  'list',
+      describe: 'List registered business actions',
+      builder: yy => yy.option('json', { type: 'boolean', default: false }),
+      handler: listHandler,
+    })
+    .command({
+      command:  'route <text>',
+      describe: 'Which business action does this request mean?',
+      builder: yy => yy
+        .positional('text', { describe: 'The request text', type: 'string' })
+        .option('max',  { type: 'number', default: 3 })
+        .option('json', { type: 'boolean', default: false }),
+      handler: routeHandler,
+    })
+    .command({
+      command:  'run <name>',
+      describe: 'Execute a business action',
+      builder: yy => yy
+        .positional('name', { describe: 'Action name (see `velaro actions list`)', type: 'string' })
+        .option('json', { describe: 'Request body as JSON', type: 'string' })
+        .option('idempotency-key', { describe: 'For writes: repeat the same key to get the same result', type: 'string' }),
+      handler: runHandler,
+    })
+    .demandCommand(1),
+  handler: () => {},
+};

package/lib/commands/ai-config.js

@@ -194,6 +194,19 @@ const aiConfigSetChannelOverrideCommand = {
   }),
 };
 
+const aiConfigSetReplyFormatCommand = {
+  command:  'set-reply-format <id>',
+  describe: 'Set reply format: global (plain text default) | plain | markdown',
+  builder:  (y) =>
+    y
+      .positional('id', { type: 'number', describe: 'AI configuration ID' })
+      .option('mode',   { type: 'string', choices: ['global', 'plain', 'markdown'], demandOption: true, describe: 'Reply format mode' }),
+  handler:  runCommand(async (argv) => {
+    const r = await messagingPut(`/AIConfiguration/${argv.id}/reply-format`, { mode: argv.mode });
+    console.log(`Reply format set: ai-config=${argv.id} mode=${argv.mode} effective=${r?.effectivePlainText ? 'plain text' : 'markdown allowed'}`);
+  }),
+};
+
 // ── resolved-model ────────────────────────────────────────────────────────────
 // Voice preview (GET avatar/voices/{voiceId}/preview) is intentionally UI-only: it streams binary
 // audio for a browser <audio> element and has no useful CLI/MCP shape.

package/lib/commands/knowledge-advisor.js

@@ -0,0 +1,64 @@
+// velaro knowledge-advisor advise — tells you, per kind of data (manuals, catalog, price list, cross-reference
+// sheet, photos, CAD), whether to embed all, embed some, use exact lookup or query live, exactly what to upload and a
+// rough size estimate. Pure computation: nothing is read from or written to your site. Wraps velaro-messaging
+// KnowledgeAdvisorController (POST KnowledgeAdvisor/advise). Numbers are estimates.
+import fs from 'node:fs';
+import { messagingPost } from '../api.js';
+import { runCommand } from '../run.js';
+
+const n = (v) => (v ?? 0).toLocaleString('en-US');
+
+export function sourcesFrom(argv) {
+  if (argv.file) {
+    const parsed = JSON.parse(fs.readFileSync(argv.file, 'utf8'));
+    const list = Array.isArray(parsed) ? parsed : parsed.sources;
+    if (!Array.isArray(list) || list.length === 0) throw new Error('The file must be a JSON array of sources or { "sources": [...] }.');
+    return list;
+  }
+  if (!argv.kind) throw new Error('Give --kind (for example manual_pdf) or --file sources.json.');
+  return [{
+    name: argv.name,
+    kind: argv.kind,
+    pages: argv.pages,
+    rows: argv.rows,
+    changeFrequency: argv['change-frequency'],
+    hasExactIdentifiers: !!argv['exact-ids'],
+    scanned: !!argv.scanned,
+    hasLiveSystem: !!argv['live-system'],
+  }];
+}
+
+export function printAdvice(a) {
+  for (const s of a.sources ?? []) {
+    console.log(`\n${s.name} (${s.kind}): ${s.recommendation}`);
+    for (const w of s.why ?? []) console.log(`  Why: ${w}`);
+    console.log(`  What to upload: ${s.whatToUpload}`);
+    const e = s.estimate ?? {};
+    console.log(`  Estimate: ${n(e.pages)} pages, ${n(e.chunks)} chunks`);
+  }
+  console.log(`\nTotal: about ${n(a.totalChunks)} chunks. Each answer retrieves about ${n(a.perAnswerRetrievalTokens)} tokens of your content. (${a.basis})`);
+  for (const note of a.notes ?? []) console.log(`Note: ${note}`);
+}
+
+export const knowledgeAdvisorCommand = {
+  command: 'knowledge-advisor',
+  describe: 'Advise what to upload, embed or query live for your bot (estimates, nothing is changed)',
+  builder: (yargs) => yargs
+    .command('advise', 'Recommend embed all / embed some / exact lookup / live query per data source', (y) => y
+      .option('file', { type: 'string', describe: 'JSON file: an array of sources or { "sources": [...] }' })
+      .option('kind', { type: 'string', describe: 'manual_pdf | spec_sheet | policy_document | faq_or_help_pages | product_catalog | price_list | cross_reference_sheet | images_or_drawings | cad_files | other_documents' })
+      .option('name', { type: 'string' })
+      .option('pages', { type: 'number' })
+      .option('rows', { type: 'number' })
+      .option('change-frequency', { type: 'string', describe: 'static | monthly | weekly | daily | realtime' })
+      .option('exact-ids', { type: 'boolean', describe: 'answers depend on exact part numbers / SKUs' })
+      .option('scanned', { type: 'boolean', describe: 'the PDF is scanned images' })
+      .option('live-system', { type: 'boolean', describe: 'a connected store/ERP/CRM can be queried for this data' })
+      .option('json', { type: 'boolean' }),
+    runCommand(async (a) => {
+      const r = await messagingPost('/KnowledgeAdvisor/advise', { sources: sourcesFrom(a) });
+      if (a.json) console.log(JSON.stringify(r, null, 2)); else printAdvice(r);
+    }))
+    .demandCommand(1, 'Specify a subcommand: advise'),
+  handler: () => {},
+};

package/lib/commands/sap.js

@@ -0,0 +1,101 @@
+/**
+ * velaro sap — SAP integration diagnostics (S/4HANA, Business One, ECC via gateway)
+ *
+ *   velaro sap diagnose --site-id <id> [--quick]   Live read-only diagnostic: config, auth, per-capability probes
+ *   velaro sap matrix   --site-id <id>             Capability matrix vs live probes (same data as diagnose)
+ *
+ * Calls messaging DiagController GET /diagnostics/test-sap?siteId=<id>&deep=<bool> (Velaro staff only). Read-only:
+ * nothing is created or changed in SAP, and a write capability is never reported as verified.
+ */
+
+import { messagingRequest } from '../api.js';
+
+const GRN  = '\x1b[32m';
+const RED  = '\x1b[31m';
+const YEL  = '\x1b[33m';
+const DIM  = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RST  = '\x1b[0m';
+
+const ICON = { pass: `${GRN}✓${RST}`, warn: `${YEL}!${RST}`, fail: `${RED}✗${RST}`, skip: `${DIM}-${RST}` };
+
+async function fetchReport(argv, deep) {
+  const siteId = argv['site-id'];
+  if (!siteId) {
+    console.error(`${RED}✗ --site-id is required${RST}`);
+    process.exitCode = 1;
+    return null;
+  }
+  try {
+    const r = await messagingRequest('GET', `/diagnostics/test-sap?siteId=${encodeURIComponent(siteId)}&deep=${deep ? 'true' : 'false'}`);
+    return r?.report ?? r;
+  } catch (e) {
+    console.error(`\n${RED}✗ Diagnostic failed: ${e.message}${RST}\n`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+function printSteps(report) {
+  console.log(`\n${BOLD}SAP diagnostic — site ${report.siteId ?? report.SiteId}${RST}  ${DIM}${report.product} / ${report.target}${RST}`);
+  console.log(`  overall: ${String(report.overall).toUpperCase()}\n`);
+  for (const s of report.steps ?? []) {
+    const ms = s.latencyMs != null ? `${DIM} (${s.latencyMs}ms)${RST}` : '';
+    console.log(`  ${ICON[s.status] ?? '?'} ${s.name}${ms}${s.detail ? `  ${DIM}${s.detail}${RST}` : ''}`);
+    if (s.hint) console.log(`      ${DIM}→ ${s.hint}${RST}`);
+  }
+}
+
+function printCapabilities(report) {
+  const caps = report.capabilities ?? [];
+  if (!caps.length) return;
+  console.log(`\n${BOLD}Capabilities${RST} ${DIM}(documented = capability matrix; live = read-only probe now)${RST}\n`);
+  for (const c of caps) {
+    const live = c.liveOk === true ? `${GRN}live ok${RST}` : c.liveOk === false ? `${RED}live FAIL${RST}` : `${DIM}not probed${RST}`;
+    const proven = c.liveVerified ? `${GRN}verified${RST}` : `${DIM}unverified${RST}`;
+    console.log(`  ${c.capability.padEnd(22)} ${String(c.documented).padEnd(28)} ${live}  ${proven}`);
+    if (c.liveOk === false && c.hint) console.log(`      ${DIM}→ ${c.hint}${RST}`);
+  }
+  console.log('');
+}
+
+async function diagnoseHandler(argv) {
+  const report = await fetchReport(argv, !argv.quick);
+  if (!report) return;
+  if (argv.json) { console.log(JSON.stringify(report, null, 2)); return; }
+  printSteps(report);
+  printCapabilities(report);
+  if (report.overall === 'failed' || report.overall === 'not_configured') process.exitCode = 1;
+}
+
+async function matrixHandler(argv) {
+  const report = await fetchReport(argv, true);
+  if (!report) return;
+  if (argv.json) { console.log(JSON.stringify(report.capabilities ?? [], null, 2)); return; }
+  printCapabilities(report);
+}
+
+export const sapCommand = {
+  command:  'sap <subcommand>',
+  describe: 'SAP integration diagnostics (S/4HANA, Business One, ECC gateway)',
+  builder: y => y
+    .command({
+      command:  'diagnose',
+      describe: 'Live read-only diagnostic: configuration, authentication, per-capability probes',
+      builder: yy => yy
+        .option('site-id', { describe: 'Customer site id', type: 'number' })
+        .option('quick',   { describe: 'Skip per-capability probes', type: 'boolean', default: false })
+        .option('json',    { describe: 'Raw JSON output', type: 'boolean', default: false }),
+      handler: diagnoseHandler,
+    })
+    .command({
+      command:  'matrix',
+      describe: 'Capability matrix: documented support vs what a live probe proves',
+      builder: yy => yy
+        .option('site-id', { describe: 'Customer site id', type: 'number' })
+        .option('json',    { describe: 'Raw JSON output', type: 'boolean', default: false }),
+      handler: matrixHandler,
+    })
+    .demandCommand(1),
+  handler: () => {},
+};

package/package.json

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