bvm-core 1.1.36 → 1.1.38

package/README.md

@@ -10,6 +10,12 @@
   <p align="center">
     <a href="https://bvm-core.pages.dev"><strong>Official Website & Documentation »</strong></a>
     <br />
+    <a href="https://bvm-core.pages.dev/zh/"><strong>中文网站 »</strong></a>
+    <br />
+    <a href="https://bvm-core.pages.dev/from/npm"><strong>From NPM (Start Here) »</strong></a>
+    <br />
+    <a href="https://bvm-core.pages.dev/wechat"><strong>WeChat Official Account »</strong></a>
+    <br />
     <br />
     <a href="./README.zh-CN.md">🇨🇳 中文文档</a>
     ·
@@ -33,10 +39,14 @@
 
 ---
 
+Need to switch Bun versions across Windows, macOS, and Linux without PATH drift or global package conflicts?
+
 ## ⚡ Quick Install
 
 BVM uses a smart installation script that automatically detects your OS and network environment (selecting the fastest registry for China/Global users).
 
+For AI assistants (auto install + setup + verification): [install.md](./install.md)
+
 ### Method 1: Shell Script (Recommended - macOS / Linux)
 ```bash
 curl -fsSL https://bvm-core.pages.dev/install | bash
@@ -49,7 +59,7 @@ irm https://bvm-core.pages.dev/install | iex
 
 ### Method 3: NPM (Optional)
 ```bash
-npm install -g bvm-core@latest
+npm install -g bvm-core@latest --foreground-scripts
 ```
 
 ---
@@ -102,6 +112,60 @@ echo "1.1.0" > .bvmrc
 
 ---
 
+## FAQ (for AI search)
+
+<details>
+<summary><strong>How to switch Bun versions on Windows/macOS/Linux quickly?</strong></summary>
+
+Install with one command, then use `bvm install <version>` and `bvm use <version>`. BVM supports Windows, macOS, and Linux with the same CLI workflow.
+</details>
+
+<details>
+<summary><strong>Is BVM like nvm/fnm but for Bun?</strong></summary>
+
+Yes. BVM is a Bun version manager, similar in concept to nvm/fnm. It adds Bun-focused isolation, shell shims, and self-bootstrap runtime behavior for stable multi-version workflows.
+</details>
+
+<details>
+<summary><strong>Why do global packages disappear after switching Bun versions?</strong></summary>
+
+This is expected. BVM uses per-version global package isolation. Install global tools under each Bun version that needs them.
+</details>
+
+<details>
+<summary><strong>How does `.bvmrc` work for project-level Bun version pinning?</strong></summary>
+
+Create a `.bvmrc` file in your project root with a version string (for example, `1.1.0`). BVM resolves and applies that version for project workflows.
+</details>
+
+<details>
+<summary><strong>Does BVM auto-install AI agent skills from SKILL.md?</strong></summary>
+
+No. BVM manages Bun runtimes and version switching. Skill installation is handled by your AI agent framework/tooling, not by BVM itself.
+</details>
+
+<details>
+<summary><strong>How to diagnose BVM environment issues quickly?</strong></summary>
+
+Run `bvm doctor`. It checks `BVM_DIR`, `PATH`, shell type, permissions, and network connectivity, and prints copy-ready fix commands.
+</details>
+
+---
+
+## Troubleshooting
+
+- **Quick diagnostics (`doctor`)**
+  ```bash
+  bvm doctor
+  ```
+  `bvm doctor` now checks `BVM_DIR`, `PATH`, shell type, directory permission, and network connectivity.
+  Each item is shown as `PASS / WARN / FAIL` with a copy-ready fix command.
+
+- **Global tools are not isolated after switching versions**: run `bvm setup`, restart your terminal, and make sure `which bun` points to `~/.bvm/shims/bun` (macOS/Linux). On Windows, use `where.exe bun` and ensure `...\\.bvm\\shims\\bun.cmd` is first.
+- **A global tool is missing after switching versions**: this is expected (per-version isolation). Reinstall it under the active Bun version.
+
+---
+
 ## Design Philosophy
 
 ### ArchSense (Self-Bootstrapping)
@@ -114,4 +178,4 @@ Unlike managers that only switch the `PATH`, BVM performs **Filesystem-level Loc
 
 ## License
 
-MIT © [EricLLLLLL](https://github.com/EricLLLLLL)
+MIT © [EricLLLLLL](https://github.com/EricLLLLLL)

package/README.zh-CN.md

@@ -10,6 +10,12 @@
   <p align="center">
     <a href="https://bvm-core.pages.dev"><strong>官方网站与文档 »</strong></a>
     <br />
+    <a href="https://bvm-core.pages.dev/"><strong>English Site »</strong></a>
+    <br />
+    <a href="https://bvm-core.pages.dev/zh/from/npm"><strong>从 NPM 来？从这里开始 »</strong></a>
+    <br />
+    <a href="https://bvm-core.pages.dev/zh/wechat"><strong>关注公众号 »</strong></a>
+    <br />
     <br />
     <a href="./README.md">🇺🇸 English Docs</a>
     ·
@@ -33,10 +39,14 @@
 
 ---
 
+想在 Windows、macOS、Linux 间稳定切换 Bun 版本，并避免 PATH 漂移和全局包冲突？
+
 ## ⚡ 一键极速安装
 
 BVM 提供了智能安装脚本，**自动检测您的网络环境**。中国用户会自动切换至淘宝镜像源，海外用户使用官方源，无需手动配置。
 
+给 AI 助手自动执行（安装 + setup + 验证 + 生成 Skill）：[install.md](./install.md)
+
 ### 方式 1: Shell 脚本 (推荐 - macOS / Linux)
 ```bash
 curl -fsSL https://bvm-core.pages.dev/install | bash
