@velaro/cli 0.2.0 → 0.3.0

package/bin/velaro.js

@@ -1,56 +1,56 @@
-#!/usr/bin/env node
-
-import yargs                                    from 'yargs';
-import { hideBin }                              from 'yargs/helpers';
-import { loginCommand, logoutCommand }          from '../lib/commands/login.js';
-import { whoamiCommand }                        from '../lib/commands/whoami.js';
-import { teamCommand }                          from '../lib/commands/team.js';
-import { botCommand }                           from '../lib/commands/bot.js';
-import { kbCommand }                            from '../lib/commands/kb.js';
-import { workflowCommand }                      from '../lib/commands/workflow.js';
-import { ruleCommand }                          from '../lib/commands/rule.js';
-import { agentCommand }                         from '../lib/commands/agent.js';
-import { ingestCommand }                        from '../lib/commands/ingest.js';
-import { mcpKeyCommand }                        from '../lib/commands/mcp-key.js';
-import { statusCommand }                        from '../lib/commands/status.js';
-import { siteCommand }                          from '../lib/commands/site.js';
-import { checkCommand }                         from '../lib/commands/check.js';
-import { updateCommand }                        from '../lib/commands/update.js';
-import { startUpdateCheck }                     from '../lib/update-check.js';
-
-// Start background update check — doesn't block the command
-const printUpdateNotice = startUpdateCheck();
-
-await yargs(hideBin(process.argv))
-  .scriptName('velaro')
-  .usage('$0 <command> [options]')
-  // Auth
-  .command(loginCommand)
-  .command(logoutCommand)
-  .command(whoamiCommand)
-  // Info
-  .command(siteCommand)
-  .command(checkCommand)
-  .command(statusCommand)
-  // Config
-  .command(teamCommand)
-  .command(botCommand)
-  .command(kbCommand)
-  .command(workflowCommand)
-  .command(ruleCommand)
-  .command(agentCommand)
-  // Integrations / keys
-  .command(ingestCommand)
-  .command(mcpKeyCommand)
-  // CLI maintenance
-  .command(updateCommand)
-  .demandCommand(1, 'Specify a command. Run velaro --help for a list.')
-  .strict()
-  .help()
-  .alias('h', 'help')
-  .alias('v', 'version')
-  .wrap(Math.min(100, process.stdout.columns || 100))
-  .parseAsync();
-
-// Print update notice after command output (non-intrusive)
-await printUpdateNotice();
+#!/usr/bin/env node
+
+import yargs                                    from 'yargs';
+import { hideBin }                              from 'yargs/helpers';
+import { loginCommand, logoutCommand }          from '../lib/commands/login.js';
+import { whoamiCommand }                        from '../lib/commands/whoami.js';
+import { teamCommand }                          from '../lib/commands/team.js';
+import { botCommand }                           from '../lib/commands/bot.js';
+import { kbCommand }                            from '../lib/commands/kb.js';
+import { workflowCommand }                      from '../lib/commands/workflow.js';
+import { ruleCommand }                          from '../lib/commands/rule.js';
+import { agentCommand }                         from '../lib/commands/agent.js';
+import { ingestCommand }                        from '../lib/commands/ingest.js';
+import { mcpKeyCommand }                        from '../lib/commands/mcp-key.js';
+import { statusCommand }                        from '../lib/commands/status.js';
+import { siteCommand }                          from '../lib/commands/site.js';
+import { checkCommand }                         from '../lib/commands/check.js';
+import { updateCommand }                        from '../lib/commands/update.js';
+import { startUpdateCheck }                     from '../lib/update-check.js';
+
+// Start background update check — doesn't block the command
+const printUpdateNotice = startUpdateCheck();
+
+await yargs(hideBin(process.argv))
+  .scriptName('velaro')
+  .usage('$0 <command> [options]')
+  // Auth
+  .command(loginCommand)
+  .command(logoutCommand)
+  .command(whoamiCommand)
+  // Info
+  .command(siteCommand)
+  .command(checkCommand)
+  .command(statusCommand)
+  // Config
+  .command(teamCommand)
+  .command(botCommand)
+  .command(kbCommand)
+  .command(workflowCommand)
+  .command(ruleCommand)
+  .command(agentCommand)
+  // Integrations / keys
+  .command(ingestCommand)
+  .command(mcpKeyCommand)
+  // CLI maintenance
+  .command(updateCommand)
+  .demandCommand(1, 'Specify a command. Run velaro --help for a list.')
+  .strict()
+  .help()
+  .alias('h', 'help')
+  .alias('v', 'version')
+  .wrap(Math.min(100, process.stdout.columns || 100))
+  .parseAsync();
+
+// Print update notice after command output (non-intrusive)
+await printUpdateNotice();

