@tvbs-ai/news-rd 0.1.2 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ TVBS News Rundown AI CLI — query rundowns, news candidates, Google Trends, and
 
 ```bash
 npm install -g @tvbs-ai/news-rd
-# or
+# or run directly
 npx @tvbs-ai/news-rd --help
 ```
 
@@ -25,6 +25,7 @@ news-rd <group> <command> [args] [options]
 | `news` | 候選新聞與趨勢關鍵字 |
 | `prompt` | Prompt 模板、變數與編譯 |
 | `token` | JWT Token 管理 |
+| `completion` | Shell auto-completion |
 
 ### Examples
 
@@ -55,7 +56,8 @@ news-rd prompt compile 2026-03-10 0600
 | `--base-url URL` | API base URL | `https://news-rundown.tvbs.ai` |
 | `--token TOKEN` | JWT token (or `RD_TOKEN` env) | — |
 | `--json` | Raw JSON output | — |
-| `--help` | Show help | — |
+| `--version, -v` | Show version | — |
+| `--help, -h` | Show help | — |
 
 ### Environment Variables
 
@@ -64,14 +66,33 @@ news-rd prompt compile 2026-03-10 0600
 | `RD_BASE_URL` | API base URL |
 | `RD_TOKEN` | JWT authentication token |
 
+### Shell Completion
+
+```bash
+# Bash
+news-rd completion bash >> ~/.bashrc && source ~/.bashrc
+
+# Zsh
+news-rd completion zsh >> ~/.zshrc && source ~/.zshrc
+```
+
+## Update
+
+The CLI automatically checks for new versions and shows a hint after command output. To update:
+
+```bash
+npm install -g @tvbs-ai/news-rd@latest
+```
+
 ## Requirements
 
 - Node.js >= 18 (uses built-in fetch)
 - A running TVBS News Rundown AI server
 
-## Publishing
+## Documentation
 
-See [CLI 發佈指南](../../docs/cli-publishing.md) for version bumping and npm publishing workflow.
+- [使用教學](../../docs/cli-guide.md) — 完整的操作教學（中文）
+- [發佈指南](../../docs/cli-publishing.md) — 版本更新與 npm 發佈流程
 
 ## License
 

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-var args = process.argv.slice(2);
+var CLI_VERSION = "0.2.0";
+var rawArgs = process.argv.slice(2);
 function parseArgs() {
   const options = {
     baseUrl: process.env.RD_BASE_URL || "https://news-rundown.tvbs.ai",
@@ -11,57 +12,93 @@ function parseArgs() {
   const positional = [];
   let group = "";
   let command = "";
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    switch (arg) {
-      case "--base-url":
-        options.baseUrl = args[++i] || options.baseUrl;
-        break;
-      case "--token":
-        options.token = args[++i] || "";
-        break;
-      case "--json":
-        options.json = true;
-        break;
-      case "--category":
-        options.category = args[++i];
-        break;
-      case "--content-type":
-        options.contentType = args[++i];
-        break;
-      case "--limit":
-        options.limit = args[++i];
-        break;
-      case "--version":
-        options.version = args[++i];
-        break;
-      case "--variables":
-        options.variables = args[++i];
-        break;
-      case "--help":
-      case "-h":
-        if (group) {
-          showGroupHelp(group);
-        } else {
-          showHelp();
-        }
-        process.exit(0);
-        break;
-      default:
-        if (!group) {
-          group = arg;
-        } else if (!command) {
-          command = arg;
-        } else {
-          positional.push(arg);
-        }
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg.startsWith("-")) {
+      switch (arg) {
+        case "--base-url":
+          options.baseUrl = rawArgs[++i] || options.baseUrl;
+          break;
+        case "--token":
+          options.token = rawArgs[++i] || "";
+          break;
+        case "--json":
+          options.json = true;
+          break;
+        case "--category":
+          options.category = rawArgs[++i];
+          break;
+        case "--content-type":
+          options.contentType = rawArgs[++i];
+          break;
+        case "--limit":
+          options.limit = rawArgs[++i];
+          break;
+        case "--version":
+          if (!group) {
+            console.log(`@tvbs-ai/news-rd v${CLI_VERSION}`);
+            process.exit(0);
+          }
+          options.version = rawArgs[++i];
+          break;
+        case "-v":
+          console.log(`@tvbs-ai/news-rd v${CLI_VERSION}`);
+          process.exit(0);
+        case "--variables":
+          options.variables = rawArgs[++i];
+          break;
+        case "--help":
+        case "-h":
+          break;
+        default:
+          console.error(`Unknown option: ${arg}`);
+          process.exit(1);
+      }
+      continue;
+    }
+    if (!group) {
+      group = arg;
+    } else if (!command) {
+      command = arg;
+    } else {
+      positional.push(arg);
     }
   }
+  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    if (group) {
+      showGroupHelp(group);
+    } else {
+      showHelp();
+    }
+    process.exit(0);
+  }
   return { group, command, positional, options };
 }