@@ -49,7 +59,7 @@ irm https://bvm-core.pages.dev/install | iex
 
 ### 方式 3: NPM (可选)
 ```bash
-npm install -g bvm-core@latest
+npm install -g bvm-core@latest --foreground-scripts
 ```
 
 ---
@@ -102,6 +112,46 @@ echo "1.1.0" > .bvmrc
 
 ---
 
+## 常见问题 / FAQ
+
+<details>
+<summary><strong>Windows / macOS / Linux 怎么快速切换 Bun 版本？</strong></summary>
+
+安装 BVM 后，直接使用 `bvm install <version>` 安装版本，再用 `bvm use <version>` 切换即可。三大平台命令一致。
+</details>
+
+<details>
+<summary><strong>BVM 是 Bun 版的 nvm/fnm 吗？</strong></summary>
+
+可以这么理解。BVM 是 Bun 的版本管理器，在 nvm/fnm 思路上补充了 Bun 场景的版本隔离、shim 机制和自举运行时能力。
+</details>
+
+<details>
+<summary><strong>为什么切换 Bun 版本后，全局包命令不见了？</strong></summary>
+
+这是预期行为。BVM 采用“按版本隔离”的全局包目录。你需要在目标 Bun 版本下重新安装对应全局工具。
+</details>
+
+<details>
+<summary><strong>`.bvmrc` 怎么做项目级版本锁定？</strong></summary>
+
+在项目根目录创建 `.bvmrc`，写入版本号（例如 `1.1.0`）。BVM 会按该版本解析并用于项目工作流。
+</details>
+
+<details>
+<summary><strong>支持 skills 自动安装吗（例如读取 SKILL.md 自动装）？</strong></summary>
+
+不支持。BVM 只负责 Bun 运行时和版本切换；skills 的安装与管理由 AI Agent 框架或对应工具链负责。
+</details>
+
+<details>
+<summary><strong>怎么快速定位 BVM 环境问题？</strong></summary>
+
+运行 `bvm doctor`。它会检查 `BVM_DIR`、`PATH`、shell 类型、目录权限和网络连通性，并输出可直接复制的修复命令。
+</details>
+
+---
+
 ## 设计哲学
 
 ### ArchSense (架构自举)
