jvm-manager-cli 1.0.0 → 1.1.0

package/AGENTS.md

@@ -0,0 +1,191 @@
+# AGENTS.md - jvm-manager
+
+## 项目概述
+
+jvm-manager (`jvm-manager-cli`) 是一个纯 Node.js CLI 工具，用于在 Linux 上管理 JDK 安装。
+单文件架构 (`bin/jvm.js`)，零运行时依赖，通过 npm 全局安装后提供 `jvm` 命令。
+
+- **语言**: JavaScript (ES Modules)
+- **运行时**: Node.js >= 14
+- **模块系统**: ESM (`"type": "module"` in package.json)
+- **依赖**: 零运行时依赖；仅 jest 作为 devDependency
+- **平台**: 仅 Linux (Ubuntu/Debian, Fedora/CentOS/RHEL, Arch Linux)
+
+## 构建 / 测试 / 发布命令
+
+```bash
+# 安装依赖
+npm install
+
+# 运行全部测试
+npm test
+# 等价于: node --experimental-vm-modules node_modules/jest/bin/jest.js
+
+# 运行单个测试文件
+node --experimental-vm-modules node_modules/jest/bin/jest.js test/basic.spec.mjs
+
+# 运行匹配名称的测试
+node --experimental-vm-modules node_modules/jest/bin/jest.js -t "should display help"
+
+# 验证 CLI 可执行
+npm run check          # node bin/jvm.js --help
+
+# 本地链接为全局命令
+npm run link           # npm unlink && npm link
+
+# 构建 (仅拷贝文件到 dist/)
+npm run build
+```
+
+### CI/CD
+
+- GitHub Actions: `.github/workflows/publish.yml`
+- 推送 `main` 分支触发构建，推送 `v*` 标签触发 npm 发布
+- CI 使用 Node.js 18
+
+## 项目结构
+
+```
+bin/jvm.js           # 唯一源文件，包含所有业务逻辑 (~800 行)
+shell/jvm.sh         # Shell 集成脚本 (由 jvm init 输出，注入 CLI 路径)
+test/
+  basic.spec.mjs     # Jest 测试 (ESM, .spec.mjs 格式)
+  debug.js            # 调试脚本 (非测试)
+  detectLatestBuild.js # 辅助脚本 (非测试)
+  installSystem.js    # 辅助脚本 (非测试)
+package.json
+```
+
+## 代码风格
+
+### 通用规则
+
+- **无 linter/formatter 配置** — 项目未使用 ESLint/Prettier，遵循现有代码风格即可
+- 缩进: 2 空格
+- 字符串: 主文件 (`bin/jvm.js`) 使用**单引号**，测试文件使用**双引号**
+- 分号: 必须加分号
+- 行尾: LF (Unix)
+- 最大行宽: 无硬性限制，但保持合理 (~120 字符)
+
+### 导入风格
+
+```javascript
+// ESM import — 仅使用 Node.js 内置模块，无第三方依赖
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync, readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { homedir } from 'os';
+
+// 测试文件中也可使用 node: 前缀
+import { existsSync, readdirSync } from 'node:fs';
+```
+
+- 使用**命名导入** (named imports)，不使用默认导入
+- 主文件使用裸模块名 (`'fs'`)，测试/调试脚本中也使用 `'node:fs'` 前缀
+- 导入顺序: child_process → fs → path → os
+
+### 函数风格
+
+- 所有功能使用**顶层 function 声明** (非箭头函数、非 class)
+- 函数命名: camelCase
+- 常量: UPPER_SNAKE_CASE（仅限模块级别常量）
+- 无 async/await — 所有外部命令通过 `execSync` 同步执行
+
+```javascript
+// 常量定义
+const APP_NAME = 'jvm-manager';
+const HOME = homedir();
+const APP_DIR = join(HOME, '.local', 'share', APP_NAME);
+
+// 函数定义
+function install(version) { ... }
+function listInstalled() { ... }
+```
+
+### 错误处理
+
+```javascript
+// 致命错误: 使用 fail() 打印消息并 process.exit(1)
+function fail(msg) {
+  console.error(`Error: ${msg}`);
+  process.exit(1);
+}
+
+// 外部命令执行: try/catch 包裹 execSync
+try {
+  run('sudo apt update -qq');
+} catch (err) {
+  console.error('Failed to update...');
+  fail('Failed to install OpenJDK');
+}
+
+// 顶层命令分发的 catch:
+try { ... } catch (error) {
+  const message = error?.stderr || error?.message || String(error);
+  fail(message);
+}
+```
+
+- 使用 `console.error()` 输出错误信息
+- 使用 `console.log()` 输出正常信息
+- 非致命警告直接 `console.log(err)` 后继续
+
+### 外部命令执行
+
+```javascript
+// 统一通过 run() 封装 execSync
+function run(cmd, options = {}) {
+  return execSync(cmd, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+    ...options
+  }).trim();
+}
+```
+
+- 路径参数用双引号包裹: `run('readlink -f "' + path + '"')`
+- 字符串拼接使用 `+` 运算符（非模板字符串），主文件中两者混用
+- 模板字符串主要用于用户提示消息
+
+### 测试规范
+
+- 框架: Jest 29，ESM 模式 (`--experimental-vm-modules`)
+- 测试文件: `test/**/*.spec.mjs` 或 `test/**/*.test.js`
+- 测试风格: `describe()` + `it()` (非 `test()`)
+- 通过 `execSync` 调用 `node bin/jvm.js` 进行集成测试
+- 断言: `expect(...).toContain()`, `expect(...).not.toThrowError()`
+
+```javascript
+// 测试辅助函数
+function runJvmCmd(cmd, options = {}) {
+  return execSync(`node bin/jvm.js ${cmd}`, {
+    encoding: "utf8",
+    stdio: "pipe",
+    ...options
+  }).trim();
+}
+
+describe("jvm CLI basic functionality", () => {
+  it("should display help information", () => {
+    const helpOutput = runJvmCmd("help");
+    expect(helpOutput.toLowerCase()).toContain("usage:");
+  });
+});
+```
+
+## 关键约束
+
+1. **零依赖原则** — 不引入任何运行时第三方依赖
+2. **单文件架构** — 所有逻辑在 `bin/jvm.js` 中，如需拆分需与维护者确认
+3. **仅限 Linux** — 不考虑 macOS/Windows 兼容
+4. **同步执行** — 使用 `execSync`，不使用 async/await
+5. **ESM 模块** — 使用 `import`/`export`，不使用 `require()`
+6. **注释语言** — 代码注释使用中文或英文均可（现有代码中混用）
+7. **commit 消息** — 中文，格式: `fix: 修复xxx` / `feat: 新增xxx`
+
+## 数据目录
+
+- 应用根目录: `~/.local/share/jvm-manager/`
+- JDK 存储: `~/.local/share/jvm-manager/jdks/`
+- 当前全局版本: `~/.local/share/jvm-manager/current` (符号链接)
+- 项目版本: 项目根目录的 `.jvmrc` 文件

