tirtc-devtools-cli 0.0.3 → 0.0.5

package/README.md

@@ -1,6 +1,6 @@
-# TiRTC DevTool CLI
+# TiRTC DevTools CLI
 
-`devtools/cli/` 承接 `TiRTC DevTool CLI`。它是当前唯一用户界面的产品门面 (command client)，为用户提供了一套操作 `Matrix Host` 控制面的终端工具。
+`devtools/cli/` 承接 `TiRTC DevTools CLI`。它是当前唯一用户界面的产品门面 (command client)，为用户提供了一套操作 `Matrix Host` 控制面的终端工具。
 
 ## 使用说明 (C-Lite)
 

package/USAGE.md

@@ -1,4 +1,4 @@
-# TiRTC DevTool CLI（用户手册）
+# TiRTC DevTools CLI（用户手册）
 
 `tirtc-devtools-cli` 是基于 `app-server/host` 的命令行门面，用来控制会话、服务、连接、流、命令通道与调试工具。
 
@@ -118,27 +118,46 @@ node devtools/cli/bin/tirtc-devtools-cli.js --help
 
 用途：直接签发 token，并把调试所需的核心信息一次性输出到控制台，同时在本地生成二维码 PNG。
 
-- `tirtc-devtools-cli token issue <accessId> <secretKey> <localId> <peerId>`：签发 token。
+- `tirtc-devtools-cli token issue <peerId>`：签发 token；默认从环境变量读取凭据，并使用 `peerId` 作为默认 `localId`。
 
 可选参数：
 
+- `--access-id <accessId>`：显式传 access id；不传时读取 `TIRTC_CONN_ACCESS_ID`。
+- `--secret-key <secretKey>`：显式传 secret key；不传时读取 `TIRTC_CONN_SECRET_KEY`。
+- `--local-id <localId>`：显式传 local id；不传时默认使用 `peerId`。
 - `--openapi-entry <url>`：覆盖默认 openapi entry。
 - `--service-entry <entry>`：附加到组合 payload，便于扫码后直接连到目标服务。
 - `--user-ttl-seconds <seconds>`：覆盖 user token ttl。
 - `--channel-ttl-seconds <seconds>`：覆盖 channel token ttl。
+- `--qr-error-correction-level <level>`：设置二维码纠错级别，可选 `L/M/Q/H`，默认 `M`。
+- `--ascii-max-columns <columns>`：显式限制 ASCII 二维码最大宽度；不传时优先读取当前终端宽度或 `COLUMNS`。
 
 默认输出四部分：
 
 - `Issued Token Summary`：面向人类阅读的摘要，快速确认 local/peer/entry/ttl。
 - `Token`：单独罗列 token 字符串，便于复制粘贴。
 - `Payload JSON`：组合 JSON，对方或 Agent 可直接复制使用。
+- `QR Code ASCII`：非 `--json` 模式下尽量输出 ASCII 二维码；如果终端宽度不足，会提示改看 PNG。
 - `QR Code PNG`：基于组合 JSON 生成的本地 PNG 文件绝对路径。适合人工打开图片后扫码。
 
 说明：
 
 - 组合 JSON 的 `type` 固定为 `tirtc-connect-token`。
 - PNG 二维码承载的是组合 JSON，不再暴露 `secret_key`。
-- `--json` 模式下会输出 `payload`、`payloadJson`、`token` 和 `qrCodePngPath`。
+- CLI 不会在最终 JSON、控制台输出或二维码内容里打印 `access_id` 和 `secret_key`。
+- `--json` 模式下只输出 `payload`、`payloadJson`、`token` 和 `qrCodePngPath`，不输出 ASCII 二维码。
+- 如果觉得 ASCII 二维码太密，可把纠错级别从默认 `M` 调低到 `L`；如果希望更耐遮挡，可调高到 `Q` 或 `H`，但二维码会更密。
+
+推荐默认做法：
+
+```bash
+export TIRTC_CONN_ACCESS_ID="<ACCESS_ID>"
+export TIRTC_CONN_SECRET_KEY="<SECRET_KEY>"
+tirtc-devtools-cli --json token issue "<PEER_ID>"
+```
+
+只有在你明确需要覆盖环境变量时，才额外传 `--access-id` 和 `--secret-key`。
+只有在你明确需要不同的本地用户标识时，才额外传 `--local-id`。
 
 ### Stream
 

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

