tirtc-devtools-cli 0.0.1

package/dist/devtools/cli/src/index.js

@@ -0,0 +1,753 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const protocol_client_1 = require("../../../app-server/protocol-client");
+const facade_1 = require("./facade");
+const config_1 = require("./config");
+const guide_1 = require("./guide");
+const session_manager_1 = require("./session_manager");
+const media_assets_1 = require("./media_assets");
+const transport_1 = require("./transport");
+const token_tool_1 = require("./token_tool");
+const CLI_VERSION = '0.0.1';
+const HOST_VERSION = '1.0.0';
+const PROTOCOL_VERSION = '1.0.0';
+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);
+    process.exit(0);
+}
+const program = new commander_1.Command();
+function getCliOptions() {
+    return program.opts();
+}
+function normalizeError(error) {
+    if (error instanceof Error) {
+        return {
+            reasonCode: 'internal_error',
+            message: error.message,
+            data: undefined,
+        };
+    }
+    if (typeof error === 'object' && error !== null) {
+        const typed = error;
+        return {
+            reasonCode: typed.reasonCode ?? 'internal_error',
+            message: typed.message ?? 'Internal error',
+            data: typed.data,
+        };
+    }
+    return {
+        reasonCode: 'internal_error',
+        message: 'Internal 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';
+}
+function resolveSessionForCommand(cmdName, options, config) {
+    const sessionOptions = {
+        logRootDir: config.logging?.root_dir,
+        consoleMirror: config.logging?.console_mirror,
+    };
+    if (cmdName === 'connection connect') {
+        if (options.session && options.session.trim().length > 0) {
+            throw new Error('connection connect always creates a new session; do not pass --session');
+        }
+        const created = (0, session_manager_1.createSession)({ ...sessionOptions, 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)({ ...sessionOptions, 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 };
+}
+async function applyConfiguredStreamBootstrap(client, config) {
+    const sendStreams = [];
+    const mode = config.stream?.request_policy?.mode;
+    if (mode === 'manual' || mode === 'auto-if-bound') {
+        await client.sendRequest('stream/requestPolicy/set', { mode });
+    }
+    const configuredSend = config.streams?.send;
+    const assetsDir = configuredSend?.assets_dir;
+    const audioStreamId = configuredSend?.audio_stream_id;
+    const videoStreamId = configuredSend?.video_stream_id;
+    if (assetsDir && assetsDir.length > 0) {
+        if (Number.isFinite(audioStreamId)) {
+            const stream = await client.sendRequest('stream/sendStart', {
+                streamId: audioStreamId,
+                media: 'audio',
+                source: {
+                    mode: 'local_assets',
+                    local_assets: {
+                        assets_dir: assetsDir,
+                    },
+                },
+            }, 180_000);
+            sendStreams.push({
+                streamId: audioStreamId,
+                assetsDir,
+                media: 'audio',
+                stream,
+            });
+        }
+        if (Number.isFinite(videoStreamId)) {
+            const stream = await client.sendRequest('stream/sendStart', {
+                streamId: videoStreamId,
+                media: 'video',
+                source: {
+                    mode: 'local_assets',
+                    local_assets: {
+                        assets_dir: assetsDir,
+                    },
+                },
+            }, 180_000);
+            sendStreams.push({
+                streamId: videoStreamId,
+                assetsDir,
+                media: 'video',
+                stream,
+            });
+        }
+    }
+    return {
+        requestPolicyMode: mode,
+        sendStreams,
+    };
+}
+async function runCommand(cmdName, params, options) {
+    let transport;
+    try {
+        const config = (0, config_1.loadConfig)(options.config);
+        const session = resolveSessionForCommand(cmdName, options, config);
+        transport = createSessionTransport(session.sessionId);
+        const client = new protocol_client_1.AppServerClient(transport);
+        await client.initialize({ name: 'tirtc-devtool-cli', version: CLI_VERSION });
+        const method = facade_1.CommandToHostMethodMapping[cmdName];
+        if (!method) {
+            throw new Error('Unknown command mapping for: ' + cmdName);
+        }
+        const commandParams = cmdName === 'stream request-policy set' ? (() => {
+            const mode = String(params.mode ?? '');
+            if (mode !== 'manual' && mode !== 'auto-if-bound') {
+                throw new Error('Invalid mode, expected manual|auto-if-bound');
+            }
+            return { mode };
+        })() : params;
+        const result = await client.sendRequest(method, commandParams);
+        let resultForPrint = result;
+        if (cmdName === 'service start') {
+            const autoApplied = await applyConfiguredStreamBootstrap(client, config);
+            const hasAutoApplied = autoApplied.requestPolicyMode !== undefined || autoApplied.sendStreams.length > 0;
+            if (hasAutoApplied) {
+                const resultObject = toResultObject(result);
+                resultForPrint = {
+                    ...resultObject,
+                    autoApplied,
+                };
+            }
+        }
+        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-devtool-cli', version: CLI_VERSION });
+        await client.subscribeEvents(families);
+        await new Promise((resolve) => {
+            process.on('SIGINT', () => {
+                transport?.stop();
+                resolve();
+            });
+            transport?.onClose(() => resolve());
+        });
+        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 runMediaAssetsPrepare(source, outputRoot, outputDir, overwrite, options) {
+    try {
+        const result = await (0, media_assets_1.prepareMediaAssets)({
+            source,
+            outputRoot,
+            outputDir,
+            overwrite,
+        });
+        if (options.json) {
+            console.log(JSON.stringify({ code: 0, message: 'OK', data: result }));
+        }
+        else {
+            console.log('Prepared media assets:', JSON.stringify(result, null, 2));
+        }
+        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;
+    }
+}
+async function runTokenIssue(params, options) {
+    try {
+        const result = await (0, token_tool_1.issueTokenWithQrcode)(params);
+        if (options.json) {
+            console.log(JSON.stringify({
+                code: 0,
+                message: 'OK',
+                data: {
+                    payload: result.payload,
+                    payloadJson: result.payloadJson,
+                    token: result.token,
+                    qrCodePngPath: result.qrCodePngPath,
+                },
+            }));
+        }
+        else {
+            console.log((0, token_tool_1.formatTokenIssueConsoleOutput)(result));
+        }
+        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;
+    }
+}
+function runAndExit(promise) {
+    promise.then((code) => {
+        process.exit(code);
+    });
+}
+function mustParseJsonPayload(input) {
+    try {
+        const parsed = JSON.parse(input);
+        return JSON.stringify(parsed);
+    }
+    catch {
+        throw new Error('payloadJson must be valid JSON text');
+    }
+}
+program.name('tirtc-devtool')
+    .description('TiRTC DevTool CLI')
+    .option('--config <path>', '配置文件路径（TOML）')
+    .option('--json', '以机器可读 JSON 输出（便于脚本集成）')
+    .option('--session <sessionId>', '指定会话 ID；除 service start/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 config = (0, config_1.loadConfig)(options.config);
+        const created = (0, session_manager_1.createSession)({
+            logRootDir: config.logging?.root_dir,
+            consoleMirror: config.logging?.console_mirror,
+            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-devtool/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 并重建')
+    .action((commandOptions) => {
+    runAndExit(runMediaAssetsPrepare(commandOptions.source, commandOptions.outputRoot, commandOptions.outputDir, commandOptions.overwrite === true, getCliOptions()));
+});
+// Backward-compatible alias.
+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 [service_entry] [license]')
+    .description('启动服务端会话（license 必填，service_entry 可省略走默认）')
+    .action((service_entry, license) => {
+    const config = (0, config_1.loadConfig)(getCliOptions().config);
+    const finalServiceEntry = service_entry ?? config.service?.service_entry;
+    const finalLicense = license ?? config.service?.license;
+    if (!finalLicense) {
+        throw new Error('service start requires license (service_entry can be omitted)');
+    }
+    runAndExit(runCommand('service start', { serviceEntry: finalServiceEntry, license: finalLicense, timeoutMs: 5000 }, getCliOptions()));
+});
+service.command('stop').description('停止服务端监听').action(() => {
+    runAndExit(runCommand('service stop', {}, getCliOptions()));
+});
+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((service_entry, peer_id, token) => {
+    const config = (0, config_1.loadConfig)(getCliOptions().config);
+    const finalServiceEntry = [service_entry, config.connection?.service_entry, config.service?.service_entry].find((value) => typeof value === "string" && value.trim().length > 0);
+    const configuredToken = config.connection?.token?.trim();
+    const manualToken = (token ?? configuredToken)?.trim();
+    const autoTokenCfg = config.connection?.auto_token;
+    const hasAutoToken = Boolean(autoTokenCfg?.access_id && autoTokenCfg?.secret_key);
+    if (!manualToken && !hasAutoToken) {
+        throw new Error('connection connect requires token or [connection.auto_token] access_id/secret_key');
+    }
+    const params = {
+        serviceEntry: finalServiceEntry,
+        peerId: peer_id,
+        timeoutMs: 5000,
+    };
+    if (manualToken && manualToken.length > 0) {
+        params.token = manualToken;
+        params.tokenMode = 'manual';
+    }
+    else {
+        params.tokenMode = 'auto';
+        params.autoToken = {
+            openapiEntry: autoTokenCfg?.openapi_entry,
+            accessId: autoTokenCfg?.access_id,
+            secretKey: autoTokenCfg?.secret_key,
+            localId: autoTokenCfg?.local_id ?? peer_id,
+            userTtlSeconds: autoTokenCfg?.user_ttl_seconds,
+            channelTtlSeconds: autoTokenCfg?.channel_ttl_seconds,
+        };
+    }
+    runAndExit(runCommand('connection connect', params, getCliOptions()));
+});
+connection.command('disconnect').description('断开当前连接').action(() => {
+    runAndExit(runCommand('connection disconnect', {}, getCliOptions()));
+});
+const token = program.command('token').description('Token 工具：签发 token，并输出可直接使用的 JSON 与本地二维码 PNG');
+token.command('issue <access_id> <secret_key> <local_id> <peer_id>')
+    .description('使用 access/secret/local/peer 签发 token；输出摘要、payload JSON、token 和二维码 PNG 路径')
+    .option('--openapi-entry <url>', '可选 openapi entry；留空时走 runtime 默认值')
+    .option('--service-entry <entry>', '可选 service entry；用于组合连接 payload 与二维码 PNG')
+    .option('--user-ttl-seconds <seconds>', '可选 user token ttl（秒）')
+    .option('--channel-ttl-seconds <seconds>', '可选 channel token ttl（秒）')
+    .action((access_id, secret_key, local_id, peer_id, commandOptions) => {
+    const parsePositiveInt = (name, raw) => {
+        if (raw === undefined) {
+            return undefined;
+        }
+        const parsed = Number.parseInt(raw, 10);
+        if (!Number.isInteger(parsed) || parsed <= 0) {
+            throw new Error(name + ' must be a positive integer');
+        }
+        return parsed;
+    };
+    runAndExit(runTokenIssue({
+        accessId: access_id,
+        secretKey: secret_key,
+        localId: local_id,
+        peerId: peer_id,
+        openapiEntry: commandOptions.openapiEntry,
+        serviceEntry: commandOptions.serviceEntry,
+        userTtlSeconds: parsePositiveInt('user-ttl-seconds', commandOptions.userTtlSeconds),
+        channelTtlSeconds: parsePositiveInt('channel-ttl-seconds', commandOptions.channelTtlSeconds),
+    }, getCliOptions()));
+});
+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, assets_dir) => {
+    runAndExit(runCommand('stream send start', {
+        streamId: Number.parseInt(streamId, 10),
+        media,
+        source: {
+            mode: 'local_assets',
+            local_assets: {
+                assets_dir,
+            },
+        },
+    }, 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 streamRequestPolicy = stream.command('request-policy').description('远端请求策略：manual/auto-if-bound');
+streamRequestPolicy.command('get').description('查看远端请求策略').action(() => {
+    runAndExit(runCommand('stream request-policy get', {}, getCliOptions()));
+});
+streamRequestPolicy.command('set <mode>')
+    .description('设置远端请求策略（manual|auto-if-bound）')
+    .action((mode) => {
+    runAndExit(runCommand('stream request-policy set', { mode }, 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('send <commandId> <kind> <payloadEncoding> <payload>')
+    .description('发送命令并等待响应')
+    .action((commandId, kind, payloadEncoding, payload) => {
+    runAndExit(runCommand('command send', {
+        commandId: Number.parseInt(commandId, 10),
+        kind,
+        payloadEncoding,
+        payload,
+        awaitResponse: true,
+        timeoutMs: 5000,
+    }, getCliOptions()));
+});
+command.command('send-json <commandId> <kind> <payloadJson>')
+    .description('发送 JSON 命令并等待响应（JSON-first）')
+    .action((commandId, kind, payloadJson) => {
+    const parsed = facade_1.CommandSendJsonParamsSchema.safeParse({
+        commandId: Number.parseInt(commandId, 10),
+        kind,
+        payloadJson,
+    });
+    if (!parsed.success) {
+        const msg = parsed.error.issues.map((issue) => issue.message).join('; ');
+        throw new Error('invalid command send-json params: ' + msg);
+    }
+    const payload = mustParseJsonPayload(payloadJson);
+    runAndExit(runCommand('command send', {
+        commandId: parsed.data.commandId,
+        kind: parsed.data.kind,
+        payloadEncoding: 'json',
+        payload,
+        awaitResponse: true,
+        timeoutMs: 5000,
+    }, 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((access_id, secret_key, peer_id, service_entry) => {
+    const payload = JSON.stringify({
+        version: 1,
+        type: 'tirtc-connect-bootstrap',
+        access_id,
+        secret_key,
+        peer_id,
+        service_entry: service_entry ?? '',
+        generated_at: new Date().toISOString(),
+    });
+    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 payload = JSON.stringify({
+        version: 1,
+        type: 'tirtc-connect-bootstrap',
+        access_id: bootstrap.access_id,
+        secret_key: bootstrap.secret_key,
+        peer_id: bootstrap.peer_id,
+        service_entry: bootstrap.service_entry ?? '',
+        generated_at: new Date().toISOString(),
+    });
+    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()));
+});
+program.parse(process.argv);