flxvm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flvm contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# flvm
+
+Flutter 多版本管理器 —— 基于 git worktree + 共享引擎缓存，专为**多分支场景**（OHOS 适配、内部 fork）设计，macOS / Windows / Linux 通用。
+
+## 特性
+
+- **秒级切换**：切换 = 改一个文件，全局立即生效
+- **多版本并存**：所有版本同时就绪，不同终端可跑不同版本
+- **省磁盘**：所有 worktree 共享同一份 `.git`；同引擎版本的补丁分支（如 `br_3.27.4-ohos-1.0.4` → `1.0.5`）**共享 `bin/cache`（Dart SDK + 引擎产物）**
+- **分支更新零下载**：`flvm update` 重建 worktree 但保留缓存，升级补丁分支不重下 SDK
+- **自动安装**：`flvm use` 未安装时自动从远程分支创建，支持模糊匹配
+
+## 安装
+
+```bash
+npm install -g flvm
+```
+
+## 使用
+
+```bash
+flvm init                  # 初始化，存储在默认目录 ~/.flvm
+flvm init ~/BigDisk/flvm   # 指定存储目录（macOS/Linux，支持 ~ 与相对路径）
+flvm init D:\flvm          # 指定存储目录（Windows）
+flvm list -r               # 查看远程可安装分支
+flvm use 3.27.4            # 安装并切换（模糊匹配 br_3.27.4-ohos-1.0.4）
+flvm use 3.22              # 切到已装版本（唯一匹配即可）
+flvm list                  # 查看已装版本（* 为当前）
+flvm update                # 全部版本更新到各自分支最新（保留缓存）
+flvm remove 3.22.3         # 删除版本（--purge-cache 顺带清理无引用缓存）
+```
+
+初始化后 `flutter` / `dart` 命令由 `<存储目录>/bin` 代理，始终执行当前选择的版本。
+
+存储目录优先级：`FLVM_HOME` 环境变量 > `flvm init <dir>` 设定的目录（记录在 `~/.flvm-home`）> 默认 `~/.flvm`。要恢复默认目录，运行 `flvm init ~/.flvm`。
+
+## 工作原理
+
+```
+<存储目录>/              # 默认 ~/.flvm，可用 flvm init <dir> 指定
+├── repo/            # 主仓库，唯一 .git（所有版本共享）
+├── worktrees/       # 各版本源码（git worktree，~400MB/版本）
+│   └── 3.27.4/      #   bin/cache → 软链到 caches/3.27.4
+├── caches/          # 引擎缓存真身（同引擎版本的补丁分支共享一份）
+├── bin/             # flutter/dart 代理命令
+└── default          # 当前版本名
+```
+
+切换原理：`flvm use <名>` 只重写 `default` 文件，代理命令按它转发，因此**无需修改 PATH、无需重新下载任何东西**。引擎缓存按版本号（从分支名提取 `x.y.z`）分组共享；若引擎 hash 不匹配，flutter 工具会自动重新下载该组缓存（自愈，不会出错）。
+
+## Windows 注意
+
+- `flvm init` 自动设置 `core.longpaths` 与 `core.autocrlf=false`
+- 缓存链接使用 NTFS junction，无需管理员权限
+- 建议为 `~/.flvm` 添加 Windows Defender 排除项以提升速度
+
+## 环境变量
+
+- `FLVM_HOME`：临时覆盖存储目录（优先级最高，不持久化）
+- `flvm init <dir>`：持久设定存储目录（推荐做法，记录在 `~/.flvm-home`）
+- `flvm init --no-mirror`：不写入国内镜像（默认写入 `PUB_HOSTED_URL` / `FLUTTER_STORAGE_BASE_URL`）
+
+## 开发
+
+```bash
+npm install
+npm run build    # tsc 编译
+npm test         # 编译 + 冒烟测试（本地假 git 仓库全流程）
+```
+
+## License
+
+MIT

package/dist/cache.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheGroupFor = cacheGroupFor;
+exports.linkCache = linkCache;
+exports.unlinkCache = unlinkCache;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const paths_1 = require("./paths");
+const util_1 = require("./util");
+/** 从分支名提取缓存组：br_3.27.4-ohos-1.0.4 → 3.27.4（同引擎版本的补丁分支共享缓存） */
+function cacheGroupFor(ref) {
+    const m = ref.match(/(\d+\.\d+\.\d+)/);
+    return m ? m[1] : ref.replace(/[/\\]/g, '-');
+}
+/**
+ * 删除链接本身（symlink / junction），绝不触碰其指向的共享缓存真身。
+ * 注意：不能用 fs.rmSync —— Node 对"指向目录的 symlink"会误判为目录抛 EISDIR。
+ */
+function removeLink(link) {
+    try {
+        node_fs_1.default.unlinkSync(link);
+    }
+    catch {
+        try {
+            node_fs_1.default.rmdirSync(link); // Windows junction 兜底
+        }
+        catch {
+            /* 不存在即可 */
+        }
+    }
+}
+/**
+ * 把 <worktree>/bin/cache 链接到共享缓存目录。
+ * macOS/Linux 用 symlink，Windows 用 junction（无需管理员权限）。
+ */
+function linkCache(worktreeDir, group) {
+    const cacheDir = node_path_1.default.join((0, paths_1.cachesDir)(), group);
+    const link = node_path_1.default.join(worktreeDir, 'bin', 'cache');
+    node_fs_1.default.mkdirSync(cacheDir, { recursive: true });
+    if ((0, util_1.exists)(link)) {
+        const st = node_fs_1.default.lstatSync(link);
+        if (st.isSymbolicLink()) {
+            removeLink(link);
+        }
+        else {
+            // 真实目录（个别分支提交过占位文件）：删除后替换为链接
+            node_fs_1.default.rmSync(link, { recursive: true, force: true });
+        }
+    }
+    node_fs_1.default.symlinkSync(cacheDir, link, process.platform === 'win32' ? 'junction' : 'dir');
+}
+/**
+ * 摘除 cache 链接（只删链接本身，绝不触碰共享缓存真身）。
+ * 必须在 git worktree remove 之前调用，避免误删共享缓存内容。
+ */
+function unlinkCache(worktreeDir) {
+    const link = node_path_1.default.join(worktreeDir, 'bin', 'cache');
+    if ((0, util_1.exists)(link) && node_fs_1.default.lstatSync(link).isSymbolicLink()) {
+        removeLink(link);
+    }
+}

