tirtc-devtools-cli 0.0.9 → 0.0.11

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 二维码生成能力，支持可选 `service_entry`。
 
 ## 不负责什么
 
@@ -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,10 @@ 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
 ```
 
 当前关键子菜单快照：
@@ -104,13 +106,19 @@ Options:
   --channel-ttl-seconds <seconds>
   --qr-error-correction-level <level>
   --ascii-max-columns <columns>
+
+$ node ... license qrcode --help
+Options:
+  --service-entry <entry>
+  --qr-error-correction-level <level>
+  --ascii-max-columns <columns>
 ```
 
 ## 四、全局参数
 
 - `--config <path>`：TOML 配置文件路径。
 - `--json`：结构化 JSON 输出。
-- `--session <sessionId>`：除 `service start` / `connection connect` 外，其余业务命令必须显式提供。
+- `--session <sessionId>`：除 `service start` / `client start` / `connection connect` 外，其余业务命令必须显式提供。
 
 ## 五、会话模型
 
@@ -120,13 +128,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]
@@ -136,10 +144,6 @@ mp4_path = "/Users/allenfeng/Development/Repositories/tirtc-nexus/tirtc-matrix/.
 video_stream_id = 11
 audio_stream_id = 10
 
-[logging]
-root_dir = "./.tmp/tirtc-devtools-cli/logging"
-console_mirror = true
-level = "info"
 ```
 
 说明：
@@ -147,11 +151,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 +175,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,18 +250,21 @@ CLI 仍会在本地收紧最小组合矩阵：
 
 `command request` 是 canonical 主语，`command send` 只保留为兼容别名。若要发 JSON，请把 JSON 文本作为 `payload` 传入。`command pending list` 用于恢复或轮询当前积压，`command reply` 基于 `remoteRequestId` 显式回复待处理请求。
 
-## 九、token / debug / report
+## 十、token / debug / report
 
 - `token issue <peerId>`：本地签发 token。
+- `license qrcode <license>`：本地生成 server 扫码二维码。
 - `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 人工闭环脚本
@@ -233,16 +272,16 @@ CLI 仍会在本地收紧最小组合矩阵：
 如果需要把 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 {};

package/dist/cli/src/bootstrap_flows.js