package/README.md

@@ -1,224 +1,94 @@
 # jvm-manager
 
-jvm-manager 是一个用于在 Linux 系统上管理 Java 开发工具包 (JDK) 的命令行工具。它提供了简单的接口来安装、链接、切换和管理不同版本的 Java。
+Linux 上的 JDK 版本管理工具。通过简单的命令安装、切换和管理不同版本的 Java。
 
-## 功能特性
-
-- **安装 JDK**：从系统依赖库安装（支持 Ubuntu/Debian、Fedora/CentOS/RHEL、Arch Linux）或从 Oracle 官方下载
-- **链接系统 JDK**：链接系统已安装的 JDK 到 jvm-manager 管理的目录
-- **切换 JDK 版本**：在全局和项目级别切换不同版本的 Java
-- **列出已安装 JDK**：显示所有已安装的 JDK 版本，包括系统 JDK
-- **管理环境变量**：生成可用于设置 Java 环境变量的命令
-- **系统兼容性检查**：检查系统是否满足运行 Java 的要求
+## 环境要求
 
-## 快速开始
+- Linux (Ubuntu/Debian, Fedora/CentOS/RHEL, Arch Linux)
+- Node.js >= 14
+- sudo 权限（用于系统包管理器安装 JDK）
 
-### 安装 jvm-manager
+## 安装
 
 ```bash
 npm install -g jvm-manager-cli
 ```
 
