@jackwener/opencli 0.3.0 → 0.4.1

package/CLI-CREATOR.md

@@ -3,6 +3,94 @@
 > 本文档教你（或 AI Agent）如何为 OpenCLI 添加一个新网站的命令。  
 > 从零到发布，覆盖 API 发现、方案选择、适配器编写、测试验证全流程。
 
+---
+
+## ⚠️ AI Agent 开发者必读：用 Playwright MCP Bridge 探索
+
+> [!CAUTION]
+> **你（AI Agent）必须通过 Playwright MCP Bridge 打开浏览器去访问目标网站！**  
+> 不要只靠 `opencli explore` 命令或静态分析来发现 API。  
+> 你拥有 Playwright MCP 工具，必须主动用它们浏览网页、观察网络请求、模拟用户交互。
+
+### 为什么？
+
+很多 API 是**懒加载**的（用户必须点击某个按钮/标签才会触发网络请求）。字幕、评论、关注列表等深层数据不会在页面首次加载时出现在 Network 面板中。**如果你不主动去浏览和交互页面，你永远发现不了这些 API。**
+
+### AI Agent 探索工作流（必须遵循）
+
+```
+ Step 0: 用 Playwright MCP 打开浏览器
+   ↓
+ Step 1: 导航到目标页面，观察页面结构
+   ↓
+ Step 2: 查看 Network 请求（browser_network_requests）
+   ↓
+ Step 3: 模拟用户交互（点击按钮/标签/展开评论）
+   ↓
+ Step 4: 再次查看 Network，发现新触发的 API
+   ↓
+ Step 5: 分析 API 的请求参数、响应结构、鉴权方式
+   ↓
+ Step 6: 编写适配器代码
+```
+
+### 具体操作步骤
+
+**Step 0: 打开浏览器**
+```
+工具: browser_navigate
+URL: https://www.bilibili.com/video/BV1xxxxx
+```
+
+**Step 1: 获取页面快照，了解页面结构**
+```
+工具: browser_snapshot
+→ 观察页面上有哪些可交互元素（按钮、标签、链接）
+```
+
+**Step 2: 查看已有的网络请求**
+```
+工具: browser_network_requests
+→ 筛选出 JSON API 端点（忽略静态资源）
+→ 记录 URL pattern、请求头、响应结构
+```
+
+**Step 3: 模拟用户交互发现深层 API**
+```
+工具: browser_click (点击"字幕"按钮、"评论"标签、"关注"链接等)
+工具: browser_wait_for (等待数据加载)
+```
+
+**Step 4: 再次抓包，发现新 API**
+```
+工具: browser_network_requests
+→ 对比 Step 2，找出新触发的 API 端点
+```
+
+**Step 5: 用 evaluate 测试 API 可行性**
+```
+工具: browser_evaluate
+代码: async () => {
+  const res = await fetch('https://api.bilibili.com/x/player/wbi/v2?bvid=BV1xxx&cid=123', 
+    { credentials: 'include' });
+  return await res.json();
+}
+→ 验证返回的数据结构和字段
+→ 如果返回空/403：检查是否需要签名（Wbi）或特殊 Header
+```
+
+### 常犯错误
+
+| ❌ 错误做法 | ✅ 正确做法 |
+|------------|------------|
+| 只用 `opencli explore` 命令，等结果自动出来 | 用 MCP Bridge 打开浏览器，主动浏览页面 |
+| 直接在代码里 `fetch(url)`，不看浏览器实际请求 | 先在浏览器中确认 API 可用，再写代码 |
+| 页面打开后直接抓包，期望所有 API 都出现 | 模拟点击交互（展开评论/切换标签/加载更多） |
+| 遇到 HTTP 200 但空数据就放弃 | 检查是否需要 Wbi 签名或 Cookie 鉴权 |
+| 完全依赖 `__INITIAL_STATE__` 拿所有数据 | `__INITIAL_STATE__` 只有首屏数据，深层数据要调 API |
+
+---
+
 ## 核心流程
 
 ```
@@ -57,8 +145,9 @@ opencli bilibili hot -v   # 查看已有命令的 pipeline 每步数据流
 
 1. **后缀爆破法 (`.json`)**: 像 Reddit 这样复杂的网站，只要在其 URL 后加上 `.json`（例如 `/r/all.json`），就能在带 Cookie 的情况下直接利用 `fetch` 拿到极其干净的 REST 数据（Tier 2 Cookie 策略极速秒杀）。另外如功能完备的**雪球 (xueqiu)** 也可以走这种纯 API 的方式极简获取，成为你构建简单 YAML 的黄金标杆。
 2. **全局状态查找法 (`__INITIAL_STATE__`)**: 许多服务端渲染 (SSR) 的网站（如小红书、Bilibili）会将首页或详情页的完整数据挂载到全局 window 对象上。与其去拦截网络请求，不如直接 `page.evaluate('() => window.__INITIAL_STATE__')` 获取整个数据树。
-3. **框架探测与 Store Action 截断**: 如果站点使用 Vue + Pinia，可以使用 `tap` 步骤调用 action，让前端框架代替你完成复杂的鉴权签名封装。
-4. **底层 XHR/Fetch 拦截**: 最后手段，当上述都不行时，使用 TypeScript 适配器进行无侵入式的请求抓取。
+3. **主动交互触发法 (Active Interaction)**: 很多深层 API（如视频字幕、评论下的回复）是懒加载的。在静态抓包找不到数据时，尝试在 `evaluate` 步骤或手动打断点时，主动去**点击（Click）页面上的对应按钮**（如"CC"、"展开全部"），从而诱发隐藏的 Network Fetch。
+4. **框架探测与 Store Action 截断**: 如果站点使用 Vue + Pinia，可以使用 `tap` 步骤调用 action，让前端框架代替你完成复杂的鉴权签名封装。
+5. **底层 XHR/Fetch 拦截**: 最后手段，当上述都不行时，使用 TypeScript 适配器进行无侵入式的请求抓取。
 
 ### 1d. 框架检测
 
@@ -411,6 +500,35 @@ cli({
 
 > **拦截核心思路**：不自己构造签名，而是利用 `installInterceptor` 劫持网站自己的 `XMLHttpRequest` 和 `fetch`，让网站发请求，我们直接在底层取出解析好的 `response.json()`。
 
+#### 进阶场景 1: 级联请求 (Cascading Requests) 与鉴权绕过
+
+部分 API 获取是非常复杂的连环请求（例如 B 站获取视频字幕：先需要 `bvid` 获取核心 `cid`，再通过 `cid` 获取包含签名/Wbi 的字幕列表拉取地址，最后 fetch 真实的 CDN 资源）。在此类场景中，你必须在一个 `evaluate` 块内部或者在 TypeScript Node 端编排整个请求链条：
+
+```typescript
+// 真实场景：B站获取视频字幕的级联获取思路
+const subtitleUrls = await page.evaluate(async (bvid) => {
+  // Step 1: 拿 CID (通常可以通过页面全局状态极速提取)
+  const cid = window.__INITIAL_STATE__?.videoData?.cid;
+  
+  // Step 2: 依据 BVID 和 CID 拿字幕配置 (可能需要携带 W_RID 签名或依赖浏览器当前登录状态 Cookie)
+  const res = await fetch(\`/x/player/wbi/v2?bvid=\${bvid}&cid=\${cid}\`, { credentials: 'include' });
+  const data = await res.json();
+  
+  // Step 3: 风控拦截/未登录降级空值检测 (Anti-Bot Empty Value Detection) ⚠️ 极其重要
+  // 很多大厂 API 只要签名失败或无强登录 Cookie 依然会返回 HTTP 200，但把关键 URL 设为 ""
+  const firstSubUrl = data.data?.subtitle?.subtitles?.[0]?.subtitle_url;
+  if (!firstSubUrl) {
+    throw new Error('被风控降级或需登录：拿不到真实的 subtitle_url，请检查 Cookie 状态 (Tier 2/3)');
+  }
+  
+  return firstSubUrl;
+}, kwargs.bvid);
+
+// Step 4: 拉取最终的 CDN 静态文件 (无鉴权)
+const finalRes = await fetch(subtitleUrls.startsWith('//') ? 'https:' + subtitleUrls : subtitleUrls);
+const subtitles = await finalRes.json();
+```
+
 ---
 
 ## Step 4: 测试
@@ -539,6 +657,70 @@ git push
 
 ---
 
+## 进阶模式: 级联请求 (Cascading Requests)
+
+当目标数据需要多步 API 链式获取时（如 `BVID → CID → 字幕列表 → 字幕内容`），必须使用 **TS 适配器**。YAML 无法处理这种多步逻辑。
+
+### 模板代码
+
+```typescript
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+import { apiGet } from '../../bilibili.js'; // 复用平台 SDK
+
+cli({
+  site: 'bilibili',
+  name: 'subtitle',
+  strategy: Strategy.COOKIE,
+  args: [{ name: 'bvid', required: true }],
+  columns: ['index', 'from', 'to', 'content'],
+  func: async (page: IPage | null, kwargs: any) => {
+    if (!page) throw new Error('Requires browser');
+
+    // Step 1: 建立 Session
+    await page.goto(`https://www.bilibili.com/video/${kwargs.bvid}/`);
+
+    // Step 2: 从页面提取中间 ID (__INITIAL_STATE__)
+    const cid = await page.evaluate(`(async () => {
+      return window.__INITIAL_STATE__?.videoData?.cid;
+    })()`);
+    if (!cid) throw new Error('无法提取 CID');
+
+    // Step 3: 用中间 ID 调用下一级 API (自动 Wbi 签名)
+    const payload = await apiGet(page, '/x/player/wbi/v2', {
+      params: { bvid: kwargs.bvid, cid },
+      signed: true, // ← 自动生成 w_rid
+    });
+
+    // Step 4: 检测风控降级 (空值断言)
+    const subtitles = payload.data?.subtitle?.subtitles || [];
+    const url = subtitles[0]?.subtitle_url;
+    if (!url) throw new Error('subtitle_url 为空，疑似风控降级');
+
+    // Step 5: 拉取最终数据 (CDN JSON)
+    const items = await page.evaluate(`(async () => {
+      const res = await fetch(${JSON.stringify('https:' + url)});
+      const json = await res.json();
+      return { data: json.body || json };
+    })()`);
+
+    return items.data.map((item, idx) => ({ ... }));
+  },
+});
+```
+
+### 关键要点
+
+| 步骤 | 注意事项 |
+|------|----------|
+| 提取中间 ID | 优先从 `__INITIAL_STATE__` 拿，避免额外 API 调用 |
+| Wbi 签名 | B 站 `/wbi/` 接口**强制校验** `w_rid`，纯 `fetch` 会被 403 |
+| 空值断言 | 即使 HTTP 200，核心字段可能为空串（风控降级） |
+| CDN URL | 常以 `//` 开头，记得补 `https:` |
+| `JSON.stringify` | 拼接 URL 到 evaluate 时必须用它转义，避免注入 |
+
+---
+
 ## 常见陷阱
 
 | 陷阱 | 表现 | 解决方案 |
