@tedbrain/vlink 0.1.63 → 0.1.64

package/README.md

@@ -37,6 +37,29 @@ npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest --versio
 
 安装命令会输出安装目标、权限回退原因及 setup 状态；失败时输出错误并返回非零退出码。
 
+需要排查安装过程时，加上 `--verbose`：
+
+```bash
+npx --registry=https://registry.npmmirror.com -y \
+  @tedbrain/vlink@latest install --verbose
+```
+
+verbose 会从 npm 包的 JavaScript wrapper 开始输出 Node、包版本、平台选择、PATH
+查找、权限检查、二进制缓存或下载、复制、补全和 setup 各阶段。也可以设置
+`VLINK_VERBOSE=1`。日志不会打印完整环境变量、registry 凭据或下载 URL 的查询参数。
+
+如果上面的命令连 `[TedBrain:verbose] wrapper entered` 都没有输出，使用 npm 的显式
+package 形式，绕过 npx 的命令推断：
+
+```bash
+npm exec --registry=https://registry.npmmirror.com \
+  --package=@tedbrain/vlink@latest -- \
+  vlink install --verbose
+```
+
+若显式形式可以输出，问题发生在本机 npx 的参数路由或缓存阶段；若仍无 wrapper
+输出，可再加 npm 自身的 `--loglevel verbose` 检查 npm 在执行包之前的行为。
+
 手动配置 Agent 时可以只安装或更新 vlink，并跳过 TedBrain 配置向导：
 
 ```bash

package/bin/vlink.js

@@ -2,12 +2,45 @@
 'use strict';
 
 const { spawn } = require('child_process');
-const { ensureBinary } = require('../install');
-const { runInstallerFromArgs } = require('../installer');
+
+function verboseEnabled(args, env = process.env) {
+  const value = String(env.VLINK_VERBOSE || '').toLowerCase();
+  return args[0] === 'install' && (
+    args.includes('--verbose') || ['1', 'true', 'yes', 'on'].includes(value)
+  );
+}
+
+function verbose(message) {
+  process.stderr.write(`[TedBrain:verbose] ${message}\n`);
+}
+
+function diagnosticArgs(args) {
+  const safe = new Set(['install', '--verbose', '--no-setup', '--help', '-h']);
+  return args.map((arg) => {
+    if (safe.has(arg)) return arg;
+    if (arg.startsWith('--')) return arg.split('=', 1)[0];
+    return '<argument>';
+  });
+}
 
 async function main() {
   const args = process.argv.slice(2);
+  const diagnostic = verboseEnabled(args);
+  if (diagnostic) {
+    process.env.VLINK_VERBOSE = '1';
+    verbose('wrapper entered');
+    verbose(`node=${process.version} executable=${process.execPath}`);
+    verbose(`wrapper=${__filename}`);
+    verbose(`cwd=${process.cwd()}`);
+    verbose(`argv=${JSON.stringify(diagnosticArgs(args))}`);
+  }
+
+  const { ensureBinary, VERSION } = require('../install');
+  const { runInstallerFromArgs } = require('../installer');
+  if (diagnostic) verbose(`package version=${VERSION}`);
+
   if (args[0] === 'install') {
+    if (diagnostic) verbose('dispatching install command');
     await runInstallerFromArgs(args.slice(1));
     return;
   }

package/binaries.json

@@ -1,12 +1,12 @@
 {
-  "version": "0.1.63",
+  "version": "0.1.64",
   "binaries": {
-    "linux-x86_64": "dffb9115be72e1b1546e5d5adc9a208de7ac869f89cfc1692edb8ef60a05e8d1",
-    "linux-x86_64-glibc2.17": "0acfdaec9e600817d55a389b9889c476dbfa9842768c9e431ef3c44df7e0fa5a",
-    "linux-aarch64": "f8a3a086cf963db72d380e410c5264dc25659c44f3770597bc36d3021bf2376c",
-    "macos-x86_64": "bc917cf21d802dc804acdcbd06eb769cd520a12475b25db9e8238036db7383ed",
-    "macos-aarch64": "14b831e1f7ff7b09def2efc34e74d0a05d437cd1650c1c6f3c254cd08fc48b64",
-    "windows-x86_64.exe": "c9ca055f7791b095f8cc958ffa0fab4d01eb0fa9b36801e25a51982ceeaf30fd",
-    "windows-aarch64.exe": "717d470b48a10b1a16d897e56738447b3b7d6128cf02ea8f428e481117e80cd4"
+    "linux-x86_64": "cd46ed189a1cb56a4d2ff84af7cda6a4870ad202f6172500e02a29654cb82b54",
+    "linux-x86_64-glibc2.17": "d578c70bafe98de520b25e78ea10919a12cb14fff0524ab3339bb0d912a78961",
+    "linux-aarch64": "8acbcce5bd84e14652f778ab987abe2a9f461b3ba4bb0dbe4022f8900a42868e",
+    "macos-x86_64": "5e96d897d75dc02a0e8acca05bfb8a5910751d38b10de0eda9f1c0ae9ac6df13",
+    "macos-aarch64": "8481807cd40cac885908550959e259164eaf9d2a20f10e2972c57a5f3e125815",
+    "windows-x86_64.exe": "90a2a090f993bc6258ccddacf62aa05d99d96b411a39a041cf2e6f19c6f8fd69",
+    "windows-aarch64.exe": "e96d0dcbfde313747a62cb7b5f945cfdf444927f40e758f25ed06da6c0d517b6"
   }
 }

package/install.js

@@ -26,6 +26,31 @@ const GLIBC217_SUFFIX = 'linux-x86_64-glibc2.17';
 
 class VlinkInstallError extends Error {}
 
+function verboseEnabled(options = {}) {
+  if (options.verbose === true) return true;
+  return ['1', 'true', 'yes', 'on'].includes(
+    String(process.env.VLINK_VERBOSE || '').toLowerCase()
+  );
+}
+
+function verboseLog(message, options = {}) {
+  if (!verboseEnabled(options)) return;
+  (options.output || process.stderr).write(`[vlink:verbose] ${message}\n`);
+}
+
+function displayUrl(value) {
+  try {
+    const url = new URL(value);
+    url.username = '';
+    url.password = '';
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+  } catch {
+    return '<invalid-url>';
+  }
+}
+
 function parseGlibcVersion(text) {
   for (const line of String(text || '').split(/\r?\n/)) {
     const glibcMatch = line.match(/\bglibc\s+([0-9]+(?:\.[0-9]+)+)/);
@@ -137,7 +162,7 @@ function httpGetText(url) {
           if (res.statusCode !== 200) {
             res.resume();
             return reject(
-              new VlinkInstallError(`HTTP ${res.statusCode} from ${target}`)
+              new VlinkInstallError(`HTTP ${res.statusCode} from ${displayUrl(target)}`)
             );
           }
 
@@ -308,7 +333,9 @@ function downloadFile(url, destPath) {
           if (res.statusCode !== 200) {
             res.resume();
             return reject(
-              new VlinkInstallError(`download failed: HTTP ${res.statusCode} from ${target}`)
+              new VlinkInstallError(
+                `download failed: HTTP ${res.statusCode} from ${displayUrl(target)}`
+              )
             );
           }
           res.pipe(fileStream);
@@ -339,14 +366,23 @@ function verifyBinary(binaryPath) {
   }
 }
 
-async function ensureBinary({ force = false } = {}) {
+async function ensureBinary(options = {}) {
+  const force = options.force === true;
   const spec = platformSpec();
   const binaryPath = resolveBinaryPath(spec);
+  verboseLog(
+    `binary resolver: version=${VERSION} platform=${spec.platform}/${spec.arch} ` +
+      `suffixes=${spec.suffixes.join(',')}`,
+    options
+  );
+  verboseLog(`binary resolver: selected path=${binaryPath} force=${force}`, options);
   if (!force && isExecutable(binaryPath)) {
+    verboseLog('binary resolver: using existing executable', options);
     return binaryPath;
   }
 
   const dir = path.dirname(binaryPath);
+  verboseLog(`binary resolver: creating download directory ${dir}`, options);
   fs.mkdirSync(dir, { recursive: true });
 
   let lastError = new VlinkInstallError('no download source available');
@@ -354,15 +390,22 @@ async function ensureBinary({ force = false } = {}) {
   for (const suffix of spec.suffixes) {
     const tempPath = path.join(dir, `.${spec.binaryName}.download-${process.pid}`);
     const sources = buildDownloadSources(spec, suffix);
+    verboseLog(
+      `download stage: suffix=${suffix} sources=${sources.map((source) => source.name).join(',')}`,
+      options
+    );
     for (const source of sources) {
       try {
+        verboseLog(`download stage: resolving ${source.name}`, options);
         const url = await source.resolve();
-        console.error(`[vlink] downloading ${url} [${source.name}]`);
+        console.error(`[vlink] downloading ${displayUrl(url)} [${source.name}]`);
         fs.rmSync(tempPath, { force: true });
         await downloadFile(url, tempPath);
+        verboseLog(`download stage: received ${source.name} payload`, options);
 
         const checksum = expectedChecksum(spec, suffix);
         if (checksum) {
+          verboseLog(`verification stage: checking SHA-256 for ${suffix}`, options);
           const actual = await sha256File(tempPath);
           if (actual !== checksum) {
             throw new VlinkInstallError(
@@ -376,7 +419,9 @@ async function ensureBinary({ force = false } = {}) {
         }
         if (fs.existsSync(binaryPath)) fs.rmSync(binaryPath, { force: true });
         fs.renameSync(tempPath, binaryPath);
+        verboseLog(`verification stage: executing ${binaryPath} -V`, options);
         verifyBinary(binaryPath);
+        verboseLog('verification stage: binary is ready', options);
         return binaryPath;
       } catch (err) {
         lastError = err;
@@ -393,6 +438,8 @@ module.exports = {
   VlinkInstallError,
   VERSION,
   GLIBC217_SUFFIX,
+  verboseEnabled,
+  displayUrl,
   parseGlibcVersion,
   glibcVersion,
   versionAtLeast,

package/installer.js

@@ -18,6 +18,20 @@ function log(message, output = process.stderr) {
   output.write(`[TedBrain] ${message}\n`);
 }
 
+function verboseEnabled(options = {}) {
+  if (options.verbose === true) return true;
+  const env = options.env || process.env;
+  return ['1', 'true', 'yes', 'on'].includes(
+    String(env.VLINK_VERBOSE || '').toLowerCase()
+  );
+}
+
+function verboseLog(message, options = {}) {
+  if (!verboseEnabled(options)) return;
+  const output = options.output || process.stderr;
+  output.write(`[TedBrain:verbose] ${message}\n`);
+}
+
 function environmentValue(env, name) {
   const expected = name.toLowerCase();
   for (const key of Object.keys(env)) {
@@ -170,6 +184,7 @@ function ensureUserPath(installDir, options = {}) {
   const fsImpl = options.fs || fs;
   const output = options.output || process.stderr;
 
+  verboseLog(`PATH stage: prioritizing ${installDir}`, options);
   prependEnvironmentPath(installDir, env, platform);
 
   if (platform === 'win32') {
@@ -291,7 +306,11 @@ function installBinary(sourcePath, targetPath, options = {}) {
   const spawnSyncImpl = options.spawnSync || spawnSync;
   const output = options.output || process.stderr;
 
-  if (samePath(sourcePath, targetPath, platform)) return targetPath;
+  if (samePath(sourcePath, targetPath, platform)) {
+    verboseLog(`copy stage: source already equals target ${targetPath}`, options);
+    return targetPath;
+  }
+  verboseLog(`copy stage: ${sourcePath} -> ${targetPath}`, options);
   fsImpl.mkdirSync(path.dirname(targetPath), { recursive: true });
 
   if (options.stopDaemon) {
@@ -365,6 +384,7 @@ function installWindowsCommandShim(vlinkPath, options = {}) {
 function installShellCompletion(vlinkPath, options = {}) {
   const spawnSyncImpl = options.spawnSync || spawnSync;
   const output = options.output || process.stderr;
+  verboseLog(`completion stage: executing ${vlinkPath}`, options);
   const result = spawnSyncImpl(
     vlinkPath,
     ['completion', '--install', '--quiet'],
@@ -400,7 +420,11 @@ async function migrateStaticVlink(vlinkPath, spec, options) {
   if (!binaryIsStaticElf(vlinkPath, options)) return vlinkPath;
 
   log('migrating the installed static vlink to the glibc 2.17 build', options.output);
-  const sourcePath = await options.ensureBinary({ force: true });
+  const sourcePath = await options.ensureBinary({
+    force: true,
+    verbose: verboseEnabled(options),
+    output: options.output
+  });
   return installBinary(sourcePath, vlinkPath, {
     ...options,
     stopDaemon: true
@@ -412,6 +436,7 @@ async function runInstaller(options = {}) {
   const platform = options.platform || env.VLINK_PLATFORM || process.platform;
   const arch = options.arch || env.VLINK_ARCH || process.arch;
   const skipSetup = Boolean(options.skipSetup);
+  const verbose = verboseEnabled(options);
   const home = options.home || os.homedir();
   const fsImpl = options.fs || fs;
   const output = options.output || process.stderr;
@@ -420,6 +445,17 @@ async function runInstaller(options = {}) {
   const ensureBinary =
     options.ensureBinary || ((settings) => installModule.ensureBinary(settings));
 
+  verboseLog(
+    `installer entered: package=${installModule.VERSION} platform=${platform} arch=${arch}`,
+    { ...options, env, output, verbose }
+  );
+  verboseLog(`runtime: node=${process.version} executable=${process.execPath}`, {
+    ...options,
+    env,
+    output,
+    verbose
+  });
+
   const spec = platformSpec({
     platform,
     arch,
@@ -437,14 +473,32 @@ async function runInstaller(options = {}) {
     home,
     fs: fsImpl,
     output,
-    spawnSync: spawnSyncImpl
+    spawnSync: spawnSyncImpl,
+    verbose
   };
 
+  verboseLog(
+    `platform stage: suffixes=${spec.suffixes.join(',')} binary=${spec.binaryName}`,
+    sharedOptions
+  );
+  verboseLog(
+    `target stage: installDir=${installDir} configured=${Boolean(env.VLINK_INSTALL_DIR)}`,
+    sharedOptions
+  );
+  const pathEntries = String(environmentValue(env, 'PATH'))
+    .split(platform === 'win32' ? ';' : path.delimiter)
+    .filter(Boolean).length;
+  verboseLog(`PATH stage: inspecting ${pathEntries} entries`, sharedOptions);
+
   let vlinkPath = findOnPath(spec.binaryName, {
     env,
     platform,
     fs: fsImpl
   });
+  verboseLog(
+    `discovery stage: native PATH binary=${vlinkPath || 'none'}`,
+    sharedOptions
+  );
 
   if (vlinkPath) {
     log(
@@ -465,9 +519,11 @@ async function runInstaller(options = {}) {
   let installTarget = env.VLINK_INSTALL_DIR ? targetPath : (vlinkPath || targetPath);
   // Avoid trying to replace a shared installation, even if its parent is writable.
   if (vlinkPath && !env.VLINK_INSTALL_DIR && !samePath(vlinkPath, targetPath, platform)) {
+    verboseLog(`permission stage: checking ${vlinkPath} and its parent directory`, sharedOptions);
     try {
       fsImpl.accessSync(vlinkPath, fs.constants.W_OK);
       fsImpl.accessSync(path.dirname(vlinkPath), fs.constants.W_OK);
+      verboseLog('permission stage: existing installation is replaceable', sharedOptions);
     } catch (error) {
       if (!PERMISSION_ERRORS.has(error.code)) throw error;
       log(`cannot replace ${vlinkPath} (${error.code}); falling back to ${targetPath}`, output);
@@ -476,7 +532,9 @@ async function runInstaller(options = {}) {
   }
   installTarget = path.resolve(installTarget);
   log(`installation target: ${installTarget}`, output);
-  const sourcePath = await ensureBinary({});
+  verboseLog('binary stage: resolving packaged or cached binary', sharedOptions);
+  const sourcePath = await ensureBinary({ verbose, output });
+  verboseLog(`binary stage: source=${sourcePath}`, sharedOptions);
   try {
     installBinary(sourcePath, installTarget, {
       ...sharedOptions,
@@ -500,18 +558,24 @@ async function runInstaller(options = {}) {
     ensureBinary
   });
   const commandShimPath = installWindowsCommandShim(vlinkPath, sharedOptions);
+  verboseLog(
+    `shim stage: ${commandShimPath || 'not required on this platform'}`,
+    sharedOptions
+  );
   installShellCompletion(vlinkPath, sharedOptions);
 
   if (skipSetup) {
     log('skipping TedBrain Agent setup', output);
   } else {
     log('starting TedBrain Agent setup', output);
+    verboseLog(`setup stage: executing ${vlinkPath} setup tedbrain`, sharedOptions);
     const setup = spawnSyncImpl(vlinkPath, ['setup', 'tedbrain'], {
       env,
       stdio: 'inherit'
     });
     const failure = commandFailure(setup, 'vlink setup tedbrain');
     if (failure) throw new VlinkSetupError(failure);
+    verboseLog('setup stage: completed successfully', sharedOptions);
   }
 
   log(`installation complete: ${vlinkPath}`, output);
@@ -522,11 +586,12 @@ async function runInstaller(options = {}) {
 function printInstallHelp(output = process.stdout) {
   output.write(
     [
-      'Usage: npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest install [--no-setup]',
+      'Usage: npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest install [--no-setup] [--verbose]',
       '',
       'Installs or updates vlink and adds it to the user PATH.',
       '',
-      '  --no-setup  Install without starting the TedBrain setup wizard.'
+      '  --no-setup  Install without starting the TedBrain setup wizard.',
+      '  --verbose   Print diagnostics for every installation stage.'
     ].join('\n') + '\n'
   );
 }
@@ -538,18 +603,23 @@ async function runInstallerFromArgs(args, options = {}) {
   }
 
   let skipSetup = false;
+  let verbose = verboseEnabled(options);
   for (const arg of args) {
     if (arg === '--no-setup') {
       skipSetup = true;
+    } else if (arg === '--verbose') {
+      verbose = true;
     } else {
-      throw new VlinkSetupError(`unknown install option: ${arg}`);
+      const displayArg = arg.startsWith('--') ? arg.split('=', 1)[0] : '<argument>';
+      throw new VlinkSetupError(`unknown install option: ${displayArg}`);
     }
   }
-  return runInstaller({ ...options, skipSetup });
+  return runInstaller({ ...options, skipSetup, verbose });
 }
 
 module.exports = {
   VlinkSetupError,
+  verboseEnabled,
   defaultInstallDir,
   installPathFor,
   isExecutableFile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tedbrain/vlink",
-  "version": "0.1.63",
+  "version": "0.1.64",
   "description": "vlink Virtuoso bridge CLI installer. Installs the matching platform binary at npm install time, like Claude Code / Codex.",
   "license": "UNLICENSED",
   "bin": {