@velaro/cli 1.2.0 → 1.4.8

package/lib/commands/article.js

@@ -1,388 +1,668 @@
-/**
- * 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.`);
-  }),
-};
-
-// ── seed-views ────────────────────────────────────────────────────────────────
-
-const seedViewsCommand = {
-  command:  'seed-views <id>',
-  describe: 'Seed an article with random view counts (for new article submissions)',
-  builder:  (y) =>
-    y
-      .positional('id', { type: 'number', describe: 'Article ID to seed' })
-      .option('hits', { type: 'number', default: 0, describe: 'Hit count (0 = random 1000-1999)' }),
-  handler: runCommand(async (argv) => {
-    const hitCount = argv.hits === 0 ? (Math.floor(Math.random() * 1000) + 1000) : argv.hits;
-    const payload = { articleId: argv.id, hitCount };
-
-    try {
-      // Call API endpoint using stored OAuth token — no credentials in code
-      await adminRequest('POST', '/api/kb/articles/seed-views', payload);
-      console.log(`✅ Article [${argv.id}] seeded with ${hitCount} views.`);
-    } catch (e) {
-      console.error(`❌ Failed to seed article: ${e.message}`);
-      throw e;
-    }
-  }),
-};
-
-// ── 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(seedViewsCommand)
-      .command(improveCommand)
-      .demandCommand(1, 'Specify a subcommand: list, get, topics, push, delete, seed-views, 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 };
-}
-
-// help.velaro.com kb.css styles .kb-article-body table/th/td natively (header #1e3a5f,
-// rounded corners, shadow, horizontal-scroll wrapper). Admin editor preview uses the same class.
-// Inline fallback styles cover any external renderer that doesn't ship our CSS.
-const TABLE_STYLE  = 'border-collapse:collapse;width:100%;margin:16px 0;font-size:14px;';
-const TH_STYLE     = 'border:1px solid #1e3a5f;padding:11px 16px;background:#1e3a5f;color:#fff;text-align:left;font-weight:600;';
-const TD_STYLE     = 'border:1px solid #e2e8f0;padding:10px 14px;vertical-align:top;color:#1e293b;';
-
-function inlineMd(s) {
-  return s
-    .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
-    .replace(/(^|[^*])\*([^*\n]+)\*/g, '$1<em>$2</em>')
-    .replace(/`([^`]+)`/g, '<code>$1</code>')
-    .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
-}
-
-function markdownToHtml(md) {
-  const lines = md.replace(/\r\n/g, '\n').split('\n');
-  const out = [];
-  let i = 0;
-  let para = [];
-  let list = null; // { type: 'ul'|'ol', items: [] }
-
-  const flushPara = () => {
-    if (para.length) {
-      out.push(`<p>${inlineMd(para.join(' '))}</p>`);
-      para = [];
-    }
-  };
-  const flushList = () => {
-    if (list) {
-      out.push(`<${list.type}>` + list.items.map(x => `<li>${inlineMd(x)}</li>`).join('') + `</${list.type}>`);
-      list = null;
-    }
-  };
-  const flushAll = () => { flushPara(); flushList(); };
-
-  const isTableSep = (s) => /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)+\|?\s*$/.test(s);
-  const splitRow = (s) => {
-    let t = s.trim();
-    if (t.startsWith('|')) t = t.slice(1);
-    if (t.endsWith('|')) t = t.slice(0, -1);
-    return t.split('|').map(c => c.trim());
-  };
-
-  while (i < lines.length) {
-    const line = lines[i];
-
-    if (/^\s*$/.test(line)) { flushAll(); i++; continue; }
-
-    const h = line.match(/^(#{1,6})\s+(.+)$/);
-    if (h) { flushAll(); out.push(`<h${h[1].length}>${inlineMd(h[2])}</h${h[1].length}>`); i++; continue; }
-
-    // Pipe table
-    if (line.includes('|') && i + 1 < lines.length && isTableSep(lines[i + 1])) {
-      flushAll();
-      const header = splitRow(line);
-      i += 2;
-      const rows = [];
-      while (i < lines.length && lines[i].includes('|') && lines[i].trim() !== '') {
-        rows.push(splitRow(lines[i]));
-        i++;
-      }
-      const thead = `<thead><tr>${header.map(c => `<th style="${TH_STYLE}">${inlineMd(c)}</th>`).join('')}</tr></thead>`;
-      const tbody = `<tbody>${rows.map(r => `<tr>${r.map(c => `<td style="${TD_STYLE}">${inlineMd(c)}</td>`).join('')}</tr>`).join('')}</tbody>`;
-      out.push(`<table class="velaro-kb-table" style="${TABLE_STYLE}">${thead}${tbody}</table>`);
-      continue;
-    }
-
-    const ul = line.match(/^\s*[-*]\s+(.+)$/);
-    if (ul) {
-      flushPara();
-      if (!list || list.type !== 'ul') { flushList(); list = { type: 'ul', items: [] }; }
-      list.items.push(ul[1]);
-      i++; continue;
-    }
-    const ol = line.match(/^\s*\d+\.\s+(.+)$/);
-    if (ol) {
-      flushPara();
-      if (!list || list.type !== 'ol') { flushList(); list = { type: 'ol', items: [] }; }
-      list.items.push(ol[1]);
-      i++; continue;
-    }
-
-    if (/^<(h[1-6]|table|ul|ol|p|div|pre|blockquote)/i.test(line.trim())) {
-      flushAll();
-      out.push(line);
-      i++; continue;
-    }
-
-    flushList();
-    para.push(line.trim());
-    i++;
-  }
-  flushAll();
-  return out.join('\n');
-}
-
-function truncate(str, max) {
-  if (!str) return '-';
-  return str.length <= max ? str : str.slice(0, max - 1) + '...';
-}
+/**
+ * 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, writeFileSync, existsSync } from 'fs';
+import { extname }                  from 'path';
+import { getCredentials }           from '../api.js';
+import { runCommand }               from '../run.js';
+import { captureKbScreenshot, uploadImage, polishScreenshot, insertImageAfterHeading, escapeAttr } from '../kb-screenshot.js';
+
+const DEFAULT_ADMIN_API = process.env.VELARO_ADMIN_API_BASE || 'https://help.velaro.com';
+
+// Exported so cli/lib/kb-screenshot.js can reuse the exact same auth/request
+// pattern instead of duplicating a parallel HTTP client. `credsOverride` lets
+// callers with their own auth source (e.g. mcp/server.js, which authenticates
+// via VELARO_MCP_KEY/VELARO_JWT env vars rather than the CLI's stored login
+// config) supply { velaroToken, adminApiBase } directly.
+export async function adminRequest(method, path, body, credsOverride) {
+  const creds   = credsOverride || 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)' })
+      .option('no-title-normalize', { type: 'boolean', default: false, describe: 'Skip auto-formatting slug-style titles to Title Case' }),
+  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 rawTitle    = argv.title || fm.title || null;
+    const skipNorm    = argv['no-title-normalize'] === true;
+    const title       = rawTitle && !skipNorm ? normalizeTitle(rawTitle) : rawTitle;
+    if (title && title !== rawTitle) console.log(`  ℹ Title normalized: "${rawTitle}" → "${title}" (use --no-title-normalize to keep as-is)`);
+    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;
+
+    if (argv['update-id']) {
+      // Merge onto the CURRENT article rather than blindly overwriting every field to a
+      // frontmatter-or-default value — a push file with no "tags:"/"published:" line must
+      // never silently wipe an existing article's searchTags (this is how the CopilotKb sync
+      // job recognizes an already-synced article; losing it causes the sync to re-create a
+      // duplicate on its next run) or unpublish a live page. Only fields explicitly provided
+      // via CLI flags or frontmatter override what's already there.
+      const existing = await adminRequest('GET', `/api/kb/articles?id=${argv['update-id']}`);
+      const payload = {
+        title,
+        slug,
+        topicId,
+        description: argv.description || fm.description || existing.description || '',
+        content,
+        visibility:        existing.visibility ?? 'Public',
+        searchTags:        fm.tags || existing.searchTags || '',
+        isPublished:       argv.publish || fm.published || existing.isPublished || false,
+        displayPriority:   existing.displayPriority ?? 0,
+        enableBotResponse: fm.botResponse !== undefined ? fm.botResponse !== false : existing.enableBotResponse !== false,
+        botSummary:        fm.botSummary || existing.botSummary || '',
+        isFeatured:        existing.isFeatured || false,
+      };
+      await adminRequest('PUT', `/api/kb/articles?id=${argv['update-id']}`, payload);
+      console.log(`Updated article [${argv['update-id']}]: "${title}"`);
+    } else {
+      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,
+      };
+      // Create response returns { id, slug, url } directly — no follow-up search needed.
+      const created = await adminRequest('POST', '/api/kb/articles', payload);
+      const id = created?.id ?? '?';
+      console.log(`Created article [${id}]: "${title}"`);
+      if (argv.publish)
+        console.log(`  Published at: ${created?.url || `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.`);
+  }),
+};
+
+// ── seed-views ────────────────────────────────────────────────────────────────
+
+const seedViewsCommand = {
+  command:  'seed-views <id>',
+  describe: 'Seed an article with random view counts (for new article submissions)',
+  builder:  (y) =>
+    y
+      .positional('id', { type: 'number', describe: 'Article ID to seed' })
+      .option('hits', { type: 'number', default: 0, describe: 'Hit count (0 = random 1000-1999)' }),
+  handler: runCommand(async (argv) => {
+    const hitCount = argv.hits === 0 ? (Math.floor(Math.random() * 1000) + 1000) : argv.hits;
+    const payload = { articleId: argv.id, hitCount };
+
+    try {
+      // Call API endpoint using stored OAuth token — no credentials in code
+      await adminRequest('POST', '/api/kb/articles/seed-views', payload);
+      console.log(`✅ Article [${argv.id}] seeded with ${hitCount} views.`);
+    } catch (e) {
+      console.error(`❌ Failed to seed article: ${e.message}`);
+      throw e;
+    }
+  }),
+};
+
+// ── screenshot ────────────────────────────────────────────────────────────────
+
+const screenshotCommand = {
+  command:  'screenshot <articleId>',
+  describe: 'Capture a live staging screenshot and insert it into a KB article',
+  builder:  (y) =>
+    y
+      .positional('articleId', { type: 'number', describe: 'Target article ID' })
+      .option('app',      { type: 'string', choices: ['admin', 'messaging'], demandOption: true, describe: 'Which app to capture from' })
+      .option('route',    { type: 'string', demandOption: true, describe: 'Route to navigate to, e.g. "/Settings/Routing"' })
+      .option('heading',  { type: 'string', describe: 'Insert the image immediately after the <h2>/<h3> whose text contains this (case-insensitive). Falls back to appending at the end.' })
+      .option('annotate', { type: 'array',  default: [], describe: 'x,y,label annotation, repeatable — e.g. --annotate 120,80,1 --annotate 400,200,"Click here"' }),
+  handler: runCommand(async (argv) => {
+    const annotations = (argv.annotate || []).map((raw) => {
+      const [x, y, ...labelParts] = String(raw).split(',');
+      return { x: parseInt(x, 10), y: parseInt(y, 10), label: labelParts.join(',').trim() || undefined };
+    });
+
+    console.log(`Capturing ${argv.app} staging screenshot of "${argv.route}" for article [${argv.articleId}]...`);
+
+    const result = await captureKbScreenshot({
+      app: argv.app,
+      route: argv.route,
+      articleId: argv.articleId,
+      heading: argv.heading,
+      annotations,
+    });
+
+    console.log(`Uploaded: ${result.imageUrl}`);
+    console.log(result.insertedAfterHeading
+      ? `Inserted after heading matching "${argv.heading}" in article [${result.articleId}].`
+      : `Appended to the end of article [${result.articleId}] (no matching heading found).`);
+  }),
+};
+
+// ── image ─────────────────────────────────────────────────────────────────────
+//
+// General-purpose image upload+polish primitive — NOT tied to the live-capture
+// flow in `screenshot`. Use for any local image (a manually captured console
+// screenshot, a design mockup, a product graphic) that needs to end up hosted
+// and, optionally, embedded in a KB article. This is the durable, reusable path
+// for building images for any KB/product doc — don't hand-roll a one-off upload.
+//
+// Root cause this exists: markdownToHtml()'s `![alt](url)` handling was added in
+// the same change (2026-07-31) after a KB article shipped with a silently broken
+// image — the CLI had no supported way to get a local file hosted at all, so an
+// ad-hoc curl against the wrong endpoint (kb/assets/upload, which 404s/disables
+// against the prod-API-base + staging-token combo every other command uses) was
+// the only option. This command is the supported replacement for that ad-hoc path.
+
+const imageCommand = {
+  command:  'image <file>',
+  describe: 'Upload a local image (optionally polished) to KB asset storage, and optionally insert it into an article',
+  builder:  (y) =>
+    y
+      .positional('file', { type: 'string', describe: 'Path to a local image file (.png/.jpg/.gif/.webp)' })
+      .option('polish',      { type: 'boolean', default: true, describe: 'Run through scripts/polish-screenshot.py with standard KB style-guide defaults before uploading' })
+      .option('bg',          { type: 'string', describe: 'Polish background hex (default F4F5F7)' })
+      .option('insert-into', { type: 'number', describe: 'Article ID to insert the uploaded image into' })
+      .option('heading',     { type: 'string', describe: 'Insert immediately after the <h2>/<h3> whose text contains this (case-insensitive). Falls back to appending at the end.' })
+      .option('alt',         { type: 'string', describe: 'Alt text for the inserted <img> tag (defaults to --heading, then the filename)' }),
+  handler: runCommand(async (argv) => {
+    if (!existsSync(argv.file)) throw new Error(`File not found: ${argv.file}`);
+
+    const creds = await getCredentials();
+
+    let imagePath = argv.file;
+    if (argv.polish) {
+      console.log('Polishing via scripts/polish-screenshot.py...');
+      imagePath = await polishScreenshot(imagePath, [], { bg: argv.bg });
+    }
+
+    console.log(`Uploading ${imagePath}...`);
+    const imageUrl = await uploadImage(imagePath, creds);
+    console.log(`Uploaded: ${imageUrl}`);
+
+    if (!argv['insert-into']) {
+      console.log('No --insert-into given — image is hosted but not attached to any article.');
+      console.log(`Reference it in markdown as: ![alt text](${imageUrl})`);
+      return;
+    }
+
+    const articleId = argv['insert-into'];
+    const article = await adminRequest('GET', `/api/kb/articles?id=${articleId}`, undefined, creds);
+    if (!article) throw new Error(`Article ${articleId} not found`);
+
+    const altText = argv.alt || argv.heading || basenameNoExt(argv.file);
+    const imgTag = `<img src="${imageUrl}" alt="${escapeAttr(altText)}" style="max-width:100%;border-radius:8px;" />`;
+    const { html: newContent, insertedAfterHeading } = insertImageAfterHeading(article.content, argv.heading, imgTag);
+
+    await adminRequest('PUT', `/api/kb/articles?id=${articleId}`, {
+      title:             article.title,
+      slug:              article.slug,
+      topicId:           article.topicId,
+      description:       article.description,
+      content:           newContent,
+      visibility:        article.visibility,
+      searchTags:        article.searchTags,
+      isPublished:       article.isPublished,
+      displayPriority:   article.displayPriority,
+      enableBotResponse: article.enableBotResponse,
+      botSummary:        article.botSummary,
+      isFeatured:        article.isFeatured,
+    }, creds);
+
+    console.log(argv.heading
+      ? `Inserted ${insertedAfterHeading ? `after heading matching "${argv.heading}"` : '(no matching heading found — appended to end)'} in article [${articleId}].`
+      : `Appended to the end of article [${articleId}].`);
+  }),
+};
+
+function basenameNoExt(p) {
+  const base = p.split(/[\\/]/).pop() || p;
+  return base.replace(/\.[^.]+$/, '');
+}
+
+// ── 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}`);
+  }),
+};
+
+// ── preview ───────────────────────────────────────────────────────────────────
+
+const previewCommand = {
+  command:  'preview <file>',
+  describe: 'Render a Markdown article to HTML and write a preview file you can open in a browser',
+  builder:  (y) =>
+    y
+      .positional('file', { type: 'string', describe: 'Path to .md or .html file' })
+      .option('output', { type: 'string', describe: 'Write HTML to this file instead of a temp file' }),
+  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 = fm.title || argv.file;
+    const content = ext === '.md' ? markdownToHtml(body) : body;
+
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escHtml(title)}</title>
+<style>
+  body { font-family: system-ui, sans-serif; max-width: 860px; margin: 40px auto; padding: 0 24px; color: #1e293b; line-height: 1.6; }
+  h1,h2,h3,h4 { color: #1e3a5f; margin-top: 1.8em; }
+  h1 { font-size: 1.8em; } h2 { font-size: 1.35em; } h3 { font-size: 1.1em; }
+  pre { background: #f1f5f9; border: 1px solid #e2e8f0; border-radius: 6px; padding: 14px 18px; overflow-x: auto; }
+  code { font-family: ui-monospace, monospace; font-size: .9em; }
+  p code, li code { background: #f1f5f9; padding: 1px 5px; border-radius: 3px; }
+  table { border-collapse: collapse; width: 100%; margin: 16px 0; font-size: .9em; }
+  th { background: #1e3a5f; color: #fff; padding: 10px 14px; text-align: left; }
+  td { border: 1px solid #e2e8f0; padding: 9px 13px; }
+  ul, ol { padding-left: 1.5em; }
+  a { color: #2563eb; }
+  .meta { background: #f8fafc; border: 1px solid #e2e8f0; border-radius: 6px; padding: 12px 16px; margin-bottom: 32px; font-size: .85em; color: #64748b; }
+</style>
+</head>
+<body>
+<div class="meta">
+  <strong>slug:</strong> ${escHtml(fm.slug || '—')} &nbsp;|&nbsp;
+  <strong>topic:</strong> ${fm.topicId ?? '—'} &nbsp;|&nbsp;
+  <strong>published:</strong> ${fm.published ?? false}
+</div>
+<h1>${escHtml(title)}</h1>
+${content}
+</body>
+</html>`;
+
+    const outPath = argv.output || `${argv.file.replace(/\.[^.]+$/, '')}.preview.html`;
+    writeFileSync(outPath, html, 'utf8');
+    console.log(`Preview written to: ${outPath}`);
+    console.log(`Open it with:  start "${outPath}"  (Windows) or  open "${outPath}"  (Mac)`);
+  }),
+};
+
+// ── 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(previewCommand)
+      .command(deleteCommand)
+      .command(seedViewsCommand)
+      .command(improveCommand)
+      .command(screenshotCommand)
+      .command(imageCommand)
+      .demandCommand(1, 'Specify a subcommand: list, get, topics, push, preview, delete, seed-views, improve, screenshot, image'),
+  handler: () => {},
+};
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Convert slug-style titles to proper Title Case.
+ * Only fires when the title looks like a slug: all-lowercase and contains hyphens but no spaces.
+ * Preserves already-formatted titles ("Gmail Inbox Guide" stays unchanged).
+ *
+ * Known acronyms/brands are uppercased correctly; common short words stay lowercase mid-title.
+ */
+function normalizeTitle(title) {
+  if (!title) return title;
+  // Only normalize if the title looks like a slug (all lowercase, hyphens, no spaces)
+  if (!/^[a-z0-9]+(-[a-z0-9]+)+$/.test(title)) return title;
+
+  const ACRONYMS = new Set(['cli', 'mcp', 'sap', 'ivr', 'crm', 'api', 'csp', 'csat', 'ai', 'sms', 'icp', 'ids', 'url', 'urls', 'sdk', 'ui', 'ux', 'id', 'json', 'xml', 'html', 'css', 'jwt', 'sso', 'saml', 'oauth', 'gdpr', 'pci']);
+  const BRANDS   = { gmail: 'Gmail', quickbooks: 'QuickBooks', skyswitch: 'SkySwitch', opentable: 'OpenTable', velaro: 'Velaro', livefluence: 'LiveFluence', mindbody: 'Mindbody', cloudbeds: 'Cloudbeds', formstack: 'Formstack', uplisting: 'Uplisting', accela: 'Accela', guesty: 'Guesty', resy: 'Resy', nextiva: 'Nextiva', zapier: 'Zapier', webflow: 'Webflow', zoho: 'Zoho', shopify: 'Shopify', hubspot: 'HubSpot', salesforce: 'Salesforce', netsuite: 'NetSuite', dynamics: 'Dynamics', bigcommerce: 'BigCommerce', woocommerce: 'WooCommerce', magento: 'Magento', square: 'Square', stripe: 'Stripe', twilio: 'Twilio', google: 'Google', outlook: 'Outlook', onedrive: 'OneDrive', sharepoint: 'SharePoint', teams: 'Teams', slack: 'Slack', make: 'Make', pipedrive: 'Pipedrive', monday: 'Monday', servicenow: 'ServiceNow' };
+  // Small words that stay lowercase unless they're first
+  const SMALL    = new Set(['a', 'an', 'and', 'as', 'at', 'but', 'by', 'for', 'in', 'nor', 'of', 'on', 'or', 'so', 'the', 'to', 'up', 'via', 'yet']);
+
+  const words = title.split('-');
+  return words.map((w, i) => {
+    const lw = w.toLowerCase();
+    if (BRANDS[lw])                     return BRANDS[lw];
+    if (ACRONYMS.has(lw))               return lw.toUpperCase();
+    if (i > 0 && SMALL.has(lw))        return lw;
+    return lw.charAt(0).toUpperCase() + lw.slice(1);
+  }).join(' ');
+}
+
+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 };
+}
+
+// help.velaro.com kb.css styles .kb-article-body table/th/td natively (header #1e3a5f,
+// rounded corners, shadow, horizontal-scroll wrapper). Admin editor preview uses the same class.
+// Inline fallback styles cover any external renderer that doesn't ship our CSS.
+const TABLE_STYLE  = 'border-collapse:collapse;width:100%;margin:16px 0;font-size:14px;';
+const TH_STYLE     = 'border:1px solid #1e3a5f;padding:11px 16px;background:#1e3a5f;color:#fff;text-align:left;font-weight:600;';
+const TD_STYLE     = 'border:1px solid #e2e8f0;padding:10px 14px;vertical-align:top;color:#1e293b;';
+
+// HTML-escape a raw string (used for code span content and plain-text regions).
+function escHtml(s) {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function inlineMd(s) {
+  // Strategy: extract code spans first (HTML-escape their content), replace with
+  // placeholder tokens that survive the subsequent markdown passes, then restore.
+  const saved = [];
+  const save  = (html) => { saved.push(html); return `\x02${saved.length - 1}\x03`; };
+
+  // 1. Code spans — escape HTML inside so <script>, <NONCE>, etc. render literally.
+  s = s.replace(/`([^`]+)`/g, (_, c) => save(`<code>${escHtml(c)}</code>`));
+
+  // 2. Escape HTML entities in the remaining plain-text regions.
+  s = escHtml(s);
+
+  // 3. Apply markdown (bold, italic, images, links) — these patterns don't contain < or >.
+  s = s.replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>');
+  s = s.replace(/(^|[^*])\*([^*\n]+)\*/g, '$1<em>$2</em>');
+  // Images MUST be matched before plain links — otherwise `![alt](url)` falls through
+  // to the link regex below, which doesn't consume the leading `!`, silently degrading
+  // every image into a broken-looking link (`!<a href="...">alt text</a>`). Confirmed
+  // 2026-07-31: this exact bug shipped a NetSuite KB article with an invisible image.
+  s = s.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (_, alt, url) =>
+    `<img src="${url.replace(/&/g, '&amp;')}" alt="${alt.replace(/"/g, '&quot;')}" style="max-width:100%;border-radius:8px;" />`);
+  s = s.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_, text, url) =>
+    `<a href="${url.replace(/&/g, '&amp;')}">${text}</a>`);
+
+  // 4. Restore saved code spans.
+  s = s.replace(/\x02(\d+)\x03/g, (_, idx) => saved[parseInt(idx)]);
+  return s;
+}
+
+function markdownToHtml(md) {
+  const lines = md.replace(/\r\n/g, '\n').split('\n');
+  const out = [];
+  let i = 0;
+  let para = [];
+  let list = null; // { type: 'ul'|'ol', items: [] }
+
+  const flushPara = () => {
+    if (para.length) {
+      out.push(`<p>${inlineMd(para.join(' '))}</p>`);
+      para = [];
+    }
+  };
+  const flushList = () => {
+    if (list) {
+      out.push(`<${list.type}>` + list.items.map(x => `<li>${inlineMd(x)}</li>`).join('') + `</${list.type}>`);
+      list = null;
+    }
+  };
+  const flushAll = () => { flushPara(); flushList(); };
+
+  const isTableSep = (s) => /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)+\|?\s*$/.test(s);
+  const splitRow = (s) => {
+    let t = s.trim();
+    if (t.startsWith('|')) t = t.slice(1);
+    if (t.endsWith('|')) t = t.slice(0, -1);
+    return t.split('|').map(c => c.trim());
+  };
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    if (/^\s*$/.test(line)) { flushAll(); i++; continue; }
+
+    // Fenced code block (``` or ~~~, with optional language tag)
+    if (/^\s*(`{3,}|~{3,})/.test(line)) {
+      flushAll();
+      i++; // skip opening fence
+      const codeLines = [];
+      const fence = line.match(/^\s*(`{3,}|~{3,})/)[1];
+      while (i < lines.length && !lines[i].trim().startsWith(fence)) {
+        codeLines.push(lines[i]);
+        i++;
+      }
+      i++; // skip closing fence
+      const escaped = codeLines.join('\n')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+      // Plain <pre><code> — kb.js wraps every code block in the KB article body with a
+      // copy button client-side (regardless of authoring path: this CLI, or the Tiptap
+      // editor in Velaro Admin), so no special markup is needed here.
+      out.push(`<pre><code>${escaped}</code></pre>`);
+      continue;
+    }
+
+    const h = line.match(/^(#{1,6})\s+(.+)$/);
+    if (h) { flushAll(); out.push(`<h${h[1].length}>${inlineMd(h[2])}</h${h[1].length}>`); i++; continue; }
+
+    // Pipe table
+    if (line.includes('|') && i + 1 < lines.length && isTableSep(lines[i + 1])) {
+      flushAll();
+      const header = splitRow(line);
+      i += 2;
+      const rows = [];
+      while (i < lines.length && lines[i].includes('|') && lines[i].trim() !== '') {
+        rows.push(splitRow(lines[i]));
+        i++;
+      }
+      const thead = `<thead><tr>${header.map(c => `<th style="${TH_STYLE}">${inlineMd(c)}</th>`).join('')}</tr></thead>`;
+      const tbody = `<tbody>${rows.map(r => `<tr>${r.map(c => `<td style="${TD_STYLE}">${inlineMd(c)}</td>`).join('')}</tr>`).join('')}</tbody>`;
+      out.push(`<table class="velaro-kb-table" style="${TABLE_STYLE}">${thead}${tbody}</table>`);
+      continue;
+    }
+
+    const ul = line.match(/^\s*[-*]\s+(.+)$/);
+    if (ul) {
+      flushPara();
+      if (!list || list.type !== 'ul') { flushList(); list = { type: 'ul', items: [] }; }
+      list.items.push(ul[1]);
+      i++; continue;
+    }
+    const ol = line.match(/^\s*\d+\.\s+(.+)$/);
+    if (ol) {
+      flushPara();
+      if (!list || list.type !== 'ol') { flushList(); list = { type: 'ol', items: [] }; }
+      list.items.push(ol[1]);
+      i++; continue;
+    }
+
+    if (/^<(h[1-6]|table|ul|ol|p|div|pre|blockquote)/i.test(line.trim())) {
+      flushAll();
+      out.push(line);
+      i++; continue;
+    }
+
+    flushList();
+    para.push(line.trim());
+    i++;
+  }
+  flushAll();
+  return out.join('\n');
+}
+
+function truncate(str, max) {
+  if (!str) return '-';
+  return str.length <= max ? str : str.slice(0, max - 1) + '...';
+}