@velaro/cli 0.2.0 → 0.3.0

package/lib/commands/kb.js

@@ -1,132 +1,241 @@
-import { get, post, del } from '../api.js';
-import { requireFeature }  from '../subscription.js';
-import { runCommand }      from '../run.js';
-
-export const kbCommand = {
-  command:  'kb <subcommand>',
-  describe: 'Manage knowledge base — Q&A pairs and bot overrides',
-  builder:  (yargs) =>
-    yargs
-      .command(qnaCommand)
-      .command(overrideCommand)
-      .demandCommand(1, 'Specify a subcommand: qna, override'),
-  handler: () => {},
-};
-
-// ────────────────────────────────────────────────────────────────────────────
-// Q&A
-// ────────────────────────────────────────────────────────────────────────────
-
-const qnaCommand = {
-  command:  'qna <subcommand>',
-  describe: 'Manage Q&A knowledge pairs',
-  builder:  (yargs) =>
-    yargs
-      .command({
-        command:  'list',
-        describe: 'List Q&A pairs',
-        builder:  (y) => y.option('bot-id', { type: 'number', describe: 'Filter by bot ID' }),
-        handler:  runCommand(async (argv) => {
-          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-          const params = argv['bot-id'] ? `?aiConfigurationId=${argv['bot-id']}` : '';
-          const items  = await get(`/api/BotQnA${params}`);
-          if (!items?.length) { console.log('No Q&A pairs found.'); return; }
-
-          console.log(`\nFound ${items.length} Q&A pair(s):\n`);
-          for (const item of items) {
-            console.log(`  [${item.id}] Q: ${truncate(item.question, 70)}`);
-            console.log(`       A: ${truncate(item.answer, 70)}\n`);
-          }
-        }),
-      })
-      .command({
-        command:  'add',
-        describe: 'Add a Q&A pair',
-        builder:  (y) =>
-          y
-            .option('bot-id',   { type: 'number', demandOption: true, describe: 'Bot ID' })
-            .option('question', { type: 'string', demandOption: true, describe: 'Question text' })
-            .option('answer',   { type: 'string', demandOption: true, describe: 'Answer text' }),
-        handler: runCommand(async (argv) => {
-          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-          const result = await post('/api/BotQnA', {
-            aiConfigurationId: argv['bot-id'],
-            question:          argv.question,
-            answer:            argv.answer,
-          });
-          console.log(`Q&A pair added: [${result.id}]`);
-        }),
-      })
-      .command({
-        command:  'delete <id>',
-        describe: 'Delete a Q&A pair',
-        builder:  (y) => y.positional('id', { type: 'number', describe: 'Q&A pair ID' }),
-        handler: runCommand(async (argv) => {
-          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-          await del(`/api/BotQnA/${argv.id}`);
-          console.log(`Q&A pair ${argv.id} deleted.`);
-        }),
-      })
-      .demandCommand(1, 'Specify a subcommand: list, add, delete'),
-  handler: () => {},
-};
-
-// ────────────────────────────────────────────────────────────────────────────
-// Overrides — authoritative facts that take priority over KB search
-// ────────────────────────────────────────────────────────────────────────────
-
-const overrideCommand = {
-  command:  'override <subcommand>',
-  describe: 'Manage bot knowledge overrides (authoritative facts)',
-  builder:  (yargs) =>
-    yargs
-      .command({
-        command:  'list',
-        describe: 'List knowledge overrides',
-        handler:  runCommand(async () => {
-          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-          const items = await get('/Ticket/knowledge-overrides');
-          if (!items?.length) { console.log('No overrides found.'); return; }
-
-          console.log(`\nFound ${items.length} override(s):\n`);
-          for (const item of items) {
-            const status = item.isActive ? 'active  ' : 'inactive';
-            const expiry = item.expiresAt ? `  expires ${new Date(item.expiresAt).toLocaleDateString()}` : '';
-            console.log(`  [${item.id}] ${status}  ${truncate(item.title ?? item.content, 60)}${expiry}`);
-          }
-        }),
-      })
-      .command({
-        command:  'add',
-        describe: 'Add a knowledge override',
-        builder:  (y) =>
-          y
-            .option('title',   { type: 'string', demandOption: true, describe: 'Override title' })
-            .option('content', { type: 'string', demandOption: true, describe: 'Authoritative content' })
-            .option('expires', { type: 'string',                     describe: 'Expiry date (ISO 8601, e.g. 2026-12-31)' }),
-        handler: runCommand(async (argv) => {
-          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-          const payload = { title: argv.title, content: argv.content, isActive: true };
-          if (argv.expires) payload.expiresAt = new Date(argv.expires).toISOString();
-          const result = await post('/Ticket/knowledge-overrides', payload);
-          console.log(`Override added: [${result.id}] "${argv.title}"`);
-        }),
-      })
-      .command({
-        command:  'delete <id>',
-        describe: 'Delete a knowledge override',
-        builder:  (y) => y.positional('id', { type: 'number', describe: 'Override ID' }),
-        handler: runCommand(async (argv) => {
-          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-          await del(`/Ticket/knowledge-overrides/${argv.id}`);
-          console.log(`Override ${argv.id} deleted.`);
-        }),
-      })
-      .demandCommand(1, 'Specify a subcommand: list, add, delete'),
-  handler: () => {},
-};
-
-function truncate(str, max) {
-  if (!str) return '—';
-  return str.length <= max ? str : str.slice(0, max - 1) + '…';
-}
+import { readFileSync }    from 'fs';
+import { basename }        from 'path';
+import { get, post, del }  from '../api.js';
+import { requireFeature }  from '../subscription.js';
+import { runCommand }      from '../run.js';
+import { articleCommand }  from './article.js';
+
+export const kbCommand = {
+  command:  'kb <subcommand>',
+  describe: 'Manage knowledge base — articles, Q&A pairs, bot overrides, and custom content',
+  builder:  (yargs) =>
+    yargs
+      .command(articleCommand)
+      .command(qnaCommand)
+      .command(overrideCommand)
+      .command(contentCommand)
+      .demandCommand(1, 'Specify a subcommand: article, qna, override, content'),
+  handler: () => {},
+};
+
+// ────────────────────────────────────────────────────────────────────────────
+// Q&A
+// ────────────────────────────────────────────────────────────────────────────
+
+const qnaCommand = {
+  command:  'qna <subcommand>',
+  describe: 'Manage Q&A knowledge pairs',
+  builder:  (yargs) =>
+    yargs
+      .command({
+        command:  'list',
+        describe: 'List Q&A pairs',
+        builder:  (y) => y.option('bot-id', { type: 'number', describe: 'Filter by bot ID' }),
+        handler:  runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          const params = argv['bot-id'] ? `?aiConfigurationId=${argv['bot-id']}` : '';
+          const items  = await get(`/api/BotQnA${params}`);
+          if (!items?.length) { console.log('No Q&A pairs found.'); return; }
+
+          console.log(`\nFound ${items.length} Q&A pair(s):\n`);
+          for (const item of items) {
+            console.log(`  [${item.id}] Q: ${truncate(item.question, 70)}`);
+            console.log(`       A: ${truncate(item.answer, 70)}\n`);
+          }
+        }),
+      })
+      .command({
+        command:  'add',
+        describe: 'Add a Q&A pair',
+        builder:  (y) =>
+          y
+            .option('bot-id',   { type: 'number', demandOption: true, describe: 'Bot ID' })
+            .option('question', { type: 'string', demandOption: true, describe: 'Question text' })
+            .option('answer',   { type: 'string', demandOption: true, describe: 'Answer text' }),
+        handler: runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          const result = await post('/api/BotQnA', {
+            aiConfigurationId: argv['bot-id'],
+            question:          argv.question,
+            answer:            argv.answer,
+          });
+          console.log(`Q&A pair added: [${result.id}]`);
+        }),
+      })
+      .command({
+        command:  'delete <id>',
+        describe: 'Delete a Q&A pair',
+        builder:  (y) => y.positional('id', { type: 'number', describe: 'Q&A pair ID' }),
+        handler: runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          await del(`/api/BotQnA/${argv.id}`);
+          console.log(`Q&A pair ${argv.id} deleted.`);
+        }),
+      })
+      .demandCommand(1, 'Specify a subcommand: list, add, delete'),
+  handler: () => {},
+};
+
+// ────────────────────────────────────────────────────────────────────────────
+// Overrides — authoritative facts that take priority over KB search
+// ────────────────────────────────────────────────────────────────────────────
+
+const overrideCommand = {
+  command:  'override <subcommand>',
+  describe: 'Manage bot knowledge overrides (authoritative facts)',
+  builder:  (yargs) =>
+    yargs
+      .command({
+        command:  'list',
+        describe: 'List knowledge overrides',
+        handler:  runCommand(async () => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          const items = await get('/Ticket/knowledge-overrides');
+          if (!items?.length) { console.log('No overrides found.'); return; }
+
+          console.log(`\nFound ${items.length} override(s):\n`);
+          for (const item of items) {
+            const status = item.isActive ? 'active  ' : 'inactive';
+            const expiry = item.expiresAt ? `  expires ${new Date(item.expiresAt).toLocaleDateString()}` : '';
+            console.log(`  [${item.id}] ${status}  ${truncate(item.title ?? item.content, 60)}${expiry}`);
+          }
+        }),
+      })
+      .command({
+        command:  'add',
+        describe: 'Add a knowledge override',
+        builder:  (y) =>
+          y
+            .option('title',   { type: 'string', demandOption: true, describe: 'Override title' })
+            .option('content', { type: 'string', demandOption: true, describe: 'Authoritative content' })
+            .option('expires', { type: 'string',                     describe: 'Expiry date (ISO 8601, e.g. 2026-12-31)' }),
+        handler: runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          const payload = { title: argv.title, content: argv.content, isActive: true };
+          if (argv.expires) payload.expiresAt = new Date(argv.expires).toISOString();
+          const result = await post('/Ticket/knowledge-overrides', payload);
+          console.log(`Override added: [${result.id}] "${argv.title}"`);
+        }),
+      })
+      .command({
+        command:  'delete <id>',
+        describe: 'Delete a knowledge override',
+        builder:  (y) => y.positional('id', { type: 'number', describe: 'Override ID' }),
+        handler: runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          await del(`/Ticket/knowledge-overrides/${argv.id}`);
+          console.log(`Override ${argv.id} deleted.`);
+        }),
+      })
+      .demandCommand(1, 'Specify a subcommand: list, add, delete'),
+  handler: () => {},
+};
+
+// ────────────────────────────────────────────────────────────────────────────
+// Custom content — push arbitrary text/files into the site's KB index
+// ────────────────────────────────────────────────────────────────────────────
+// Note: content goes into the site's default index (determined server-side by
+// SiteId). Index selection is not yet supported by this API endpoint.
+
+const contentCommand = {
+  command:  'content <subcommand>',
+  describe: 'Push custom text or files into the knowledge base index',
+  builder:  (yargs) =>
+    yargs
+      .command({
+        command:  'ingest',
+        describe: 'Push a file or text snippet into the KB index',
+        builder:  (y) =>
+          y
+            .option('file', {
+              describe: 'Path to a .txt or .md file to ingest',
+              type:     'string',
+            })
+            .option('text', {
+              describe: 'Inline text content to ingest (alternative to --file)',
+              type:     'string',
+            })
+            .option('content-id', {
+              describe: 'Stable ID for this document (used for dedup/updates). Defaults to filename.',
+              type:     'string',
+            })
+            .option('title', {
+              describe: 'Document title shown when bot attributes this content. Defaults to filename.',
+              type:     'string',
+            })
+            .option('source-url', {
+              describe: 'Canonical URL to show when bot cites this content',
+              type:     'string',
+            })
+            .check((argv) => {
+              if (!argv.file && !argv.text) throw new Error('Provide either --file or --text');
+              if (argv.file && argv.text)   throw new Error('Use --file or --text, not both');
+              return true;
+            }),
+        handler: runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+
+          let text, defaultId, defaultTitle;
+          if (argv.file) {
+            text         = readFileSync(argv.file, 'utf8');
+            defaultId    = basename(argv.file);
+            defaultTitle = basename(argv.file);
+          } else {
+            text         = argv.text;
+            defaultId    = `inline-${Date.now()}`;
+            defaultTitle = defaultId;
+          }
+
+          const contentId = argv['content-id'] || defaultId;
+          const title     = argv.title          || defaultTitle;
+
+          const result = await post('/AzureIndexes/IngestContent', {
+            contentId,
+            title,
+            text,
+            sourceUrl: argv['source-url'] || undefined,
+          });
+
+          if (result.unchanged) {
+            console.log(`Unchanged: "${title}" — content hash matches, no re-embedding needed.`);
+          } else {
+            console.log(`Indexed:   "${title}"  [${contentId}]`);
+            console.log(`           ${result.chunks} chunk(s) embedded and searchable immediately.`);
+          }
+        }),
+      })
+      .command({
+        command:  'list',
+        describe: 'List all custom content documents in the KB index',
+        handler:  runCommand(async () => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          const items = await get('/AzureIndexes/IngestContent');
+          if (!items?.length) { console.log('No custom content found.'); return; }
+
+          console.log(`\nFound ${items.length} document(s):\n`);
+          for (const item of items) {
+            const indexed = item.lastIndexedAt ? new Date(item.lastIndexedAt).toLocaleDateString() : 'never';
+            const status  = item.lastError ? `  error: ${item.lastError}` : '';
+            console.log(`  [${item.contentId}]  chunks=${item.chunkCount ?? '?'}  indexed=${indexed}${status}`);
+            if (item.title && item.title !== item.contentId) console.log(`    "${item.title}"`);
+          }
+        }),
+      })
+      .command({
+        command:  'remove <content-id>',
+        describe: 'Remove a custom content document from the KB index',
+        builder:  (y) => y.positional('content-id', { type: 'string', describe: 'Content ID to remove' }),
+        handler:  runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          await del(`/AzureIndexes/IngestContent/${encodeURIComponent(argv['content-id'])}`);
+          console.log(`Removed "${argv['content-id']}" from the index.`);
+        }),
+      })
+      .demandCommand(1, 'Specify a subcommand: ingest, list, remove'),
+  handler: () => {},
+};
+
+function truncate(str, max) {
+  if (!str) return '—';
+  return str.length <= max ? str : str.slice(0, max - 1) + '…';
+}