package/dist/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const picocolors_1 = __importDefault(require("picocolors"));
+const init = __importStar(require("./commands/init"));
+const use = __importStar(require("./commands/use"));
+const list = __importStar(require("./commands/list"));
+const remove = __importStar(require("./commands/remove"));
+const update = __importStar(require("./commands/update"));
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const pkg = require('../package.json');
+const program = new commander_1.Command();
+program
+    .name('flvm')
+    .version(pkg.version)
+    .description('Flutter 多版本管理器（git worktree + 共享引擎缓存）');
+program
+    .command('init [dir]')
+    .description('初始化：<dir> 自定义存储目录（如 flvm init D:\\flvm，默认 ~/.flvm）')
+    .option('--url <git-url>', 'Flutter 仓库地址（支持 OHOS fork）', init.DEFAULT_URL)
+    .option('--no-mirror', '不写入国内镜像环境变量')
+    .option('--no-shell', '不修改 shell 配置文件（自行配置 PATH）')
+    .action(init.run);
+program
+    .command('use [query]')
+    .description('切换版本（未安装时自动安装，支持模糊匹配；无参数显示当前版本）')
+    .action(use.run);
+program
+    .command('list')
+    .alias('ls')
+    .description('列出已安装版本')
+    .option('-r, --remote', '显示远程可安装的分支')
+    .action(list.run);
+program
+    .command('remove <query>')
+    .alias('rm')
+    .description('删除已安装版本（共享缓存默认保留）')
+    .option('-f, --force', '忽略未提交改动')
+    .option('--purge-cache', '同时删除不再被引用的共享缓存')
+    .action(remove.run);
+program
+    .command('update')
+    .description('更新所有已安装版本到各自分支最新提交（保留缓存，秒级完成）')
+    .option('-f, --force', '忽略未提交改动')
+    .action(update.run);
+program.parseAsync(process.argv).catch((err) => {
+    console.error(picocolors_1.default.red(`✗ ${err.message}`));
+    process.exit(1);
+});

package/dist/commands/init.js

@@ -0,0 +1,71 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_URL = void 0;
+exports.run = run;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const paths_1 = require("../paths");
+const git_1 = require("../git");
+const shim_1 = require("../shim");
+const util_1 = require("../util");
+exports.DEFAULT_URL = 'https://gitcode.com/openharmony-tpc/flutter_flutter.git';
+async function run(dir, opts) {
+    // 0. 指定存储目录：记录到 ~/.flvm-home，之后所有命令与 shim 都使用该目录
+    if (dir) {
+        const oldHome = (0, paths_1.flvmHome)();
+        const abs = (0, paths_1.setFlvmHome)(dir);
+        console.log(picocolors_1.default.green(`✓ 存储目录已设定: ${abs}`));
+        console.log(picocolors_1.default.dim('  已记录，后续所有 flvm 命令与 flutter 代理命令都会使用此目录'));
+        if (oldHome !== abs && (0, util_1.exists)(node_path_1.default.join(oldHome, 'registry.json'))) {
+            console.log(picocolors_1.default.yellow(`  提示: ${oldHome} 下已有安装数据，切换目录后将不再使用它们`));
+        }
+    }
+    const home = (0, paths_1.flvmHome)();
+    node_fs_1.default.mkdirSync(home, { recursive: true });
+    node_fs_1.default.mkdirSync((0, paths_1.worktreesDir)(), { recursive: true });
+    node_fs_1.default.mkdirSync((0, paths_1.cachesDir)(), { recursive: true });
+    // 1. 主仓库（唯一 .git，之后所有版本共享）
+    if (!(0, util_1.exists)((0, paths_1.repoDir)())) {
+        console.log(picocolors_1.default.bold('克隆 Flutter 主仓库（仅此一次，之后所有版本共享 .git）…'));
+        console.log(picocolors_1.default.dim(`  ${opts.url}`));
+        (0, git_1.gitClone)(opts.url, (0, paths_1.repoDir)());
+    }
+    else {
+        console.log(picocolors_1.default.dim('主仓库已存在，跳过克隆'));
+    }
+    // 2. Windows 兼容配置（longpaths 防深层路径 checkout 失败；autocrlf 防 flutter 自检报错）
+    if (process.platform === 'win32') {
+        (0, git_1.git)(['config', 'core.longpaths', 'true'], { cwd: (0, paths_1.repoDir)() });
+        (0, git_1.git)(['config', 'core.autocrlf', 'false'], { cwd: (0, paths_1.repoDir)() });
+    }
+    // 3. git 排除规则：bin/cache 链接不计为未跟踪文件
+    (0, git_1.ensureGitExclude)();
+    // 3. flutter / dart 代理命令
+    (0, shim_1.installShims)();
+    // 4. shell PATH 集成
+    if (opts.shell) {
+        const written = (0, shim_1.setupShellIntegration)(opts.mirror);
+        for (const f of written) {
+            console.log(picocolors_1.default.green(`✓ 已写入 PATH 配置: ${f}`));
+        }
+        if (written.length === 0) {
+            console.log(picocolors_1.default.dim('shell 配置已包含 flvm，跳过'));
+        }
+    }
+    console.log('');
+    console.log(picocolors_1.default.green('✓ flvm 初始化完成'));
+    console.log('');
+    console.log('下一步:');
+    console.log(`  ${picocolors_1.default.cyan('flvm list -r')}         查看远程可安装的分支`);
+    console.log(`  ${picocolors_1.default.cyan('flvm use 3.27.4')}      安装并切换（首次会自动创建 worktree）`);
+    if (opts.shell) {
+        console.log(picocolors_1.default.dim('  注意: 请打开新终端使 PATH 生效；若 PATH 中已有其他 flutter，请将其移除'));
+    }
+    else {
+        console.log(picocolors_1.default.dim(`  注意: 已跳过 shell 配置，请手动将 ${home}/bin 加入 PATH`));
+    }
+}