-### 使用
-
-#### 1. 查看帮助
+安装后，在 `.bashrc` 或 `.zshrc` 中添加 shell 集成：
 
 ```bash
-jvm help
+eval "$(jvm init)"
 ```
 
-#### 2. 安装 JDK
+重新打开终端或 `source ~/.bashrc` 生效。启用后 `jvm use` 会自动设置当前 shell 的 `JAVA_HOME` 和 `PATH`。
+
+## 使用
 
 ```bash
+# 安装 JDK
 jvm install 17
-```
-
-#### 3. 列出所有已安装的 JDK 版本
 
-```bash
+# 查看已安装版本
 jvm list
-```
-
-#### 4. 切换全局默认 JDK
-
-```bash
-jvm use 17 --global
-```
 
-#### 5. 在项目中使用特定版本的 JDK
+# 切换全局版本
+jvm use 17
 
-```bash
+# 为当前项目指定版本 (写入 .jvmrc)
 jvm use 11 --project
-```
-
-#### 6. 设置 Java 环境变量
-
-```bash
-eval "$(jvm env --global)"
-java -version
-```
-
-#### 7. 检查系统兼容性
-
-```bash
-jvm doctor
-```
-
-## 命令说明
-
-### install
-
-安装指定版本的 JDK。支持系统依赖库安装（apt、yum、pacman）和 Oracle 官方下载。
-
-```bash
-jvm install <version>
-```
-
-**参数：**
-- `<version>`：Java 版本号（如 8、11、17、21 等）
-
-### list
-
-列出所有已安装的 JDK 版本，包括系统 JDK。
-
-```bash
-jvm list
-```
-
-### use
-
-切换到指定版本的 JDK。支持全局和项目级别。
-
-```bash
-jvm use <version> [--global|--project]
-```
-
-**参数：**
-- `<version>`：Java 版本号（如 8、11、17、21 等）
-- `--global`（可选）：将指定版本设置为全局默认（默认）
-- `--project`（可选）：将指定版本设置为项目默认，创建或更新 `.jvmrc` 文件
-
-### env
-
-生成可用于设置 Java 环境变量的命令。支持全局和项目级别。
-
-```bash
-jvm env [--global|--project]
-```
 
-**参数：**
-- `--global`（可选）：生成全局 Java 环境变量设置命令（默认）
-- `--project`（可选）：生成项目 Java 环境变量设置命令
-
-### current
-
-显示当前全局和项目级别的 Java 版本。
-
-```bash
+# 查看当前版本
 jvm current
-```
-
-### remove
-
-移除指定版本的 JDK。
-
-```bash
-jvm remove <version>
-```
-
-**参数：**
-- `<version>`：Java 版本号（如 8、11、17、21 等）
-
-### link
 
-链接系统已安装的 JDK 到 jvm-manager 管理的目录。
-
-```bash
-jvm link <system-path> <version>
-```
-
-**参数：**
-- `<system-path>`：系统上已安装的 Java 路径（如 `/usr/lib/jvm/java-17-openjdk-amd64`）
-- `<version>`：Java 版本号（如 17）
-
-### doctor
+# 链接系统已有的 JDK
+jvm link /usr/lib/jvm/java-17-openjdk-amd64 17
 
-检查系统是否满足运行 Java 的要求，包括 Node.js 版本、架构、操作系统平台和所需的工具。
+# 移除已安装版本
+jvm remove 17
 
-```bash
+# 检查系统兼容性
 jvm doctor
 ```
 
-## 项目级配置
-
-在项目根目录创建一个名为 `.jvmrc` 的文件，其中包含所需的 Java 版本号，即可实现项目级别的 Java 版本管理。
+## 命令参考
 