+var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+var VALID_TIMESLOTS = ["0600", "0700", "0800", "1400", "1500", "1600"];
+function requireDateTimeslot(positional, group, command) {
+  const [date, timeslot] = positional;
+  if (!date || !timeslot) {
+    console.error(`Usage: news-rd ${group} ${command} <date> <timeslot>`);
+    console.error(`  date:     YYYY-MM-DD (e.g. 2026-03-10)`);
+    console.error(`  timeslot: ${VALID_TIMESLOTS.join(" | ")}`);
+    process.exit(1);
+  }
+  if (!DATE_RE.test(date)) {
+    console.error(`Invalid date format: "${date}"`);
+    console.error(`  Expected YYYY-MM-DD (e.g. 2026-03-10)`);
+    process.exit(1);
+  }
+  if (!VALID_TIMESLOTS.includes(timeslot)) {
+    console.error(`Invalid timeslot: "${timeslot}"`);
+    console.error(`  Available: ${VALID_TIMESLOTS.join(", ")}`);
+    process.exit(1);
+  }
+  return [date, timeslot];
+}
 function showHelp() {
   console.log(`
-tvbs-news-rd \u2014 TVBS News Rundown AI CLI
+@tvbs-ai/news-rd v${CLI_VERSION} \u2014 TVBS News Rundown AI CLI
 
 Usage: news-rd <group> <command> [args] [options]
 
@@ -71,11 +108,13 @@ Groups:
   news       \u5019\u9078\u65B0\u805E\u8207\u8DA8\u52E2\u95DC\u9375\u5B57
   prompt     Prompt \u6A21\u677F\u3001\u8B8A\u6578\u8207\u7DE8\u8B6F
   token      JWT Token \u7BA1\u7406
+  completion Shell auto-completion
 
 Global Options:
   --base-url URL   API base URL (default: https://news-rundown.tvbs.ai)
   --token TOKEN    JWT token (or RD_TOKEN env)
   --json           Raw JSON output
+  --version, -v    Show version
   --help, -h       Show help
 
 Run 'news-rd <group> --help' for group-specific commands.
@@ -146,10 +185,25 @@ Examples:
 token \u2014 JWT Token \u7BA1\u7406
 
 Commands:
-  generate    Generate a new admin JWT token (requires Clerk session)
+  generate    Generate a new admin JWT token
+
+Note: Token generation requires a Clerk session cookie.
+      The easiest way is to use the Web UI \u2014 log in and click "API Token"
+      in the header. The CLI command is for scripting with an existing session.
 
 Examples:
   news-rd token generate
+`,
+  completion: `
+completion \u2014 Shell auto-completion
+
+Commands:
+  bash    Output bash completion script
+  zsh     Output zsh completion script
+
+Setup:
+  news-rd completion bash >> ~/.bashrc && source ~/.bashrc
+  news-rd completion zsh >> ~/.zshrc && source ~/.zshrc
 `
 };
 function showGroupHelp(group) {
@@ -223,8 +277,7 @@ async function apiCall(path, options, method = "GET") {
         console.error(`    # or`);
         console.error(`    export RD_TOKEN=YOUR_TOKEN
 `);
-        console.error(`  To generate a token, log in to the web UI and click "API Token",`);
-        console.error(`  or run: news-rd token generate (requires Clerk session).
+        console.error(`  To generate a token, log in to the web UI and click "API Token".
 `);
       } else {
         console.error(`  ${errorMsg}
@@ -259,14 +312,6 @@ function printTable(rows, columns) {
     console.log(cols.map((c, i) => String(row[c] ?? "").padEnd(widths[i])).join("  "));
   }
 }
-function requireDateTimeslot(positional, group, command) {
-  const [date, timeslot] = positional;
-  if (!date || !timeslot) {
-    console.error(`Usage: news-rd ${group} ${command} <date> <timeslot>`);
-    process.exit(1);
-  }
-  return [date, timeslot];
-}
 async function handleConfig(command, _positional, options) {
   switch (command) {
     case "timeslots": {
@@ -275,12 +320,12 @@ async function handleConfig(command, _positional, options) {
         printJson(data);
         return;
       }
-      printTable(data.timeslots, ["slot_code", "description", "include_google_trends"]);
+      printTable(data.timeslots, ["slot_code", "description"]);
       return;
     }
     default:
       showGroupHelp("config");
-      process.exit(1);
+      process.exit(0);
   }
 }
 async function handleRundown(command, positional, options) {
@@ -292,10 +337,30 @@ async function handleRundown(command, positional, options) {
         printJson(data);
         return;
       }
-      console.log(`Rundown: ${data.rundown_id}`);
       const items = data.rundown.items || [];
-      console.log(`Items: ${items.length}`);
-      printJson(data);
+      console.log(`Rundown: ${data.rundown_id}`);
+      console.log(`Items: ${items.length}
+`);
+      printTable(items.map((item, i) => {
+        const newsItem = item.news_item;
+        const scoring = newsItem?.scoring || {};
+        const bonus = scoring.rundown_bonus || {};
+        return {
+          "#": item.sequence ?? i + 1,
+          type: item.item_type,
+          slug: newsItem?.slug ?? "-",
+          category: newsItem?.category ?? "-",
+          content_type: newsItem?.content_type ?? "-",
+          final: newsItem ? scoring.rundown_final_score?.toFixed?.(1) ?? "-" : "-",
+          summary: newsItem ? scoring.summary_score?.toFixed?.(1) ?? "-" : "-",
+          visual: newsItem ? scoring.visual_score?.toFixed?.(1) ?? "-" : "-",
+          trends: newsItem ? bonus.google_trends_score ?? 0 : "-",
+          excl: newsItem ? bonus.exclusivity_score ?? 0 : "-",
+          radar: newsItem ? bonus.trending_keywords_score ?? 0 : "-",
+          topic: newsItem ? bonus.featured_topic_score ?? 0 : "-",
+          title: newsItem ? String(newsItem.title ?? "").substring(0, 40) : item.placeholder?.caption ?? "-"
+        };
+      }), ["#", "type", "slug", "category", "content_type", "final", "summary", "visual", "trends", "excl", "radar", "topic", "title"]);
       return;
     }
     case "history": {
@@ -316,7 +381,7 @@ async function handleRundown(command, positional, options) {
     }
     default:
       showGroupHelp("rundown");
-      process.exit(1);
+      process.exit(0);
   }
 }
 async function handleNews(command, positional, options) {
@@ -336,13 +401,23 @@ async function handleNews(command, positional, options) {
       }
       console.log(`Statistics: total=${data.statistics.total}, with_slug=${data.statistics.with_slug}, without_slug=${data.statistics.without_slug}
 `);
-      printTable(data.candidates.map((c) => ({
-        score: c.final_score?.toFixed(1),
-        title: String(c.title).substring(0, 50),
-        category: c.category,
-        slug: c.slug || "-",
-        video_id: c.video_id
-      })), ["score", "category", "title", "slug", "video_id"]);
+      printTable(data.candidates.map((c) => {
+        const bonus = c.bonus_scoring || {};
+        return {
+          slug: c.slug || "-",
+          category: c.category,
+          content_type: c.content_type || "-",
+          publish_time: c.publish_time ? String(c.publish_time).substring(0, 16) : "-",
+          final: c.final_score?.toFixed(1),
+          summary: c.summary_score?.toFixed(1) ?? "-",
+          visual: c.visual_score?.toFixed(1) ?? "-",
+          trends: bonus.google_trends_score ?? 0,
+          excl: bonus.exclusivity_score ?? 0,
+          radar: bonus.trending_keywords_score ?? 0,
+          topic: bonus.featured_topic_score ?? 0,
+          title: String(c.title).substring(0, 40)
+        };
+      }), ["slug", "category", "content_type", "publish_time", "final", "summary", "visual", "trends", "excl", "radar", "topic", "title"]);
       return;
     }
     case "trends": {
@@ -373,7 +448,7 @@ ${window} keywords (${trends.keywords.length}):`);
     }
     default:
       showGroupHelp("news");
-      process.exit(1);
+      process.exit(0);
   }
 }
 async function handlePrompt(command, positional, options) {
@@ -460,7 +535,7 @@ ${data.compiled_prompt}
     }
     default:
       showGroupHelp("prompt");
-      process.exit(1);
+      process.exit(0);
   }
 }
 async function handleToken(command, _positional, options) {
@@ -479,15 +554,156 @@ Set env: export RD_TOKEN="${data.token}"`);
     }
     default:
       showGroupHelp("token");
-      process.exit(1);
+      process.exit(0);
+  }
+}
+function handleCompletion(command) {
+  switch (command) {
+    case "bash":
+      console.log(generateBashCompletion());
+      return;
+    case "zsh":
+      console.log(generateZshCompletion());
+      return;
+    default:
+      showGroupHelp("completion");
+      process.exit(0);
+  }
+}
+function generateBashCompletion() {
+  return `# bash completion for news-rd
+_news_rd_completions() {
+  local cur prev groups
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  groups="config rundown news prompt token completion"
+
+  case "\${COMP_WORDS[1]}" in
+    config)
+      COMPREPLY=($(compgen -W "timeslots" -- "$cur"))
+      ;;
+    rundown)
+      COMPREPLY=($(compgen -W "get history" -- "$cur"))
+      ;;
+    news)
+      COMPREPLY=($(compgen -W "candidates trends keywords" -- "$cur"))
+      ;;
+    prompt)
+      COMPREPLY=($(compgen -W "list show variables resolve compile" -- "$cur"))
+      ;;
+    token)
+      COMPREPLY=($(compgen -W "generate" -- "$cur"))
+      ;;
+    completion)
+      COMPREPLY=($(compgen -W "bash zsh" -- "$cur"))
+      ;;
+    *)
+      if [[ \${COMP_CWORD} -eq 1 ]]; then
+        COMPREPLY=($(compgen -W "$groups --help --version --json" -- "$cur"))
+      fi
+      ;;
+  esac
+
+  case "$prev" in
+    --base-url|--token|--category|--content-type|--limit|--version|--variables)
+      COMPREPLY=()
+      ;;
+    get|history|candidates|trends|keywords|resolve|compile)
+      # Suggest timeslots after date
+      if [[ \${COMP_CWORD} -ge 4 ]]; then
+        COMPREPLY=($(compgen -W "0600 0700 0800 1400 1500 1600" -- "$cur"))
+      fi
+      ;;
+  esac
+}
+complete -F _news_rd_completions news-rd`;
+}
+function generateZshCompletion() {
+  return `# zsh completion for news-rd
+#compdef news-rd
+
+_news_rd() {
+  local -a groups
+  groups=(
+    'config:\u6642\u6BB5\u8207\u74B0\u5883\u8A2D\u5B9A'
+    'rundown:Rundown \u67E5\u8A62\u8207\u7248\u672C\u6BD4\u5C0D'
+    'news:\u5019\u9078\u65B0\u805E\u8207\u8DA8\u52E2\u95DC\u9375\u5B57'
+    'prompt:Prompt \u6A21\u677F\u3001\u8B8A\u6578\u8207\u7DE8\u8B6F'
+    'token:JWT Token \u7BA1\u7406'
+    'completion:Shell auto-completion'
+  )
+
+  local -a timeslots
+  timeslots=(0600 0700 0800 1400 1500 1600)
+
+  _arguments -C \\
+    '--base-url[API base URL]:url:' \\
+    '--token[JWT token]:token:' \\
+    '--json[Raw JSON output]' \\
+    '--version[Show version]' \\
+    '--help[Show help]' \\
+    '1:group:->group' \\
+    '*::arg:->args'
+
+  case $state in
+    group)
+      _describe 'group' groups
+      ;;
+    args)
+      case \${words[1]} in
+        config)
+          _values 'command' 'timeslots[List timeslots]'
+          ;;
+        rundown)
+          _values 'command' 'get[Get rundown]' 'history[Version history]'
+          ;;
+        news)
+          _values 'command' 'candidates[Scored candidates]' 'trends[Google Trends]' 'keywords[NewsRadar keywords]'
+          ;;
+        prompt)
+          _values 'command' 'list[List prompts]' 'show[Get template]' 'variables[List variables]' 'resolve[Resolve variables]' 'compile[Compiled prompt]'
+          ;;
+        token)
+          _values 'command' 'generate[Generate JWT token]'
+          ;;
+        completion)
+          _values 'command' 'bash[Bash completion]' 'zsh[Zsh completion]'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_news_rd "$@"`;
+}
+async function checkForUpdates() {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3e3);
+    const res = await fetch(
+      "https://registry.npmjs.org/@tvbs-ai/news-rd/latest",
+      { signal: controller.signal }
+    );
+    clearTimeout(timeout);
+    if (!res.ok) return;
+    const data = await res.json();
+    const latest = data.version;
+    if (latest && latest !== CLI_VERSION) {
+      console.error(`
+  \u65B0\u7248\u672C\u53EF\u7528: v${latest} (\u76EE\u524D v${CLI_VERSION})`);
+      console.error(`  \u66F4\u65B0\u6307\u4EE4: npm install -g @tvbs-ai/news-rd@latest
+`);
+    }
+  } catch {
   }
 }
 async function main() {
   const { group, command, positional, options } = parseArgs();
   if (!group) {
     showHelp();
-    process.exit(1);
+    process.exit(0);
   }
+  const updateCheck = checkForUpdates();
   try {
     switch (group) {
       case "config":
@@ -505,6 +721,9 @@ async function main() {
       case "token":
         await handleToken(command, positional, options);
         break;
+      case "completion":
+        handleCompletion(command);
+        break;
       default:
         console.error(`Unknown group: ${group}`);
         showHelp();
@@ -514,5 +733,6 @@ async function main() {
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
   }
+  await updateCheck;
 }
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tvbs-ai/news-rd",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "TVBS News Rundown AI CLI — query rundowns, candidates, trends, and prompts",
   "type": "module",
   "bin": {