connelio 0.1.0 → 0.1.2

package/README.md

@@ -42,11 +42,14 @@ Tokens are stored in `~/.connelio/agents/` with file mode 600. `forget` removes
 One command on the computer that runs Hermes:
 
 ```bash
-npx connelio connect --hermes                          # use the active Hermes profile
-npx connelio connect --hermes --hermes-profile connelio # keep your Telegram bot, add Connelio as its own profile
+npx connelio connect --hermes
 ```
 
-Scan the QR code, and the command writes Hermes's settings (address, token, and an allow-list with only you) through `hermes config set`, then restarts the Hermes gateway.
+That's the whole thing — it never asks you to choose between commands. If the Hermes on this computer already talks to a Telegram bot, Connelio gets its own Hermes profile (`connelio`) and leaves that bot alone; if a `connelio` profile is already there, it is reused. Only `--replace` swaps the bot your current profile uses. To put Connelio on a specific profile instead: `--hermes-profile <name>`.
+
+Each step prints as it happens — checking Hermes, preparing the config, waiting for your phone, connected, restarting Hermes — and a failed step says what to do next. The QR code is drawn large (two characters per module, quiet zone around it, and the pairing code on its own line below), and falls back to the compact version only when the terminal is too narrow for it.
+
+Scan the QR code, and the command writes Hermes's settings (address, token, and an allow-list with only you) through `hermes config set`, then restarts the Hermes gateway (`hermes gateway ensure` when it is not running yet).
 
 Doing it by hand: Hermes talks to Telegram through python-telegram-bot and lets you set the API address. Create a Bot Agent in Connelio, copy its token once, then in your Hermes config:
 

package/bin/connelio.mjs

@@ -7,7 +7,9 @@ import { pair } from '../src/pair.mjs';
 import { runAgent } from '../src/runner.mjs';
 import { claudeCodeAdapter } from '../src/adapters/claude-code.mjs';
 import { commandAdapter } from '../src/adapters/command.mjs';
