@tedbrain/vlink 0.1.38

package/README.md

@@ -0,0 +1,83 @@
+# @tedbrain/vlink
+
+跨平台 vlink npm 安装包。包本身不包含 Rust 二进制，安装时会像 Claude Code /
+Codex 一样按当前平台下载对应的 vlink 二进制。推荐统一使用 npx 完成持久化安装
+和 TedBrain 初始化：
+
+```bash
+npx -y @tedbrain/vlink@latest install
+```
+
+该命令会识别平台和架构、安装或更新 vlink、配置用户 PATH，并启动
+`vlink setup tedbrain`。安装完成后可直接运行：
+
+```bash
+vlink --version
+```
+
+也可以只把 npm 包作为临时 CLI 使用：
+
+```bash
+npx -y @tedbrain/vlink@latest --version
+```
+
+## 下载地址
+
+安装脚本优先从 Gitee Release 解析当前版本对应平台的附件并下载；Gitee 不可用、
+release 不存在或校验失败时，自动回退到 d01 下载服务器：
+
+```text
+优先: https://gitee.com/ted-team/tedbrain 的 release attachment
+回退: http://49.232.144.199/downloads/oss/vlink/<version>/vlink-<platform>
+```
+
+可用环境变量覆盖：
+
+```bash
+# 跳过 Gitee，直接使用 d01/自定义下载源
+VLINK_SKIP_GITEE=1 npx -y @tedbrain/vlink@latest install
+
+# d01 回退源改用开发通道
+VLINK_DOWNLOAD_CHANNEL=oss-dev npx -y @tedbrain/vlink@latest install
+
+# 自定义回退下载根路径（会自动拼接 <channel>/vlink/<version>/vlink-<platform>）
+VLINK_DOWNLOAD_BASE=https://internal.example/downloads npx -y @tedbrain/vlink@latest install
+
+# 自定义回退下载目录（会自动拼接 vlink-<platform>）
+VLINK_DOWNLOAD_URL=https://internal.example/vlink npx -y @tedbrain/vlink@latest install
+
+# 指定不同版本（同时影响 Gitee release tag 与 d01 回退路径）
+VLINK_VERSION=0.1.21 npx -y @tedbrain/vlink@latest install
+```
+
+## 平台映射
+
+| npm platform/arch | 下载文件 |
+| --- | --- |
+| linux/x64, glibc >= 2.17 | `vlink-linux-x86_64-glibc2.17` |
+| linux/x64 | `vlink-linux-x86_64` |
+| linux/arm64 | `vlink-linux-aarch64` |
+| darwin/x64 | `vlink-macos-x86_64` |
+| darwin/arm64 | `vlink-macos-aarch64` |
+| win32/x64 | `vlink-windows-x86_64.exe` |
+| win32/arm64 | `vlink-windows-aarch64.exe` |
+
+## 二进制存放位置
+
+- 优先写入 npm 包目录 `vendor/vlink`（或 `vlink.exe`）。
+- 如果包目录不可写，则回退到 `~/.cache/vlink/<version>/`。
+- 也可以直接指定 `VLINK_BINARY_PATH` 指向一个已存在的 vlink 二进制。
+
+安装脚本会校验 SHA-256（与 `dist/*.manifest` 一致），并执行一次
+`vlink -V` 验证可运行。
+
+## 发布
+
+```bash
+cd biz/eda/packages/vlink/npm
+./scripts/publish.sh --dry-run
+./scripts/publish.sh
+```
+
+发布脚本会从 `Cargo.toml` 读取 version，动态生成 `package.json`，再以 public
+访问级别执行 `npm pack`/`npm publish`；仓库不维护静态 `package.json`。

