@tedbrain/vlink 0.1.76 → 0.1.77

package/README.md

@@ -8,6 +8,17 @@ Codex 一样按当前平台下载对应的 vlink 二进制。推荐统一使用
 npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest install
 ```
 
+npm 包只注册 `vlink-install` 命令；`vlink` 命令由安装后的原生程序提供。
+`npx` 会自动选择包中唯一的命令入口，因此上面的安装命令保持不变。
+全局安装 npm 包只会注册 `vlink-install`；Windows 下 npm 会生成
+`vlink-install`、`vlink-install.cmd`、`vlink-install.ps1` 三个入口。
+通过全局 npm 包安装原生程序时，执行：
+
+```bash
+npm install -g @tedbrain/vlink@latest --registry=https://registry.npmmirror.com
+vlink-install install
+```
+
 该命令会识别平台和架构，始终安装与当前 npm 包版本一致的 vlink，配置用户
 PATH，并启动 `vlink setup tedbrain`。如果 PATH 中已有原生 vlink，会优先更新该位置；
 旧文件或目录不可写时，自动回退到用户安装目录（Unix 为 `~/.local/bin`，Windows 为
@@ -54,7 +65,7 @@ package 形式，绕过 npx 的命令推断：
 ```bash
 npm exec --registry=https://registry.npmmirror.com \
   --package=@tedbrain/vlink@latest -- \
-  vlink install --verbose
+  vlink-install install --verbose
 ```
 
 若显式形式可以输出，问题发生在本机 npx 的参数路由或缓存阶段；若仍无 wrapper
@@ -66,6 +77,47 @@ npm exec --registry=https://registry.npmmirror.com \
 npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest install --no-setup
 ```
 
+## 从旧版全局 npm 安装迁移
+
+旧版 npm 包会注册 `vlink`、`vlink.cmd`、`vlink.ps1` 入口。新版改为由 npm
+生成和管理 `vlink-install` 系列入口，不直接重命名历史脚本，避免保留失效目标
+或覆盖新版入口。
+
+npm 的 `postinstall` 下载成功后，以及原生 `install` 流程成功后，会自动清理
+当前 PATH、npm 提供的 prefix 中的旧入口；原生安装还会检查安装目标目录。
+清理只针对调用或链接目标明确指向 `@tedbrain/vlink/bin/vlink.js` 或历史
+`@tedmind/vlink/bin/vlink.js` 的 npm 启动文件，也能处理包已删除的脚本和失效链接。
+原生程序、转发到 `vlink.exe` 的 `vlink.cmd`、无关脚本及 `vlink-install`
+系列入口会保留。重复执行无需额外处理；遇到权限不足会保留文件并报告具体路径。
+
+已有旧入口或卸载残留时，可直接重新运行安装器：
+
+```bash
+npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest install
+```
+
+使用 `npm install --ignore-scripts` 会跳过 `postinstall` 清理，可随后执行
+`vlink-install install`。`npm uninstall -g @tedbrain/vlink` 会移除当前包管理的
+`vlink-install` 入口，保留已经持久化安装的原生 vlink。npm 7 起不再支持
+[卸载钩子](https://docs.npmjs.com/cli/v11/using-npm/scripts/#a-note-on-a-lack-of-npm-uninstall-scripts)，
+因此历史孤立入口由上述安装流程修复。
+
+完成后重新打开终端。Windows 可以用以下命令检查实际命中的入口：
+
+```powershell
+Get-Command vlink -All | Format-Table CommandType, Name, Source -AutoSize
+```
+
+应优先命中原生安装目录中的 `vlink.exe` 或转发到它的 `vlink.cmd`。使用 nvm
+切换 Node 版本后，其他版本目录里的旧 npm 入口也可能重新出现；需要在对应
+版本下重新运行安装器。不会递归搜索当前 PATH 和 npm prefix 之外的其他 Node
+安装目录；无法自动清理的文件会在安装日志中列出。
+当前窗口可直接使用原生程序的完整路径：
+
+```powershell
+& "$env:LOCALAPPDATA\TedBrain\bin\vlink.exe" --version
+```
+
 ## 安装 Web 通道
 
 用于网页接入、终端和协议命令调用时，执行：

package/binaries.json

@@ -1,12 +1,12 @@
 {
-  "version": "0.1.76",
+  "version": "0.1.77",
   "binaries": {
-    "linux-x86_64": "03ecd407f13911ffbe63af7fdc97f98a0925ca2fc8283414c0c03ed1b0cee7c6",
-    "linux-x86_64-glibc2.17": "b5a58a3d2415e5e48f6c640e782fc8f0f61b062ebe0987787f3f67dae9705057",
-    "linux-aarch64": "75c7e079cc999938a60e53db08067007d9d06d9419af56539d1d93b521d26d07",
-    "macos-x86_64": "100342baaa28c36499b4378d5b433c09c7c7d287de381cb118a11616e36a8293",
-    "macos-aarch64": "b5d7d6ad04b3e925b02d58d4a590b5df3d6dc912c639bb8227ce2173b0700c04",
-    "windows-x86_64.exe": "240ee12509e9044a4bfc89b931f18e5fc15369ae01b2fd547f279d90b82174ac",
-    "windows-aarch64.exe": "a31ad59bd7d3279cb9e3cdeb08dfad513f4d0aa3028e49b31a0fa56291bf7585"
+    "linux-x86_64": "34b6523d3ae77305c78aac9d8d1a3519cd5fc87144a8dd7279255fbe6601e486",
+    "linux-x86_64-glibc2.17": "4f2b0cac4ae9d581505f11cc4ed82a6b3759985a9e58dc1031aa5075690b3d72",
+    "linux-aarch64": "ef3ba7b89ad9a6d8f119723e1d221ddeb4e1a07f63306fd61ef031f309a477a8",
+    "macos-x86_64": "53c8176ba9b1b2c0ebec3421ca544b167b7cf767cb90988434137ac85fc4d9b5",
+    "macos-aarch64": "c017542b6850381c9f3da83654293d3515d794fe03f7a595786a849f43dc3eaa",
+    "windows-x86_64.exe": "6e22d3983d359375873908f6bde9b13f1f2dc149510f8c1ab4666429f3f6c77d",
+    "windows-aarch64.exe": "dc5691a3a162fd4279210e8f70ce4f0a84fb0e5cb90865368dd79df684c86caa"
   }
 }

package/install.js

@@ -11,6 +11,8 @@ const { spawnSync } = require('child_process');
 const { HttpProxyAgent } = require('http-proxy-agent');
 const { HttpsProxyAgent } = require('https-proxy-agent');
 
+const { cleanupLegacyNpmShims } = require('./npm-shims');
+
 const PKG_ROOT = path.resolve(__dirname);
 const PKG = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
 const CHECKSUMS = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'binaries.json'), 'utf8'));