@@ -553,6 +735,8 @@ git push
 | TS evaluate 格式 | `() => {}` 报 `result is not a function` | TS 中 `page.evaluate()` 必须用 IIFE：`(async () => { ... })()` |
 | 页面异步加载 | evaluate 拿到空数据（store state 还没更新） | 在 evaluate 内用 polling 等待数据出现，或增加 `wait` 时间 |
 | YAML 内嵌大段 JS | 调试困难，字符串转义问题 | 超过 10 行 JS 的命令改用 TS adapter |
+| **风控被拦截(伪200)** | 获取到的 JSON 里核心数据是 `""` (空串) | 极易被误判。必须添加断言！无核心数据立刻要求升级鉴权 Tier 并重新配置 Cookie |
+| **API 没找见** | `explore` 工具打分出来的都拿不到深层数据 | 点击页面按钮诱发懒加载数据，再结合 `getInterceptedRequests` 获取 |
 
 ---
 
@@ -565,9 +749,10 @@ git push
 opencli generate https://www.example.com --goal "hot"
 
 # 或分步执行：
-opencli explore https://www.example.com --site mysite   # 发现 API
-opencli synthesize mysite                                # 生成候选 YAML
-opencli verify mysite/hot --smoke                        # 冒烟测试
+opencli explore https://www.example.com --site mysite           # 发现 API
+opencli explore https://www.example.com --auto --click "字幕,CC"  # 模拟点击触发懒加载 API
+opencli synthesize mysite                                        # 生成候选 YAML
+opencli verify mysite/hot --smoke                                # 冒烟测试
 ```
 
 生成的候选 YAML 保存在 `.opencli/explore/mysite/candidates/`，可直接复制到 `src/clis/mysite/` 并微调。

package/README.md

@@ -7,7 +7,7 @@
 
 [![npm](https://img.shields.io/npm/v/@jackwener/opencli)](https://www.npmjs.com/package/@jackwener/opencli)
 
-A CLI tool that turns **any website** into a command-line interface. **35+ commands** across **17 sites** — bilibili, zhihu, xiaohongshu, twitter, reddit, xueqiu, github, v2ex, hackernews, bbc, weibo, boss, yahoo-finance, reuters, smzdm, ctrip, youtube — powered by browser session reuse and AI-native discovery.
+A CLI tool that turns **any website** into a command-line interface. **47 commands** across **17 sites** — bilibili, zhihu, xiaohongshu, twitter, reddit, xueqiu, github, v2ex, hackernews, bbc, weibo, boss, yahoo-finance, reuters, smzdm, ctrip, youtube — powered by browser session reuse and AI-native discovery.
 
 ## ✨ Highlights
 
@@ -82,12 +82,12 @@ Public API commands (`hackernews`, `github search`, `v2ex`) need no browser at a
 
 | Site | Commands | Mode |
 |------|----------|------|
-| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` | 🔐 Browser |
+| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` `subtitle` `dynamic` `ranking` `following` | 🔐 Browser |
 | **zhihu** | `hot` `search` `question` | 🔐 Browser |
-| **xiaohongshu** | `search` `notifications` `feed` | 🔐 Browser |
+| **xiaohongshu** | `search` `notifications` `feed` `me` `user` | 🔐 Browser |
 | **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 🔐 Browser |
-| **twitter** | `trending` `bookmarks` | 🔐 Browser |
-| **reddit** | `hot` | 🔐 Browser |
+| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` | 🔐 Browser |
+| **reddit** | `hot` `frontpage` `search` `subreddit` | 🔐 Browser |
 | **weibo** | `hot` | 🔐 Browser |
 | **boss** | `search` | 🔐 Browser |
 | **youtube** | `search` | 🔐 Browser |