package/dist/commands/list.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const picocolors_1 = __importDefault(require("picocolors"));
+const paths_1 = require("../paths");
+const git_1 = require("../git");
+const util_1 = require("../util");
+const worktree_1 = require("../worktree");
+async function run(opts) {
+    (0, util_1.ensureInit)();
+    if (!opts.remote) {
+        const reg = (0, paths_1.readRegistry)();
+        const names = Object.keys(reg);
+        if (names.length === 0) {
+            console.log('尚未安装任何版本');
+            console.log(`  运行 ${picocolors_1.default.cyan('flvm list -r')} 查看远程分支，${picocolors_1.default.cyan('flvm use <版本>')} 安装`);
+            return;
+        }
+        const cur = (0, paths_1.getDefault)();
+        console.log(picocolors_1.default.bold('已安装版本:'));
+        for (const name of names) {
+            const e = reg[name];
+            const mark = name === cur ? picocolors_1.default.green('*') : ' ';
+            console.log(` ${mark} ${name.padEnd(12)} ${e.ref.padEnd(28)} ` +
+                `${e.commit.slice(0, 8)}  ${(0, git_1.commitDate)(e.commit)}  cache:${e.cacheGroup}`);
+        }
+        return;
+    }
+    // 远程分支视图
+    (0, git_1.fetchAll)();
+    const branches = (0, git_1.listRemoteBranches)();
+    if (branches.length === 0) {
+        console.log(picocolors_1.default.yellow('远程没有分支，请检查 flvm init --url'));
+        return;
+    }
+    const installedRefs = new Set(Object.values((0, paths_1.readRegistry)()).map((e) => e.ref));
+    console.log(picocolors_1.default.bold(`远程分支（共 ${branches.length} 个）:`));
+    for (const b of branches.sort()) {
+        const tag = installedRefs.has(b) ? picocolors_1.default.green(' [已安装]') : '';
+        console.log(`  ${(0, worktree_1.nameForRef)(b).padEnd(12)} ${b}${tag}`);
+    }
+    console.log('');
+    console.log(picocolors_1.default.dim(`安装: flvm use <版本号或分支名关键词>`));
+}