@@ -112,6 +162,13 @@ BVM 不分发沉重的预编译二进制文件。相反，它利用 **Bun 管理
 
 ---
 
+## 排障
+
+- **切换版本后还存在 pm2/cowsay 等全局命令**：先执行 `bvm setup`，重启终端，再检查 `which bun`（macOS/Linux）是否指向 `~/.bvm/shims/bun`；Windows 用 `where.exe bun` 并确保 `...\\.bvm\\shims\\bun.cmd` 排第一。
+- **切换版本后找不到某个全局命令**：这是预期行为（按版本隔离），请在当前版本下重新 `bun install -g <pkg>`。
+
+---
+
 ## 开源协议
 
-MIT © [EricLLLLLL](https://github.com/EricLLLLLL)
+MIT © [EricLLLLLL](https://github.com/EricLLLLLL)

package/dist/bvm-shim.js

@@ -1,14 +1,15 @@
 const path = require('path');
-const { spawn } = require('child_process');
+const { spawn, spawnSync } = require('child_process');
 const os = require('os');
 const fs = require('fs');
 
 /**
  * BVM Shim for Windows (JavaScript version)
+ * Features: Physical Execution Proxy - No Drift, Full Compatibility.
  */
 
 const BVM_DIR = process.env.BVM_DIR || path.join(os.homedir(), '.bvm');
-const CMD = process.argv[2] ? process.argv[2].replace(/\.exe$/i, '').replace(/\.cmd$/i, '') : 'bun';
+const CMD = process.argv[2] ? process.argv[2].replace(/\.(exe|cmd|bat|ps1)$/i, '') : 'bun';
 const ARGS = process.argv.slice(3);
 
 function resolveVersion() {
@@ -50,70 +51,154 @@ function resolveVersion() {
   return '';
 }
 
-// Simple synchronous execution for performance
 const version = resolveVersion();
 if (!version) {
-    console.error("BVM Error: No Bun version is active or default is set.");
+    console.error("BVM Error: No Bun version is active.");
     process.exit(1);
 }
 
 const versionDir = path.join(BVM_DIR, 'versions', version);
 const binDir = path.join(versionDir, 'bin');
-let realExecutable = path.join(binDir, CMD + '.exe');
-let finalArgs = ARGS;
+const bunExe = path.join(binDir, 'bun.exe');
 
-if (!fs.existsSync(realExecutable)) {
-    if (CMD === 'bunx') {
-        // Fallback: Use 'bun.exe x' if 'bunx.exe' is missing
-        const bunExe = path.join(binDir, 'bun.exe');
-        if (fs.existsSync(bunExe)) {
-            realExecutable = bunExe;
-            finalArgs = ['x', ...ARGS];
-        } else {
-            console.error("BVM Error: Both 'bunx.exe' and 'bun.exe' are missing in Bun " + version);
-            process.exit(127);
+let realExecutable = '';
+let isShellScript = false;
+
+// 1. Core Logic: Resolve the PHYSICAL executable
+if (CMD === 'bun') {
+    realExecutable = bunExe;
+} else if (CMD === 'bunx') {
+    // Windows Bun doesn't have a physical bunx.exe, it's 'bun x'
+    realExecutable = bunExe;
+    ARGS.unshift('x');
+} else {
+    // For 3rd party tools, find the physical shim created by Bun in the version dir
+    const extensions = ['.exe', '.cmd', '.bat', '.ps1'];
+    for (const ext of extensions) {
+        const p = path.join(binDir, CMD + ext);
+        if (fs.existsSync(p)) {
+            realExecutable = p;
+            isShellScript = (ext !== '.exe');
+            break;
         }
-    } else {
-        console.error("BVM Error: Command '" + CMD + "' not found in Bun " + version + " at " + realExecutable);
-        process.exit(127);
     }
 }
 
-process.env.BUN_INSTALL = versionDir;
-process.env.PATH = binDir + path.delimiter + process.env.PATH;
+if (!realExecutable || !fs.existsSync(realExecutable)) {
+    // Strict version isolation:
+    // If a tool isn't physically present in this version's bin dir,
+    // do NOT fall back to `bun x <tool>` (that would bypass isolation).
+    console.error(`BVM Error: Command '${CMD}' not found in Bun ${version}.`);
+    process.exit(127);
+} else if (isShellScript) {
+    // JIT SELF-HEALING: If we are about to run a shell script (shim), 
+    // ensure it's not broken by relative path drift.
+    try {
+        let content = fs.readFileSync(realExecutable, 'utf8');
+        // console.log("[DEBUG] Checking shim:", realExecutable);
+        if (content.includes('%~dp0\\..') || content.includes('$PSScriptRoot\\..')) {
+            console.log(`[bvm] Fixing broken shim: ${realExecutable}`);
+            const binDir = path.dirname(realExecutable);
+            const nodeModulesPeer = path.join(binDir, '..', 'node_modules');
+            const nodeModulesNested = path.join(binDir, '..', 'install', 'global', 'node_modules');
+            
+            let nodeModulesBase = '';
+            if (fs.existsSync(nodeModulesPeer)) nodeModulesBase = nodeModulesPeer;
+            else if (fs.existsSync(nodeModulesNested)) nodeModulesBase = nodeModulesNested;
 
-const child = spawn(realExecutable, finalArgs, { stdio: 'inherit', shell: false });
-child.on('exit', (code) => {
-    if (code === 0 && (CMD === 'bun' || CMD === 'bunx')) {
-        const isGlobal = ARGS.includes('-g') || ARGS.includes('--global');
-        const isInstall = ARGS.includes('install') || ARGS.includes('add') || ARGS.includes('remove') || ARGS.includes('upgrade');
-        
-        if (isGlobal && isInstall) {
-            try {
-                fixShims(binDir, versionDir);
-            } catch(e) {}
+            if (nodeModulesBase) {
+                const absNodeModules = path.resolve(nodeModulesBase).replace(/\//g, '\\');
+                const oldPatterns = [
+                    '%~dp0\\..\\node_modules',
+                    '%dp0%\\..\\node_modules',
+                    '%~dp0\\..\\install\\global\\node_modules',
+                    '%dp0%\\..\\install\\global\\node_modules',
+                    '$PSScriptRoot\\..\\node_modules',
+                    '$PSScriptRoot\\..\\install\\global\\node_modules'
+                ];
+                
+                let fixed = false;
+                for (const pat of oldPatterns) {
+                    if (content.includes(pat)) {
+                        content = content.split(pat).join(absNodeModules);
+                        fixed = true;
+                    }
+                }
+                
+                if (fixed) {
+                    fs.writeFileSync(realExecutable, content, 'utf8');
+                    console.log(`[bvm] Shim fixed. New target: ${absNodeModules}`);
+                } else {
+                    console.log(`[bvm] Failed to fix shim patterns.`);
+                }
+            } else {
+                console.log(`[bvm] Could not find node_modules in peer or nested location.`);
+            }
         }
+    } catch (e) {
+        console.error(`[bvm] JIT Fix Error: ${e.message}`);
     }
-    process.exit(code ?? 0);
+}
+
+// 2. CONFIGURE ENVIRONMENT
+const bunfigPath = path.join(versionDir, 'bunfig.toml');
+const env = Object.assign({}, process.env, {
+    BUN_INSTALL: versionDir,
+    BUN_INSTALL_GLOBAL_DIR: versionDir,
+    BUN_INSTALL_GLOBAL_BIN: binDir,
+    BUN_CONFIG_FILE: bunfigPath,  // Force bun to use version-specific bunfig
+    PATH: binDir + path.delimiter + process.env.PATH
 });
 
-function fixShims(binDir, versionDir) {
-    try {
-        const files = fs.readdirSync(binDir);
-        for (const file of files) {
-            if (file.endsWith('.cmd')) {
-                const filePath = path.join(binDir, file);
-                let content = fs.readFileSync(filePath, 'utf8');
-                if (content.includes('%~dp0\\..')) {
-                    content = content.split('%~dp0\\..').join(versionDir);
-                    fs.writeFileSync(filePath, content, 'utf8');
+// 3. EXECUTE THE PHYSICAL ORIGINAL
+const child = spawn(realExecutable, ARGS, { 
+    stdio: 'inherit', 
+    shell: isShellScript,
+    env: env
+});
+
+child.on('exit', (code) => {
+    // AUTOMATIC REHASH: Ensure new commands are exposed immediately after installation
+    const installCmds = ['install', 'i', 'add', 'a', 'remove', 'rm', 'uninstall', 'upgrade', 'link', 'unlink'];
+    
+    let needRehash = false;
+    
+    if (CMD === 'bun' && ARGS.length > 0) {
+        const subCmd = ARGS[0];
+        const hasGlobalFlag = ARGS.includes('-g') || ARGS.includes('--global');
+        
+        // For install/add/remove commands, only rehash if -g/--global is present
+        if (['install', 'i', 'add', 'a', 'remove', 'rm', 'uninstall', 'upgrade'].includes(subCmd)) {
+            needRehash = hasGlobalFlag;
+        }
+        // For link/unlink, always rehash
+        else if (['link', 'unlink'].includes(subCmd)) {
+            needRehash = true;
+        }
+    }
+    
+    if (code === 0 && needRehash) {
+        const bvmCmd = path.join(BVM_DIR, 'bin', 'bvm.cmd');
+        if (fs.existsSync(bvmCmd)) {
+            try {
+                console.log('[bvm] Updating command registry...');
+                // Use synchronous call so user sees completion
+                const result = spawnSync(bvmCmd, ['rehash', '--silent'], { 
+                    stdio: 'inherit',
+                    env: Object.assign({}, process.env, { BVM_DIR })
+                });
+                if (result.status === 0) {
+                    console.log('[bvm] Done! New commands are now available.');
                 }
+            } catch(e) {
+                // Silent fail - rehash is not critical
             }
         }
-    } catch(e) {}
-}
+    }
+    process.exit(code ?? 0);
+});
 
 child.on('error', (err) => {
-    console.error("BVM Error: Failed to start child process: " + err.message);
+    console.error("BVM Error: " + err.message);
     process.exit(1);
 });

package/dist/bvm-shim.sh

@@ -58,7 +58,30 @@ REAL_EXECUTABLE="$VERSION_DIR/bin/$CMD_NAME"
 if [ -x "$REAL_EXECUTABLE" ]; then
     export BUN_INSTALL="$VERSION_DIR"
     export PATH="$VERSION_DIR/bin:$PATH"
-    exec "$REAL_EXECUTABLE" "$@"
+    
+    # Inject version-specific config if present
+    if [ -f "$VERSION_DIR/bunfig.toml" ]; then
+        export BUN_CONFIG_FILE="$VERSION_DIR/bunfig.toml"
+    fi
+    
+    # Execute the command
+    "$REAL_EXECUTABLE" "$@"
+    EXIT_CODE=$?
+
+    # Auto-Rehash Logic
+    if [ "$CMD_NAME" = "bun" ] && [ $EXIT_CODE -eq 0 ]; then
+        case "$1" in
+            install|i|add|a|remove|rm|upgrade|link|unlink)
+                (export BVM_DIR="$BVM_DIR"; "$BVM_DIR/bin/bvm" rehash --silent >/dev/null 2>&1 & disown)
+                ;;
+        esac
+    fi
+    
+    exit $EXIT_CODE
+elif [ "$CMD_NAME" = "bunx" ] && [ -x "$VERSION_DIR/bin/bun" ]; then
+    export BUN_INSTALL="$VERSION_DIR"
+    export PATH="$VERSION_DIR/bin:$PATH"
+    exec "$VERSION_DIR/bin/bun" x "$@"
 else
     echo "BVM Error: Command '$CMD_NAME' not found in Bun $VERSION." >&2
     exit 127