tirtc-devtools-cli 0.0.10 → 0.0.12

package/README.md

@@ -1,12 +1,17 @@
 # TiRTC DevTools CLI
 
-`devtools/cli/` 承接 `TiRTC DevTools CLI`。它是当前唯一用户界面的产品门面 (command client)，为用户提供了一套操作 `Matrix Host` 控制面的终端工具。
+`products/cli/` 承接 `TiRTC DevTools CLI`。它是当前唯一用户界面的产品门面 (command client)，为用户提供了一套操作 `Matrix Host` 控制面的终端工具。
 
 ## 使用说明 (C-Lite)
 
 关于 `tirtc-devtools-cli` 命令的详细使用方法、参数说明与示例，请参考 [USAGE.md](./USAGE.md)。
 
-如果要先快速确认当前 binary 暴露了哪些命令面，直接运行：`node devtools/cli/bin/tirtc-devtools-cli.js --help`。
+如果要先快速确认当前 binary 暴露了哪些命令面，直接运行：`node products/cli/bin/tirtc-devtools-cli.js --help`。
+
+当前正式入口补充：
+
+- server 侧最小入口：`service start`
+- client 本地预览正式入口：`client start --token <token>` + `[client]` TOML
 
 ## 负责什么
 
@@ -15,6 +20,7 @@
 - **产品级 Observability**：将底层的运行时事件和状态翻译为结构化输出 (JSON) 或友好的终端日志输出；对长耗时命令补轻量进度提示。
 - **调试期工具内聚**：承接调试期必要工具（如 token bootstrap、二维码与媒体预处理）的产品化入口，避免把调试流程散落在 runtime 或外部手工步骤中。
 - **本地 token 工具**：提供直接签发 token、打印组合 JSON、单独 token 与本地二维码 PNG 路径的公开 CLI 能力，服务本地联调与体验验证。
+- **本地 license 二维码工具**：提供 server 扫码用的 license JSON 二维码生成能力，支持可选 `endpoint`。
 
 ## 不负责什么
 
@@ -24,7 +30,7 @@
 
 ## 依赖方向
 
-- **依赖 `app-server/protocol-client/`**：通过可复用的第一方协议客户端与 `Matrix Host` 进程通信。
+- **依赖 `products/app-server/protocol-client/`**：通过可复用的第一方协议客户端与 `Matrix Host` 进程通信。
 - **绝不依赖 `runtime/` 代码实现**：CLI 不直接链接 runtime 模块，只消费 app-server 打包好的运行时产物与 Host 协议。
 
 ## 这里应该放什么
@@ -36,7 +42,7 @@
 
 ## 代码规范与 lint
 
-- TypeScript 代码规范通过 `eslint` 承接，配置文件位于 `devtools/cli/.eslintrc.cjs`。
+- TypeScript 代码规范通过 `eslint` 承接，配置文件位于 `products/cli/.eslintrc.cjs`。
 - 本目录作者侧收口命令：`npm run lint`、`npm test`、`npm run build`。
 - 仓库级 gate 会通过 `./script/lint_node_products.sh` 在 `pre-commit` 与 `./script/check.sh` 中统一执行 Node 产品 lint。
 
@@ -44,18 +50,18 @@
 
 - `npm run build`：执行 TypeScript 编译。
 - `npm test`：运行 CLI 门面与 Smoke 测试。
-- `npm run package`：执行 `./script/package.sh`，构建 CLI 本体并同步 npm 发布所需的 app-server/runtime vendor 资产。
+- `npm run package`：执行 `./script/package.sh`，构建 CLI 本体并同步 npm 发布所需的 products/app-server/runtime vendor 资产。
 - 运行 `media assets prepare` 时，CLI 会优先复用系统 `ffmpeg/ffprobe`；若本机不存在，则首次使用时自动下载到用户缓存目录。
 
 ## Runtime E2E Tester Config
 
