tirtc-devtools-cli 0.0.3 → 0.0.4

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` 的命令行门面，用来控制会话、服务、连接、流、命令通道与调试工具。
 
@@ -126,19 +126,23 @@ node devtools/cli/bin/tirtc-devtools-cli.js --help
 - `--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`。
+- `--json` 模式下只输出 `payload`、`payloadJson`、`token` 和 `qrCodePngPath`，不输出 ASCII 二维码。
+- 如果觉得 ASCII 二维码太密，可把纠错级别从默认 `M` 调低到 `L`；如果希望更耐遮挡，可调高到 `Q` 或 `H`，但二维码会更密。
 
 ### Stream
 

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

@@ -9,7 +9,7 @@ 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.4';
 const HOST_VERSION = '1.0.0';
 const PROTOCOL_VERSION = '1.0.0';
 if (process.argv.includes('--version') || process.argv.includes('-V')) {
@@ -551,6 +551,8 @@ token.command('issue <access_id> <secret_key> <local_id> <peer_id>')
     .option('--service-entry <entry>', '可选 service entry；用于组合连接 payload 与二维码 PNG')
     .option('--user-ttl-seconds <seconds>', '可选 user token ttl（秒）')
     .option('--channel-ttl-seconds <seconds>', '可选 channel token ttl（秒）')
+    .option('--qr-error-correction-level <level>', '二维码纠错级别：L/M/Q/H；默认 M')
+    .option('--ascii-max-columns <columns>', 'ASCII 二维码最大宽度；不传时优先读取当前终端宽度或 COLUMNS')
     .action((access_id, secret_key, local_id, peer_id, commandOptions) => {
     const parsePositiveInt = (name, raw) => {
         if (raw === undefined) {
@@ -562,6 +564,16 @@ token.command('issue <access_id> <secret_key> <local_id> <peer_id>')
         }
         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;
+    };
     runAndExit(runTokenIssue({
         accessId: access_id,
         secretKey: secret_key,
@@ -571,6 +583,8 @@ token.command('issue <access_id> <secret_key> <local_id> <peer_id>')
         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),
     }, getCliOptions()));
 });
 const stream = program.command('stream').description('流控制：发送/接收/请求策略');

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.4",
   "private": false,
   "main": "dist/index.js",
   "bin": {