@@ -31,9 +31,12 @@ function printQuickstartGuide() {
         '  - 持 token + peer_id 连接服务端；连接成功后请求 audio_stream_id/video_stream_id',
         '',
         '额外：如果你只想本地直接签发并拿到可扫码 payload，可执行：',
-        '  node devtools/cli/bin/tirtc-devtools-cli.js token issue "<ACCESS_ID>" "<SECRET_KEY>" "<LOCAL_ID>" "<PEER_ID>" \\',
+        '  export TIRTC_CONN_ACCESS_ID="<ACCESS_ID>"',
+        '  export TIRTC_CONN_SECRET_KEY="<SECRET_KEY>"',
+        '  node devtools/cli/bin/tirtc-devtools-cli.js token issue "<LOCAL_ID>" "<PEER_ID>" \\',
         '    --service-entry "<SERVICE_ENTRY>"',
         '  # CLI 会直接打印摘要、payload JSON、token，并生成本地二维码 PNG 路径',
+        '  # 如需临时覆盖，也可显式传 --access-id / --secret-key',
         '',
         '步骤 5：服务端观测',
         '  node devtools/cli/bin/tirtc-devtools-cli.js --session <SESSION_ID> events tail',

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

@@ -9,9 +9,11 @@ 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.3';
+const CLI_VERSION = '0.0.5';
 const HOST_VERSION = '1.0.0';
 const PROTOCOL_VERSION = '1.0.0';
+const kTokenIssueAccessIdEnvVar = 'TIRTC_CONN_ACCESS_ID';
+const kTokenIssueSecretKeyEnvVar = 'TIRTC_CONN_SECRET_KEY';
 if (process.argv.includes('--version') || process.argv.includes('-V')) {
     console.log('CLI Version: ' + CLI_VERSION);
     console.log('Host Version: ' + HOST_VERSION);
@@ -325,6 +327,60 @@ async function runTokenIssue(params, options) {
         return exitCode;
     }
 }
+async function runTokenIssueFromCli(peerId, commandOptions, options) {
+    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;
+    };
+    const parseQrErrorCorrectionLevel = (raw) => {
+        if (raw === undefined) {
+            return undefined;
+        }
+        const normalized = raw.trim().toUpperCase();
+        if (normalized !== 'L' && normalized !== 'M' && normalized !== 'Q' && normalized !== 'H') {
+            throw new Error('qr-error-correction-level must be one of: L, M, Q, H');
+        }
+        return normalized;
+    };
+    try {
+        const accessId = resolveTokenIssueCredential(commandOptions.accessId, kTokenIssueAccessIdEnvVar, '--access-id');
+        const secretKey = resolveTokenIssueCredential(commandOptions.secretKey, kTokenIssueSecretKeyEnvVar, '--secret-key');
+        return await runTokenIssue({
+            accessId,
+            secretKey,
+            localId: commandOptions.localId?.trim() || peerId,
+            peerId,
+            openapiEntry: commandOptions.openapiEntry,
+            serviceEntry: commandOptions.serviceEntry,
+            userTtlSeconds: parsePositiveInt('user-ttl-seconds', commandOptions.userTtlSeconds),
+            channelTtlSeconds: parsePositiveInt('channel-ttl-seconds', commandOptions.channelTtlSeconds),
+            qrErrorCorrectionLevel: parseQrErrorCorrectionLevel(commandOptions.qrErrorCorrectionLevel),
+            asciiMaxColumns: parsePositiveInt('ascii-max-columns', commandOptions.asciiMaxColumns),
+        }, options);
+    }
+    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);
@@ -339,6 +395,18 @@ function mustParseJsonPayload(input) {
         throw new Error('payloadJson must be valid JSON text');
     }
 }
+function resolveTokenIssueCredential(explicitValue, envVarName, optionName) {
+    const normalizedExplicit = explicitValue?.trim();
+    if (normalizedExplicit) {
+        return normalizedExplicit;
+    }
+    const normalizedEnv = process.env[envVarName]?.trim();
+    if (normalizedEnv) {
+        return normalizedEnv;
+    }
+    throw new Error('missing credential: set environment variable ' + envVarName +
+        ' or pass ' + optionName + ' explicitly');
+}
 program.name('tirtc-devtools-cli')
     .description('TiRTC DevTools CLI')
     .option('--config <path>', '配置文件路径（TOML）')