-- 本地测试配置文件路径：`devtools/cli/tests/.local/runtime-backed.e2e.local.json`（必需，已在 `.gitignore` 忽略）。
-- 示例模板：`devtools/cli/tests/runtime-backed.e2e.config.example.json`。
-- CLI server-only 正式 E2E 现在直接读取 `mp4Path`，由 `service start` 内部自动 prepare；不再要求先手工 prepare 再维护 `assetsDir`。
+- CLI server/client E2E 本地配置路径：`products/cli/config/.local/server.local.toml` + `products/cli/config/.local/client.local.toml`。
+- `products/cli/config/.local/` 默认整体忽略；本地 gate 直接读取这两份 TOML，不再依赖 `tests/.local/*.json`。
+- `server.local.toml` 负责 `service start` 和 `debug.connect_bootstrap` 真相；`client.local.toml` 负责 `client start` 与 `token issue` 所需的本地 truth。`license qrcode` 为纯命令行输入，不依赖 TOML。
 
 ## Command Loop E2E Harness
 
-- 长驻人工验收脚本：`devtools/cli/script/command_loop_e2e.sh`
-- 示例配置：`devtools/cli/config/command_loop_e2e.example.toml`
-- 本地配置路径：`devtools/cli/config/.local/command_loop_e2e.local.toml`（已在 `.gitignore` 忽略）
+- 长驻人工验收脚本：`products/cli/script/command_loop_e2e.sh`
+- 示例配置：`products/cli/config/command_loop_e2e.example.toml`
+- 本地配置路径：`products/cli/config/.local/command_loop_e2e.local.toml`（已在 `.gitignore` 忽略）
 - 该脚本会先打包最新 `runtime + app-server + cli`，再清场、`service start`、周期性发送 `stream message` / time command，并轮询 `command pending list` 后自动做 CLI 侧显式 reply；启动成功后保持常驻，等待人工去操作 Android example。

package/USAGE.md

@@ -1,6 +1,6 @@
 # TiRTC DevTools CLI（用户手册）
 
-`tirtc-devtools-cli` 是基于 `app-server/host` 的命令行门面，用来控制会话、服务、连接、流、命令通道与调试工具。
+`tirtc-devtools-cli` 是基于 `products/app-server/host` 的命令行门面，用来控制会话、服务、连接、流、命令通道与调试工具。
 
 ## 一、关系
 
@@ -11,16 +11,16 @@
 ## 二、开发态构建
 
 ```bash
-npm --prefix app-server ci
-npm --prefix devtools/cli ci
-npm --prefix app-server run build
-npm --prefix devtools/cli run build
+npm --prefix products/app-server ci
+npm --prefix products/cli ci
+npm --prefix products/app-server run build
+npm --prefix products/cli run build
 ```
 
 运行入口：
 
 ```bash
-node devtools/cli/bin/tirtc-devtools-cli.js --help
+node products/cli/bin/tirtc-devtools-cli.js --help
 ```
 
 ## 三、Help 菜单速览
@@ -28,7 +28,7 @@ node devtools/cli/bin/tirtc-devtools-cli.js --help
 安装或构建完成后，先用 help 菜单确认当前 binary 暴露的命令面：
 
 ```bash
-node devtools/cli/bin/tirtc-devtools-cli.js --help
+node products/cli/bin/tirtc-devtools-cli.js --help
 ```
 
 当前顶层 help 快照：
@@ -41,7 +41,7 @@ TiRTC DevTools CLI
 Options:
   --config <path>        配置文件路径（TOML）
   --json                 以机器可读 JSON 输出（便于脚本集成）
-  --session <sessionId>  指定会话 ID；除 service start/connect 外必须传
+  --session <sessionId>  指定会话 ID；除 service start / client start / connection connect 外必须传
   -h, --help             display help for command
 
 Commands:
@@ -49,8 +49,10 @@ Commands:
   init        新手第一步：生成 CLI 配置模板
   media       媒体素材辅助：prepare local assets
   service     服务端能力：启动/停止服务，等待远端接入
+  client      客户端正式入口：连接远端并自动挂载本地 web preview
   connection  客户端能力：主动连接远端 peer
   token       Token 工具：签发 token，并输出可直接使用的 JSON 与本地二维码 PNG
+  license     License 工具：生成 server 扫码 JSON 与本地二维码 PNG
   stream      流控制：发送/接收/消息
   output      输出挂载：文件等消费者 attach/detach
   command     命令通道：发送命令与事件跟踪
