tirtc-devtools-cli 0.0.13 → 0.0.15

package/dist/cli/src/index.js

@@ -1,23 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
-const protocol_client_1 = require("../../app-server/protocol-client");
-const bootstrap_flows_1 = require("./bootstrap_flows");
-const config_1 = require("./config");
-const facade_1 = require("./facade");
-const guide_1 = require("./guide");
-const session_manager_1 = require("./session_manager");
 const media_assets_1 = require("./media_assets");
 const token_command_1 = require("./token_command");
-const transport_1 = require("./transport");
-const progress_1 = require("./progress");
-const CLI_VERSION = '0.0.13';
-const HOST_VERSION = '1.0.0';
-const PROTOCOL_VERSION = '1.0.0';
+const role_driver_1 = require("./role_driver");
+const cliVersion = '0.0.14';
 if (process.argv.includes('--version') || process.argv.includes('-V')) {
-    console.log('CLI Version: ' + CLI_VERSION);
-    console.log('Host Version: ' + HOST_VERSION);
-    console.log('Protocol Version: ' + PROTOCOL_VERSION);
+    console.log('CLI Version: ' + cliVersion);
+    console.log('DevTools Driver Contract: 1');
     process.exit(0);
 }
 const program = new commander_1.Command();
@@ -48,201 +38,26 @@ function normalizeError(error) {
         data: undefined,
     };
 }