package/dist/commands/remove.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const paths_1 = require("../paths");
+const git_1 = require("../git");
+const cache_1 = require("../cache");
+const util_1 = require("../util");
+const worktree_1 = require("../worktree");
+async function run(query, opts) {
+    (0, util_1.ensureInit)();
+    const m = (0, worktree_1.findInstalled)(query);
+    if (m.kind === 'none') {
+        console.log(picocolors_1.default.red(`✗ 未找到版本 "${query}"，运行 flvm list 查看已安装版本`));
+        return;
+    }
+    if (m.kind === 'ambiguous') {
+        (0, worktree_1.printCandidates)('匹配到多个已安装版本:', m.candidates);
+        return;
+    }
+    const { name, entry } = m;
+    const dir = node_path_1.default.join((0, paths_1.worktreesDir)(), name);
+    if (!opts.force && (0, git_1.isDirty)(dir)) {
+        console.log(picocolors_1.default.red(`✗ ${name} 有未提交改动，如确认放弃请使用: flvm remove ${name} --force`));
+        return;
+    }
+    // 先摘缓存链接（只删链接本身），再删 worktree —— 保证共享缓存不被误删
+    (0, cache_1.unlinkCache)(dir);
+    if ((0, util_1.exists)(dir))
+        (0, git_1.worktreeRemove)(dir);
+    const reg = (0, paths_1.readRegistry)();
+    delete reg[name];
+    (0, paths_1.writeRegistry)(reg);
+    // 处理共享缓存
+    if (opts.purgeCache) {
+        const stillUsed = Object.values(reg).some((e) => e.cacheGroup === entry.cacheGroup);
+        if (stillUsed) {
+            console.log(picocolors_1.default.dim(`  缓存组 ${entry.cacheGroup} 仍被其他版本使用，保留`));
+        }
+        else {
+            node_fs_1.default.rmSync(node_path_1.default.join((0, paths_1.cachesDir)(), entry.cacheGroup), { recursive: true, force: true });
+            console.log(picocolors_1.default.dim(`  已删除缓存组 ${entry.cacheGroup}`));
+        }
+    }
+    if ((0, paths_1.getDefault)() === name) {
+        (0, paths_1.setDefault)(null);
+        console.log(picocolors_1.default.yellow(`  当前默认版本已被删除，请重新 flvm use`));
+    }
+    console.log(picocolors_1.default.green(`✓ 已删除 ${name} (${entry.ref})`));
+}