package/bin/vlink.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawn } = require('child_process');
+const { ensureBinary } = require('../install');
+const { runInstallerFromArgs } = require('../installer');
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args[0] === 'install') {
+    await runInstallerFromArgs(args.slice(1));
+    return;
+  }
+
+  const binaryPath = await ensureBinary();
+  const child = spawn(binaryPath, args, { stdio: 'inherit' });
+
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(signal, () => {
+      if (!child.killed) {
+        child.kill(signal);
+      }
+    });
+  }
+
+  child.on('error', (err) => {
+    console.error(`[vlink] failed to start ${binaryPath}: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      try {
+        process.kill(process.pid, signal);
+      } catch {
+        process.exit(1);
+      }
+      return;
+    }
+    process.exit(code == null ? 1 : code);
+  });
+}
+
+main().catch((err) => {
+  console.error(`[vlink] ${err.message}`);
+  process.exit(1);
+});

package/binaries.json

@@ -0,0 +1,12 @@
+{
+  "version": "0.1.38",
+  "binaries": {
+    "linux-x86_64": null,
+    "linux-x86_64-glibc2.17": null,
+    "linux-aarch64": null,
+    "macos-x86_64": null,
+    "macos-aarch64": null,
+    "windows-x86_64.exe": null,
+    "windows-aarch64.exe": null
+  }
+}

package/install.js

@@ -0,0 +1,417 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+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'));
+
+const VERSION = process.env.VLINK_VERSION || PKG.version;
+const CHANNEL = process.env.VLINK_DOWNLOAD_CHANNEL || 'oss';
+const DOWNLOAD_BASE = (process.env.VLINK_DOWNLOAD_BASE || 'http://49.232.144.199/downloads')
+  .replace(/\/+$/, '');
+
+const GITEE_API_BASE = (
+  process.env.VLINK_GITEE_API_BASE || 'https://gitee.com/api/v5/repos/ted-team/tedbrain'
+).replace(/\/+$/, '');
+
+const GLIBC217_SUFFIX = 'linux-x86_64-glibc2.17';
+
+class VlinkInstallError extends Error {}
+
+function parseGlibcVersion(text) {
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const glibcMatch = line.match(/\bglibc\s+([0-9]+(?:\.[0-9]+)+)/);
+    if (glibcMatch) return glibcMatch[1];
+    const versionMatch = line.match(/\b([0-9]+(?:\.[0-9]+)+)\b/);
+    if (versionMatch) return versionMatch[1];
+  }
+  return null;
+}
+
+function glibcVersion(deps = {}) {
+  if (Object.prototype.hasOwnProperty.call(process.env, 'VLINK_GLIBC_VERSION')) {
+    return process.env.VLINK_GLIBC_VERSION || null;
+  }
+
+  const run = deps.spawnSync || spawnSync;
+  const getconf = run('getconf', ['GNU_LIBC_VERSION'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore']
+  });
+  if (getconf && getconf.status === 0) {
+    const parsed = parseGlibcVersion(getconf.stdout);
+    if (parsed) return parsed;
+  }
+
+  const ldd = run('ldd', ['--version'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  if (ldd && ldd.status === 0) {
+    return parseGlibcVersion(`${ldd.stdout || ''}\n${ldd.stderr || ''}`);
+  }
+  return null;
+}
+
+function versionAtLeast(actual, requiredMajor, requiredMinor) {
+  const match = String(actual || '').match(/^([0-9]+)\.([0-9]+)/);
+  if (!match) return false;
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  return major > requiredMajor || (major === requiredMajor && minor >= requiredMinor);
+}
+
+function platformSpec(options = {}) {
+  const platform = options.platform || process.env.VLINK_PLATFORM || process.platform;
+  const arch = options.arch || process.env.VLINK_ARCH || process.arch;
+  const detectedGlibc =
+    options.glibcVersion !== undefined
+      ? options.glibcVersion
+      : platform === 'linux' && arch === 'x64'
+        ? glibcVersion(options)
+        : null;
+
+  const spec = { platform, arch, suffixes: [], binaryName: 'vlink' };
+
+  if (platform === 'linux') {
+    if (arch === 'x64') {
+      if (versionAtLeast(detectedGlibc, 2, 17)) {
+        spec.suffixes.push(GLIBC217_SUFFIX);
+      }
+      spec.suffixes.push('linux-x86_64');
+    } else if (arch === 'arm64') {
+      spec.suffixes.push('linux-aarch64');
+    }
+  } else if (platform === 'darwin') {
+    if (arch === 'x64') spec.suffixes.push('macos-x86_64');
+    else if (arch === 'arm64') spec.suffixes.push('macos-aarch64');
+  } else if (platform === 'win32') {
+    spec.binaryName = 'vlink.exe';
+    if (arch === 'x64') spec.suffixes.push('windows-x86_64.exe');
+    else if (arch === 'arm64') spec.suffixes.push('windows-aarch64.exe');
+  }
+
+  if (spec.suffixes.length === 0) {
+    throw new VlinkInstallError(
+      `unsupported platform/architecture: ${platform}/${arch}`
+    );
+  }
+  spec.suffix = spec.suffixes[0];
+  return spec;
+}
+
+function fallbackDownloadUrl(spec, suffix = spec.suffix) {
+  const base = process.env.VLINK_DOWNLOAD_URL;
+  if (base) {
+    return `${base.replace(/\/+$/, '')}/vlink-${suffix}`;
+  }
+  return `${DOWNLOAD_BASE}/${CHANNEL}/vlink/${VERSION}/vlink-${suffix}`;
+}
+
+function httpGetText(url) {
+  return new Promise((resolve, reject) => {
+    const request = (target, redirects) => {
+      const transport = target.startsWith('https:') ? https : http;
+      const req = transport.get(
+        target,
+        { headers: { 'user-agent': `${PKG.name}/${PKG.version}` } },
+        (res) => {
+          if (
+            res.statusCode >= 300 &&
+            res.statusCode < 400 &&
+            res.headers.location &&
+            redirects < 5
+          ) {
+            res.resume();
+            const next = new URL(res.headers.location, target).toString();
+            return request(next, redirects + 1);
+          }
+          if (res.statusCode !== 200) {
+            res.resume();
+            return reject(
+              new VlinkInstallError(`HTTP ${res.statusCode} from ${target}`)
+            );
+          }
+
+          const chunks = [];
+          res.on('data', (chunk) => chunks.push(chunk));
+          res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        }
+      );
+
+      req.on('error', reject);
+      req.setTimeout(30000, () => req.destroy(new VlinkInstallError('request timed out')));
+    };
+
+    request(url, 0);
+  });
+}
+
+function parseJson(text, url) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new VlinkInstallError(`invalid JSON from ${url}: ${error.message}`);
+  }
+}
+
+async function giteeReleaseId(version) {
+  const url = `${GITEE_API_BASE}/releases/tags/${version}`;
+  const release = parseJson(await httpGetText(url), url);
+  if (!release || typeof release !== 'object' || !Number.isInteger(release.id)) {
+    throw new VlinkInstallError(`gitee release is missing an id: ${url}`);
+  }
+  return release.id;
+}
+
+async function giteeAttachmentDownloadUrl(spec, suffix = spec.suffix) {
+  const releaseId = await giteeReleaseId(VERSION);
+  const attachmentsUrl = `${GITEE_API_BASE}/releases/${releaseId}/attach_files?per_page=100`;
+  const attachments = parseJson(await httpGetText(attachmentsUrl), attachmentsUrl);
+  if (!Array.isArray(attachments)) {
+    throw new VlinkInstallError(`gitee attachments response is not an array: ${attachmentsUrl}`);
+  }
+
+  const remoteName = `vlink-${suffix}`;
+  const attachment = attachments.find((item) => item && item.name === remoteName);
+  if (!attachment) {
+    throw new VlinkInstallError(`gitee release attachment not found: ${remoteName}`);
+  }
+
+  if (
+    typeof attachment.browser_download_url === 'string' &&
+    attachment.browser_download_url.trim() !== ''
+  ) {
+    return attachment.browser_download_url.trim();
+  }
+  if (Number.isInteger(attachment.id)) {
+    return `${GITEE_API_BASE}/releases/${releaseId}/attach_files/${attachment.id}/download`;
+  }
+  throw new VlinkInstallError(`gitee attachment has no usable download URL: ${remoteName}`);
+}
+
+function buildDownloadSources(spec, suffix = spec.suffix) {
+  const sources = [];
+  if (process.env.VLINK_SKIP_GITEE !== '1') {
+    sources.push({
+      name: 'gitee',
+      resolve: () => giteeAttachmentDownloadUrl(spec, suffix)
+    });
+  }
+  sources.push({
+    name: process.env.VLINK_DOWNLOAD_URL ? 'custom' : 'd01',
+    resolve: () => Promise.resolve(fallbackDownloadUrl(spec, suffix))
+  });
+  return sources;
+}
+
+function packageBinaryPath(spec) {
+  return path.join(PKG_ROOT, 'vendor', spec.binaryName);
+}
+
+function cacheBinaryPath(spec) {
+  const cacheRoot =
+    process.env.VLINK_BINARY_DIR ||
+    path.join(
+      process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'),
+      'vlink',
+      VERSION
+    );
+  return path.join(cacheRoot, spec.binaryName);
+}
+
+function isExecutable(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.X_OK);
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isWritable(dir) {
+  try {
+    fs.accessSync(dir, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveBinaryPath(spec) {
+  if (process.env.VLINK_BINARY_PATH) {
+    return process.env.VLINK_BINARY_PATH;
+  }
+
+  const primary = packageBinaryPath(spec);
+  if (isExecutable(primary)) return primary;
+
+  const cache = cacheBinaryPath(spec);
+  if (isExecutable(cache)) return cache;
+
+  if (isWritable(PKG_ROOT)) return primary;
+  return cache;
+}
+
+function expectedChecksum(spec, suffix = spec.suffix) {
+  if (VERSION !== PKG.version) return null;
+  if (CHECKSUMS.version && CHECKSUMS.version !== VERSION) return null;
+  const value = CHECKSUMS.binaries && CHECKSUMS.binaries[suffix];
+  return typeof value === 'string' && value.length === 64 ? value.toLowerCase() : null;
+}
+
+function sha256File(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(filePath);
+    stream.on('error', reject);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', () => resolve(hash.digest('hex')));
+  });
+}
+
+function downloadFile(url, destPath) {
+  return new Promise((resolve, reject) => {
+    const fileStream = fs.createWriteStream(destPath, { mode: 0o755 });
+
+    const finish = () => {
+      fileStream.close((closeErr) => {
+        if (closeErr) reject(closeErr);
+        else resolve();
+      });
+    };
+
+    const request = (target, redirects) => {
+      const transport = target.startsWith('https:') ? https : http;
+      const req = transport.get(
+        target,
+        { headers: { 'user-agent': `${PKG.name}/${PKG.version}` } },
+        (res) => {
+          if (
+            res.statusCode >= 300 &&
+            res.statusCode < 400 &&
+            res.headers.location &&
+            redirects < 5
+          ) {
+            res.resume();
+            const next = new URL(res.headers.location, target).toString();
+            return request(next, redirects + 1);
+          }
+          if (res.statusCode !== 200) {
+            res.resume();
+            return reject(
+              new VlinkInstallError(`download failed: HTTP ${res.statusCode} from ${target}`)
+            );
+          }
+          res.pipe(fileStream);
+        }
+      );
+
+      req.on('error', reject);
+      req.setTimeout(300000, () => req.destroy(new VlinkInstallError('download timed out')));
+    };
+
+    fileStream.on('finish', finish);
+    fileStream.on('error', reject);
+    request(url, 0);
+  });
+}
+
+function verifyBinary(binaryPath) {
+  const result = spawnSync(binaryPath, ['-V'], {
+    stdio: ['ignore', 'ignore', 'pipe'],
+    encoding: 'utf8',
+    timeout: 30000
+  });
+  if (result.error) {
+    throw new VlinkInstallError(`downloaded binary is not executable: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new VlinkInstallError(`downloaded binary failed its version check (exit ${result.status})`);
+  }
+}
+
+async function ensureBinary({ force = false } = {}) {
+  const spec = platformSpec();
+  const binaryPath = resolveBinaryPath(spec);
+  if (!force && isExecutable(binaryPath)) {
+    return binaryPath;
+  }
+
+  const dir = path.dirname(binaryPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  let lastError = new VlinkInstallError('no download source available');
+
+  for (const suffix of spec.suffixes) {
+    const tempPath = path.join(dir, `.${spec.binaryName}.download-${process.pid}`);
+    const sources = buildDownloadSources(spec, suffix);
+    for (const source of sources) {
+      try {
+        const url = await source.resolve();
+        console.error(`[vlink] downloading ${url} [${source.name}]`);
+        fs.rmSync(tempPath, { force: true });
+        await downloadFile(url, tempPath);
+
+        const checksum = expectedChecksum(spec, suffix);
+        if (checksum) {
+          const actual = await sha256File(tempPath);
+          if (actual !== checksum) {
+            throw new VlinkInstallError(
+              `checksum mismatch for ${suffix}: expected ${checksum}, got ${actual}`
+            );
+          }
+        }
+
+        if (process.platform !== 'win32') {
+          fs.chmodSync(tempPath, 0o755);
+        }
+        if (fs.existsSync(binaryPath)) fs.rmSync(binaryPath, { force: true });
+        fs.renameSync(tempPath, binaryPath);
+        verifyBinary(binaryPath);
+        return binaryPath;
+      } catch (err) {
+        lastError = err;
+        fs.rmSync(tempPath, { force: true });
+        console.error(`[vlink] ${source.name} download failed for ${suffix}: ${err.message}`);
+      }
+    }
+  }
+
+  throw new VlinkInstallError(`all download sources failed: ${lastError.message}`);
+}
+
+module.exports = {
+  VlinkInstallError,
+  VERSION,
+  GLIBC217_SUFFIX,
+  parseGlibcVersion,
+  glibcVersion,
+  versionAtLeast,
+  platformSpec,
+  fallbackDownloadUrl,
+  giteeAttachmentDownloadUrl,
+  buildDownloadSources,
+  resolveBinaryPath,
+  ensureBinary,
+  verifyBinary
+};
+
+if (require.main === module) {
+  ensureBinary()
+    .then((binaryPath) => {
+      console.error(`[vlink] installed ${binaryPath}`);
+    })
+    .catch((err) => {
+      console.error(`[vlink] install failed: ${err.message}`);
+      process.exitCode = 1;
+    });
+}

package/installer.js

@@ -0,0 +1,479 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const installModule = require('./install');
+
+const CURRENT_WRAPPER = path.resolve(__dirname, 'bin', 'vlink.js');
+
+class VlinkSetupError extends Error {}
+
+function log(message, output = process.stderr) {
+  output.write(`[TedBrain] ${message}\n`);
+}
+
+function environmentValue(env, name) {
+  const expected = name.toLowerCase();
+  for (const key of Object.keys(env)) {
+    if (key.toLowerCase() === expected && env[key] !== undefined) {
+      return env[key];
+    }
+  }
+  return '';
+}
+
+function defaultInstallDir(spec, env = process.env, home = os.homedir()) {
+  if (env.VLINK_INSTALL_DIR) return env.VLINK_INSTALL_DIR;
+  if (spec.platform === 'win32') {
+    const localAppData = env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+    return path.join(localAppData, 'TedBrain', 'bin');
+  }
+  return path.join(home, '.local', 'bin');
+}
+
+function installPathFor(spec, installDir) {
+  return path.join(installDir, spec.binaryName);
+}
+
+function isExecutableFile(filePath, platform = process.platform, fsImpl = fs) {
+  try {
+    if (!fsImpl.statSync(filePath).isFile()) return false;
+    if (platform === 'win32') return true;
+    fsImpl.accessSync(filePath, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isVlinkWrapper(filePath, fsImpl = fs) {
+  const normalized = path.resolve(filePath).replace(/\\/g, '/').toLowerCase();
+  if (normalized.includes('/node_modules/.bin/')) return true;
+
+  let realPath = normalized;
+  try {
+    realPath = fsImpl.realpathSync(filePath).replace(/\\/g, '/').toLowerCase();
+  } catch {
+    // The regular path is still useful when realpath is unavailable.
+  }
+
+  if (realPath === CURRENT_WRAPPER.replace(/\\/g, '/').toLowerCase()) return true;
+  if (/\/@(tedbrain|tedmind)\/vlink\/bin\/vlink\.js$/.test(realPath)) return true;
+
+  let fd;
+  try {
+    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');
+    return /@(tedbrain|tedmind)\/vlink\/bin\/vlink\.js/.test(contents);
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fsImpl.closeSync(fd);
+      } catch {
+        // Best-effort cleanup only.
+      }
+    }
+  }
+}
+
+function findOnPath(binaryName, options = {}) {
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const fsImpl = options.fs || fs;
+  const rawPath = environmentValue(env, 'PATH');
+  const delimiter = platform === 'win32' ? ';' : path.delimiter;
+
+  for (const entry of String(rawPath).split(delimiter)) {
+    if (!entry) continue;
+    const candidate = path.join(entry, binaryName);
+    if (
+      isExecutableFile(candidate, platform, fsImpl) &&
+      !isVlinkWrapper(candidate, fsImpl)
+    ) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function prependEnvironmentPath(directory, env, platform) {
+  const delimiter = platform === 'win32' ? ';' : path.delimiter;
+  const current = environmentValue(env, 'PATH');
+  const entries = String(current)
+    .split(delimiter)
+    .filter(Boolean);
+  const alreadyPresent = entries.some((entry) => entry === directory);
+  const next = alreadyPresent ? entries.join(delimiter) : [directory, ...entries].join(delimiter);
+
+  for (const key of Object.keys(env)) {
+    if (key.toLowerCase() === 'path') delete env[key];
+  }
+  env.PATH = next;
+}
+
+function samePath(left, right, platform) {
+  const normalize = (value) => {
+    let normalized = path.resolve(value);
+    while (normalized.length > 1 && /[\\/]$/.test(normalized)) {
+      normalized = normalized.slice(0, -1);
+    }
+    return platform === 'win32' ? normalized.toLowerCase() : normalized;
+  };
+  return normalize(left) === normalize(right);
+}
+
+function updateWindowsUserPath(directory, options) {
+  const spawnSyncImpl = options.spawnSync || spawnSync;
+  const env = { ...options.env, TEDBRAIN_INSTALL_DIR: directory };
+  const script = [
+    "$entry = $env:TEDBRAIN_INSTALL_DIR.TrimEnd('\\')",
+    "$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')",
+    "$entries = @($userPath -split ';' | Where-Object { $_ })",
+    "if (-not ($entries | Where-Object { $_.TrimEnd('\\') -ieq $entry })) {",
+    "  $newPath = (@($env:TEDBRAIN_INSTALL_DIR) + $entries) -join ';'",
+    "  [Environment]::SetEnvironmentVariable('Path', $newPath, 'User')",
+    "  Write-Output 'changed'",
+    "}"
+  ].join('\n');
+  const result = spawnSyncImpl('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+    env,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  if (result.error) {
+    throw new VlinkSetupError(`failed to update the Windows user PATH: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const detail = String(result.stderr || '').trim();
+    throw new VlinkSetupError(
+      `failed to update the Windows user PATH${detail ? `: ${detail}` : ''}`
+    );
+  }
+  return String(result.stdout || '').trim() === 'changed';
+}
+
+function ensureUserPath(installDir, options = {}) {
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const home = options.home || os.homedir();
+  const fsImpl = options.fs || fs;
+  const output = options.output || process.stderr;
+
+  prependEnvironmentPath(installDir, env, platform);
+
+  if (platform === 'win32') {
+    const changed = updateWindowsUserPath(installDir, {
+      ...options,
+      env,
+      fs: fsImpl,
+      output
+    });
+    if (changed) log(`added ${installDir} to the user PATH`, output);
+    return { changed, persistent: true };
+  }
+
+  const defaultDir = path.join(home, '.local', 'bin');
+  if (!samePath(installDir, defaultDir, platform)) {
+    log(`using custom install directory; add ${installDir} to your shell PATH permanently`, output);
+    return { changed: false, persistent: false };
+  }
+
+  const shellName = path.basename(env.SHELL || 'bash');
+  let rcFile;
+  let pathLine;
+  switch (shellName) {
+    case 'zsh':
+      rcFile = path.join(home, '.zshrc');
+      pathLine = 'export PATH="$HOME/.local/bin:$PATH"';
+      break;
+    case 'fish':
+      rcFile = path.join(home, '.config', 'fish', 'config.fish');
+      pathLine = 'fish_add_path "$HOME/.local/bin"';
+      break;
+    case 'csh':
+    case 'tcsh':
+      rcFile = path.join(home, `.${shellName}rc`);
+      pathLine = 'setenv PATH "$HOME/.local/bin:$PATH"';
+      break;
+    default:
+      rcFile = path.join(home, '.bashrc');
+      pathLine = 'export PATH="$HOME/.local/bin:$PATH"';
+      break;
+  }
+
+  fsImpl.mkdirSync(path.dirname(rcFile), { recursive: true });
+  const current = fsImpl.existsSync(rcFile) ? fsImpl.readFileSync(rcFile, 'utf8') : '';
+  if (current.split(/\r?\n/).includes(pathLine)) {
+    return { changed: false, persistent: true, rcFile };
+  }
+
+  const separator = current && !current.endsWith('\n') ? '\n' : '';
+  fsImpl.writeFileSync(rcFile, `${current}${separator}\n${pathLine}\n`);
+  log(`added ${installDir} to PATH in ${rcFile}`, output);
+  return { changed: true, persistent: true, rcFile };
+}
+
+function commandFailure(result, label) {
+  if (result.error) return `${label}: ${result.error.message}`;
+  if (result.status !== 0) {
+    const detail = String(result.stderr || '').trim();
+    return `${label} failed with exit code ${result.status}${detail ? `: ${detail}` : ''}`;
+  }
+  return null;
+}
+
+function runVlinkUpdate(vlinkPath, options = {}) {
+  const spawnSyncImpl = options.spawnSync || spawnSync;
+  const check = spawnSyncImpl(vlinkPath, ['update', '--json'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  if (check.error || check.status !== 0) {
+    return { supported: false };
+  }
+
+  let update;
+  try {
+    update = JSON.parse(String(check.stdout || '').trim());
+  } catch (error) {
+    throw new VlinkSetupError(
+      `vlink update returned invalid JSON: ${error.message}`
+    );
+  }
+
+  if (update.update_required === false) {
+    return { supported: true, updateRequired: false };
+  }
+  if (update.update_required !== true) {
+    throw new VlinkSetupError('vlink update returned invalid JSON: missing update_required');
+  }
+
+  const apply = spawnSyncImpl(vlinkPath, ['update', '--apply', '--json'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  const failure = commandFailure(apply, 'vlink update --apply');
+  if (failure) throw new VlinkSetupError(failure);
+
+  let applied;
+  try {
+    applied = JSON.parse(String(apply.stdout || '').trim());
+  } catch (error) {
+    throw new VlinkSetupError(
+      `vlink update --apply returned invalid JSON: ${error.message}`
+    );
+  }
+
+  return {
+    supported: true,
+    updateRequired: true,
+    installedPath:
+      typeof applied.installed_path === 'string' && applied.installed_path.trim()
+        ? applied.installed_path.trim()
+        : null
+  };
+}
+
+function installBinary(sourcePath, targetPath, options = {}) {
+  const platform = options.platform || process.platform;
+  const fsImpl = options.fs || fs;
+  const spawnSyncImpl = options.spawnSync || spawnSync;
+  const output = options.output || process.stderr;
+
+  if (samePath(sourcePath, targetPath, platform)) return targetPath;
+  fsImpl.mkdirSync(path.dirname(targetPath), { recursive: true });
+
+  if (options.stopDaemon) {
+    log('stopping the existing vlink daemon before replacement', output);
+    const stop = spawnSyncImpl(sourcePath, ['daemon', 'stop'], { stdio: 'inherit' });
+    const failure = commandFailure(stop, 'vlink daemon stop');
+    if (failure) throw new VlinkSetupError(failure);
+  }
+
+  const temporary = path.join(
+    path.dirname(targetPath),
+    `.${path.basename(targetPath)}.install-${process.pid}-${Date.now()}`
+  );
+  try {
+    fsImpl.copyFileSync(sourcePath, temporary);
+    if (platform !== 'win32') fsImpl.chmodSync(temporary, 0o755);
+    if (platform === 'win32' && fsImpl.existsSync(targetPath)) {
+      fsImpl.rmSync(targetPath, { force: true });
+    }
+    fsImpl.renameSync(temporary, targetPath);
+  } catch (error) {
+    fsImpl.rmSync(temporary, { force: true });
+    throw new VlinkSetupError(`failed to install vlink at ${targetPath}: ${error.message}`);
+  }
+  fsImpl.rmSync(temporary, { force: true });
+  log(`installed vlink at ${targetPath}`, output);
+  return targetPath;
+}
+
+function binaryIsStaticElf(binaryPath, options = {}) {
+  if ((options.platform || process.platform) !== 'linux') return false;
+  const spawnSyncImpl = options.spawnSync || spawnSync;
+  const result = spawnSyncImpl('file', [binaryPath], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore']
+  });
+  if (result.error || result.status !== 0) return false;
+  const details = String(result.stdout || '');
+  return details.includes('ELF') && !details.includes('dynamically linked');
+}
+
+async function migrateStaticVlink(vlinkPath, spec, options) {
+  if (spec.suffixes[0] !== installModule.GLIBC217_SUFFIX) return vlinkPath;
+  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 });
+  return installBinary(sourcePath, vlinkPath, {
+    ...options,
+    stopDaemon: true
+  });
+}
+
+async function runInstaller(options = {}) {
+  const env = options.env || process.env;
+  const platform = options.platform || env.VLINK_PLATFORM || process.platform;
+  const arch = options.arch || env.VLINK_ARCH || process.arch;
+  const home = options.home || os.homedir();
+  const fsImpl = options.fs || fs;
+  const output = options.output || process.stderr;
+  const spawnSyncImpl = options.spawnSync || spawnSync;
+  const platformSpec = options.platformSpec || installModule.platformSpec;
+  const ensureBinary =
+    options.ensureBinary || ((settings) => installModule.ensureBinary(settings));
+
+  const spec = platformSpec({
+    platform,
+    arch,
+    glibcVersion:
+      options.glibcVersion !== undefined
+        ? options.glibcVersion
+        : env.VLINK_GLIBC_VERSION,
+    spawnSync: spawnSyncImpl
+  });
+  const installDir = defaultInstallDir(spec, env, home);
+  const targetPath = installPathFor(spec, installDir);
+  const sharedOptions = {
+    env,
+    platform,
+    home,
+    fs: fsImpl,
+    output,
+    spawnSync: spawnSyncImpl
+  };
+
+  let vlinkPath = findOnPath(spec.binaryName, {
+    env,
+    platform,
+    fs: fsImpl
+  });
+
+  if (vlinkPath) {
+    log(`found vlink at ${vlinkPath}`, output);
+  } else if (isExecutableFile(targetPath, platform, fsImpl)) {
+    vlinkPath = targetPath;
+    ensureUserPath(installDir, sharedOptions);
+    log(`found vlink at ${vlinkPath}`, output);
+  } else {
+    log(`installing vlink ${installModule.VERSION}`, output);
+    const sourcePath = await ensureBinary({});
+    installBinary(sourcePath, targetPath, {
+      ...sharedOptions,
+      stopDaemon: false
+    });
+    ensureUserPath(installDir, sharedOptions);
+    vlinkPath = targetPath;
+  }
+
+  const update = runVlinkUpdate(vlinkPath, { spawnSync: spawnSyncImpl });
+  if (update.supported) {
+    if (update.updateRequired) {
+      log('a newer vlink release is available; applying it', output);
+      if (
+        update.installedPath &&
+        isExecutableFile(update.installedPath, platform, fsImpl)
+      ) {
+        vlinkPath = update.installedPath;
+        if (samePath(path.dirname(vlinkPath), installDir, platform)) {
+          ensureUserPath(installDir, sharedOptions);
+        }
+      }
+    } else {
+      log('vlink is up to date', output);
+    }
+  } else {
+    log('installed vlink does not support update checks; installing the latest release', output);
+    const sourcePath = await ensureBinary({});
+    installBinary(sourcePath, targetPath, {
+      ...sharedOptions,
+      stopDaemon: true
+    });
+    ensureUserPath(installDir, sharedOptions);
+    vlinkPath = targetPath;
+  }
+
+  vlinkPath = await migrateStaticVlink(vlinkPath, spec, {
+    ...sharedOptions,
+    ensureBinary
+  });
+
+  log('starting TedBrain Agent setup', output);
+  const setup = spawnSyncImpl(vlinkPath, ['setup', 'tedbrain'], {
+    stdio: 'inherit'
+  });
+  const failure = commandFailure(setup, 'vlink setup tedbrain');
+  if (failure) throw new VlinkSetupError(failure);
+
+  return { installDir, vlinkPath };
+}
+
+function printInstallHelp(output = process.stdout) {
+  output.write(
+    [
+      'Usage: npx -y @tedbrain/vlink@latest install',
+      '',
+      'Installs or updates vlink, adds it to the user PATH, and starts',
+      'the TedBrain setup wizard.'
+    ].join('\n') + '\n'
+  );
+}
+
+async function runInstallerFromArgs(args, options = {}) {
+  if (args.includes('--help') || args.includes('-h')) {
+    printInstallHelp(options.output || process.stdout);
+    return null;
+  }
+  if (args.length > 0) {
+    throw new VlinkSetupError(`unknown install option: ${args[0]}`);
+  }
+  return runInstaller(options);
+}
+
+module.exports = {
+  VlinkSetupError,
+  defaultInstallDir,
+  installPathFor,
+  isExecutableFile,
+  isVlinkWrapper,
+  findOnPath,
+  prependEnvironmentPath,
+  ensureUserPath,
+  runVlinkUpdate,
+  installBinary,
+  binaryIsStaticElf,
+  runInstaller,
+  runInstallerFromArgs,
+  printInstallHelp
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@tedbrain/vlink",
+  "version": "0.1.38",
+  "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"
+  },
+  "files": [
+    "bin/",
+    "install.js",
+    "installer.js",
+    "binaries.json",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node install.js",
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "vlink",
+    "virtuoso",
+    "eda",
+    "skill"
+  ]
+}