package/lib/commands/login.js

@@ -1,59 +1,60 @@
-import { requestDeviceCode, pollForToken, exchangeForVelaroToken } from '../oauth.js';
-import { readConfig, writeConfig, DEFAULT_API_BASE, STAGING_API_BASE } from '../config.js';
-import { runCommand }                                               from '../run.js';
-
-export const loginCommand = {
-  command:  'login',
-  describe: 'Authenticate with Velaro using your browser',
-  builder:  (y) =>
-    y
-      .option('staging', {
-        describe: 'Connect to the Velaro staging environment',
-        type:     'boolean',
-        default:  false,
-      })
-      .option('api', {
-        describe: 'Override the Velaro API base URL (advanced)',
-        type:     'string',
-      }),
-
-  handler: runCommand(async (argv) => {
-    const apiBase = argv.api ?? (argv.staging ? STAGING_API_BASE : DEFAULT_API_BASE);
-
-    console.log('Starting Velaro login...\n');
-
-    const deviceData = await requestDeviceCode();
-
-    console.log(`  Open:  ${deviceData.verification_uri}`);
-    console.log(`  Enter: ${deviceData.user_code}\n`);
-    console.log('Waiting for you to complete login in your browser...');
-
-    const entraTokens  = await pollForToken(deviceData.device_code, deviceData.interval ?? 5);
-    const velaroResult = await exchangeForVelaroToken(entraTokens.access_token, apiBase);
-
-    writeConfig({
-      ...readConfig(),
-      apiBase,
-      velaroToken:       velaroResult.token.token,
-      velaroExpires:     velaroResult.token.expires,
-      entraRefreshToken: entraTokens.refresh_token,
-      siteId:            velaroResult.profile?.SiteId,
-      userName:          velaroResult.profile?.Name,
-    });
-
-    const envLabel = argv.staging || argv.api ? ` (${apiBase})` : '';
-    console.log(`\nLogged in as ${velaroResult.profile?.Name ?? velaroResult.profile?.UserName}${envLabel}`);
-    console.log(`Site ID: ${velaroResult.profile?.SiteId}`);
-    console.log('Credentials saved to ~/.velaro/config.json');
-  }),
-};
-
-export const logoutCommand = {
-  command:  'logout',
-  describe: 'Clear stored credentials',
-  handler:  runCommand(async () => {
-    const { clearConfig } = await import('../config.js');
-    clearConfig();
-    console.log('Logged out. Credentials removed from ~/.velaro/config.json');
-  }),
-};
+import { requestDeviceCode, pollForToken, exchangeForVelaroToken } from '../oauth.js';
+import { readConfig, writeConfig, DEFAULT_API_BASE, STAGING_API_BASE } from '../config.js';
+import { runCommand }                                               from '../run.js';
+
+export const loginCommand = {
+  command:  'login',
+  describe: 'Authenticate with Velaro using your browser',
+  builder:  (y) =>
+    y
+      .option('staging', {
+        describe: 'Connect to the Velaro staging environment',
+        type:     'boolean',
+        default:  false,
+      })
+      .option('api', {
+        describe: 'Override the Velaro API base URL. Set VELARO_API_BASE env var to make it permanent. ' +
+                  'Production cutover: set this to your production API URL before going live.',
+        type:     'string',
+      }),
+
+  handler: runCommand(async (argv) => {
+    const apiBase = argv.api ?? (argv.staging ? STAGING_API_BASE : DEFAULT_API_BASE);
+
+    console.log('Starting Velaro login...\n');
+
+    const deviceData = await requestDeviceCode();
+
+    console.log(`  Open:  ${deviceData.verification_uri}`);
+    console.log(`  Enter: ${deviceData.user_code}\n`);
+    console.log('Waiting for you to complete login in your browser...');
+
+    const entraTokens  = await pollForToken(deviceData.device_code, deviceData.interval ?? 5);
+    const velaroResult = await exchangeForVelaroToken(entraTokens.access_token, apiBase);
+
+    writeConfig({
+      ...readConfig(),
+      apiBase,
+      velaroToken:       velaroResult.token.token,
+      velaroExpires:     velaroResult.token.expires,
+      entraRefreshToken: entraTokens.refresh_token,
+      siteId:            velaroResult.profile?.SiteId,
+      userName:          velaroResult.profile?.Name,
+    });
+
+    const envLabel = argv.staging || argv.api ? ` (${apiBase})` : '';
+    console.log(`\nLogged in as ${velaroResult.profile?.Name ?? velaroResult.profile?.UserName}${envLabel}`);
+    console.log(`Site ID: ${velaroResult.profile?.SiteId}`);
+    console.log('Credentials saved to ~/.velaro/config.json');
+  }),
+};
+
+export const logoutCommand = {
+  command:  'logout',
+  describe: 'Clear stored credentials',
+  handler:  runCommand(async () => {
+    const { clearConfig } = await import('../config.js');
+    clearConfig();
+    console.log('Logged out. Credentials removed from ~/.velaro/config.json');
+  }),
+};