@@ -0,0 +1,249 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BootstrapStepError = void 0;
+exports.validateServerConfig = validateServerConfig;
+exports.validateClientConfig = validateClientConfig;
+exports.applyConfiguredServerBootstrap = applyConfiguredServerBootstrap;
+exports.applyClientStartBootstrap = applyClientStartBootstrap;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const default_paths_1 = require("./default_paths");
+const media_assets_1 = require("./media_assets");
+class BootstrapStepError extends Error {
+    reasonCode;
+    data;
+    constructor(reasonCode, message, data) {
+        super(message);
+        this.name = 'BootstrapStepError';
+        this.reasonCode = reasonCode;
+        this.data = data;
+    }
+}
+exports.BootstrapStepError = BootstrapStepError;
+function resolveProtocolError(error) {
+    if (typeof error === 'object' && error !== null) {
+        const typed = error;
+        if (typed.data?.reasonCode && typed.data.reasonCode.trim().length > 0) {
+            return {
+                reasonCode: typed.data.reasonCode,
+                message: typed.data.message ?? typed.message ?? 'Request failed',
+            };
+        }
+        if (typed.message && typed.message.trim().length > 0) {
+            return {
+                reasonCode: 'internal_error',
+                message: typed.message,
+            };
+        }
+    }
+    if (error instanceof Error) {
+        return {
+            reasonCode: 'internal_error',
+            message: error.message,
+        };
+    }
+    return {
+        reasonCode: 'internal_error',
+        message: 'Request failed',
+    };
+}
+function ensureNonNegativeInteger(value, field) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new Error(field + ' must be a non-negative integer');
+    }
+    return value;
+}
+function ensureNonEmptyString(value, field) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(field + ' must be a non-empty string');
+    }
+    return value.trim();
+}
+function extractPreview(result, step) {
+    if (typeof result !== 'object' || result === null) {
+        throw new Error(step + ' did not return an object result');
+    }
+    const previewRaw = result.preview;
+    if (typeof previewRaw !== 'object' || previewRaw === null) {
+        throw new Error(step + ' did not return preview metadata');
+    }
+    const preview = previewRaw;
+    const url = ensureNonEmptyString(preview.url, step + ' preview.url');
+    return {
+        url,
+        token: typeof preview.token === 'string' && preview.token.trim().length > 0 ? preview.token.trim() : undefined,
+        endpoint: typeof preview.endpoint === 'string' && preview.endpoint.trim().length > 0 ? preview.endpoint.trim() : undefined,
+    };
+}
+async function runBootstrapStep(client, method, params, step, completed) {
+    try {
+        return await client.sendRequest(method, params);
+    }
+    catch (error) {
+        const resolved = resolveProtocolError(error);
+        throw new BootstrapStepError(resolved.reasonCode, resolved.message, {
+            failedStep: step,
+            completedSteps: completed,
+        });
+    }
+}
+function validateServerConfig(config) {
+    const server = config.server;
+    const license = server?.license?.trim() ?? '';
+    const mp4Path = server?.mp4_path?.trim() ?? '';
+    const audioStreamId = ensureNonNegativeInteger(server?.audio_stream_id, '[server].audio_stream_id');
+    const videoStreamId = ensureNonNegativeInteger(server?.video_stream_id, '[server].video_stream_id');
+    if (license.length === 0) {
+        throw new Error('server-only config requires [server].license');
+    }
+    if (mp4Path.length === 0) {
+        throw new Error('server-only config requires [server].mp4_path');
+    }
+    if (audioStreamId === videoStreamId) {
+        throw new Error('server-only config requires distinct audio_stream_id and video_stream_id');
+    }
+    const resolvedMp4Path = path_1.default.resolve(mp4Path);
+    let stats;
+    try {
+        stats = fs_1.default.statSync(resolvedMp4Path);
+    }
+    catch {
+        throw new Error('server-only config mp4_path does not exist: ' + resolvedMp4Path);
+    }
+    if (!stats.isFile()) {
+        throw new Error('server-only config mp4_path must be a readable file: ' + resolvedMp4Path);
+    }
+    const serviceEntry = server?.service_entry?.trim();
+    return {
+        serviceEntry: serviceEntry && serviceEntry.length > 0 ? serviceEntry : undefined,
+        license,
+        mp4Path: resolvedMp4Path,
+        audioStreamId,
+        videoStreamId,
+    };
+}
+function validateClientConfig(config) {
+    const client = config.client;
+    if (!client) {
+        throw new Error('client start requires [client] config');
+    }
+    const peerId = ensureNonEmptyString(client.peer_id, '[client].peer_id');
+    const audioStreamId = ensureNonNegativeInteger(client.audio_stream_id, '[client].audio_stream_id');
+    const videoStreamId = ensureNonNegativeInteger(client.video_stream_id, '[client].video_stream_id');
+    if (audioStreamId === videoStreamId) {
+        throw new Error('client config requires distinct audio_stream_id and video_stream_id');
+    }
+    if (client.consumer !== 'web_preview') {
+        throw new Error('client config requires [client].consumer = "web_preview"');
+    }
+    const serviceEntry = client.service_entry?.trim();
+    return {
+        serviceEntry: serviceEntry && serviceEntry.length > 0 ? serviceEntry : undefined,
+        peerId,
+        audioStreamId,
+        videoStreamId,
+        consumer: 'web_preview',
+    };
+}
+async function applyConfiguredServerBootstrap(client, config, progress) {
+    const server = validateServerConfig(config);
+    progress?.start('Preparing MP4 assets');
+    const prepared = await (0, media_assets_1.prepareMediaAssets)({
+        source: server.mp4Path,
+        outputRoot: (0, default_paths_1.resolveCliPreparedAssetsRoot)(),
+    });
+    progress?.update('Prepared MP4 assets');
+    const bootstrapSendStreams = [
+        { streamId: server.audioStreamId, media: 'audio' },
+        { streamId: server.videoStreamId, media: 'video' },
+    ].map(({ streamId, media }) => ({
+        streamId,
+        media,
+        source: {
+            mode: 'local_assets',
+            local_assets: {
+                assets_dir: prepared.assets_dir,
+            },
+        },
+    }));
+    return {
+        preparedAssetsDir: prepared.assets_dir,
+        mediaSendPolicy: 'AUTO_ON_CONNECTED',
+        bootstrapSendStreams,
+    };
+}
+async function applyClientStartBootstrap(client, config, token, progress) {
+    const normalizedToken = ensureNonEmptyString(token, '--token');
+    const clientConfig = validateClientConfig(config);
+    const audioArtifactPath = path_1.default.join(os_1.default.tmpdir(), `tirtc-client-preview-audio-${Date.now()}-${process.pid}.pcm`);
+    const videoArtifactPath = path_1.default.join(os_1.default.tmpdir(), `tirtc-client-preview-video-${Date.now()}-${process.pid}.jpeg`);
+    const completed = {
+        consumer: clientConfig.consumer,
+    };
+    progress?.start('Connecting client session');
+    const connection = await runBootstrapStep(client, 'connection/connect', {
+        serviceEntry: clientConfig.serviceEntry,
+        peerId: clientConfig.peerId,
+        token: normalizedToken,
+        timeoutMs: 5000,
+    }, 'connect', completed);
+    completed.connection = connection;
+    progress?.update('Connected client session');
+    const audioStream = await runBootstrapStep(client, 'stream/receiveStart', {
+        streamId: clientConfig.audioStreamId,
+        media: 'audio',
+    }, 'receive audio', completed);
+    completed.audioStream = audioStream;
+    progress?.update('Attached audio receive stream');
+    const videoStream = await runBootstrapStep(client, 'stream/receiveStart', {
+        streamId: clientConfig.videoStreamId,
+        media: 'video',
+    }, 'receive video', completed);
+    completed.videoStream = videoStream;
+    progress?.update('Attached video receive stream');
+    const audioOutput = await runBootstrapStep(client, 'output/attach', {
+        streamId: clientConfig.audioStreamId,
+        consumer: clientConfig.consumer,
+        mediaView: 'encoded_packet',
+        format: 'pcm',
+        delivery: 'artifact_path',
+        targetPath: audioArtifactPath,
+    }, 'attach audio preview', completed);
+    completed.audioOutput = audioOutput;
+    progress?.update('Attached audio preview output');
+    const videoOutput = await runBootstrapStep(client, 'output/attach', {
+        streamId: clientConfig.videoStreamId,
+        consumer: clientConfig.consumer,
+        mediaView: 'encoded_packet',
+        format: 'jpeg',
+        delivery: 'artifact_path',
+        targetPath: videoArtifactPath,
+    }, 'attach video preview', completed);
+    completed.videoOutput = videoOutput;
+    progress?.succeed('Client preview session is ready');
+    const audioPreview = extractPreview(audioOutput, 'attach audio preview');
+    const videoPreview = extractPreview(videoOutput, 'attach video preview');
+    if (audioPreview.url !== videoPreview.url) {
+        throw new BootstrapStepError('internal_error', 'web_preview outputs returned different preview URLs', {
+            failedStep: 'preview aggregation',
+            completedSteps: completed,
+            audioPreview,
+            videoPreview,
+        });
+    }
+    return {
+        connection,
+        autoApplied: {
+            consumer: clientConfig.consumer,
+            audioStream,
+            videoStream,
+            audioOutput,
+            videoOutput,
+            preview: audioPreview,
+        },
+    };
+}

package/dist/{devtools/cli → cli}/src/config.d.ts

@@ -6,23 +6,12 @@ export type CliConfig = {
         video_stream_id?: number;
         audio_stream_id?: number;
     };
-    connection?: {
+    client?: {
         service_entry?: string;
         peer_id?: string;
-        token?: string;
-        auto_token?: {
-            openapi_entry?: string;
-            access_id?: string;
-            secret_key?: string;
-            local_id?: string;
-            user_ttl_seconds?: number;
-            channel_ttl_seconds?: number;
-        };
-    };
-    logging?: {
-        root_dir?: string;
-        console_mirror?: boolean;
-        level?: 'verbose' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+        audio_stream_id?: number;
+        video_stream_id?: number;
+        consumer?: 'web_preview';
     };
     debug?: {
         connect_bootstrap?: {