ultrastiching-cli 0.2.0 → 0.2.2

package/README.md

@@ -16,22 +16,22 @@ ultrastiching auth configure
 # 主动替换 Key，需确认：ultrastiching auth configure --replace
 ```
 
-`auth status` 只输出是否配置及来源。`auth sync` 由安装器自动调用：环境变量没有值时，从已有凭据文件同步到当前进程和持久环境。`auth configure` 已有 Key 时不重复输入；缺失时在本机终端隐藏输入一次，同时保存私有文件和持久环境。`--replace` 确认一次后更换两处的 Key。macOS 更新 Shell、launchd 环境和登录恢复任务；Windows 更新用户环境；Linux 更新 Shell 和用户 environment.d，有会话总线时同步服务启动环境。含 Key 的 POSIX 配置使用 0600，Windows 凭据文件使用私有 ACL。保存后完全退出并重启客户端。不要在 Agent 对话中填写 Key。`ultrastiching mcp headers` 只供 MCP 客户端调用，stdout 含鉴权头，Agent 不应执行或打印该命令的输出。
+`auth status` 只输出是否配置及来源。`auth sync` 由安装器自动调用：环境变量没有值时，从已有凭据文件同步到当前进程和持久环境。`auth configure` 已有 Key 时不重复输入；缺失时在本机终端隐藏输入一次，同时保存私有文件和持久环境。`--replace` 确认一次后更换两处的 Key。macOS 确认 zsh 后只写 `.zshrc`（遵循用户已有的 `ZDOTDIR`），确认 bash 后只写 `.bashrc`，并同步当前用户会话环境，不创建登录启动项；无法确定 Shell 或配置目录时提示用户自行确认，不猜测文件位置。Windows 更新用户环境；Linux 使用相同的 Shell 默认规则并更新用户 environment.d，有会话总线时同步服务启动环境。含 Key 的 POSIX 配置使用 0600，Windows 凭据文件使用私有 ACL。保存后完全退出并重启客户端。macOS 注销或重启电脑后，若桌面启动的客户端缺少变量，在登录终端运行 `ultrastiching auth sync --from-file` 再重新打开客户端即可，无需重新输入 Key。不要在 Agent 对话中填写 Key。`ultrastiching mcp headers` 只供 MCP 客户端调用，stdout 含鉴权头，Agent 不应执行或打印该命令的输出。
 
-本版为 0.2.0，支持共享凭据配置和安装器自动同步。
+本版为 0.2.1，支持共享凭据配置和安装器自动同步；输入 API Key 时回显星号，退格同步擦除，实际 Key 不回显。
 
 ## 安装与离线发现
 
 从 npm 安装指定版本：
 
 ```bash