-function createSessionTransport(sessionId) {
-    const session = (0, session_manager_1.resolveSession)(sessionId);
-    return new transport_1.SocketTransport(session.socketPath);
-}
-function isBootstrapCommand(cmdName) {
-    return cmdName === 'service start' || cmdName === 'connection connect' || cmdName === 'client start';
-}
-function resolveSessionForCommand(cmdName, options) {
-    if (cmdName === 'connection connect' || cmdName === 'client start') {
-        if (options.session && options.session.trim().length > 0) {
-            throw new Error(cmdName + ' always creates a new session; do not pass --session');
-        }
-        const created = (0, session_manager_1.createSession)({ role: 'client' });
-        return { sessionId: created.sessionId, created: true };
-    }
-    if (cmdName === 'service start') {
-        if (options.session && options.session.trim().length > 0) {
-            const existing = (0, session_manager_1.resolveSession)(options.session);
-            (0, session_manager_1.setSessionRole)(existing.sessionId, 'service');
-            return { sessionId: existing.sessionId, created: false };
-        }
-        const created = (0, session_manager_1.createSession)({ role: 'service' });
-        return { sessionId: created.sessionId, created: true };
-    }
-    if (cmdName === 'debug bootstrap qrcode') {
-        const existing = (0, session_manager_1.resolveSession)(options.session);
-        return { sessionId: existing.sessionId, created: false };
-    }
-    if (options.session && options.session.trim().length > 0) {
-        const existing = (0, session_manager_1.resolveSession)(options.session);
-        return { sessionId: existing.sessionId, created: false };
-    }
-    throw new Error(cmdName + ' requires --session <sessionId>');
-}
-function printSuccess(options, result, session, cmdName) {
-    const attachSession = isBootstrapCommand(cmdName);
-    if (options.json) {
-        const data = attachSession ? { session: { sessionId: session.sessionId, created: session.created }, result } : result;
-        console.log(JSON.stringify({ code: 0, message: 'OK', data }));
-        return;
-    }
-    if (attachSession) {
-        const lifecycle = session.created ? 'created' : 'selected';
-        console.log('Session ' + lifecycle + ': ' + session.sessionId);
-    }
-    console.log('Success:', JSON.stringify(result, null, 2));
-}
-function toResultObject(result) {
-    if (typeof result === 'object' && result !== null && !Array.isArray(result)) {
-        return { ...result };
-    }
-    return { result };
-}
-function requireConfigPath(configPath) {
-    if (!configPath || configPath.trim().length === 0) {
-        throw new Error('command requires --config <path>');
-    }
-    return configPath;
-}
-function createProgressIndicator(options) {
+function printError(error, options) {
+    const normalized = normalizeError(error);
     if (options.json) {
-        return undefined;
-    }
-    return new progress_1.ProgressIndicator();
-}
-async function runCommand(cmdName, params, options) {
-    let transport;
-    try {
-        const config = (0, config_1.loadConfig)(options.config);
-        const session = resolveSessionForCommand(cmdName, options);
-        transport = createSessionTransport(session.sessionId);
-        const client = new protocol_client_1.AppServerClient(transport);
-        await client.initialize({ name: 'tirtc-devtools-cli', version: CLI_VERSION });
-        const method = facade_1.CommandToHostMethodMapping[cmdName];
-        if (!method) {
-            throw new Error('Unknown command mapping for: ' + cmdName);
-        }
-        let resultForPrint;
-        if (cmdName === 'service start') {
-            const progress = createProgressIndicator(options);
-            try {
-                const autoApplied = await (0, bootstrap_flows_1.applyConfiguredServerBootstrap)(client, config, progress);
-                progress?.update('Starting service session');
-                const requestParams = {
-                    ...params,
-                    bootstrapSendStreams: autoApplied.bootstrapSendStreams,
-                };
-                const result = await client.sendRequest(method, requestParams, 180_000);
-                progress?.succeed('Service session is ready');
-                const resultObject = toResultObject(result);
-                resultForPrint = {
-                    ...resultObject,
-                    autoApplied,
-                };
-                printSuccess(options, resultForPrint, session, cmdName);
-                transport.stop();
-                return 0;
-            }
-            catch (error) {
-                progress?.fail('Service start failed');
-                throw error;
-            }
-        }
-        if (cmdName === 'client start') {
-            const progress = createProgressIndicator(options);
-            try {
-                const token = String(params.token ?? '');
-                const result = await (0, bootstrap_flows_1.applyClientStartBootstrap)(client, config, token, progress);
-                printSuccess(options, result, session, cmdName);
-                transport.stop();
-                return 0;
-            }
-            catch (error) {
-                progress?.fail('Client start failed');
-                throw error;
-            }
-        }
-        const result = await client.sendRequest(method, params);
-        resultForPrint = result;
-        printSuccess(options, resultForPrint, session, cmdName);
-        transport.stop();
-        return 0;
-    }
-    catch (error) {
-        const normalized = normalizeError(error);
-        const reasonCode = normalized.reasonCode;
-        const exitCode = facade_1.ErrorReasonCodeMapping[reasonCode] ?? 1;
-        if (options.json) {
-            console.log(JSON.stringify({
-                code: exitCode,
-                message: normalized.message,
-                data: normalized.data,
-            }));
-        }
-        else {
-            console.error('Error (' + reasonCode + '): ' + normalized.message);
-        }
-        transport?.stop();
-        return exitCode;
-    }
-}
-async function tailEvents(_cmdName, families, options) {
-    let transport;
-    try {
-        if (!options.session || options.session.trim().length === 0) {
-            throw new Error('events tail requires --session <sessionId>');
-        }
-        const session = (0, session_manager_1.resolveSession)(options.session);
-        transport = new transport_1.SocketTransport(session.socketPath);
-        const client = new protocol_client_1.AppServerClient(transport);
-        client.on('event', (event) => {
-            console.log(JSON.stringify(event));
-        });
-        client.on('error', (error) => {
-            if (!options.json) {
-                console.error('Client error:', error);
-            }
-            transport?.stop();
-        });
-        await client.initialize({ name: 'tirtc-devtools-cli', version: CLI_VERSION });
-        await client.subscribeEvents(families);
-        await new Promise((resolve) => {
-            process.on('SIGINT', () => {
-                transport?.stop();
-                resolve();
-            });
-            transport?.onClose(() => resolve());
-        });
-        return 0;
+        console.log(JSON.stringify({
+            code: 1,
+            message: normalized.message,
+            data: normalized.data ?? { reason_code: normalized.reasonCode },
+        }));
     }
-    catch (error) {
-        const normalized = normalizeError(error);
-        const reasonCode = normalized.reasonCode;
-        const exitCode = facade_1.ErrorReasonCodeMapping[reasonCode] ?? 1;
-        if (options.json) {
-            console.log(JSON.stringify({
-                code: exitCode,
-                message: normalized.message,
-                data: normalized.data,
-            }));
-        }
-        else {
-            console.error('Error (' + reasonCode + '): ' + normalized.message);
-        }
-        transport?.stop();
-        return exitCode;
+    else {
+        console.error('Error (' + normalized.reasonCode + '): ' + normalized.message);
     }
+    return 1;
 }
-async function runMediaAssetsPrepare(source, outputRoot, outputDir, overwrite, options) {
+async function runAssetsPrepare(commandOptions, options) {
     try {
         const result = await (0, media_assets_1.prepareMediaAssets)({
-            source,
-            outputRoot,
-            outputDir,
-            overwrite,
+            source: commandOptions.source ?? 'runtime/assets/source.mp4',
+            outputRoot: commandOptions.outputRoot ?? 'runtime/assets/.workspace',
+            overwrite: false,
         });
         if (options.json) {
             console.log(JSON.stringify({ code: 0, message: 'OK', data: result }));
@@ -253,394 +68,77 @@ async function runMediaAssetsPrepare(source, outputRoot, outputDir, overwrite, o
         return 0;
     }
     catch (error) {
-        const normalized = normalizeError(error);
-        const reasonCode = normalized.reasonCode;
-        const exitCode = facade_1.ErrorReasonCodeMapping[reasonCode] ?? 1;
-        if (options.json) {
-            console.log(JSON.stringify({
-                code: exitCode,
-                message: normalized.message,
-                data: normalized.data,
-            }));
-        }
-        else {
-            console.error('Error (' + reasonCode + '): ' + normalized.message);
-        }
-        return exitCode;
+        return printError(error, options);
     }
 }
 function runAndExit(promise) {
-    promise.then((code) => {
-        process.exit(code);
-    });
+    promise.then((code) => process.exit(code));
 }
 program.name('tirtc-devtools-cli')
     .description('TiRTC DevTools CLI')
-    .option('--config <path>', '配置文件路径（TOML）')
-    .option('--json', '以机器可读 JSON 输出（便于脚本集成）')
-    .option('--session <sessionId>', '指定会话 ID；除 service start / client start / connection connect 外必须传');
-const host = program.command('host').description('Host 基础能力（状态、停止）');
-host.command('status').description('查看 Host/service/connection/artifact 当前状态').action(() => {
-    runAndExit(runCommand('host status', {}, getCliOptions()));
-});
-host.command('stop')
-    .description('停止 Host 进程（可用 --all 停止所有会话）')
-    .option('--all', '停止所有会话对应的 Host 进程')
-    .action(() => {
-    const options = getCliOptions();
-    const stopAll = process.argv.includes('--all');
-    if (!stopAll) {
-        runAndExit(runCommand('host stop', {}, options));
-        return;
-    }
-    try {
-        const stopped = (0, session_manager_1.stopAllSessions)();
-        if (options.json) {
-            console.log(JSON.stringify({ code: 0, message: 'OK', data: { count: stopped.length, sessions: stopped } }));
-            return;
-        }
-        console.log('Stopped sessions:', stopped.length);
-    }
-    catch (error) {
-        const normalized = normalizeError(error);
-        const code = facade_1.ErrorReasonCodeMapping[normalized.reasonCode] ?? 1;
-        if (options.json) {
-            console.log(JSON.stringify({ code, message: normalized.message, data: normalized.data }));
-            return;
-        }
-        console.error('Error:', normalized.message);
-    }
-});
-const hostSession = host.command('session').description('会话管理：start/list/stop（推荐先 start）');
-hostSession.command('start').description('创建并启动一个常驻会话，返回 sessionId').action(() => {
-    try {
-        const options = getCliOptions();
-        const created = (0, session_manager_1.createSession)({
-            role: 'idle',
-        });
-        if (options.json) {
-            console.log(JSON.stringify({ code: 0, message: 'OK', data: created }));
-            return;
-        }
-        console.log('Session started:', created.sessionId);
-    }
-    catch (error) {
-        const normalized = normalizeError(error);
-        const options = getCliOptions();
-        const code = facade_1.ErrorReasonCodeMapping[normalized.reasonCode] ?? 1;
-        if (options.json) {
-            console.log(JSON.stringify({ code, message: normalized.message }));
-            return;
-        }
-        console.error('Error:', normalized.message);
-    }
-});
-hostSession.command('list').description('列出当前所有会话及其状态').action(() => {
-    try {
-        const sessions = (0, session_manager_1.listSessions)();
-        const options = getCliOptions();
-        if (options.json) {
-            console.log(JSON.stringify({ code: 0, message: 'OK', data: sessions }));
-            return;
-        }
-        console.log(JSON.stringify(sessions, null, 2));
-    }
-    catch (error) {
-        const normalized = normalizeError(error);
-        const options = getCliOptions();
-        const code = facade_1.ErrorReasonCodeMapping[normalized.reasonCode] ?? 1;
-        if (options.json) {
-            console.log(JSON.stringify({ code, message: normalized.message }));
-            return;
-        }
-        console.error('Error:', normalized.message);
-    }
-});
-hostSession.command('stop <sessionId>')
-    .description('停止并回收指定会话')
-    .action((sessionId) => {
-    try {
-        const stopped = (0, session_manager_1.stopSession)(sessionId);
-        const options = getCliOptions();
-        if (options.json) {
-            console.log(JSON.stringify({ code: 0, message: 'OK', data: stopped }));
-            return;
-        }
-        console.log('Session stopped:', stopped.sessionId);
-    }
-    catch (error) {
-        const normalized = normalizeError(error);
-        const options = getCliOptions();
-        const code = facade_1.ErrorReasonCodeMapping[normalized.reasonCode] ?? 1;
-        if (options.json) {
-            console.log(JSON.stringify({ code, message: normalized.message }));
-            return;
-        }
-        console.error('Error:', normalized.message);
-    }
-});
-function handleConfigInit(outputPath) {
-    try {
-        const written = (0, config_1.writeConfigTemplate)(outputPath);
-        const options = getCliOptions();
-        if (options.json) {
-            console.log(JSON.stringify({ code: 0, message: 'OK', data: { path: written } }));
-            return;
-        }
-        console.log('Config template created:', written);
-    }
-    catch (error) {
-        const normalized = normalizeError(error);
-        const options = getCliOptions();
-        const code = facade_1.ErrorReasonCodeMapping[normalized.reasonCode] ?? 1;
-        if (options.json) {
-            console.log(JSON.stringify({ code, message: normalized.message }));
-            return;
-        }
-        console.error('Error:', normalized.message);
-    }
-}
-const init = program.command('init [outputPath]').description('新手第一步：生成 CLI 配置模板（默认输出到 ./.tmp/tirtc-devtools-cli/config.toml）');
-init.action((outputPath) => {
-    handleConfigInit(outputPath);
-});
-const media = program.command('media').description('媒体素材辅助：prepare local assets');
-const mediaAssets = media.command('assets').description('prepared local assets contract');
-mediaAssets.command('prepare')
-    .description('把 MP4 prepare 为 local_assets 目录')
-    .requiredOption('--source <path>', '输入 MP4 路径')
-    .requiredOption('--output-root <dir>', 'prepared assets 输出根目录')
-    .option('--output-dir <dir>', 'prepared assets 精确输出目录（可选）')
-    .option('--overwrite', '忽略现有 cache 并重建')
+    .option('--json', '以机器可读 JSON 输出（便于脚本集成）');
+(0, token_command_1.registerTokenCommands)(program, getCliOptions, runAndExit);
+const assets = program.command('assets').description('准备 DevTools driver 使用的媒体资产');
+assets.command('prepare')
+    .description('准备默认 runtime assets 或把显式 source 写入 output root')
+    .option('--source <path>', '输入 MP4 路径；send start 使用输出的 manifest_path')
+    .option('--output-root <dir>', 'prepared assets 输出根目录')
+    .addHelpText('after', `
+Examples:
+  $ tirtc-devtools-cli --json assets prepare --source ./movie.mp4 --output-root .build/tirtc-assets
+  $ tirtc-devtools-cli --json send start --source .build/tirtc-assets/manifest.json --video-codec h264
+`)
     .action((commandOptions) => {
-    runAndExit(runMediaAssetsPrepare(commandOptions.source, commandOptions.outputRoot, commandOptions.outputDir, commandOptions.overwrite === true, getCliOptions()));
-});
-const hostConfig = host.command('config').description('配置辅助（兼容别名，推荐用顶层 config）');
-hostConfig.command('init [outputPath]').description('生成配置模板（等价于 config init）').action((outputPath) => {
-    handleConfigInit(outputPath);
-});
-const service = program.command('service').description('服务端能力：启动/停止服务，等待远端接入');
-service.command('start')
-    .description('启动 server-only 会话（必须显式提供 --config）')
-    .action(() => {
-    const options = getCliOptions();
-    const config = (0, config_1.loadConfig)(requireConfigPath(options.config));
-    const server = (0, bootstrap_flows_1.validateServerConfig)(config);
-    runAndExit(runCommand('service start', { serviceEntry: server.serviceEntry, license: server.license, timeoutMs: 5000 }, options));
-});
-service.command('stop').description('停止服务端监听').action(() => {
-    runAndExit(runCommand('service stop', {}, getCliOptions()));
-});
-const client = program.command('client').description('客户端正式入口：连接远端并自动挂载本地 web preview');
-client.command('start')
-    .description('读取 [client] 配置，连接远端并输出 web preview 地址')
-    .requiredOption('--token <token>', '显式 client token；不支持 auto token')
+    runAndExit(runAssetsPrepare(commandOptions, getCliOptions()));
+});
+const send = program.command('send').description('作为标准上行端运行 native DevTools driver');
+send.command('start')
+    .description('启动 send role，产出 bootstrap.json 与 summary.json')
+    .option('--execution-id <id>', 'runtime validation execution id')
+    .option('--case-id <id>', 'runtime validation case id')
+    .option('--app-id <id>', 'runtime validation app id')
+    .option('--artifact-root <dir>', 'artifact 输出目录')
+    .option('--remote-id <id>', 'server remote id；默认读取 TIRTC_DEVICE_ID')
+    .option('--source <path>', 'prepared asset root、manifest_path 或 encoded track；MP4 先运行 assets prepare')
+    .option('--video-codec <codec>', 'h264|h265|mjpeg', 'h264')
+    .option('--duration-ms <ms>', 'role active 时长')
+    .option('--connect-timeout-ms <ms>', 'service ready / connect 最大等待')
+    .option('--first-packet-timeout-ms <ms>', '首包最大等待')
+    .option('--bootstrap-token-json <path>', 'script/issue_devtools_token.sh --json 输出文件')
+    .addHelpText('after', `
+Examples:
+  $ tirtc-devtools-cli --json assets prepare --source ./movie.mp4 --output-root .build/tirtc-assets
+  $ tirtc-devtools-cli --json send start --source .build/tirtc-assets/manifest.json --artifact-root .build/tirtc-send
+
+bootstrap.json is a local handoff artifact for receive/sample/validation automation.
+It is not a mobile SDK connection protocol.
+`)
     .action((commandOptions) => {
-    const options = getCliOptions();
-    (0, config_1.loadConfig)(requireConfigPath(options.config));
-    runAndExit(runCommand('client start', { token: commandOptions.token }, options));
-});
-const connection = program.command('connection').description('客户端能力：主动连接远端 peer');
-connection.command('show').description('查看连接状态').action(() => {
-    runAndExit(runCommand('connection show', {}, getCliOptions()));
-});
-connection.command('connect [service_entry] <peer_id> <token>')
-    .description('作为客户端连接远端（总是新建 session；要求显式 token）')
-    .action((serviceEntry, peerId, token) => {
-    const config = (0, config_1.loadConfig)(getCliOptions().config);
-    const finalServiceEntry = [serviceEntry, config.client?.service_entry, config.server?.service_entry]
-        .find((value) => typeof value === 'string' && value.trim().length > 0);
-    const manualToken = token.trim();
-    if (manualToken.length === 0) {
-        throw new Error('connection connect requires non-empty token');
-    }
-    const params = {
-        serviceEntry: finalServiceEntry,
-        peerId,
-        token: manualToken,
-        timeoutMs: 5000,
-    };
-    runAndExit(runCommand('connection connect', params, getCliOptions()));
-});
-connection.command('disconnect').description('断开当前连接').action(() => {
-    runAndExit(runCommand('connection disconnect', {}, getCliOptions()));
-});
-(0, token_command_1.registerTokenCommands)(program, getCliOptions, runAndExit);
-const stream = program.command('stream').description('流控制：发送/接收/消息');
-stream.command('list').description('查看流快照列表').action(() => {
-    runAndExit(runCommand('stream list', {}, getCliOptions()));
-});
-const streamSend = stream.command('send').description('发送流：绑定 prepared local assets 并发起上行');
-streamSend.command('start <streamId> <media> <assets_dir>')
-    .description('开始发送流（绑定 source.local_assets 并触发上行）')
-    .action((streamId, media, assetsDir) => {
-    runAndExit(runCommand('stream send start', {
-        streamId: Number.parseInt(streamId, 10),
-        media,
-        source: {
-            mode: 'local_assets',
-            local_assets: {
-                assets_dir: assetsDir,
-            },
-        },
-    }, getCliOptions()));
-});
-streamSend.command('stop <streamId>').description('停止发送指定流').action((streamId) => {
-    runAndExit(runCommand('stream send stop', { streamId: Number.parseInt(streamId, 10) }, getCliOptions()));
-});
-const streamReceive = stream.command('receive').description('接收流：声明并接收下行');
-streamReceive.command('start <streamId> <media>')
-    .description('开始接收指定流')
-    .action((streamId, media) => {
-    runAndExit(runCommand('stream receive start', {
-        streamId: Number.parseInt(streamId, 10),
-        media,
-    }, getCliOptions()));
-});
-streamReceive.command('stop <streamId>')
-    .description('停止接收指定流')
-    .action((streamId) => {
-    runAndExit(runCommand('stream receive stop', { streamId: Number.parseInt(streamId, 10) }, getCliOptions()));
-});
-const streamMessage = stream.command('message').description('发送 stream message');
-streamMessage.command('send <streamId> <payload>')
-    .description('发送 UTF-8 字符串型 stream message')
-    .action((streamId, payload) => {
-    runAndExit(runCommand('stream message send', { streamId: Number.parseInt(streamId, 10), payload }, getCliOptions()));
-});
-const output = program.command('output').description('输出挂载：文件等消费者 attach/detach');
-output.command('attach <streamId> <consumer> <mediaView> <format> <delivery> [targetPath] [maxFiles]')
-    .description('挂载输出消费者（如 file_sink）')
-    .action((streamId, consumer, mediaView, format, delivery, targetPath, maxFiles) => {
-    const parsed = facade_1.OutputAttachCliParamsSchema.safeParse({
-        streamId: Number.parseInt(streamId, 10),
-        consumer,
-        mediaView,
-        format,
-        delivery,
-        targetPath,
-        maxFiles: maxFiles ? Number.parseInt(maxFiles, 10) : undefined,
-    });
-    if (!parsed.success) {
-        const msg = parsed.error.issues.map((issue) => issue.message).join('; ');
-        throw new Error('invalid output attach params: ' + msg);
-    }
-    runAndExit(runCommand('output attach', {
-        streamId: Number.parseInt(streamId, 10),
-        consumer,
-        mediaView,
-        format,
-        delivery,
-        targetPath,
-        maxFiles: maxFiles ? Number.parseInt(maxFiles, 10) : undefined,
-    }, getCliOptions()));
-});
-output.command('detach <outputId>').description('卸载输出消费者').action((outputId) => {
-    runAndExit(runCommand('output detach', { outputId }, getCliOptions()));
-});
-const command = program.command('command').description('命令通道：发送命令与事件跟踪');
-command.command('request <commandId> <payloadEncoding> <payload>')
-    .description('发送命令请求并等待响应')
-    .option('--timeout-ms <ms>', '请求超时（毫秒）', '5000')
-    .action((commandId, payloadEncoding, payload, commandOptions) => {
-    runAndExit(runCommand('command request', {
-        commandId: Number.parseInt(commandId, 10),
-        payloadEncoding,
-        payload,
-        timeoutMs: Number.parseInt(commandOptions.timeoutMs, 10),
-    }, getCliOptions()));
-});
-command.command('send <commandId> <payloadEncoding> <payload>')
-    .description('兼容别名：等价于 command request')
-    .option('--timeout-ms <ms>', '请求超时（毫秒）', '5000')
-    .action((commandId, payloadEncoding, payload, commandOptions) => {
-    runAndExit(runCommand('command send', {
-        commandId: Number.parseInt(commandId, 10),
-        payloadEncoding,
-        payload,
-        timeoutMs: Number.parseInt(commandOptions.timeoutMs, 10),
-    }, getCliOptions()));
-});
-const commandPending = command.command('pending').description('查看当前会话内待回复的远端命令请求');
-commandPending.command('list')
-    .description('列出当前待回复的远端命令请求')
-    .action(() => {
-    runAndExit(runCommand('command pending list', {}, getCliOptions()));
-});
-command.command('reply <remoteRequestId> <commandId> <payloadEncoding> <payload>')
-    .description('按 remoteRequestId 显式回复待处理命令')
-    .action((remoteRequestId, commandId, payloadEncoding, payload) => {
-    runAndExit(runCommand('command reply', {
-        remoteRequestId: Number.parseInt(remoteRequestId, 10),
-        commandId: Number.parseInt(commandId, 10),
-        payloadEncoding,
-        payload,
-    }, getCliOptions()));
-});
-command.command('tail').description('持续监听命令相关事件').action(() => {
-    runAndExit(tailEvents('command tail', ['command'], getCliOptions()));
-});
-const debug = program.command('debug').description('调试工具：连接 bootstrap 二维码');
-const debugBootstrap = debug.command('bootstrap').description('连接 bootstrap（不在 App Server 侧签发 token）');
-debugBootstrap.command('qrcode <access_id> <secret_key> <peer_id> [service_entry]')
-    .description('生成客户端连接 bootstrap 二维码（payload 包含 access_id/secret_key/peer_id）')
-    .action((accessId, secretKey, peerId, serviceEntry) => {
-    const payloadObject = {
-        access_id: accessId,
-        secret_key: secretKey,
-        peer_id: peerId,
-    };
-    if (serviceEntry && serviceEntry.length > 0) {
-        payloadObject.service_entry = serviceEntry;
-    }
-    const payload = JSON.stringify(payloadObject);
-    runAndExit(runCommand('debug bootstrap qrcode', { payload, outputStem: 'connect-bootstrap' }, getCliOptions()));
-});
-debugBootstrap.command('qrcode-from-config')
-    .description('从 --config 读取 debug.connect_bootstrap 并生成二维码')
-    .action(() => {
-    const config = (0, config_1.loadConfig)(getCliOptions().config);
-    const bootstrap = config.debug?.connect_bootstrap;
-    if (!bootstrap) {
-        throw new Error('missing debug.connect_bootstrap in config');
-    }
-    if (!bootstrap.access_id || !bootstrap.secret_key || !bootstrap.peer_id) {
-        throw new Error('debug.connect_bootstrap requires access_id + secret_key + peer_id');
-    }
-    const payloadObject = {
-        access_id: bootstrap.access_id,
-        secret_key: bootstrap.secret_key,
-        peer_id: bootstrap.peer_id,
-    };
-    if (bootstrap.service_entry && bootstrap.service_entry.length > 0) {
-        payloadObject.service_entry = bootstrap.service_entry;
-    }
-    const payload = JSON.stringify(payloadObject);
-    runAndExit(runCommand('debug bootstrap qrcode', { payload, outputStem: 'connect-bootstrap' }, getCliOptions()));
-});
-const events = program.command('events').description('事件订阅：实时观察 Host 事件');
-events.command('tail').description('持续监听 Host 事件').action(() => {
-    runAndExit(tailEvents('events tail', ['service', 'connection', 'stream', 'command', 'operation', 'logs'], getCliOptions()));
-});
-const logs = program.command('logs').description('日志导出：导出运行日志');
-logs.command('export <outputPath>')
-    .description('导出运行日志到指定路径')
-    .action((outputPath) => {
-    runAndExit(runCommand('logs export', { outputPath }, getCliOptions()));
-});
-const report = program.command('report').description('报告查看/导出：验收证据');
-const guide = program.command('guide').description('新手入口：按场景给出可执行步骤');
-guide.command('quickstart')
-    .description('打印服务端启动 -> 安卓扫码连接 的最小闭环步骤')
-    .action(() => {
-    (0, guide_1.printQuickstartGuide)();
-});
-report.command('show').description('查看当前报告内容').action(() => {
-    runAndExit(runCommand('report show', {}, getCliOptions()));
-});
-report.command('export <outputPath>')
-    .description('导出报告到指定路径')
-    .action((outputPath) => {
-    runAndExit(runCommand('report export', { outputPath }, getCliOptions()));
+    runAndExit((0, role_driver_1.runSendStart)(commandOptions, getCliOptions()));
+});
+const receive = program.command('receive').description('作为标准下行端运行 native DevTools driver');
+receive.command('start')
+    .description('启动 receive role，消费 bootstrap 或显式 identity 并产出 frame_dump')
+    .option('--artifact-root <dir>', 'artifact 输出目录')
+    .option('--bootstrap <path>', 'send role 产出的 bootstrap.json')
+    .option('--remote-id <id>', '显式 remote id；优先于 bootstrap')
+    .option('--token <token>', '显式 token；优先于 bootstrap')
+    .option('--audio-stream-id <id>', '音频 stream id')
+    .option('--video-stream-id <id>', '视频 stream id')
+    .option('--consumer <consumer>', 'packet_dump|frame_dump', 'frame_dump')
+    .option('--frame-limit <count>', 'frame_dump 帧数上限')
+    .option('--duration-ms <ms>', 'role active 时长')
+    .option('--connect-timeout-ms <ms>', 'connect 最大等待')
+    .option('--first-packet-timeout-ms <ms>', '首包最大等待')
+    .option('--first-output-timeout-ms <ms>', '首帧输出最大等待')
+    .addHelpText('after', `
+Examples:
+  $ tirtc-devtools-cli --json receive start --bootstrap .build/tirtc-send/bootstrap.json
+
+bootstrap.json is expected to come from a local send start run.
+For mobile device debugging, use token/license QR or a future session QR/deeplink.
+`)
+    .action((commandOptions) => {
+    runAndExit((0, role_driver_1.runReceiveStart)(commandOptions, getCliOptions()));
 });
 program.parse(process.argv);