package/dist/commands/update.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const node_path_1 = __importDefault(require("node:path"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const paths_1 = require("../paths");
+const git_1 = require("../git");
+const cache_1 = require("../cache");
+const util_1 = require("../util");
+/** 更新全部已安装版本到各自分支的最新提交（保留共享缓存，不重新下载 SDK） */
+async function run(opts) {
+    (0, util_1.ensureInit)();
+    const reg = (0, paths_1.readRegistry)();
+    const names = Object.keys(reg);
+    if (names.length === 0) {
+        console.log('没有已安装版本，运行 flvm use <版本> 先安装');
+        return;
+    }
+    console.log(picocolors_1.default.dim('拉取远程更新…'));
+    (0, git_1.fetchAll)();
+    (0, git_1.worktreePrune)();
+    let updated = 0;
+    let uptodate = 0;
+    let skipped = 0;
+    for (const name of names) {
+        const e = reg[name];
+        const dir = node_path_1.default.join((0, paths_1.worktreesDir)(), name);
+        try {
+            const { spec, commit } = (0, git_1.resolveRef)(e.ref);
+            if ((0, util_1.exists)(dir) && commit === e.commit) {
+                console.log(`${picocolors_1.default.dim('=')} ${name} ${picocolors_1.default.dim('已最新')}`);
+                uptodate++;
+                continue;
+            }
+            if (!(0, util_1.exists)(dir)) {
+                // worktree 目录丢失（曾被手动删除）→ 直接重建
+                (0, git_1.worktreeAdd)(dir, spec);
+                (0, cache_1.linkCache)(dir, e.cacheGroup);
+                e.commit = commit;
+                e.updatedAt = new Date().toISOString();
+                console.log(`${picocolors_1.default.green('✓')} ${name} ${picocolors_1.default.dim('重建')} ${e.ref} (${commit.slice(0, 8)})`);
+                updated++;
+                continue;
+            }
+            if (!opts.force && (0, git_1.isDirty)(dir)) {
+                console.log(`${picocolors_1.default.yellow('!')} ${name} ${picocolors_1.default.yellow('有未提交改动，跳过（--force 强制）')}`);
+                skipped++;
+                continue;
+            }
+            // 保缓存更新：摘链接 → 删 worktree → 建新 worktree → 挂回链接
+            (0, cache_1.unlinkCache)(dir);
+            (0, git_1.worktreeRemove)(dir);
+            (0, git_1.worktreeAdd)(dir, spec);
+            (0, cache_1.linkCache)(dir, e.cacheGroup);
+            const old = e.commit.slice(0, 8);
+            e.commit = commit;
+            e.updatedAt = new Date().toISOString();
+            console.log(`${picocolors_1.default.green('✓')} ${name} ${e.ref} ${picocolors_1.default.dim(`${old} → ${commit.slice(0, 8)}`)}`);
+            updated++;
+        }
+        catch (err) {
+            console.log(`${picocolors_1.default.red('!')} ${name} 更新失败: ${err.message.split('\n')[0]}`);
+            skipped++;
+        }
+    }
+    (0, paths_1.writeRegistry)(reg);
+    console.log('');
+    console.log(`结果: ${picocolors_1.default.green(`${updated} 更新`)} / ${uptodate} 已最新 / ${skipped} 跳过`);
+}

package/dist/commands/use.js

@@ -0,0 +1,71 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const node_path_1 = __importDefault(require("node:path"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const paths_1 = require("../paths");
+const git_1 = require("../git");
+const util_1 = require("../util");
+const worktree_1 = require("../worktree");
+function printCurrent() {
+    const name = (0, paths_1.getDefault)();
+    if (!name) {
+        console.log(picocolors_1.default.yellow('当前未选择版本，运行: flvm use <版本>'));
+        return;
+    }
+    const e = (0, paths_1.readRegistry)()[name];
+    console.log(picocolors_1.default.green(`✓ Flutter → ${name}`));
+    if (e)
+        console.log(`  分支: ${e.ref} (${e.commit.slice(0, 8)})`);
+    console.log(`  路径: ${node_path_1.default.join((0, paths_1.worktreesDir)(), name)}`);
+}
+async function run(query) {
+    (0, util_1.ensureInit)();
+    if (!query) {
+        printCurrent();
+        return;
+    }
+    // 1. 已安装：精确名 / 模糊匹配 → 直接切换
+    const m = (0, worktree_1.findInstalled)(query);
+    if (m.kind === 'ok') {
+        (0, paths_1.setDefault)(m.name);
+        printCurrent();
+        return;
+    }
+    if (m.kind === 'ambiguous') {
+        (0, worktree_1.printCandidates)('匹配到多个已安装版本:', m.candidates);
+        return;
+    }
+    // 2. 未安装：拉取远程分支并模糊匹配 → 自动安装
+    console.log(picocolors_1.default.dim('未匹配到已安装版本，正在获取远程分支…'));
+    (0, git_1.fetchAll)();
+    const branches = (0, git_1.listRemoteBranches)().filter((b) => b.includes(query));
+    if (branches.length === 0) {
+        console.log(picocolors_1.default.red(`✗ 没有匹配 "${query}" 的远程分支，运行 flvm list -r 查看全部`));
+        return;
+    }
+    if (branches.length > 1) {
+        console.log(`匹配到多个远程分支:`);
+        for (const b of branches) {
+            console.log(`  ${(0, worktree_1.nameForRef)(b).padEnd(12)} ${b}`);
+        }
+        console.log('请使用更精确的名称重试');
+        return;
+    }
+    const ref = branches[0];
+    const name = (0, worktree_1.nameForRef)(ref);
+    const reg = (0, paths_1.readRegistry)();
+    if (reg[name] && reg[name].ref !== ref) {
+        throw new Error(`版本名 "${name}" 已被 ${reg[name].ref} 占用。\n` +
+            `  如需换分支: flvm remove ${name} 后重新 flvm use ${ref}`);
+    }
+    console.log(`安装 ${picocolors_1.default.cyan(ref)} → worktree "${name}" …`);
+    const entry = (0, worktree_1.installWorktree)(name, ref);
+    (0, paths_1.setDefault)(name);
+    console.log(picocolors_1.default.green(`✓ Flutter → ${name} (${entry.ref})`));
+    console.log(`  路径: ${node_path_1.default.join((0, paths_1.worktreesDir)(), name)}`);
+    console.log(picocolors_1.default.dim('  首次运行 flutter 会下载 Dart SDK / 引擎产物（同引擎版本的分支将共享此缓存）'));
+}

package/dist/git.js

@@ -0,0 +1,125 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureGitExclude = ensureGitExclude;
+exports.git = git;
+exports.gitClone = gitClone;
+exports.fetchAll = fetchAll;
+exports.listRemoteBranches = listRemoteBranches;
+exports.resolveRef = resolveRef;
+exports.commitDate = commitDate;
+exports.isDirty = isDirty;
+exports.worktreeAdd = worktreeAdd;
+exports.worktreeRemove = worktreeRemove;
+exports.worktreePrune = worktreePrune;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const paths_1 = require("./paths");
+/**
+ * 向主仓库 .git/info/exclude 写入 bin/cache 排除规则（对所有 worktree 生效）。
+ * 必要性：bin/cache 是 symlink 时，仓库自带 .gitignore 的目录规则（bin/cache/）匹配不到它，
+ * git status 会误报未跟踪文件。
+ */
+function ensureGitExclude() {
+    const exclude = node_path_1.default.join((0, paths_1.repoDir)(), '.git', 'info', 'exclude');
+    let content = '';
+    try {
+        content = node_fs_1.default.readFileSync(exclude, 'utf8');
+    }
+    catch {
+        content = '';
+    }
+    if (!content.split('\n').some((l) => l.trim() === 'bin/cache')) {
+        const prefix = content && !content.endsWith('\n') ? '\n' : '';
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(exclude), { recursive: true });
+        node_fs_1.default.appendFileSync(exclude, `${prefix}\n# flvm: engine cache link\nbin/cache\n`);
+    }
+}
+/** 执行 git 命令，失败抛出含 stderr 的 Error */
+function git(args, opts = {}) {
+    const r = (0, node_child_process_1.spawnSync)('git', args, {
+        cwd: opts.cwd,
+        encoding: 'utf8',
+        stdio: opts.inherit ? 'inherit' : ['ignore', 'pipe', 'pipe'],
+        maxBuffer: 1024 * 1024 * 64,
+    });
+    if (r.status !== 0) {
+        const err = r.stderr || String(r.error?.message || '');
+        throw new Error(`git ${args.join(' ')} 失败:\n${err.trim()}`);
+    }
+    return opts.inherit ? '' : String(r.stdout).trim();
+}
+/** 克隆主仓库（进度直接输出到终端） */
+function gitClone(url, dest) {
+    const r = (0, node_child_process_1.spawnSync)('git', ['clone', url, dest], { stdio: 'inherit' });
+    if (r.status !== 0)
+        throw new Error(`克隆失败: ${url}`);
+}
+/** 拉取全部远程分支与 tag */
+function fetchAll() {
+    git(['fetch', '--all', '--prune', '--tags'], { cwd: (0, paths_1.repoDir)(), inherit: true });
+}
+/** 列出 origin 的全部分支名（去 origin/ 前缀） */
+function listRemoteBranches() {
+    const out = git(['for-each-ref', '--format=%(refname:short)', 'refs/remotes/origin'], {
+        cwd: (0, paths_1.repoDir)(),
+    });
+    return out
+        .split('\n')
+        .map((s) => s.trim())
+        .filter((s) => s && !s.startsWith('origin/HEAD'))
+        .map((s) => s.replace(/^origin\//, ''));
+}
+/** 解析 ref 为可用 spec + commit。优先 origin/<ref>，其次 ref 本身（tag/commit） */
+function resolveRef(ref) {
+    const candidates = [`origin/${ref}`, ref];
+    for (const spec of candidates) {
+        try {
+            const commit = git(['rev-parse', '--verify', `${spec}^{commit}`], { cwd: (0, paths_1.repoDir)() });
+            if (commit)
+                return { spec, commit };
+        }
+        catch {
+            /* 尝试下一个 */
+        }
+    }
+    throw new Error(`找不到分支或提交: ${ref}（可先运行 flvm update 拉取最新）`);
+}
+/** commit 的提交日期（YYYY-MM-DD） */
+function commitDate(commit) {
+    try {
+        return git(['show', '-s', '--format=%cs', commit], { cwd: (0, paths_1.repoDir)() });
+    }
+    catch {
+        return '?';
+    }
+}
+/** worktree 是否有未提交改动（含未跟踪文件；忽略 bin/cache 链接） */
+function isDirty(dir) {
+    try {
+        const out = git(['-C', dir, 'status', '--porcelain']);
+        return out
+            .split('\n')
+            .some((l) => l.trim() && !l.trim().endsWith('bin/cache'));
+    }
+    catch {
+        return false;
+    }
+}
+function worktreeAdd(dir, spec) {
+    git(['worktree', 'add', '--detach', dir, spec], { cwd: (0, paths_1.repoDir)() });
+}
+function worktreeRemove(dir) {
+    git(['worktree', 'remove', '--force', dir], { cwd: (0, paths_1.repoDir)() });
+}
+function worktreePrune() {
+    try {
+        git(['worktree', 'prune'], { cwd: (0, paths_1.repoDir)() });
+    }
+    catch {
+        /* 无害 */
+    }
+}

package/dist/paths.js

@@ -0,0 +1,102 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registryFile = exports.defaultFile = exports.binDir = exports.cachesDir = exports.worktreesDir = exports.repoDir = void 0;
+exports.homeMarkerFile = homeMarkerFile;
+exports.flvmHome = flvmHome;
+exports.setFlvmHome = setFlvmHome;
+exports.readRegistry = readRegistry;
+exports.writeRegistry = writeRegistry;
+exports.getDefault = getDefault;
+exports.setDefault = setDefault;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+/** 记录自定义存储目录的标记文件（固定在用户主目录，跨 shell / 跨平台持久） */
+function homeMarkerFile() {
+    return node_path_1.default.join(node_os_1.default.homedir(), '.flvm-home');
+}
+/** 展开 ~ 并转为绝对路径 */
+function resolveTilde(p) {
+    if (p === '~')
+        return node_os_1.default.homedir();
+    if (p.startsWith('~/') || p.startsWith('~\\')) {
+        return node_path_1.default.join(node_os_1.default.homedir(), p.slice(2));
+    }
+    return node_path_1.default.resolve(p);
+}
+/**
+ * flvm 根目录。优先级：
+ *   1. FLVM_HOME 环境变量（临时覆盖，便于测试）
+ *   2. flvm init <dir> 记录的目录（~/.flvm-home 标记文件）
+ *   3. 默认 ~/.flvm
+ */
+function flvmHome() {
+    if (process.env.FLVM_HOME)
+        return resolveTilde(process.env.FLVM_HOME);
+    try {
+        const v = node_fs_1.default.readFileSync(homeMarkerFile(), 'utf8').trim();
+        if (v)
+            return resolveTilde(v);
+    }
+    catch {
+        /* 无标记文件，走默认 */
+    }
+    return node_path_1.default.join(node_os_1.default.homedir(), '.flvm');
+}
+/** 记录自定义存储目录（flvm init <dir>），返回解析后的绝对路径 */
+function setFlvmHome(dir) {
+    const abs = resolveTilde(dir);
+    node_fs_1.default.mkdirSync(abs, { recursive: true });
+    node_fs_1.default.writeFileSync(homeMarkerFile(), abs + '\n');
+    return abs;
+}
+const repoDir = () => node_path_1.default.join(flvmHome(), 'repo');
+exports.repoDir = repoDir;
+const worktreesDir = () => node_path_1.default.join(flvmHome(), 'worktrees');
+exports.worktreesDir = worktreesDir;
+const cachesDir = () => node_path_1.default.join(flvmHome(), 'caches');
+exports.cachesDir = cachesDir;
+const binDir = () => node_path_1.default.join(flvmHome(), 'bin');
+exports.binDir = binDir;
+const defaultFile = () => node_path_1.default.join(flvmHome(), 'default');
+exports.defaultFile = defaultFile;
+const registryFile = () => node_path_1.default.join(flvmHome(), 'registry.json');
+exports.registryFile = registryFile;
+function readRegistry() {
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync((0, exports.registryFile)(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeRegistry(reg) {
+    node_fs_1.default.mkdirSync(flvmHome(), { recursive: true });
+    node_fs_1.default.writeFileSync((0, exports.registryFile)(), JSON.stringify(reg, null, 2) + '\n');
+}
+/** 当前默认版本名，未设置返回 null */
+function getDefault() {
+    try {
+        const v = node_fs_1.default.readFileSync((0, exports.defaultFile)(), 'utf8').trim();
+        return v || null;
+    }
+    catch {
+        return null;
+    }
+}
+function setDefault(name) {
+    if (name === null) {
+        try {
+            node_fs_1.default.unlinkSync((0, exports.defaultFile)());
+        }
+        catch {
+            /* 不存在即可 */
+        }
+    }
+    else {
+        node_fs_1.default.writeFileSync((0, exports.defaultFile)(), name);
+    }
+}

package/dist/shim.js

@@ -0,0 +1,123 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installShims = installShims;
+exports.setupShellIntegration = setupShellIntegration;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const paths_1 = require("./paths");
+const util_1 = require("./util");
+const MARKER = '>>> flvm >>>';
+/** sh 版代理脚本（macOS / Linux） */
+function shShim(tool) {
+    const home = (0, paths_1.flvmHome)();
+    return `#!/bin/sh
+FLVM_HOME="\${FLVM_HOME:-}"
+if [ -z "$FLVM_HOME" ] && [ -f "$HOME/.flvm-home" ]; then
+  FLVM_HOME="$(cat "$HOME/.flvm-home")"
+fi
+if [ -z "$FLVM_HOME" ]; then
+  FLVM_HOME="${home}"
+fi
+NAME="$(cat "$FLVM_HOME/default" 2>/dev/null)"
+if [ -z "$NAME" ] || [ ! -d "$FLVM_HOME/worktrees/$NAME" ]; then
+  echo "flvm: 尚未选择 Flutter 版本，请运行: flvm use <版本>" >&2
+  exit 1
+fi
+exec "$FLVM_HOME/worktrees/$NAME/bin/${tool}" "$@"
+`;
+}
+/** cmd 版代理脚本（Windows，同时供 cmd / PowerShell 使用） */
+function cmdShim(tool) {
+    const home = (0, paths_1.flvmHome)();
+    return `@echo off
+setlocal
+if "%FLVM_HOME%"=="" (
+  if exist "%USERPROFILE%\\.flvm-home" set /p FLVM_HOME=<"%USERPROFILE%\\.flvm-home"
+)
+if "%FLVM_HOME%"=="" set "FLVM_HOME=${home}"
+set "NAME="
+if exist "%FLVM_HOME%\\default" set /p NAME=<"%FLVM_HOME%\\default"
+if "%NAME%"=="" goto :err
+if not exist "%FLVM_HOME%\\worktrees\\%NAME%\\bin\\${tool}.bat" goto :err
+call "%FLVM_HOME%\\worktrees\\%NAME%\\bin\\${tool}.bat" %*
+exit /b %ERRORLEVEL%
+:err
+echo flvm: 尚未选择 Flutter 版本，请运行: flvm use ^<版本^>
+exit /b 1
+`;
+}
+/**
+ * 在 ~/.flvm/bin 下安装 flutter / dart 代理命令。
+ * 代理读取 ~/.flvm/default 决定转发目标，因此「切换版本 = 改一个文件」，秒级生效。
+ */
+function installShims() {
+    node_fs_1.default.mkdirSync((0, paths_1.binDir)(), { recursive: true });
+    for (const tool of ['flutter', 'dart']) {
+        if (process.platform !== 'win32') {
+            const p = node_path_1.default.join((0, paths_1.binDir)(), tool);
+            node_fs_1.default.writeFileSync(p, shShim(tool), { mode: 0o755 });
+        }
+        else {
+            node_fs_1.default.writeFileSync(node_path_1.default.join((0, paths_1.binDir)(), `${tool}.cmd`), cmdShim(tool));
+        }
+    }
+}
+function shBlock(mirror) {
+    const home = (0, paths_1.flvmHome)();
+    const env = mirror
+        ? `\nexport PUB_HOSTED_URL="https://pub.flutter-io.cn"\nexport FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"`
+        : '';
+    return `\n# ${MARKER}\nexport PATH="${home}/bin:$PATH"${env}\n# <<< flvm <<<\n`;
+}
+function psBlock(mirror) {
+    const home = (0, paths_1.flvmHome)();
+    const env = mirror
+        ? `\n$env:PUB_HOSTED_URL = "https://pub.flutter-io.cn"\n$env:FLUTTER_STORAGE_BASE_URL = "https://storage.flutter-io.cn"`
+        : '';
+    return `\n# ${MARKER}\n$env:PATH = "${home}\\bin;$env:PATH"${env}\n# <<< flvm <<<\n`;
+}
+function appendBlock(file, block) {
+    let content = '';
+    try {
+        content = node_fs_1.default.readFileSync(file, 'utf8');
+    }
+    catch {
+        content = '';
+    }
+    if (content.includes(MARKER))
+        return false;
+    const prefix = content && !content.endsWith('\n') ? '\n' : '';
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    node_fs_1.default.appendFileSync(file, prefix + block);
+    return true;
+}
+/**
+ * 把 ~/.flvm/bin 写入 shell 配置（幂等，带标记块）。
+ * 返回被修改的配置文件路径列表。
+ */
+function setupShellIntegration(mirror) {
+    const written = [];
+    if (process.platform === 'win32') {
+        const docs = process.env.OneDrive
+            ? node_path_1.default.join(process.env.OneDrive, 'Documents')
+            : node_path_1.default.join(node_os_1.default.homedir(), 'Documents');
+        const ps7 = node_path_1.default.join(docs, 'PowerShell', 'Microsoft.PowerShell_profile.ps1');
+        const ps5 = node_path_1.default.join(docs, 'WindowsPowerShell', 'Microsoft.PowerShell_profile.ps1');
+        const target = (0, util_1.exists)(ps7) ? ps7 : (0, util_1.exists)(ps5) ? ps5 : ps7;
+        if (appendBlock(target, psBlock(mirror)))
+            written.push(target);
+    }
+    else {
+        const shell = process.env.SHELL || '';
+        const rc = shell.includes('zsh') || process.platform === 'darwin'
+            ? node_path_1.default.join(node_os_1.default.homedir(), '.zshrc')
+            : node_path_1.default.join(node_os_1.default.homedir(), '.bashrc');
+        if (appendBlock(rc, shBlock(mirror)))
+            written.push(rc);
+    }
+    return written;
+}

package/dist/util.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exists = exists;
+exports.ensureInit = ensureInit;
+const node_fs_1 = __importDefault(require("node:fs"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const paths_1 = require("./paths");
+/** lstat 判断存在（对 dangling symlink 也返回 true） */
+function exists(p) {
+    try {
+        node_fs_1.default.lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 确保已执行 flvm init，否则引导用户 */
+function ensureInit() {
+    if (!exists((0, paths_1.repoDir)())) {
+        console.error(picocolors_1.default.red('✗ flvm 尚未初始化，请先运行: flvm init'));
+        process.exit(1);
+    }
+}

package/dist/worktree.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nameForRef = nameForRef;
+exports.installWorktree = installWorktree;
+exports.findInstalled = findInstalled;
+exports.printCandidates = printCandidates;
+const node_path_1 = __importDefault(require("node:path"));
+const paths_1 = require("./paths");
+const git_1 = require("./git");
+const cache_1 = require("./cache");
+const util_1 = require("./util");
+/** worktree 目录名：优先取分支名中的 x.y.z 版本号，取不到则清洗分支名 */
+function nameForRef(ref) {
+    const m = ref.match(/(\d+\.\d+\.\d+)/);
+    return m ? m[1] : ref.replace(/[/\\]/g, '-');
+}
+/**
+ * 创建 worktree 并挂共享缓存，登记到注册表。
+ * 返回版本名。
+ */
+function installWorktree(name, ref) {
+    const dir = node_path_1.default.join((0, paths_1.worktreesDir)(), name);
+    if ((0, util_1.exists)(dir)) {
+        throw new Error(`目录已存在: ${dir}，如需重建请先 flvm remove ${name}`);
+    }
+    (0, git_1.worktreePrune)();
+    (0, git_1.ensureGitExclude)();
+    const { spec, commit } = (0, git_1.resolveRef)(ref);
+    (0, git_1.worktreeAdd)(dir, spec);
+    const group = (0, cache_1.cacheGroupFor)(ref);
+    (0, cache_1.linkCache)(dir, group);
+    const now = new Date().toISOString();
+    const entry = { ref, commit, cacheGroup: group, installedAt: now, updatedAt: now };
+    const reg = (0, paths_1.readRegistry)();
+    reg[name] = entry;
+    (0, paths_1.writeRegistry)(reg);
+    return entry;
+}
+/** 在已安装版本中查找：精确名 → 名字/分支名子串模糊匹配 */
+function findInstalled(query) {
+    const reg = (0, paths_1.readRegistry)();
+    if (reg[query])
+        return { kind: 'ok', name: query, entry: reg[query] };
+    const hits = Object.entries(reg).filter(([n, e]) => n.includes(query) || e.ref.includes(query));
+    if (hits.length === 1)
+        return { kind: 'ok', name: hits[0][0], entry: hits[0][1] };
+    if (hits.length > 1)
+        return { kind: 'ambiguous', candidates: hits };
+    return { kind: 'none' };
+}
+function printCandidates(title, items) {
+    console.log(title);
+    for (const [n, e] of items) {
+        console.log(`  ${n.padEnd(12)} ${e.ref}`);
+    }
+    console.log('请使用更精确的名称重试');
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "flxvm",
+  "version": "0.1.0",
+  "description": "Flutter multi-version manager based on git worktree with shared engine cache (OHOS friendly)",
+  "bin": {
+    "flvm": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "test": "npm run build && bash test/smoke.sh",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "flutter",
+    "version",
+    "manager",
+    "worktree",
+    "ohos",
+    "harmonyos",
+    "fvm-alternative"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0",
+    "picocolors": "^1.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  }
+}