@@ -572,6 +574,7 @@ module.exports = {
 if (require.main === module) {
   ensureBinary()
     .then((binaryPath) => {
+      cleanupLegacyNpmShims();
       console.error(`[vlink] installed ${binaryPath}`);
     })
     .catch((err) => {

package/installer.js

@@ -7,6 +7,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 
 const installModule = require('./install');
+const { cleanupLegacyNpmShims } = require('./npm-shims');
 
 const PERMISSION_ERRORS = new Set(['EACCES', 'EPERM', 'EROFS']);
 
@@ -85,7 +86,7 @@ function isVlinkWrapper(filePath, fsImpl = fs) {
     fd = fsImpl.openSync(filePath, 'r');
     const buffer = Buffer.alloc(64 * 1024);
     const length = fsImpl.readSync(fd, buffer, 0, buffer.length, 0);
-    const contents = buffer.subarray(0, length).toString('utf8');
+    const contents = buffer.subarray(0, length).toString('utf8').replace(/\\/g, '/');
     return /@(tedbrain|tedmind)\/vlink\/bin\/vlink\.js/.test(contents);
   } catch {
     return false;
@@ -593,6 +594,10 @@ async function runInstaller(options = {}) {
     log('Web channel is ready', output);
   }
 
+  cleanupLegacyNpmShims({
+    ...sharedOptions,
+    directories: [installDir, path.dirname(vlinkPath)]
+  });
   log(`installation complete: ${vlinkPath}`, output);
   log('open a new terminal to use the updated PATH', output);
   return { installDir, vlinkPath, commandShimPath, setupSkipped: skipSetup, webStarted: web };
@@ -602,6 +607,7 @@ function printInstallHelp(output = process.stdout) {
   output.write(
     [
       'Usage: npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest install [--no-setup] [--web] [--verbose]',
+      '       vlink-install install [--no-setup] [--web] [--verbose]',
       '',
       'Installs or updates vlink and adds it to the user PATH.',
       '',

package/npm-shims.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const LEGACY_COMMANDS = ['vlink', 'vlink.cmd', 'vlink.ps1'];
+const MAX_SHIM_BYTES = 64 * 1024;
+const PACKAGE_WRAPPER = /\/node_modules\/@(?:tedbrain|tedmind)\/vlink\/bin\/vlink\.js$/i;
+const MISSING_PATH_ERRORS = new Set(['ENOENT', 'ENOTDIR']);
+
+function environmentValue(env, name) {
+  const key = Object.keys(env).find((key) => key.toLowerCase() === name.toLowerCase());
+  return key ? String(env[key] || '') : '';
+}
+
+function isPackageWrapper(target) {
+  return PACKAGE_WRAPPER.test(target.replace(/\\/g, '/'));
+}
+
+function shimTarget(contents, extension) {
+  // Match the invocation, not mentions of the package in comments or other text.
+  for (let line of contents.replace(/\\/g, '/').split(/\r?\n/)) {
+    line = line.trim();
+    let match;
+    if (extension === '.cmd') {
+      line = line.replace(/^endLocal & goto #_undefined_# 2>NUL \|\| title %COMSPEC% & /i, '');
+      match = line.match(/^@?(?:"(?:%_prog%|(?:%~dp0|%dp0%)\/?node(?:\.exe)?|node(?:\.exe)?)"|node(?:\.exe)?)\s+"%(?:~dp0|dp0%)\/?([^"]+)"\s+%\*$/i);
+    } else if (extension === '.ps1') {
+      match = line.match(/^(?:\$input\s*\|\s*)?&\s+"(?:\$basedir\/)?node(?:\$exe|\.exe)?"\s+"\$basedir\/([^"]+)"\s+\$args$/i);
+    } else {
+      match = line.match(/^exec\s+(?:"\$basedir\/node(?:\.exe)?"|node(?:\.exe)?)\s+"\$basedir\/([^"]+)"\s+"\$@"$/);
+    }
+    if (match) return match[1];
+  }
+  return null;
+}
+
+function isNpmVlinkShim(filePath, fsImpl = fs) {
+  const stat = fsImpl.lstatSync(filePath);
+  if (stat.isSymbolicLink()) {
+    // readlink also identifies orphaned Unix bin links after package removal.
+    return isPackageWrapper(path.resolve(path.dirname(filePath), fsImpl.readlinkSync(filePath)));
+  }
+  if (!stat.isFile() || stat.size > MAX_SHIM_BYTES) return false;
+
+  const contents = fsImpl.readFileSync(filePath, 'utf8');
+  if (contents.includes('\0')) return false;
+  const target = shimTarget(contents, path.extname(filePath).toLowerCase());
+  return target !== null && isPackageWrapper(path.resolve(path.dirname(filePath), target));
+}
+
+function cleanupLegacyNpmShims(options = {}) {
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const fsImpl = options.fs || fs;
+  const output = options.output || process.stderr;
+  const directories = environmentValue(env, 'PATH').split(platform === 'win32' ? ';' : ':');
+  const prefix = environmentValue(env, 'npm_config_prefix');
+  if (prefix) directories.push(platform === 'win32' ? prefix : path.join(prefix, 'bin'));
+  directories.push(env.VLINK_INSTALL_DIR, ...(options.directories || []));
+
+  const visited = new Set();
+  const removed = [];
+  const failed = [];
+  for (let directory of directories) {
+    if (!directory) continue;
+    if (platform === 'win32') directory = directory.replace(/^"(.*)"$/, '$1');
+    if (!directory) continue;
+    directory = path.resolve(directory);
+    const key = platform === 'win32' ? directory.toLowerCase() : directory;
+    if (visited.has(key)) continue;
+    visited.add(key);
+
+    for (const name of LEGACY_COMMANDS) {
+      const candidate = path.join(directory, name);
+      try {
+        if (!isNpmVlinkShim(candidate, fsImpl)) continue;
+        // Never recurse or follow the link when removing an npm-owned entry.
+        fsImpl.unlinkSync(candidate);
+        removed.push(candidate);
+        output.write(`[vlink] removed legacy npm shim: ${candidate}\n`);
+      } catch (error) {
+        if (MISSING_PATH_ERRORS.has(error.code)) continue;
+        failed.push(candidate);
+        output.write(`[vlink] warning: cannot clean legacy npm shim ${candidate}: ${error.message}\n`);
+      }
+    }
+  }
+  return { removed, failed };
+}
+
+module.exports = { cleanupLegacyNpmShims, isNpmVlinkShim };

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@tedbrain/vlink",
-  "version": "0.1.76",
+  "version": "0.1.77",
   "description": "vlink Virtuoso bridge CLI installer. Installs the matching platform binary at npm install time, like Claude Code / Codex.",
   "license": "UNLICENSED",
   "bin": {
-    "vlink": "bin/vlink.js"
+    "vlink-install": "bin/vlink.js"
   },
   "files": [
     "bin/",
     "install.js",
     "installer.js",
+    "npm-shims.js",
     "binaries.json",
     "README.md"
   ],