-```bash
-# 在项目根目录创建 .jvmrc 文件
-jvm use 11 --project
-```
+| 命令 | 说明 |
+|------|------|
+| `jvm install <version>` | 安装指定版本 JDK（通过系统包管理器或 Oracle 下载） |
+| `jvm list` | 列出所有已安装的 JDK，包括系统 JDK |
+| `jvm use <version> [--global\|--project]` | 切换 JDK 版本，默认全局；`--project` 写入 `.jvmrc` |
+| `jvm current` | 显示当前全局和项目级 Java 版本 |
+| `jvm env [--global\|--project]` | 输出 `export JAVA_HOME=...` 等环境变量设置语句 |
+| `jvm init` | 输出 shell 集成脚本，用于 `eval` |
+| `jvm remove <version>` | 移除已安装的 JDK |
+| `jvm link <path> <version>` | 将系统已安装的 JDK 链接到 jvm-manager |
+| `jvm doctor` | 检查系统兼容性 |
 
-## 系统兼容性
-
-jvm-manager 支持以下操作系统：
-- Ubuntu/Debian
-- Fedora/CentOS/RHEL
-- Arch Linux
-- 其他 Linux 发行版（会尝试使用 Oracle 官方下载）
-
-## 环境要求
+## 项目级配置
 
-- Node.js 14 或更高版本
-- 具有执行 `sudo` 命令的权限（用于系统依赖库安装）
+在项目根目录执行 `jvm use <version> --project` 会创建 `.jvmrc` 文件。启用 shell 集成后，进入项目目录时可通过 `jvm use --project` 切换到项目指定版本。
 
 ## 常见问题
 
-### 1. 安装失败
-
-如果在使用系统依赖库安装时遇到问题，请尝试手动运行以下命令更新包管理器：
-
-```bash
-# Ubuntu/Debian
-sudo apt update
-```
-
-### 2. 权限问题
+**`jvm use` 后 `java -version` 没变？**
+需要启用 shell 集成。在 `.bashrc` 中添加 `eval "$(jvm init)"`，否则需手动执行 `eval "$(jvm env --global)"`。
 
-如果遇到权限问题，请确保您有执行 `sudo` 命令的权限，并在需要时输入密码。
+**安装失败？**
+先手动更新包管理器：`sudo apt update`（Debian/Ubuntu）或 `sudo yum makecache`（RHEL/CentOS）。
 
-### 3. 无法找到 JDK
-
-如果系统上已安装 Java，但 jvm-manager 无法找到，请尝试使用 `jvm link` 命令手动链接：
-
-```bash
-jvm link /usr/lib/jvm/java-17-openjdk-amd64 17
-```
-
-## 故障排除
-
-如果您遇到任何问题，请尝试使用 `jvm doctor` 命令检查系统兼容性，或使用 `--help` 查看特定命令的帮助信息。
+**系统已有 JDK 但 jvm-manager 找不到？**
+用 `jvm link` 手动链接：`jvm link /usr/lib/jvm/java-17-openjdk-amd64 17`。
 
 ## 开发
 
-### 本地开发
-
 ```bash
-git clone https://github.com/your-username/jvm-manager.git
+git clone https://github.com/veater16/jvm-manager.git
 cd jvm-manager
 npm install
-npm link
+npm link    # 本地链接为全局命令
+npm test    # 运行测试
 ```
 
-### 运行测试
-
-```bash
-npm test
-```
-
-## 贡献
-
-欢迎提交问题和拉取请求。对于重大更改，请先创建一个问题来讨论您想要更改的内容。
-
 ## 许可证
 
-MIT License
+MIT

package/bin/jvm.js

@@ -3,6 +3,7 @@
 import { execSync } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'fs';
 import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
 import { homedir } from 'os';
 
 const APP_NAME = 'jvm-manager';
@@ -44,6 +45,7 @@ Usage:
   jvm use <version> --project     Write .jvmrc in current project
   jvm current                     Show current global and project JDK
   jvm env [--global|--project]    Print export lines for shell