-import { configureHermes, hermesCli } from '../src/hermes.mjs';
+import { configureHermes, hermesCli, ISOLATED_PROFILE, isConnelioBase } from '../src/hermes.mjs';
+import { createProgress } from '../src/progress.mjs';
+import { copy as copyFor, detectLang } from '../src/i18n.mjs';
 
 const HELP = `connelio — put your AI agent in Connelio
 
@@ -25,8 +27,11 @@ Options for connect:
   --knowledge <path>      read-only folder that public chats may read
   --name <text>           how this computer is shown on your phone
   --server <url>          Connelio server (default https://connelio.app)
-  --hermes-profile <name> with --hermes: use (or create) this Hermes profile instead of the active one
+  --hermes-profile <name> with --hermes: use (or create) this Hermes profile instead of choosing one for you
   --replace               with --hermes: replace the Telegram bot this Hermes profile already uses
+
+With --hermes, if the Hermes on this computer already talks to a Telegram bot, Connelio
+gets its own Hermes profile (${ISOLATED_PROFILE}) and leaves that bot alone. No questions asked.
 `;
 
 function parse(argv) {
@@ -46,6 +51,9 @@ function parse(argv) {
   return { verb, flags, positional, command };
 }
 
+const flagOn = (value) => value === true || value === 'true' || value === '1';
+const firstLine = (message) => String(message || '').split('\n').map((l) => l.trim()).filter(Boolean)[0] || '';
+
 async function adapterFor(config) {
   return config.command?.length ? commandAdapter(config.command) : claudeCodeAdapter();
 }
@@ -61,24 +69,91 @@ async function start(config) {
   saveAgent(config);
 }
 
+/** connect --hermes：一步不停，不再让用户在两行命令里选。 */
+async function connectHermes({ server, flags, out = process.stdout }) {
+  const text = copyFor(detectLang());
+  const progress = createProgress(out);
+  const replace = flagOn(flags.replace);
+  const explicit = typeof flags['hermes-profile'] === 'string' ? flags['hermes-profile'] : '';
+  const deviceName = typeof flags.name === 'string' ? flags.name : undefined;
+
+  // 1 检查 Hermes
+  if (!hermesCli('').available()) {
+    progress.fail(text.steps.check, text.errors.noHermes.why, text.errors.noHermes.next);
+    return 1;
+  }
+  progress.ok(text.steps.check);
+
+  // 2 建配置：已有别的 Telegram 机器人就自动开独立 profile（原来的不受影响），只有 --replace 才替换
+  let profile = explicit;
+  let notice = '';
+  if (!explicit && !replace) {
+    const state = hermesCli('').telegramState();
+    if (state.token && !isConnelioBase(state.baseUrl, server)) profile = ISOLATED_PROFILE;
+    else if (state.token) notice = text.alreadyConnelio;
+  }
+  if (explicit && !replace) {
+    const state = hermesCli(explicit).telegramState();
+    if (state.token && !isConnelioBase(state.baseUrl, server)) {
+      progress.fail(text.steps.prepare, text.errors.profileHasBot.why(explicit), text.errors.profileHasBot.next);
+      return 1;
+    }
+  }
+  const hermes = hermesCli(profile);
+  let prepared;
+  try {
+    prepared = hermes.ensureProfile();
+  } catch (error) {
+    progress.fail(text.steps.prepare, text.errors.profileFailed.why, text.errors.profileFailed.next);
+    progress.note(firstLine(error.message));
+    return 1;
+  }
+  progress.ok(text.steps.prepare);
+  if (profile === ISOLATED_PROFILE && !explicit) progress.note(prepared.existed ? text.reuseProfile : text.createProfile);
+  else if (replace) progress.note(text.keepActive);
+  if (notice) progress.note(notice);
+
+  // 3 二维码 + 等手机扫码
+  progress.waiting(text.steps.scan);
+  let result;
+  try {
+    result = await pair({ server, kind: 'hermes', deviceName, out });
+  } catch (error) {
+    const known = text.errors[error.code];
+    progress.fail(text.steps.scan, known?.why || text.errors.network.why, known?.next || text.errors.network.next);
+    if (!known && error.message) progress.note(firstLine(error.message));
+    return 1;
+  }
+
+  // 4 写配置 = 已连接
+  try {
+    configureHermes({ hermes, server, token: result.token, ownerTelegramId: result.owner?.telegramId });
+  } catch (error) {
+    progress.fail(text.steps.connected, text.errors.configWrite.why, text.errors.configWrite.next);
+    progress.note(firstLine(error.message));
+    return 1;
+  }
+  const bot = result.bot ?? {};
+  progress.ok(`${text.steps.connected}${bot.displayName ? ` — ${bot.displayName}${bot.username ? ` (@${bot.username})` : ''}` : ''}`);
+
+  // 5 重启 Hermes
+  const startCommand = `hermes${profile ? ` -p ${profile}` : ''} gateway run`;
+  progress.begin(text.steps.restart);
+  if (hermes.restart()) progress.ok(text.steps.restart);
+  else progress.warn(text.steps.restart, `${text.manualStart} ${startCommand}`);
+
+  progress.blank();
+  out.write(`  ${text.done}\n`);
+  return 0;
+}
+
 async function main() {
   const { verb, flags, positional, command } = parse(process.argv.slice(2));
   if (!verb || verb === 'help' || flags.help || flags.h) { process.stdout.write(HELP); return; }
   const server = String(flags.server || process.env.CONNELIO_SERVER || 'https://connelio.app');
 
   if (verb === 'connect' && flags.hermes) {
-    const profile = typeof flags['hermes-profile'] === 'string' ? flags['hermes-profile'] : '';
-    const hermes = hermesCli(profile);
-    if (!hermes.available()) throw new Error('Hermes was not found on this computer (`hermes --version` failed). Install Hermes first: https://hermes-agent.nousresearch.com');
-    hermes.ensureProfile();
-    if (hermes.existingTelegramToken() && !flags.replace) {
-      throw new Error(`This Hermes profile already talks to a Telegram bot. Keep it and add Connelio as a separate profile:\n  npx connelio connect --hermes --hermes-profile connelio\nor replace it:\n  npx connelio connect --hermes --replace`);
-    }
-    const result = await pair({ server, kind: 'hermes', deviceName: typeof flags.name === 'string' ? flags.name : undefined });
-    configureHermes({ hermes, server, token: result.token, ownerTelegramId: result.owner?.telegramId });
-    process.stdout.write(`✓ Hermes is now connected as ${result.bot.displayName} (@${result.bot.username}).\n`);
-    if (hermes.restart()) process.stdout.write('✓ Hermes gateway restarted. Say hi to it in Connelio.\n');
-    else process.stdout.write(`Start Hermes to go online:  hermes${profile ? ` -p ${profile}` : ''} gateway run\n`);
+    process.exitCode = await connectHermes({ server, flags });
     return;
   }
   if (verb === 'connect') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "connelio",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Put your AI agent (Claude Code, Hermes, any CLI) in Connelio: pair with a QR code, chat with it from your phone.",
   "license": "MIT",
   "type": "module",

package/src/hermes.mjs

@@ -1,35 +1,81 @@
 // Hermes 一键接入：配对拿到 token 后，用 Hermes 自己的 `hermes config set` 把 Telegram 通道指向 Connelio。
 // Hermes 走 python-telegram-bot，原生支持 platforms.telegram.extra.base_url —— 不需要给 Hermes 装任何插件。
 import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** 独立 profile 名字：已有 Telegram 机器人时，Connelio 用它自己的配置，互不影响。 */
+export const ISOLATED_PROFILE = 'connelio';
 
 export function hermesCli(profile) {
   const bin = process.env.CONNELIO_HERMES_BIN || 'hermes';
   const prefix = profile ? ['-p', profile] : [];
-  const run = (args) => spawnSync(bin, [...prefix, ...args], { encoding: 'utf8' });
-  return {
+  const run = (args) => spawnSync(bin, [...prefix, ...args], { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
+  const cli = {
+    profile,
     available() {
-      const r = spawnSync(bin, ['--version'], { encoding: 'utf8' });
+      const r = spawnSync(bin, ['--version'], { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
       return !r.error && r.status === 0;
     },
-    /** 这个 profile 是否已经接着一个 Telegram 机器人（接上 Connelio 会把它替换掉） */
-    existingTelegramToken() {
-      const r = run(['config', 'get', 'TELEGRAM_BOT_TOKEN']);
+    /** 这个 profile 名是否已经存在（`hermes profile list` 第一列） */
+    profileExists() {
+      if (!profile) return true;
+      const r = spawnSync(bin, ['profile', 'list'], { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
+      if (r.error || r.status !== 0) return existsSync(join(homedir(), '.hermes', 'profiles', profile));
+      return r.stdout.split('\n')
+        .map((line) => line.replace(/[─━│]/g, ' ').trim().split(/\s+/)[0] || '')
+        .map((name) => name.replace(/^[^\w.-]+/, ''))
+        .includes(profile);
+    },
+    /** 读一个配置项；没设置返回空串（Hermes 会打“Config key not set”并退出 1） */
+    get(key) {
+      const r = run(['config', 'get', key]);
+      if (r.error || r.status !== 0) return '';
       const value = (r.stdout || '').trim();
-      return r.status === 0 && value && !/^(none|null|not set|)$/i.test(value) ? value : '';
+      return /^config key not set/i.test(value) ? '' : value;
+    },
+    /** 当前 profile 的 Telegram 状况：是否已有机器人、指向哪里 */
+    telegramState() {
+      const token = cli.get('TELEGRAM_BOT_TOKEN');
+      const baseUrl = cli.get('platforms.telegram.extra.base_url');
+      return { token, baseUrl, enabled: /^(true|1|yes)$/i.test(cli.get('platforms.telegram.enabled')) };
     },
+    /** 建 profile（--clone：不带原来的机器人 token）；已存在就复用 */
     ensureProfile() {
-      if (!profile) return;
-      spawnSync(bin, ['profile', 'create', profile, '--clone'], { encoding: 'utf8' });   // 已存在会失败，无妨
+      if (!profile) return { existed: true, created: false };
+      if (cli.profileExists()) return { existed: true, created: false };
+      const r = spawnSync(bin, ['profile', 'create', profile, '--clone'], { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
+      if (r.error || r.status !== 0) throw new Error((r.stderr || r.error?.message || `hermes profile create exited ${r.status}`).trim());
+      return { existed: false, created: true };
     },
     set(key, value) {
       const r = run(['config', 'set', key, String(value)]);
       if (r.error || r.status !== 0) throw new Error(`hermes config set ${key} failed: ${(r.stderr || r.error?.message || '').trim()}`);
     },
-    restart() {
-      const r = run(['gateway', 'restart']);
+    /** 网关现在是否在跑（`gateway status` 没跑时也退出 0，只能看文字） */
+    gatewayRunning() {
+      const r = run(['gateway', 'status']);
+      return !r.error && r.status === 0 && !/not running/i.test(`${r.stdout || ''}${r.stderr || ''}`);
+    },
+    /** 让新配置生效：在跑就重启；没跑就拉起来（ensure 起本地运行时，不装服务）。
+     *  真机上这两条都要几十秒，给足时间但不许无限等。 */
+    restart({ timeout = 150_000 } = {}) {
+      const r = spawnSync(bin, [...prefix, 'gateway', cli.gatewayRunning() ? 'restart' : 'ensure'], { encoding: 'utf8', timeout, env: { ...process.env, NO_COLOR: '1' } });
       return !r.error && r.status === 0;
     },
   };
+  return cli;
+}
+
+/** 同一台 Connelio 服务器的配对地址（已经接着 Connelio 时不必再开独立 profile） */
+export function isConnelioBase(baseUrl, server) {
+  if (!baseUrl) return false;
+  try {
+    const configured = new URL(baseUrl);
+    const target = new URL(server);
+    return configured.origin === target.origin && /\/tg\/bot\/?$/.test(configured.pathname);
+  } catch { return false; }
 }
 
 export function configureHermes({ hermes, server, token, ownerTelegramId }) {

package/src/i18n.mjs

@@ -0,0 +1,68 @@
+// 命令行文字：跟系统语言走（中文系统出中文，其余出英文）。只影响终端里的提示，不影响协议。
+export function detectLang(env = process.env, intlLocale) {
+  const raw = String(env.CONNELIO_LANG || env.LC_ALL || env.LC_MESSAGES || env.LANG || '').toLowerCase();
+  const tag = raw || String(intlLocale || (typeof Intl !== 'undefined' ? Intl.DateTimeFormat().resolvedOptions().locale : '') || 'en').toLowerCase();
+  if (tag.startsWith('zh')) return 'zh';
+  return 'en';
+}
+
+const COPY = {
+  zh: {
+    steps: { check: '检查 Hermes', prepare: '建配置', scan: '等手机扫码…', connected: '已连接', restart: '重启 Hermes' },
+    createProfile: '已为 Connelio 单独建了一个 Hermes 配置，原来的 Telegram 不受影响。',
+    reuseProfile: '这台电脑上已有 connelio 配置，接着用它，原来的 Telegram 不受影响。',
+    keepActive: '用的就是当前这个 Hermes 配置（--replace）。',
+    alreadyConnelio: '这个 Hermes 已经接着 Connelio，这次会换成新的配对。',
+    scanHint: '手机上打开 Connelio：消息 → 右上 + → 接入 Agent，扫上面的码。',
+    codeLabel: '配对码',
+    manualStart: 'Hermes 没在后台运行，手动启动一次：',
+    done: '好了，在手机 Connelio 里给它发条消息试试。',
+    errors: {
+      noHermes: { why: '这台电脑上没找到 Hermes。', next: '先安装 Hermes（https://hermes-agent.nousresearch.com），装好再跑一次。' },
+      profileHasBot: {
+        why: (name) => `配置 ${name} 已经接着一个 Telegram 机器人。`,
+        next: '想保留它：去掉 --hermes-profile，让 Connelio 自己建配置；确实要替换：加 --replace。',
+      },
+      profileFailed: { why: '新建 Hermes 配置失败。', next: '跑 hermes profile create connelio --clone 看具体报错，修好再重试。' },
+      'start-failed': { why: '连不上 Connelio 服务器。', next: '检查网络；换服务器用 --server https://…，然后重试。' },
+      declined: { why: '手机上取消了配对。', next: '想接的话再跑一次：npx connelio connect --hermes' },
+      expired: { why: '配对码过期了。', next: '再跑一次，重新出码。' },
+      claimed: { why: '这个配对码已经被用过了。', next: '再跑一次，重新出码。' },
+      cancelled: { why: '已取消。', next: '重新跑一次即可。' },
+      notSupported: { why: '这台服务器还没开配对功能。', next: '升级 Connelio 服务端，或用 --server 指向已开通的服务器。' },
+      network: { why: '和服务器通信中断了。', next: '网络恢复后再跑一次。' },
+      configWrite: { why: '写入 Hermes 配置失败。', next: '看上面那行报错；修好后重跑本命令。' },
+    },
+    retry: '再跑一次：npx connelio connect --hermes',
+  },
+  en: {
+    steps: { check: 'Checking Hermes', prepare: 'Preparing config', scan: 'Waiting for your phone…', connected: 'Connected', restart: 'Restarting Hermes' },
+    createProfile: 'Connelio got its own Hermes profile. Your existing Telegram bot is untouched.',
+    reuseProfile: 'Reusing the connelio profile on this computer. Your existing Telegram bot is untouched.',
+    keepActive: 'Using this Hermes profile (--replace).',
+    alreadyConnelio: 'This Hermes is already connected to Connelio — this run replaces the pairing.',
+    scanHint: 'On your phone open Connelio: Chats → + → Connect an Agent, then scan the code above.',
+    codeLabel: 'Pairing code',
+    manualStart: 'Hermes is not running in the background. Start it once:',
+    done: 'Done. Send it a message from Connelio on your phone.',
+    errors: {
+      noHermes: { why: 'Hermes was not found on this computer.', next: 'Install Hermes (https://hermes-agent.nousresearch.com), then run this again.' },
+      profileHasBot: {
+        why: (name) => `The ${name} profile already talks to a Telegram bot.`,
+        next: 'To keep it, drop --hermes-profile and let Connelio make its own profile; to replace it, add --replace.',
+      },
+      profileFailed: { why: 'Could not create the Hermes profile.', next: 'Run hermes profile create connelio --clone to see the error, fix it, then retry.' },
+      'start-failed': { why: 'Could not reach the Connelio server.', next: 'Check your network; use --server https://… for another server, then retry.' },
+      declined: { why: 'Pairing was declined on the phone.', next: 'Run it again when you want to connect: npx connelio connect --hermes' },
+      expired: { why: 'The pairing code expired.', next: 'Run it again for a fresh code.' },
+      claimed: { why: 'That pairing code was already used.', next: 'Run it again for a fresh code.' },
+      cancelled: { why: 'Cancelled.', next: 'Just run it again.' },
+      notSupported: { why: 'This server does not have pairing enabled.', next: 'Upgrade the Connelio server, or point --server at one that has it.' },
+      network: { why: 'Lost contact with the server.', next: 'Run it again when the network is back.' },
+      configWrite: { why: 'Writing the Hermes settings failed.', next: 'Read the error line above, fix it, then run this again.' },
+    },
+    retry: 'Run it again: npx connelio connect --hermes',
+  },
+};
+
+export const copy = (lang) => COPY[lang] || COPY.en;

package/src/pair.mjs

@@ -1,32 +1,60 @@
 // 设备码配对：终端出二维码 + 8 位码 → 手机确认 → 一次性领 token。
-import QRCode from 'qrcode';
 import { hostname } from 'node:os';
+import { fitsWide, renderQr } from './qr.mjs';
+import { copy as copyFor, detectLang } from './i18n.mjs';
 
-export async function pair({ server, kind, deviceName = prettyHost(), out = process.stdout, signal }) {
+export class PairError extends Error {
+  constructor(code, message) {
+    super(message || code);
+    this.code = code;
+  }
+}
+
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+const bold = (text) => `${BOLD}${text}${RESET}`;
+
+export async function pair({ server, kind, deviceName = prettyHost(), out = process.stdout, signal, lang = detectLang(), columns = out.columns, tty = out.isTTY }) {
+  const text = copyFor(lang);
   const base = server.replace(/\/+$/, '');
-  const started = await fetch(`${base}/api/agent-pair/start`, { method: 'POST', headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ deviceName, kind }), signal });
-  if (started.status === 404) throw new Error('This Connelio server does not have agent pairing enabled yet.');
-  if (!started.ok) throw new Error(`Pairing failed to start (HTTP ${started.status}).`);
+  let started;
+  try {
+    started = await fetch(`${base}/api/agent-pair/start`, { method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ deviceName, kind }), signal });
+  } catch (error) {
+    if (error?.name === 'AbortError') throw new PairError('cancelled');
+    throw new PairError('start-failed', error?.message);
+  }
+  if (started.status === 404) throw new PairError('notSupported');
+  if (!started.ok) throw new PairError('start-failed', `HTTP ${started.status}`);
   const pairing = await started.json();
-  const qr = await QRCode.toString(pairing.qr, { type: 'terminal', small: true, errorCorrectionLevel: 'M' });
-  out.write(`\n${qr}\n`);
-  out.write(`  Open Connelio on your phone → Chats → + → Connect an Agent\n`);
-  out.write(`  Scan the QR code above, or enter this code:  ${pairing.code}\n\n`);
-  out.write(`  在手机 Connelio 里：消息 → 右上 + → 接入 Agent，扫上面的码或输入配对码。\n\n`);
+
+  // 大码优先：每格两字符，放不进终端才退小码
+  const big = fitsWide(pairing.qr, columns);
+  out.write(`\n${renderQr(pairing.qr, { small: !big, indent: 2 })}\n\n`);
+  out.write(`  ${text.scanHint}\n\n`);
+  const strong = tty ? bold : (value) => value;
+  out.write(`  ${strong(text.codeLabel)}  ${strong(pairing.code)}\n\n`);
+
   const deadline = Date.now() + pairing.expiresInSeconds * 1000;
+  let dropped = 0;   // 连续连不上就别死等：网络断了要立刻说人话
   while (Date.now() < deadline) {
-    if (signal?.aborted) throw new Error('Pairing cancelled.');
+    if (signal?.aborted) throw new PairError('cancelled');
     const response = await fetch(`${base}/api/agent-pair/poll`, { method: 'POST', headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ pairingId: pairing.pairingId, pollSecret: pairing.pollSecret, timeout: 20 }), signal }).catch(() => null);
-    if (!response) { await sleep(2000); continue; }
+    if (!response) {
+      if (++dropped >= 3) throw new PairError('network');
+      await sleep(2000);
+      continue;
+    }
+    dropped = 0;
     const result = await response.json().catch(() => ({}));
     if (result.status === 'approved') return result;
-    if (result.status === 'denied') throw new Error('Pairing was declined on the phone.');
-    if (result.status === 'expired' || response.status === 404) throw new Error('The pairing code expired. Run the command again.');
-    if (result.status === 'claimed') throw new Error('This pairing was already used.');
+    if (result.status === 'denied') throw new PairError('declined');
+    if (result.status === 'expired' || response.status === 404) throw new PairError('expired');
+    if (result.status === 'claimed') throw new PairError('claimed');
   }
-  throw new Error('The pairing code expired. Run the command again.');
+  throw new PairError('expired');
 }
 
 function prettyHost() {

package/src/progress.mjs

@@ -0,0 +1,52 @@
+// 每一步一行：终端里先显示「… 这一步」，做完原地变成「✓ 这一步」；
+// 输出被重定向到文件时只留结果行，日志照样看得懂。
+export function createProgress(out = process.stdout, { tty = Boolean(out.isTTY) } = {}) {
+  let open = false;
+  const close = () => { if (open) { if (tty) out.write('\r\x1b[2K'); open = false; } };
+  return {
+    starts: () => tty,
+    /** 开始一步（可打印「…」），fn 返回后收尾成 ✓；fn 抛错就只写 ✗ 交给调用方 */
+    async step(label, fn) {
+      if (tty) { close(); out.write(`  … ${label}`); open = true; }
+      try {
+        const value = await fn();
+        close();
+        out.write(`  ✓ ${label}\n`);
+        return value;
+      } catch (error) {
+        close();
+        throw error;
+      }
+    },
+    /** 耗时又不确定多久的一步：先把「…」打出来（重定向到日志也打），做完再收尾 */
+    begin(label) {
+      close();
+      out.write(`  … ${label}\n`);
+    },
+    /** 长时间等待（等手机扫码）：这行要一直留着 */
+    waiting(label) {
+      close();
+      if (tty) { out.write(`  … ${label}`); open = true; } else out.write(`  … ${label}\n`);
+    },
+    ok(label) {
+      close();
+      out.write(`  ✓ ${label}\n`);
+    },
+    fail(label, why, next) {
+      close();
+      out.write(`  ✗ ${label}\n`);
+      if (why) out.write(`    ${why}\n`);
+      if (next) out.write(`    → ${next}\n`);
+    },
+    warn(label, next) {
+      close();
+      out.write(`  ! ${label}\n`);
+      if (next) out.write(`    → ${next}\n`);
+    },
+    note(line) {
+      close();
+      if (line) out.write(`    ${line}\n`);
+    },
+    blank() { close(); out.write('\n'); },
+  };
+}

package/src/qr.mjs

@@ -0,0 +1,46 @@
+// 终端二维码：每格两字符（大码，手机好扫），四周留白两格；终端太窄才退回半高小码。
+// 自己按矩阵画，不依赖 ANSI 背景色 —— 复制粘贴到别处也不会变成乱码。
+import QRCode from 'qrcode';
+
+export const MARGIN = 2;
+
+function matrixOf(text, errorCorrectionLevel) {
+  const { modules } = QRCode.create(text, { errorCorrectionLevel });
+  return { size: modules.size, dark: (x, y) => x >= 0 && y >= 0 && x < modules.size && y < modules.size && Boolean(modules.get(x, y)) };
+}
+
+/** 大码宽度（含留白），用于判断终端放不放得下 */
+export function wideWidth(text, { margin = MARGIN, errorCorrectionLevel = 'M' } = {}) {
+  return (matrixOf(text, errorCorrectionLevel).size + margin * 2) * 2;
+}
+
+/** 窄终端用：一格一字符、两行并一行（半块字符），宽度减半 */
+export function fitsWide(text, columns, options) {
+  return !columns || wideWidth(text, options) <= columns;
+}
+
+export function renderQr(text, { small = false, margin = MARGIN, errorCorrectionLevel = 'M', indent = 0 } = {}) {
+  const { size, dark } = matrixOf(text, errorCorrectionLevel);
+  const pad = ' '.repeat(indent);
+  const lines = [];
+  const from = -margin;
+  const to = size + margin;
+  if (!small) {
+    for (let y = from; y < to; y++) {
+      let line = '';
+      for (let x = from; x < to; x++) line += dark(x, y) ? '██' : '  ';
+      lines.push(pad + line);
+    }
+    return lines.join('\n');
+  }
+  for (let y = from; y < to; y += 2) {
+    let line = '';
+    for (let x = from; x < to; x++) {
+      const top = dark(x, y);
+      const bottom = dark(x, y + 1);
+      line += top && bottom ? '█' : top ? '▀' : bottom ? '▄' : ' ';
+    }
+    lines.push(pad + line);
+  }
+  return lines.join('\n');
+}