@@ -64,10 +66,11 @@ Commands:
 常用子菜单 help：
 
 ```bash
-node devtools/cli/bin/tirtc-devtools-cli.js service --help
-node devtools/cli/bin/tirtc-devtools-cli.js stream --help
-node devtools/cli/bin/tirtc-devtools-cli.js command --help
-node devtools/cli/bin/tirtc-devtools-cli.js token issue --help
+node products/cli/bin/tirtc-devtools-cli.js service --help
+node products/cli/bin/tirtc-devtools-cli.js stream --help
+node products/cli/bin/tirtc-devtools-cli.js command --help
+node products/cli/bin/tirtc-devtools-cli.js token issue --help
+node products/cli/bin/tirtc-devtools-cli.js license qrcode --help
 ```
 
 当前关键子菜单快照：
@@ -94,14 +97,21 @@ Commands:
   tail                                                             持续监听命令相关事件
 
 $ node ... token issue --help
+Usage: tirtc-devtools-cli token issue [options] <remote_id>
+
 Options:
   --access-id <accessId>
   --secret-key <secretKey>
-  --local-id <localId>
-  --openapi-entry <url>
-  --service-entry <entry>
-  --user-ttl-seconds <seconds>
-  --channel-ttl-seconds <seconds>
+  --openapi-endpoint <url>
+  --endpoint <entry>
+  --qr-error-correction-level <level>
+  --ascii-max-columns <columns>
+
+$ node ... license qrcode --help
+Usage: tirtc-devtools-cli license qrcode [options] <license>
+
+Options:
+  --endpoint <entry>
   --qr-error-correction-level <level>
   --ascii-max-columns <columns>
 ```
@@ -110,7 +120,7 @@ Options:
 
 - `--config <path>`：TOML 配置文件路径。
 - `--json`：结构化 JSON 输出。
-- `--session <sessionId>`：除 `service start` / `connection connect` 外，其余业务命令必须显式提供。
+- `--session <sessionId>`：除 `service start` / `client start` / `connection connect` 外，其余业务命令必须显式提供。
 
 ## 五、会话模型
 
@@ -120,13 +130,13 @@ Options:
 - `host session list`：查看会话。
 - `host session stop <sessionId>`：停止会话。
 - `service start`：默认创建 `service` 会话；可通过 `--session` 绑定已有空闲会话。
-- `connection connect`：总是创建新的 `client` 会话，不允许复用 `--session`。
+- `client start` / `connection connect`：总是创建新的 `client` 会话，不允许复用 `--session`。
 
 ## 六、server-only 正式入口
 
 ### 1. 配置真相
 
-server-only 正式路径只认 `[server] + [logging]`：
+server-only 正式路径只认 `[server]`：
 
 ```toml
 [server]
@@ -135,11 +145,6 @@ license = "runtime-license"
 mp4_path = "/Users/allenfeng/Development/Repositories/tirtc-nexus/tirtc-matrix/.refers/simple.mp4"
 video_stream_id = 11
 audio_stream_id = 10
-
-[logging]
-root_dir = "./.tmp/tirtc-devtools-cli/logging"
-console_mirror = true
-level = "info"
 ```
 
 说明：
@@ -147,11 +152,12 @@ level = "info"
 - `license`、`mp4_path`、`video_stream_id`、`audio_stream_id` 必填。
 - `service_entry` 可留空，回退到底层默认值。
 - 旧 `[service]`、`[stream.request_policy]`、`[streams.send]` 不再属于正式合同。
+- 正式命令默认开启 console mirror，并把日志固定落到 `~/.tirtc-devtools-cli/logging/`。
 
 ### 2. 启动命令
 
 ```bash
-node devtools/cli/bin/tirtc-devtools-cli.js --config ./server.toml --json service start
+node products/cli/bin/tirtc-devtools-cli.js --config ./server.toml --json service start
 ```
 
 `service start` 固定流程：
@@ -170,18 +176,49 @@ node devtools/cli/bin/tirtc-devtools-cli.js --config ./server.toml --json servic
 - CLI 不再暴露 request-policy 配置或命令。
 - 一旦远端请求对应 media，已绑定的发送流会自动转为 `active`。
 
-## 七、connection connect
+## 七、client start
+
+```bash
+node products/cli/bin/tirtc-devtools-cli.js --config ./client.toml --json client start --token <TOKEN>
+```
+
+client 正式路径只认 `[client]`：
+
+```toml
+[client]
+service_entry = ""
+peer_id = "peer-123"
+audio_stream_id = 10
+video_stream_id = 11
+consumer = "web_preview"
+```
+
+说明：
+
+- `peer_id`、`audio_stream_id`、`video_stream_id`、`consumer` 必填。
+- `consumer` 当前固定为 `web_preview`。
+- token 必须通过命令行 `--token` 显式提供，不进入配置文件。
+
+`client start` 固定流程：
+
+1. 读取并校验 `[client]`。
+2. 调用 `connection/connect`。
+3. 自动调用两次 `stream/receiveStart`：一次音频、一次视频。
+4. 自动调用两次 `output/attach`，consumer 固定为 `web_preview`。
+5. 返回 `autoApplied` 摘要，其中 `preview.url` 是正式浏览器入口。
+
+## 八、connection connect
 
 ```bash