+  jvm init                        Print shell integration script
   jvm doctor                      Check system for compatibility
   jvm remove <version>            Remove installed JDK
   jvm link <system-path> <version> Link system JDK to local store
@@ -53,7 +55,9 @@ Examples:
   jvm use 21 --global
   jvm use 17 --project
   jvm link /usr/lib/jvm/java-17-openjdk-amd64 17
-  eval "$(jvm env --project)"`);
+
+Shell integration (add to .bashrc or .zshrc):
+  eval "$(jvm init)"`);
 }
 
 function detectArch() {
@@ -550,7 +554,7 @@ function setGlobal(version) {
   rmSync(CURRENT_GLOBAL, { recursive: true, force: true });
   symlinkSync(target, CURRENT_GLOBAL, 'dir');
   console.log('Global JDK set to ' + version);
-  console.log('Run: eval "$(jvm env --global)"');
+  console.log('Tip: eval "$(jvm init)" in .bashrc to auto-apply on use');
 }
 
 function setProject(version) {
@@ -574,7 +578,7 @@ function setProject(version) {
   const file = join(cwd, PROJECT_FILE);
   writeFileSync(file, version + '\n', 'utf8');
   console.log('Project JDK set to ' + version + ' via ' + PROJECT_FILE);
-  console.log('Run: eval "$(jvm env --project)"');
+  console.log('Tip: eval "$(jvm init)" in .bashrc to auto-apply on use');
 }
 
 function findProjectVersion(startDir) {
@@ -711,6 +715,17 @@ function doctor() {
   }
 }
 
+function printInit() {
+  const cliPath = resolve(fileURLToPath(import.meta.url));
+  const shellScript = join(dirname(cliPath), '..', 'shell', 'jvm.sh');
+  if (!existsSync(shellScript)) {
+    fail('Shell integration script not found: ' + shellScript);
+  }
+  const content = readFileSync(shellScript, 'utf8');
+  // 注入 CLI 实际路径，替换动态查找
+  console.log(content.replace('__JVM_CLI__', cliPath));
+}
+
 function parseFlags(args) {
   const flags = new Set(args.filter(a => a.startsWith('--')));
   return {
@@ -775,6 +790,10 @@ function main() {
       showCurrent();
       return;
     }
+    if (cmd === 'init') {
+      printInit();
+      return;
+    }
     if (cmd === 'doctor') {
       doctor();
       return;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "jvm-manager-cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A simple CLI to manage Java installations on Linux",
   "main": "bin/jvm.js",
   "scripts": {
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
     "check": "node bin/jvm.js --help",
     "link": "npm unlink 2>/dev/null || true && npm link",
-    "build": "mkdir -p dist && cp bin/jvm.js dist/ && cp package.json dist/ && cp README.md dist/ && cp LICENSE dist/"
+    "build": "mkdir -p dist && cp bin/jvm.js dist/ && cp package.json dist/ && cp README.md dist/ && cp LICENSE dist/ && cp -r shell dist/"
   },
   "author": "",
   "license": "MIT",

package/shell/jvm.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# jvm-manager shell 集成
+# 使用方式: eval "$(jvm init)"
+
+__JVM_CLI="__JVM_CLI__"
+
+jvm() {
+  case "$1" in
+    use)
+      command node "$__JVM_CLI" "$@"
+      local rc=$?
+      if [ $rc -ne 0 ]; then
+        return $rc
+      fi
+
+      local env_flag="--global"
+      local arg
+      for arg in "$@"; do
+        if [ "$arg" = "--project" ]; then
+          env_flag="--project"
+          break
+        fi
+      done
+
+      eval "$(command node "$__JVM_CLI" env "$env_flag" 2>/dev/null)"
+      ;;
+    env)
+      eval "$(command node "$__JVM_CLI" "$@")"
+      ;;
+    *)
+      command node "$__JVM_CLI" "$@"
+      ;;
+  esac
+}
+
+if [ -L "${HOME}/.local/share/jvm-manager/current" ]; then
+  eval "$(command node "$__JVM_CLI" env --global 2>/dev/null)"
+fi