@@ -95,7 +95,7 @@ Public API commands (`hackernews`, `github search`, `v2ex`) need no browser at a
 | **reuters** | `search` | 🔐 Browser |
 | **smzdm** | `search` | 🔐 Browser |
 | **ctrip** | `search` | 🔐 Browser |
-| **github** | `trending` `search` | 🔐 / 🌐 |
+| **github** | `search` | 🌐 Public |
 | **v2ex** | `hot` `latest` `topic` | 🌐 Public |
 | **hackernews** | `top` | 🌐 Public |
 | **bbc** | `news` | 🌐 Public |

package/README.zh-CN.md

@@ -11,7 +11,7 @@ OpenCLI 通过 Chrome 浏览器 + [Playwright MCP Bridge](https://github.com/nic
 
 ## ✨ 亮点
 
-- 🌐 **35+ 命令，17 个站点** — B站、知乎、小红书、Twitter、Reddit、雪球(xueqiu)、GitHub、V2EX、Hacker News、BBC、微博、BOSS直聘、Yahoo Finance、路透社、什么值得买、携程、YouTube
+- 🌐 **47 个命令，17 个站点** — B站、知乎、小红书、Twitter、Reddit、雪球(xueqiu)、GitHub、V2EX、Hacker News、BBC、微博、BOSS直聘、Yahoo Finance、路透社、什么值得买、携程、YouTube
 - 🔐 **零风控** — 复用 Chrome 登录态，无需存储任何凭证
 - 🤖 **AI 原生** — `explore` 自动发现 API，`synthesize` 生成适配器，`cascade` 探测认证策略
 - 🚀 **动态加载引擎** — 只需将 `.ts` 或 `.yaml` 适配器放入 `clis/` 文件夹即可自动注册生效
@@ -83,12 +83,12 @@ npm install -g @jackwener/opencli@latest
 
 | 站点 | 命令 | 模式 |
 |------|------|------|
-| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` | 🔐 浏览器 |
+| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` `subtitle` `dynamic` `ranking` `following` | 🔐 浏览器 |
 | **zhihu** | `hot` `search` `question` | 🔐 浏览器 |
-| **xiaohongshu** | `search` `notifications` `feed` | 🔐 浏览器 |
+| **xiaohongshu** | `search` `notifications` `feed` `me` `user` | 🔐 浏览器 |
 | **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 🔐 浏览器 |
-| **twitter** | `trending` `bookmarks` | 🔐 浏览器 |
-| **reddit** | `hot` | 🔐 浏览器 |
+| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` | 🔐 浏览器 |
+| **reddit** | `hot` `frontpage` `search` `subreddit` | 🔐 浏览器 |
 | **weibo** | `hot` | 🔐 浏览器 |
 | **boss** | `search` | 🔐 浏览器 |
 | **youtube** | `search` | 🔐 浏览器 |
@@ -96,7 +96,7 @@ npm install -g @jackwener/opencli@latest
 | **reuters** | `search` | 🔐 浏览器 |
 | **smzdm** | `search` | 🔐 浏览器 |
 | **ctrip** | `search` | 🔐 浏览器 |
-| **github** | `trending` `search` | 🔐 / 🌐 |
+| **github** | `search` | 🌐 公共 API |
 | **v2ex** | `hot` `latest` `topic` | 🌐 公共 API |
 | **hackernews** | `top` | 🌐 公共 API |
 | **bbc** | `news` | 🌐 公共 API |

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: opencli
 description: "OpenCLI — Make any website your CLI. Zero risk, AI-powered, reuse Chrome login."
-version: 0.1.0
+version: 0.4.0
 author: jackwener
 tags: [cli, browser, web, mcp, playwright, bilibili, zhihu, twitter, github, v2ex, hackernews, reddit, xiaohongshu, xueqiu, AI, agent]
 ---
@@ -49,6 +49,10 @@ opencli bilibili favorite                 # 我的收藏
 opencli bilibili history --limit 20       # 观看历史
 opencli bilibili feed --limit 10          # 动态时间线
 opencli bilibili user-videos --uid 12345  # 用户投稿
+opencli bilibili subtitle --bvid BV1xxx   # 获取视频字幕 (支持 --lang zh-CN)
+opencli bilibili dynamic --limit 10       # 动态
+opencli bilibili ranking --limit 10       # 排行榜
+opencli bilibili following --limit 20     # 我的关注列表 (支持 --uid 查看他人)
 
 # 知乎 (browser)
 opencli zhihu hot --limit 10             # 知乎热榜
@@ -59,24 +63,33 @@ opencli zhihu question --id 34816524     # 问题详情和回答
 opencli xiaohongshu search --keyword "美食"  # 搜索笔记
 opencli xiaohongshu notifications             # 通知（mentions/likes/connections）
 opencli xiaohongshu feed --limit 10           # 推荐 Feed
+opencli xiaohongshu me                         # 我的信息
+opencli xiaohongshu user --uid xxx             # 用户主页
 
 # 雪球 Xueqiu (browser)
 opencli xueqiu hot-stock --limit 10      # 雪球热门股票榜
 opencli xueqiu stock --symbol SH600519   # 查看股票实时行情
 opencli xueqiu watchlist                 # 获取自选股/持仓列表
 opencli xueqiu feed                      # 我的关注 timeline
+opencli xueqiu hot --limit 10            # 雪球热榜
+opencli xueqiu search --keyword "特斯拉"  # 搜索
 
-# GitHub (trending=browser, search=public)
-opencli github trending --limit 10       # GitHub Trending
+# GitHub (public)
 opencli github search --keyword "cli"    # 搜索仓库
 
 # Twitter/X (browser)
 opencli twitter trending --limit 10      # 热门话题
 opencli twitter bookmarks --limit 20     # 获取收藏的书签推文
+opencli twitter search --keyword "AI"    # 搜索推文
+opencli twitter profile --username elonmusk  # 用户资料
+opencli twitter timeline --limit 20      # 时间线
 
 # Reddit (browser)
 opencli reddit hot --limit 10            # 热门帖子
 opencli reddit hot --subreddit programming  # 指定子版块
+opencli reddit frontpage --limit 10      # 首页
+opencli reddit search --keyword "AI"     # 搜索
+opencli reddit subreddit --name rust     # 子版块浏览
 
 # V2EX (public)
 opencli v2ex hot --limit 10              # 热门话题
@@ -135,6 +148,9 @@ opencli generate <url> --goal "hot"
 # Strategy Cascade: auto-probe PUBLIC → COOKIE → HEADER
 opencli cascade <api-url>
 
+# Explore with interactive fuzzing (click buttons to trigger lazy APIs)
+opencli explore <url> --auto --click "字幕,CC,评论"
+
 # Verify: smoke-test a generated adapter
 opencli verify <site/name> --smoke
 ```

package/dist/browser.d.ts

@@ -23,7 +23,11 @@ export declare class Page implements IPage {
     click(ref: string): Promise<void>;
     typeText(ref: string, text: string): Promise<void>;
     pressKey(key: string): Promise<void>;
-    wait(seconds: number): Promise<void>;
+    wait(options: number | {
+        text?: string;
+        time?: number;
+        timeout?: number;
+    }): Promise<void>;
     tabs(): Promise<any>;
     closeTab(index?: number): Promise<void>;
     newTab(): Promise<void>;

package/dist/browser.js

@@ -110,8 +110,14 @@ export class Page {
     async pressKey(key) {
         await this.call('tools/call', { name: 'browser_press_key', arguments: { key } });
     }
-    async wait(seconds) {
-        await this.call('tools/call', { name: 'browser_wait_for', arguments: { time: seconds } });
+    async wait(options) {
+        if (typeof options === 'number') {
+            await this.call('tools/call', { name: 'browser_wait_for', arguments: { time: options } });
+        }
+        else {
+            // Pass directly to native wait_for, which supports natively awaiting text strings without heavy DOM polling
+            await this.call('tools/call', { name: 'browser_wait_for', arguments: options });
+        }
     }
     async tabs() {
         return this.call('tools/call', { name: 'browser_tabs', arguments: { action: 'list' } });
@@ -137,10 +143,32 @@ export class Page {
     async autoScroll(options = {}) {
         const times = options.times ?? 3;
         const delayMs = options.delayMs ?? 2000;
-        for (let i = 0; i < times; i++) {
-            await this.evaluate('() => window.scrollTo(0, document.body.scrollHeight)');
-            await this.wait(delayMs / 1000);
+        const js = `
+      async () => {
+        const maxTimes = ${times};
+        const maxWaitMs = ${delayMs};
+        for (let i = 0; i < maxTimes; i++) {
+          const lastHeight = document.body.scrollHeight;
+          window.scrollTo(0, lastHeight);
+          await new Promise(resolve => {
+            let timeoutId;
+            const observer = new MutationObserver(() => {
+              if (document.body.scrollHeight > lastHeight) {
+                clearTimeout(timeoutId);
+                observer.disconnect();
+                setTimeout(resolve, 100); // Small debounce for rendering
+              }
+            });
+            observer.observe(document.body, { childList: true, subtree: true });
+            timeoutId = setTimeout(() => {
+              observer.disconnect();
+              resolve(null);
+            }, maxWaitMs);
+          });
         }
+      }
+    `;
+        await this.evaluate(js);
     }
     async installInterceptor(pattern) {
         const js = `

package/dist/build-manifest.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Build-time CLI manifest compiler.
+ *
+ * Scans all YAML/TS CLI definitions and pre-compiles them into a single
+ * manifest.json for instant cold-start registration (no runtime YAML parsing).
+ *
+ * Usage: npx tsx src/build-manifest.ts
+ * Output: dist/cli-manifest.json
+ */
+export {};

package/dist/build-manifest.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Build-time CLI manifest compiler.
+ *
+ * Scans all YAML/TS CLI definitions and pre-compiles them into a single
+ * manifest.json for instant cold-start registration (no runtime YAML parsing).
+ *
+ * Usage: npx tsx src/build-manifest.ts
+ * Output: dist/cli-manifest.json
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLIS_DIR = path.resolve(__dirname, 'clis');
+const OUTPUT = path.resolve(__dirname, '..', 'dist', 'cli-manifest.json');
+function scanYaml(filePath, site) {
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const def = yaml.load(raw);
+        if (!def || typeof def !== 'object')
+            return null;
+        const strategyStr = def.strategy ?? (def.browser === false ? 'public' : 'cookie');
+        const strategy = strategyStr.toUpperCase();
+        const browser = def.browser ?? (strategy !== 'PUBLIC');
+        const args = [];
+        if (def.args && typeof def.args === 'object') {
+            for (const [argName, argDef] of Object.entries(def.args)) {
+                args.push({
+                    name: argName,
+                    type: argDef?.type ?? 'str',
+                    default: argDef?.default,
+                    required: argDef?.required ?? false,
+                    help: argDef?.description ?? argDef?.help ?? '',
+                    choices: argDef?.choices,
+                });
+            }
+        }
+        return {
+            site: def.site ?? site,
+            name: def.name ?? path.basename(filePath, path.extname(filePath)),
+            description: def.description ?? '',
+            domain: def.domain,
+            strategy: strategy.toLowerCase(),
+            browser,
+            args,
+            columns: def.columns,
+            pipeline: def.pipeline,
+            timeout: def.timeout,
+            type: 'yaml',
+        };
+    }
+    catch (err) {
+        process.stderr.write(`Warning: failed to parse ${filePath}: ${err.message}\n`);
+        return null;
+    }
+}
+function scanTs(filePath, site) {
+    // TS adapters self-register via cli() at import time.
+    // We record their module path for lazy dynamic import.
+    const baseName = path.basename(filePath, path.extname(filePath));
+    const relativePath = `${site}/${baseName}.js`;
+    return {
+        site,
+        name: baseName,
+        description: '',
+        strategy: 'cookie',
+        browser: true,
+        args: [],
+        type: 'ts',
+        modulePath: relativePath,
+    };
+}
+// Main
+const manifest = [];
+if (fs.existsSync(CLIS_DIR)) {
+    for (const site of fs.readdirSync(CLIS_DIR)) {
+        const siteDir = path.join(CLIS_DIR, site);
+        if (!fs.statSync(siteDir).isDirectory())
+            continue;
+        for (const file of fs.readdirSync(siteDir)) {
+            const filePath = path.join(siteDir, file);
+            if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+                const entry = scanYaml(filePath, site);
+                if (entry)
+                    manifest.push(entry);
+            }
+            else if ((file.endsWith('.ts') && !file.endsWith('.d.ts') && file !== 'index.ts') ||
+                (file.endsWith('.js') && !file.endsWith('.d.js') && file !== 'index.js')) {
+                manifest.push(scanTs(filePath, site));
+            }
+        }
+    }
+}
+// Ensure output directory exists
+fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
+fs.writeFileSync(OUTPUT, JSON.stringify(manifest, null, 2));
+const yamlCount = manifest.filter(e => e.type === 'yaml').length;
+const tsCount = manifest.filter(e => e.type === 'ts').length;
+console.log(`✅ Manifest compiled: ${manifest.length} entries (${yamlCount} YAML, ${tsCount} TS) → ${OUTPUT}`);