package/lib/commands/article.js

@@ -0,0 +1,280 @@
+/**
+ * velaro kb article — CRUD for help-center KB articles.
+ *
+ * Auth: uses the stored OAuth JWT (same as all other commands).
+ * API:  velaro-admin (help.velaro.com), not the messaging API.
+ *       Base URL read from VELARO_ADMIN_API_BASE env var or creds.adminApiBase,
+ *       falling back to https://help.velaro.com.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { extname }                  from 'path';
+import { getCredentials }           from '../api.js';
+import { runCommand }               from '../run.js';
+
+const DEFAULT_ADMIN_API = process.env.VELARO_ADMIN_API_BASE || 'https://help.velaro.com';
+
+async function adminRequest(method, path, body) {
+  const creds   = await getCredentials();
+  const apiBase = creds.adminApiBase || DEFAULT_ADMIN_API;
+
+  const res = await fetch(`${apiBase}${path}`, {
+    method,
+    headers: {
+      Authorization:  `Bearer ${creds.velaroToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+
+  if (!res.ok) {
+    let msg = `${method} ${path} -> ${res.status}`;
+    try { const t = await res.text(); if (t) msg += `: ${t.slice(0, 300)}`; } catch { /* ignore */ }
+    throw new Error(msg);
+  }
+
+  const text = await res.text();
+  return text ? JSON.parse(text) : null;
+}
+
+// ── list ──────────────────────────────────────────────────────────────────────
+
+const listCommand = {
+  command:  'list',
+  describe: 'List KB articles',
+  builder:  (y) =>
+    y
+      .option('topic-id',  { type: 'number', describe: 'Filter by topic ID' })
+      .option('search',    { type: 'string', describe: 'Search term' })
+      .option('published', { type: 'boolean', describe: 'Show only published articles' }),
+  handler: runCommand(async (argv) => {
+    const payload = {};
+    if (argv['topic-id'])  payload.topicId     = argv['topic-id'];
+    if (argv.search)       payload.searchTerm  = argv.search;
+    if (argv.published)    payload.publishStatus = 'Published';
+
+    const data = await adminRequest('POST', '/api/kb/articles/search', payload);
+    const articles = data?.articles ?? [];
+
+    if (!articles.length) { console.log('No articles found.'); return; }
+
+    console.log(`\nFound ${articles.length} article(s):\n`);
+    for (const a of articles) {
+      const status = a.isPublished ? 'published  ' : 'draft      ';
+      const views  = `${a.hitCount ?? 0} views`;
+      console.log(`  [${a.id}] ${status}  ${truncate(a.title, 55)}  (${views})`);
+      if (a.topicName) console.log(`         topic: ${a.topicName}`);
+    }
+  }),
+};
+
+// ── get ───────────────────────────────────────────────────────────────────────
+
+const getCommand = {
+  command:  'get <id>',
+  describe: 'Get a KB article by ID',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Article ID' }),
+  handler: runCommand(async (argv) => {
+    const a = await adminRequest('GET', `/api/kb/articles?id=${argv.id}`);
+    console.log(`\n[${a.id}] ${a.title}`);
+    console.log(`  slug:      ${a.slug}`);
+    console.log(`  topic:     ${a.topicId}`);
+    console.log(`  published: ${a.isPublished}`);
+    console.log(`  url:       ${a.url ?? '(not public)'}`);
+    console.log(`\n--- content (HTML) ---\n${a.content ?? ''}\n`);
+  }),
+};
+
+// ── topics ────────────────────────────────────────────────────────────────────
+
+const topicsCommand = {
+  command:  'topics',
+  describe: 'List available KB topics (you need a topic ID to push an article)',
+  handler: runCommand(async () => {
+    const data = await adminRequest('GET', '/api/kb/topics');
+    const topics = data?.topics ?? [];
+    if (!topics.length) { console.log('No topics found.'); return; }
+    console.log(`\nTopics:\n`);
+    for (const t of topics)
+      console.log(`  [${t.id}] ${t.name}  (${t.articleCount} articles)`);
+  }),
+};
+
+// ── push ──────────────────────────────────────────────────────────────────────
+
+const pushCommand = {
+  command:  'push <file>',
+  describe: 'Create or update a KB article from a Markdown or HTML file',
+  builder:  (y) =>
+    y
+      .positional('file', { type: 'string', describe: 'Path to .md or .html file' })
+      .option('title',       { type: 'string',  describe: 'Article title (override file frontmatter)' })
+      .option('slug',        { type: 'string',  describe: 'URL slug (override file frontmatter)' })
+      .option('topic-id',    { type: 'number',  describe: 'Topic ID (required if not in frontmatter)' })
+      .option('description', { type: 'string',  describe: 'Short description' })
+      .option('publish',     { type: 'boolean', default: false, describe: 'Publish immediately' })
+      .option('update-id',   { type: 'number',  describe: 'Article ID to update (if omitted, creates new)' }),
+  handler: runCommand(async (argv) => {
+    if (!existsSync(argv.file)) throw new Error(`File not found: ${argv.file}`);
+
+    const raw  = readFileSync(argv.file, 'utf8');
+    const ext  = extname(argv.file).toLowerCase();
+    const fm   = parseFrontmatter(raw);
+    const body = fm.body;
+
+    const title       = argv.title       || fm.title       || null;
+    const slug        = argv.slug        || fm.slug        || null;
+    const topicId     = argv['topic-id'] || fm.topicId     || null;
+    const description = argv.description || fm.description || '';
+
+    if (!title)   throw new Error('Title is required. Add "title:" to frontmatter or use --title.');
+    if (!slug)    throw new Error('Slug is required. Add "slug:" to frontmatter or use --slug.');
+    if (!topicId) throw new Error('Topic ID is required. Run "velaro kb article topics" then use --topic-id.');
+
+    const content = ext === '.md' ? markdownToHtml(body) : body;
+
+    const payload = {
+      title,
+      slug,
+      topicId,
+      description,
+      content,
+      visibility:        'Public',
+      searchTags:        fm.tags || '',
+      isPublished:       argv.publish || fm.published || false,
+      displayPriority:   0,
+      enableBotResponse: fm.botResponse !== false,
+      botSummary:        fm.botSummary || '',
+      isFeatured:        false,
+    };
+
+    if (argv['update-id']) {
+      await adminRequest('PUT', `/api/kb/articles?id=${argv['update-id']}`, payload);
+      console.log(`Updated article [${argv['update-id']}]: "${title}"`);
+    } else {
+      await adminRequest('POST', '/api/kb/articles', payload);
+      // Look up the newly created article by slug to get its ID
+      const result = await adminRequest('POST', '/api/kb/articles/search', { searchTerm: slug, topicId });
+      const created = result?.articles?.find(a => a.slug === slug);
+      const id = created?.id ?? '?';
+      console.log(`Created article [${id}]: "${title}"`);
+      if (argv.publish)
+        console.log(`  Published at: https://help.velaro.com/kb/article/${id}/${slug}`);
+      else
+        console.log(`  Draft saved. Use --publish to make it public.`);
+    }
+  }),
+};
+
+// ── delete ────────────────────────────────────────────────────────────────────
+
+const deleteCommand = {
+  command:  'delete <id>',
+  describe: 'Delete a KB article',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Article ID' }),
+  handler: runCommand(async (argv) => {
+    await adminRequest('DELETE', `/api/kb/articles?id=${argv.id}`);
+    console.log(`Article ${argv.id} deleted.`);
+  }),
+};
+
+// ── improve ───────────────────────────────────────────────────────────────────
+
+const improveCommand = {
+  command:  'improve <id>',
+  describe: 'AI-improve a KB article using a file or instruction (requires VelaroCopilotApiKey)',
+  builder:  (y) =>
+    y
+      .positional('id', { type: 'number', describe: 'Article ID to improve' })
+      .option('file',        { type: 'string', describe: 'Path to a reference file (.md, .txt, .html) to incorporate' })
+      .option('instruction', { type: 'string', describe: 'Plain-language instruction, e.g. "add a troubleshooting section"' })
+      .option('publish',     { type: 'boolean', default: false, describe: 'Publish after improving' })
+      .check((argv) => {
+        if (!argv.file && !argv.instruction) throw new Error('Provide --file and/or --instruction.');
+        return true;
+      }),
+  handler: runCommand(async (argv) => {
+    // 1. Fetch the existing article
+    const article = await adminRequest('GET', `/api/kb/articles?id=${argv.id}`);
+    console.log(`Improving: "${article.title}" [${article.id}]`);
+
+    // 2. Build prompt context
+    let reference = '';
+    if (argv.file) {
+      if (!existsSync(argv.file)) throw new Error(`File not found: ${argv.file}`);
+      reference = readFileSync(argv.file, 'utf8');
+    }
+
+    // 3. POST to the server-side AI improve endpoint
+    const result = await adminRequest('POST', `/api/kb/articles/${argv.id}/ai-improve`, {
+      instruction: argv.instruction || '',
+      referenceContent: reference,
+      publish: argv.publish,
+    });
+
+    console.log(`\nImprovement applied.`);
+    if (result?.changesSummary) console.log(`Changes: ${result.changesSummary}`);
+    if (argv.publish) console.log(`Published: https://help.velaro.com/kb/article/${article.id}/${article.slug}`);
+  }),
+};
+
+// ── export command ─────────────────────────────────────────────────────────────
+
+export const articleCommand = {
+  command:  'article <subcommand>',
+  describe: 'Manage help-center KB articles',
+  builder:  (yargs) =>
+    yargs
+      .command(listCommand)
+      .command(getCommand)
+      .command(topicsCommand)
+      .command(pushCommand)
+      .command(deleteCommand)
+      .command(improveCommand)
+      .demandCommand(1, 'Specify a subcommand: list, get, topics, push, delete, improve'),
+  handler: () => {},
+};
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function parseFrontmatter(raw) {
+  const fm = {};
+  let body = raw;
+
+  if (raw.startsWith('---')) {
+    const end = raw.indexOf('\n---', 3);
+    if (end !== -1) {
+      const block = raw.slice(3, end).trim();
+      body = raw.slice(end + 4).trim();
+      for (const line of block.split('\n')) {
+        const sep = line.indexOf(':');
+        if (sep === -1) continue;
+        const key = line.slice(0, sep).trim();
+        const val = line.slice(sep + 1).trim().replace(/^["']|["']$/g, '');
+        if (key === 'topicId' || key === 'topic_id') fm.topicId = parseInt(val, 10);
+        else fm[key] = val === 'true' ? true : val === 'false' ? false : val;
+      }
+    }
+  }
+
+  return { ...fm, body };
+}
+
+function markdownToHtml(md) {
+  // Minimal markdown-to-HTML — headings, bold, inline code, paragraphs.
+  // For rich content use an .html file or the admin UI.
+  return md
+    .replace(/^### (.+)$/gm, '<h3>$1</h3>')
+    .replace(/^## (.+)$/gm,  '<h2>$1</h2>')
+    .replace(/^# (.+)$/gm,   '<h1>$1</h1>')
+    .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
+    .replace(/`([^`]+)`/g,    '<code>$1</code>')
+    .replace(/\n\n+/g,        '</p><p>')
+    .replace(/^(?!<[hup])/gm, '')
+    .replace(/^(.+)(?!>)$/gm, (m) => m.startsWith('<') ? m : `<p>${m}</p>`);
+}
+
+function truncate(str, max) {
+  if (!str) return '-';
+  return str.length <= max ? str : str.slice(0, max - 1) + '...';
+}