-node devtools/cli/bin/tirtc-devtools-cli.js --config ./server.toml --json connection connect <serviceEntry> <peerId> [token]
+node products/cli/bin/tirtc-devtools-cli.js --config ./client.toml --json connection connect <serviceEntry> <peerId> <token>
 ```
 
 说明：
 
-- 若未显式传 `token`，CLI 会尝试使用 `[connection.auto_token]` 触发 App Server 自动签发。
-- 若命令行、省略 token、且配置也缺自动签发凭据，则命令失败。
+- 该命令保留为 expert/atomic 路径。
+- token 必须显式提供；CLI 不再提供 auto token 回退。
 
-## 八、stream / output / command
+## 九、stream / output / command
 
 ### Stream
 
@@ -214,35 +251,105 @@ CLI 仍会在本地收紧最小组合矩阵：
 
 `command request` 是 canonical 主语，`command send` 只保留为兼容别名。若要发 JSON，请把 JSON 文本作为 `payload` 传入。`command pending list` 用于恢复或轮询当前积压，`command reply` 基于 `remoteRequestId` 显式回复待处理请求。
 
-## 九、token / debug / report
+## 十、token / license / debug / report
+
+### token issue
+
+命令形态：
+
+```bash
+export TIRTC_CONN_ACCESS_ID="<ACCESS_ID>"
+export TIRTC_CONN_SECRET_KEY="<SECRET_KEY>"
+node products/cli/bin/tirtc-devtools-cli.js --json token issue <REMOTE_ID>
+```
+
+如果要覆盖默认 endpoint，并显式透传给底层签发路径：
+
+```bash
+node products/cli/bin/tirtc-devtools-cli.js --json token issue <REMOTE_ID> \
+  --endpoint <ENDPOINT> \
+  --openapi-endpoint <OPENAPI_ENDPOINT>
+```
+
+当前 CLI 合同：
+
+- 位置参数改为 `<remote_id>`。
+- `--endpoint` 取代旧 `--service-entry`。
+- `--openapi-endpoint` 取代旧 `--openapi-entry`。
+- 不再接收 `local_id`。
+- 显式传入的 `endpoint` / `openapi_endpoint` 会透传给 C 层签发路径，并同时进入二维码 payload。
+- 若未显式传入 `endpoint` / `openapi_endpoint`，则 payload 中不再补默认字段。
+
+`--json` 输出保持外层 envelope 不变：
+
+```json
+{
+  "code": 0,
+  "message": "OK",
+  "data": {
+    "payload": {
+      "remote_id": "TESTFENGJUN4",
+      "token": "<TOKEN>",
+      "endpoint": "http://ep-test-tirtc.tange365.com",
+      "openapi_endpoint": "http://api-test-tirtc.tange365.com"
+    },
+    "payloadJson": "{\"remote_id\":\"TESTFENGJUN4\",\"token\":\"<TOKEN>\",\"endpoint\":\"http://ep-test-tirtc.tange365.com\",\"openapi_endpoint\":\"http://api-test-tirtc.tange365.com\"}",
+    "token": "<TOKEN>",
+    "qrCodePngPath": "/absolute/path/to/token-*.png"
+  }
+}
+```
+
+说明：
+
+- payload 只保留 `remote_id`、`token`、可选 `endpoint`、可选 `openapi_endpoint`。
+- 已删除字段不再出现：`version`、`type`、`local_id`、`peer_id`、`openapi_entry`、`service_entry`、`user_ttl_seconds`、`channel_ttl_seconds`、`generated_at`。
+
+### license qrcode
+
+命令形态：
+
+```bash
+node products/cli/bin/tirtc-devtools-cli.js --json license qrcode <LICENSE>
+node products/cli/bin/tirtc-devtools-cli.js --json license qrcode <LICENSE> --endpoint <ENDPOINT>
+```
+
+当前 CLI 合同：
+
+- 只保留 `license` 和可选 `endpoint`。
+- `--endpoint` 取代旧 `--service-entry`。
+- 若未显式传入 `endpoint`，payload 中不再补默认字段。
+
+### 其他命令
 
-- `token issue <peerId>`：本地签发 token。
 - `debug bootstrap qrcode ...` / `debug bootstrap qrcode-from-config`：生成联调用二维码。
 - `events tail`：实时查看事件流。
 - `logs export <outputPath>`：导出日志。
 - `report show` / `report export <outputPath>`：查看或导出报告。
 
-## 十、本地 E2E 配置
+## 十一、本地 E2E 配置
 
-- CLI server/client E2E 本地配置文件：`devtools/cli/tests/.local/runtime-backed.e2e.local.json`
-- 推荐字段：`mp4Path`、`serviceEntry`、`license`、`peerId`、`accessId`、`secretKey`、可选 `e2eToken`
+- CLI server/client E2E 本地配置文件：`products/cli/config/.local/server.local.toml` + `products/cli/config/.local/client.local.toml`
+- `products/cli/config/.local/` 默认整体忽略，由本地联调环境自行维护
+- `server.local.toml` 字段：`[server]` + `[debug.connect_bootstrap]`
+- `client.local.toml` 字段：`[client]` + `[debug.token_issue]`
 - CLI server-only E2E 不再要求先手工 `media assets prepare` 再回填 `assetsDir`
 
-## 十一、Android 人工闭环脚本
+## 十二、Android 人工闭环脚本
 
 如果需要把 CLI 侧闭环常驻起来，再手工去操作 Android example，使用：
 
 ```bash