-npm install -g ultrastiching-cli@0.2.0
+npm install -g ultrastiching-cli@0.2.1
 ultrastiching --help
 ultrastiching list --search 交易日历
 ultrastiching info plasma_trade_cal
 ```
 
-`list` 和 `info` 使用随包携带的目录，不需要 API Key，不发送业务请求。也可安装维护者提供的包：`npm install -g ./ultrastiching-cli-0.2.0.tgz`。源码环境使用下面的安装方式：
+`list` 和 `info` 使用随包携带的目录，不需要 API Key，不发送业务请求。也可安装维护者提供的包：`npm install -g ./ultrastiching-cli-0.2.1.tgz`。源码环境使用下面的安装方式：
 
 ```bash
 cd meridian-cli

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultrastiching-cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "UltraStiching data API command line client",
   "type": "module",
   "bin": {

package/src/auth.js

@@ -33,14 +33,14 @@ export async function configureCredential({
 } = {}) {
   const current = configuredCredential(env, home);
   if (current.key && !replace) {
-    log('已配置 API Key，直接复用，无需再次输入。');
-    return syncCredentialEnvironment({ env, home, log, environmentOptions });
+    const result = syncCredentialEnvironment({ env, home, log: () => {}, environmentOptions });
+    log('已成功设置 Ultrastiching 的 API Key');
+    return result;
   }
   const file = readCredentialFile(home);
   const target = credentialsPath(home);
   const expected = inspectEnvironment({ ...environmentOptions, env, home });
-  if (current.key && !await confirm(`将替换现有 API Key，同时更新 ${target} 和用户持久环境中的 ${ENV_KEY}，是否继续？`)) return { configured: true, source: current.source, cancelled: true };
-  log(`API Key 将明文保存在本机私有文件 ${target} 和用户持久环境配置；不要粘贴到 Agent 对话中。`);
+  if (current.key && !await confirm('将替换现有的 Ultrastiching API Key，是否继续？')) return { configured: true, source: current.source, cancelled: true };
   const key = await readKey();
   saveCredential(key, { home, expectedDigest: file?.digest });
   let result;
@@ -51,7 +51,7 @@ export async function configureCredential({
     error.message = `凭据文件已保存，但环境同步未完成；修复下述错误后重新运行 ultrastiching auth sync --from-file，无需重新输入 Key。${error.message}`;
     throw error;
   }
-  log('API Key 已同步保存到凭据文件和持久环境；请完全退出并重启客户端。');
+  log('已成功设置 Ultrastiching 的 API Key');
   return { ...credentialStatus({ env, home }), ...result };
 }
 

package/src/environment.js

@@ -9,7 +9,20 @@ const START = '# >>> UltraStiching environment >>>';
 const END = '# <<< UltraStiching environment <<<';
 const digest = content => createHash('sha256').update(content).digest('hex');
 const quote = value => "'" + value.replaceAll("'", "'\\''") + "'";
-const xml = value => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+
+/** 需要用户确认配置入口；命令显示简短提示，调用方仍能取得判断失败的原因。 */
+export class ShellConfigurationError extends Error {
+  constructor(code, details) {
+    super('无法确定 Shell 配置文件，请自行确认后设置环境变量。');
+    this.name = 'ShellConfigurationError';
+    this.code = code;
+    this.details = details;
+  }
+
+  toDiagnostic() {
+    return { type: this.name, code: this.code, message: this.message, details: this.details };
+  }
+}
 
 /** 只接受当前用户拥有的普通配置文件；读取用于保留原文和复核并发修改，不执行内容。 */
 function snapshot(path) {
@@ -49,20 +62,17 @@ function shellContent(content, key) {
 export function inspectEnvironment({ home = homedir(), platform = process.platform, env = process.env } = {}) {
   if (platform === 'win32') return [];
   if (!['darwin', 'linux'].includes(platform)) throw new Error(`暂不支持 ${platform} 的环境变量持久化。`);
-  const shell = (env.SHELL ?? '').split('/').at(-1) || (platform === 'darwin' ? 'zsh' : 'bash');
-  if (!['bash', 'zsh', 'sh', 'dash'].includes(shell)) throw new Error(`暂不支持 ${shell} 的启动文件，请先确认该 Shell 的持久化方式。`);
-  const paths = [join(home, '.profile')];
-  if (shell === 'zsh') paths.push(join(env.ZDOTDIR && isAbsolute(env.ZDOTDIR) ? env.ZDOTDIR : home, '.zshrc'), join(env.ZDOTDIR && isAbsolute(env.ZDOTDIR) ? env.ZDOTDIR : home, '.zprofile'));
-  if (shell === 'bash') {
-    paths.push(join(home, '.bashrc'));
-    // Bash 只加载第一个存在的登录文件；不创建优先级更高的新文件来遮住用户原配置。
-    for (const name of ['.bash_profile', '.bash_login']) {
-      try { lstatSync(join(home, name)); paths.push(join(home, name)); break; }
-      catch (error) { if (error.code !== 'ENOENT') throw error; }
-    }
+  const shell = (env.SHELL ?? '').split('/').at(-1);
+  if (!['bash', 'zsh'].includes(shell)) {
+    throw new ShellConfigurationError(shell ? 'shell_unsupported' : 'shell_unknown', { shell: env.SHELL ?? null });
+  }
+  let directory = home;
+  if (shell === 'zsh' && env.ZDOTDIR !== undefined) {
+    if (!isAbsolute(env.ZDOTDIR)) throw new ShellConfigurationError('shell_directory_unknown', { shell: env.SHELL, directory: env.ZDOTDIR });
+    directory = env.ZDOTDIR;
   }
-  if (platform === 'darwin') paths.push(join(home, 'Library', 'LaunchAgents', 'com.ultrastiching.environment.plist'));
-  else paths.push(join(env.XDG_CONFIG_HOME && isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : join(home, '.config'), 'environment.d', '90-ultrastiching.conf'));
+  const paths = [join(directory, shell === 'zsh' ? '.zshrc' : '.bashrc')];
+  if (platform === 'linux') paths.push(join(env.XDG_CONFIG_HOME && isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : join(home, '.config'), 'environment.d', '90-ultrastiching.conf'));
   return [...new Set(paths)].map(snapshot);
 }
 
@@ -79,7 +89,7 @@ function nativeCommand(command, args, key, options, execute) {
   }
 }
 
-/** 更新系统启动环境与本进程；已运行的客户端需重启才能继承新值。 */
+/** 更新当前用户会话与本进程的环境；已运行的客户端需重启才能继承新值。 */
 export function updateSessionEnvironment(key, { platform = process.platform, env = process.env, execute = execFileSync } = {}) {
   requireKey(key);
   const next = { ...env, [ENV_KEY]: key };
@@ -94,7 +104,7 @@ export function updateSessionEnvironment(key, { platform = process.platform, env
   env[ENV_KEY] = key;
 }
 
-/** 保存 Shell 与系统持久环境，macOS 登录任务只调用原生 setenv，不转接 MCP。 */
+/** 保存一个 Shell 交互配置；macOS 只同步当前会话，不创建登录任务。 */
 export function persistEnvironment(key, {
   home = homedir(), platform = process.platform, env = process.env, execute = execFileSync,
   expected = inspectEnvironment({ home, platform, env }),
@@ -102,10 +112,7 @@ export function persistEnvironment(key, {
   requireKey(key);
   const prepared = expected.map(entry => {
     let content;
-    if (entry.path.endsWith('.plist')) {
-      const args = ['/bin/launchctl', 'setenv', ENV_KEY, key].map(value => `    <string>${xml(value)}</string>`).join('\n');
-      content = `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n  <key>Label</key><string>com.ultrastiching.environment</string>\n  <key>ProgramArguments</key><array>\n${args}\n  </array>\n  <key>RunAtLoad</key><true/>\n</dict></plist>\n`;
-    } else if (entry.path.endsWith('.conf')) {
+    if (entry.path.endsWith('.conf')) {
       // systemd environment.d 用 $$ 表示字面美元符号；其他字符按双引号规则转义。
       const value = key.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('`', '\\`').replaceAll('$', () => '$$');
       content = `${ENV_KEY}="${value}"\n`;

package/src/main.js

@@ -6,6 +6,7 @@ import { callByName, redactKey } from './http.js';
 import { buildPayload, endpoint, loadRegistry, parseParameter, searchEndpoints } from './registry.js';
 import { streamNewsflash } from './websocket.js';
 import { credentialStatus, configureCredential, syncCredentialEnvironment, mcpHeaders } from './auth.js';
+import { ShellConfigurationError } from './environment.js';
 import { readFileSync } from 'node:fs';
 
 const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
@@ -84,12 +85,19 @@ export async function main(argv, { write = (line) => process.stdout.write(line),
   if (command === 'auth') {
     if (positional.length !== 2) throw new Error('Use ultrastiching auth status|sync|configure');
     assertFlags(flags, new Set(name === 'configure' ? ['replace', 'compact'] : name === 'sync' ? ['from_file', 'compact'] : ['compact']));
-    if (name === 'configure') {
-      if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error('请在交互式终端运行 ultrastiching auth configure；Key 不能从参数或管道传入。');
-      emit(write, await configureCredential({ replace: !!flags.replace }), flags.compact);
-    } else if (name === 'status') emit(write, credentialStatus(), flags.compact);
-    else if (name === 'sync') emit(write, syncCredentialEnvironment({ fromFile: !!flags.from_file }), flags.compact);
-    else throw new Error('Use ultrastiching auth status|sync|configure');
+    try {
+      if (name === 'configure') {
+        if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error('请在交互式终端运行 ultrastiching auth configure；Key 不能从参数或管道传入。');
+        const result = await configureCredential({ replace: !!flags.replace, log: line => write(`${line}\n`) });
+        if (result.cancelled) write('已取消，未修改 API Key。\n');
+      } else if (name === 'status') emit(write, credentialStatus(), flags.compact);
+      else if (name === 'sync') emit(write, syncCredentialEnvironment({ fromFile: !!flags.from_file }), flags.compact);
+      else throw new Error('Use ultrastiching auth status|sync|configure');
+    } catch (error) {
+      if (!(error instanceof ShellConfigurationError)) throw error;
+      write(`${error.message}\n`);
+      return { exitCode: 1 };
+    }
     return;
   }
   if (command === 'mcp') {

package/src/prompt.js

@@ -1,6 +1,9 @@
 import { emitKeypressEvents } from "node:readline";
 
-/** 本机输入隐藏 Key；取消时恢复终端状态，凭据不进入参数或 Shell 历史。 */
+/**
+ * 本机输入 Key 时仅回显星号，让输入和粘贴都有可见反馈，退格同步擦除一个星号。
+ * 确认或取消时移除输入监听并恢复终端状态；真实凭据不回显，也不进入参数或 Shell 历史。
+ */
 export function hiddenKey(input = process.stdin, output = process.stdout) {
   emitKeypressEvents(input);
   const previousRaw = input.isRaw;
@@ -15,11 +18,17 @@ export function hiddenKey(input = process.stdin, output = process.stdout) {
     const onKey = (text, key = {}) => {
       if (key.ctrl && key.name === "c") return finish(new Error("已取消，未保存。"));
       if (key.name === "return" || key.name === "enter") return finish();
-      if (key.name === "backspace") value = Array.from(value).slice(0, -1).join("");
-      else if (text && !key.ctrl && !key.meta && !/[\x00-\x1f\x7f]/u.test(text)) value += text;
+      if (key.name === "backspace") {
+        if (!value) return;
+        value = Array.from(value).slice(0, -1).join("");
+        output.write("\b \b");
+      } else if (text && !key.ctrl && !key.meta && !/[\x00-\x1f\x7f]/u.test(text)) {
+        value += text;
+        output.write("*".repeat(Array.from(text).length));
+      }
     };
     input.on("keypress", onKey);
-    output.write("粘贴 ultrastiching 数据 API Key（输入隐藏，Enter 确认，Ctrl+C 取消）：");
+    output.write("请粘贴 Ultrastiching 的 API Key（Enter 确认，Ctrl+C 取消）");
   });
 }