@@ -545,33 +613,19 @@ 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 路径')
+token.command('issue <peer_id>')
+    .description('默认从环境变量读取 access/secret，并以 peer_id 作为默认 local_id 来签发 token')
+    .option('--access-id <accessId>', '显式 access id；不传时读取 ' + kTokenIssueAccessIdEnvVar)
+    .option('--secret-key <secretKey>', '显式 secret key；不传时读取 ' + kTokenIssueSecretKeyEnvVar)
+    .option('--local-id <localId>', '显式 local id；不传时默认使用 peer_id')
     .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()));
+    .option('--qr-error-correction-level <level>', '二维码纠错级别：L/M/Q/H；默认 M')
+    .option('--ascii-max-columns <columns>', 'ASCII 二维码最大宽度；不传时优先读取当前终端宽度或 COLUMNS')
+    .action((peer_id, commandOptions) => {
+    runAndExit(runTokenIssueFromCli(peer_id, commandOptions, getCliOptions()));
 });
 const stream = program.command('stream').description('流控制：发送/接收/请求策略');
 stream.command('list').description('查看流快照列表').action(() => {

package/dist/devtools/cli/src/token_tool.d.ts

@@ -7,6 +7,8 @@ export type TokenIssueInput = {
     serviceEntry?: string;
     userTtlSeconds?: number;
     channelTtlSeconds?: number;
+    qrErrorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H';
+    asciiMaxColumns?: number;
 };
 export type IssuedTokenPayload = {
     version: 1;
@@ -26,10 +28,11 @@ export type TokenIssueOutput = {
     token: string;
     qrCodePngPath: string;
     qrCodeAscii: string;
+    qrCodeAsciiIncluded: boolean;
 };
 export declare function issueToken(input: TokenIssueInput): Promise<string>;
 export declare function buildIssuedTokenPayload(input: TokenIssueInput, token: string): IssuedTokenPayload;
-export declare function writePngQrcode(payloadJson: string, outputPath: string): Promise<string>;
-export declare function buildAsciiQrcode(payloadJson: string): Promise<string>;
+export declare function writePngQrcode(payloadJson: string, outputPath: string, errorCorrectionLevel: 'L' | 'M' | 'Q' | 'H'): Promise<string>;
+export declare function buildAsciiQrcode(payloadJson: string, terminalColumns?: number, errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H'): Promise<string>;
 export declare function issueTokenWithQrcode(input: TokenIssueInput): Promise<TokenIssueOutput>;
 export declare function formatTokenIssueConsoleOutput(output: TokenIssueOutput): string;

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

@@ -17,8 +17,6 @@ const embedded_paths_1 = require("./embedded_paths");
 const kDefaultOpenapiEntry = 'http://api-test-tirtc.tange365.com';
 const kDefaultUserTtlSeconds = 86400;
 const kDefaultChannelTtlSeconds = 300;
-const kAsciiQrBlack = '██';
-const kAsciiQrWhite = '  ';
 const kAsciiQrQuietZoneModules = 2;
 function pathExists(filePath) {
     return fs_1.default.existsSync(filePath);
@@ -176,6 +174,58 @@ function issueTokenViaSubprocess(addonPath, input) {
 function readQrModule(modules, row, column) {
     return Boolean(modules.data[row * modules.size + column]);
 }
+function resolveTerminalColumns() {
+    if (typeof process.stdout.columns === 'number' && Number.isInteger(process.stdout.columns) && process.stdout.columns > 0) {
+        return process.stdout.columns;
+    }
+    const raw = process.env.COLUMNS;
+    if (!raw) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        return undefined;
+    }
+    return parsed;
+}
+function resolveAsciiMaxColumns(explicit) {
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    return resolveTerminalColumns();
+}
+function readQrModuleOrWhite(modules, row, column) {
+    if (row < 0 || column < 0 || row >= modules.size || column >= modules.size) {
+        return false;
+    }
+    return readQrModule(modules, row, column);
+}
+function renderHalfBlockQr(modules) {
+    const lines = [];
+    const start = -kAsciiQrQuietZoneModules;
+    const end = modules.size + kAsciiQrQuietZoneModules;
+    for (let row = start; row < end; row += 2) {
+        let line = '';
+        for (let column = start; column < end; column += 1) {
+            const top = readQrModuleOrWhite(modules, row, column);
+            const bottom = readQrModuleOrWhite(modules, row + 1, column);
+            if (top && bottom) {
+                line += '█';
+            }
+            else if (top) {
+                line += '▀';
+            }
+            else if (bottom) {
+                line += '▄';
+            }
+            else {
+                line += ' ';
+            }
+        }
+        lines.push(line);
+    }
+    return lines.join('\n');
+}
 async function issueToken(input) {
     const runtimePlatform = resolveRuntimePlatform();
     const runtimeBundleRoot = resolveRuntimeBundleRoot(runtimePlatform);
@@ -204,50 +254,45 @@ function buildIssuedTokenPayload(input, token) {
         generated_at: new Date().toISOString(),
     };
 }
-async function writePngQrcode(payloadJson, outputPath) {
+async function writePngQrcode(payloadJson, outputPath, errorCorrectionLevel) {
     const resolvedPath = path_1.default.resolve(outputPath);
     ensureDirectory(path_1.default.dirname(resolvedPath));
     await qrcode_1.default.toFile(resolvedPath, payloadJson, {
-        errorCorrectionLevel: 'M',
+        errorCorrectionLevel,
         margin: 2,
         type: 'png',
         width: 960,
     });
     return resolvedPath;
 }
-async function buildAsciiQrcode(payloadJson) {
-    const qr = qrcode_1.default.create(payloadJson, { errorCorrectionLevel: 'M' });
-    const quietZone = kAsciiQrWhite.repeat(kAsciiQrQuietZoneModules);
-    const fullQuietLine = quietZone + kAsciiQrWhite.repeat(qr.modules.size) + quietZone;
-    const lines = [];
-    for (let index = 0; index < kAsciiQrQuietZoneModules; index += 1) {
-        lines.push(fullQuietLine);
+async function buildAsciiQrcode(payloadJson, terminalColumns, errorCorrectionLevel = 'M') {
+    const qr = qrcode_1.default.create(payloadJson, { errorCorrectionLevel });
+    const requiredColumns = qr.modules.size + (kAsciiQrQuietZoneModules * 2);
+    const availableColumns = resolveAsciiMaxColumns(terminalColumns);
+    if (availableColumns !== undefined && availableColumns < requiredColumns) {
+        return [
+            '(omitted: terminal width too narrow for ASCII QR)',
+            `required_columns: ${requiredColumns}`,
+            `available_columns: ${availableColumns}`,
+            'open the QR Code PNG path below instead.',
+        ].join('\n');
     }
-    for (let row = 0; row < qr.modules.size; row += 1) {
-        let line = quietZone;
-        for (let column = 0; column < qr.modules.size; column += 1) {
-            line += readQrModule(qr.modules, row, column) ? kAsciiQrBlack : kAsciiQrWhite;
-        }
-        line += quietZone;
-        lines.push(line);
-    }
-    for (let index = 0; index < kAsciiQrQuietZoneModules; index += 1) {
-        lines.push(fullQuietLine);
-    }
-    return lines.join('\n');
+    return renderHalfBlockQr(qr.modules);
 }
 async function issueTokenWithQrcode(input) {
     const token = await issueToken(input);
     const payload = buildIssuedTokenPayload(input, token);
     const payloadJson = JSON.stringify(payload);
-    const qrCodePngPath = await writePngQrcode(payloadJson, buildQrCodePngPath(payload));
-    const qrCodeAscii = await buildAsciiQrcode(payloadJson);
+    const qrErrorCorrectionLevel = input.qrErrorCorrectionLevel ?? 'M';
+    const qrCodePngPath = await writePngQrcode(payloadJson, buildQrCodePngPath(payload), qrErrorCorrectionLevel);
+    const qrCodeAscii = await buildAsciiQrcode(payloadJson, input.asciiMaxColumns, qrErrorCorrectionLevel);
     return {
         payload,
         payloadJson,
         token,
         qrCodePngPath,
         qrCodeAscii,
+        qrCodeAsciiIncluded: !qrCodeAscii.startsWith('(omitted:'),
     };
 }
 function formatTokenIssueConsoleOutput(output) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-devtools-cli",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "private": false,
   "main": "dist/index.js",
   "bin": {