-./devtools/cli/script/command_loop_e2e.sh
+./products/cli/script/command_loop_e2e.sh
 ```
 
-默认读取：`devtools/cli/config/.local/command_loop_e2e.local.toml`
+默认读取：`products/cli/config/.local/command_loop_e2e.local.toml`
 
 建议先从模板复制：
 
 ```bash
-mkdir -p devtools/cli/config/.local
-cp devtools/cli/config/command_loop_e2e.example.toml devtools/cli/config/.local/command_loop_e2e.local.toml
+mkdir -p products/cli/config/.local
+cp products/cli/config/command_loop_e2e.example.toml products/cli/config/.local/command_loop_e2e.local.toml
 ```
 
 该脚本会：

package/bin/tirtc-devtools-cli.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-require('../dist/devtools/cli/src/index.js');
+require('../dist/cli/src/index.js');

package/dist/cli/src/bootstrap_flows.d.ts

@@ -0,0 +1,46 @@
+import { AppServerClient } from '../../app-server/protocol-client';
+import type { CliConfig } from './config';
+import { ProgressIndicator } from './progress';
+type ClientPreview = {
+    url: string;
+    token?: string;
+    endpoint?: string;
+};
+export type ServerBootstrapConfig = {
+    serviceEntry?: string;
+    license: string;
+    mp4Path: string;
+    audioStreamId: number;
+    videoStreamId: number;
+};
+export type ClientBootstrapConfig = {
+    serviceEntry?: string;
+    peerId: string;
+    audioStreamId: number;
+    videoStreamId: number;
+    consumer: 'web_preview';
+};
+export declare class BootstrapStepError extends Error {
+    readonly reasonCode: string;
+    readonly data: Record<string, unknown>;
+    constructor(reasonCode: string, message: string, data: Record<string, unknown>);
+}
+export declare function validateServerConfig(config: CliConfig): ServerBootstrapConfig;
+export declare function validateClientConfig(config: CliConfig): ClientBootstrapConfig;
+export declare function applyConfiguredServerBootstrap(client: AppServerClient, config: CliConfig, progress?: ProgressIndicator): Promise<{
+    preparedAssetsDir: string;
+    mediaSendPolicy: 'AUTO_ON_CONNECTED';
+    bootstrapSendStreams: Array<Record<string, unknown>>;
+}>;
+export declare function applyClientStartBootstrap(client: AppServerClient, config: CliConfig, token: string, progress?: ProgressIndicator): Promise<{
+    connection: unknown;
+    autoApplied: {
+        consumer: 'web_preview';
+        audioStream: unknown;
+        videoStream: unknown;
+        audioOutput: unknown;
+        videoOutput: unknown;
+        preview: ClientPreview;
+    };
+}>;
+export {};