zcode-idea 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,296 @@
-# Temporary Holding Version
+# zcode-idea
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 **ZCode IDE 插件** 安装到本机已安装的 JetBrains IDE：自动发现 IDE、对比版本、
+关闭对应进程、从七牛 CDN 下载插件包（Ed25519 验签 + sha256 校验）、删除旧版本、
+解压，并在安装完成后重新启动 IDE。
+
+npm 包只包含安装器代码与内置公钥（约 **33 KB**），不携带插件 zip。
+
+```bash
+npx zcode-idea
+```
+
+> 安装器只替换 `<IDE>/plugins/zcode-ide/`，不会改动 IDE 的其它配置、项目或插件。
+
+## 插件来源
+
+| 方式 | 说明 |
+|---|---|
+| 默认源 | `http://tnbe4cmeo.hn-bkt.clouddn.com/zcode-ide/plugin/stable`（七牛测试域名，HTTP） |
+| `--source <url>` | 覆盖默认源，例如 `https://cdn.example.com/zcode-ide/plugin/stable` |
+| `ZCODE_IDE_PLUGIN_BASE_URL` | 与 `--source` 等价的环境变量（`--source` 优先） |
+| `--zip <path>` | 离线：直接使用本地插件 zip，跳过 manifest 与下载 |
+
+使用默认的七牛测试域名时**不需要** `--allow-http`，但每次启动会打印一次醒目警告；
+用 `--source` / 环境变量指定其他 HTTP 源时必须显式加 `--allow-http`（仅联调用），
+HTTPS 源直接允许。
+
+远端目录结构（对象键含 `QINIU_PREFIX`）：
+
+```
+zcode-ide/plugin/stable/manifest.json
+zcode-ide/plugin/stable/manifest.sig
+zcode-ide/plugin/stable/0.1.0/zcode-ide-0.1.0-b3bb4620163c.zip
+```
+
+`manifest.archivePath` 是**相对 CDN 根**的对象键（含 prefix），例如
+`zcode-ide/plugin/stable/0.1.0/zcode-ide-0.1.0-b3bb4620163c.zip`。
+zip 使用**内容寻址**：同一版本重新构建会得到新的 `sha12`，旧 zip 保留不覆盖；
+manifest/sig 是唯一可变指针，因此即使边缘 manifest 短暂滞后，也只会指向旧 zip，
+不会出现“清单与包不配对”。安装器会拒绝绝对 URL、`..`、反斜杠、以 `/` 开头
+或带查询参数的值。
+
+## 选项
+
+```
+npx zcode-idea [--all] [--dry-run] [--check] [--yes] [--force] [--no-launch]
+               [--source <url>] [--zip <path>] [--allow-http]
+               [--target <dir>] [--timeout <秒>] [--clean-cache]
+```
+
+| 选项 | 说明 |
+|---|---|
+| `--all` | 处理全部发现的 IDE，跳过交互选择 |
+| `--check` | 只拉取并校验 manifest、打印版本对比表后退出；不下载、不关 IDE、不安装 |
+| `--dry-run` | 拉取 manifest + 版本对比 + 安装计划；不下载、不关 IDE、不解压、不启动 |
+| `--force` | 已是最新或远端版本更低时也强制安装 |
+| `--yes` | 跳过“关闭 IDE”前的二次确认 |
+| `--no-launch` | 安装完成后不启动 IDE（默认会启动） |
+| `--source <url>` | 插件分发根 URL（覆盖默认源/环境变量） |
+| `--zip <path>` | 使用本地插件 zip（离线逃生口；仍做 zip 结构/jar 校验） |
+| `--allow-http` | 允许非默认的 HTTP 插件源（仅测试域名联调） |
+| `--target <dir>` | 直接指定 **plugins 目录**；可重复或逗号分隔，跳过发现与选择 |
+| `--timeout <秒>` | 等待 IDE 退出的时间，默认 30，范围 1–600 |
+| `--clean-cache` | 安装结束后清理其它版本的插件包缓存（只处理 sha256 命名的缓存文件；保留本次使用的版本；仅在至少一个目标安装成功后清理）；`--check` / `--dry-run` 只读，不删除 |
+| `--help` / `--version` | 中文帮助 / npm 包版本 |
+
+示例：
+
+```bash
+# 只看版本对比，不做任何安装动作
+npx zcode-idea --check --all
+
+# 安装到全部发现的 IDE
+npx zcode-idea --all --yes
+
+# 离线安装（CI / 内网）
+npx zcode-idea --zip ./build/distributions/zcode-ide-0.1.0.zip --all --no-launch
+```
+
+**非交互环境（CI、管道）：** 必须提供 `--all` 或 `--target`，否则以退出码 2 结束。
+未传 `--yes` 时不会自动关闭 IDE，而是提示“请先手动退出 IDE”。
+
+## 版本语义
+
+对每个目标读取已安装插件版本（`<pluginsDir>/zcode-ide/lib/zcode-ide-*.jar` 内
+`META-INF/plugin.xml` 的 `<version>`），与远端 manifest 的 `pluginVersion` 比较：
+
+| 情况 | 默认行为 |
+|---|---|
+| 未安装 / 远端更高 | 安装或更新 |
+| 相同 | 显示“已是最新”，跳过（`--force` 可重装） |
+| 远端更低 | 拒绝降级并提示（`--force` 可强制降级） |
+
+`--check` 只打印对比表；`--dry-run` 额外打印安装计划与缓存状态。
+
+## 安装流程
+
+1. 拉取 `manifest.json` + `manifest.sig`，用 **内置公钥** 验证 Ed25519 签名
+   （对 manifest 原始字节），校验字段、`schemaVersion`、`archivePath`、sha256 格式；
+2. 发现 IDE（配置目录优先；安装目录需通过真实写探针，不可写的跳过并提示）；
+3. 选择目标（`--all` / `--target` 可跳过）；
+4. 对比版本，决定安装 / 跳过；
+5. 关闭所选目标对应的 IDE 进程：先优雅关闭，超时后强制结束；
+6. 下载插件包到缓存并校验 sha256/size，再校验 zip 结构（zip-slip、符号链接、
+   主 jar 内 `dev.zcode.ide`、runtime 完整性）；
+7. 删除 `<pluginsDir>/zcode-ide` 后解压，保留 unix 权限位；
+   某个目标失败不阻断其它目标，最终有失败则退出码 1；
+8. 打印安装路径与文件数，并按目标版本查找可执行文件启动 IDE。
+
+退出码：`0` 成功；`1` 校验/下载/安装失败；`2` 参数或环境用法错误；`130` 用户取消。
+
+## 缓存与离线
+
+- 缓存路径：`${ZCODE_DATA_BASE_DIR:-~/.zcode}/ide/plugin-cache/<sha256>.zip`
+  （`ZCODE_DATA_BASE_DIR` 用于覆盖 `~/.zcode` 根目录）；
+- 命中缓存且 sha256/size 一致时直接复用；不一致则删除重新下载；
+- 下载先写 `<sha256>.zip.part`，校验通过后原子改名；
+- 每个版本在缓存中约占 49 MB；加 `--clean-cache` 可在安装结束后自动清理：
+  - **仅在至少一个目标安装成功后清理**；全部目标安装失败时跳过清理并告警，
+    保留旧版本缓存以便回滚或重试；
+  - 只处理 sha256 命名的缓存文件：保留本次使用（远端 manifest 的 sha256；
+    `--zip` 时为本地包的 sha256）对应的 `<64位十六进制>.zip`，删除其它缓存 zip
+    与全部缓存 `.part`；缓存目录里的其它文件（包括 `backup.zip` 这类非 sha256
+    命名的 zip）一律不动；
+  - **`--check` 与 `--dry-run` 是只读模式，绝不删除文件**；`--dry-run` 只打印
+    “安装后将清理 N 个旧缓存（释放约 X）”一行预览（即使所有目标已是最新也会打印）；
+  - 单个文件删除失败只打印警告，不影响安装结果与退出码；
+  - 不传 `--clean-cache` 时不做任何清理，缓存行为与之前一致；
+  - 不要与其他 `zcode-idea` 安装进程并发运行 `--clean-cache`，否则可能删掉对方
+    正在写入的 `.part` 或待解压的 zip；
+- 也可以直接删除整个 `plugin-cache` 目录（安全）；
+- 完全离线时用 `--zip <本地 zip>`，不访问网络；此时仍会校验 zip 结构与主 jar。
+
+## 安全模型
+
+- **信任根**是 npm 包内的 `lib/plugin-signing-public.pem`（与仓库
+  `src/main/resources/runtime-signing-public.pem` 同一把 Ed25519 公钥）；
+- manifest 验签失败立即中止，不会使用其中的 sha256/version；
+- zip 必须与验签后的 manifest 的 sha256、size、pluginVersion 一致；
+- zip 条目拒绝绝对路径、`..`、反斜杠、符号链接、重复文件、非 `zcode-ide/` 前缀；
+- 发布侧 zip 使用内容寻址 key（`<version>/zcode-ide-<version>-<sha12>.zip`），
+  同版本重发不会覆盖旧对象；manifest/sig 是唯一可变指针，生产 CDN 需支持刷新；
+- 发布脚本从不打印 AK/SK/token。
+
+## 支持的 IDE
+
+| 产品 | 配置目录前缀 | Windows 进程 |
+|---|---|---|
+| IntelliJ IDEA Ultimate | `IntelliJIdea<年.版本>` | `idea64.exe` / `idea.exe` |
+| IntelliJ IDEA Community | `IdeaIC<年.版本>` | `idea64.exe` / `idea.exe` |
+| WebStorm | `WebStorm<年.版本>` | `webstorm64.exe` |
+| PhpStorm | `PhpStorm<年.版本>` | `phpstorm64.exe` |
+| PyCharm Professional / Community | `PyCharm<年.版本>` / `PyCharmCE<年.版本>` | `pycharm64.exe` |
+| GoLand | `GoLand<年.版本>` | `goland64.exe` |
+| CLion | `CLion<年.版本>` | `clion64.exe` |
+| DataGrip | `DataGrip<年.版本>` | `datagrip64.exe` |
+| Rider | `Rider<年.版本>` | `rider64.exe` |
+| RubyMine | `RubyMine<年.版本>` | `rubymine64.exe` |
+| Aqua | `Aqua<年.版本>` | `aqua64.exe` |
+| RustRover | `RustRover<年.版本>` | `rustrover64.exe` |
+| DataSpell | `DataSpell<年.版本>` | `dataspell64.exe` |
+| Writerside | `Writerside<年.版本>` | `writerside64.exe` |
+| MPS | `MPS<年.版本>` | `mps64.exe` |
+| Android Studio | `AndroidStudio<年.版本>` | `studio64.exe` |
+
+macOS / Linux 使用对应的小写进程名（`idea`、`webstorm`、`studio` 等）。
+
+## 支持的平台
+
+- **Windows**：`%APPDATA%\JetBrains\*`、`%APPDATA%\Google\AndroidStudio*`；
+  次级选项为 `%PROGRAMFILES%\JetBrains\*`、`%LOCALAPPDATA%\Programs\*`、
+  `%LOCALAPPDATA%\JetBrains\Toolbox\apps\<Product>\<channel>\<version>`。
+- **macOS**：`~/Library/Application Support/JetBrains/*`、
+  `~/Library/Application Support/Google/AndroidStudio*`；
+  次级选项为 `/Applications/*.app`、`~/Applications/*.app` 与 Toolbox。
+- **Linux**：`$XDG_CONFIG_HOME`（默认 `~/.config`）下的 `JetBrains/*`、`Google/AndroidStudio*`；
+  次级选项为 `/opt/*`、`/snap/*/current` 与 Toolbox。
+
+“次级选项”指 IDE 安装目录里的 `plugins/`，升级或重装 IDE 时可能被清掉。
+安装器会对这类目录做一次真实写探针（创建并立即删除临时文件）；
+不可写时跳过并提示“已跳过 N 个不可写的 IDE 安装目录（需要管理员权限）”。
+配置目录（`config`）不受写探针影响，始终保留。
+
+## 常用命令（仓库根 npm scripts）
+
+在仓库根目录执行：
+
+| 命令 | 作用 |
+|---|---|
+| `npm run release` | 发布流程 dry-run：只读版本/环境、打印计划，不构建、不上传 |
+| `npm run release:push` | `release.mjs --apply --push`：构建/复用 zip + 上传七牛 |
+| `npm run release:npm` | `release.mjs --apply --push --npm`：再发布 npm（版本需手动 bump） |
+| `npm run plugin:build` | 只构建插件 zip（build-runtime + gradlew），不发布 |
+| `npm run plugin:pack` | 只打 npm tarball（`scripts/npm` 下 `npm pack`） |
+| `npm run plugin:local-update` | 本地打包并用 tarball 强制更新已安装插件 |
+
+`plugin:local-update` 会先 `npm pack`（输出到独立临时目录），再用
+`npx --yes --package <tarball> -- zcode-idea --all --yes --force` 运行本地安装器；
+默认强制重装，并会从插件源（默认七牛测试域名）下载 zip。
+透传参数追加在命令末尾，可覆盖默认行为：
+
+```bash
+# 只对临时目录测试，不关 IDE、不启动
+npm run plugin:local-update -- --target "C:\Temp\zcode-plugin-test\plugins" --no-launch
+
+# 指定其他源
+npm run plugin:local-update -- --source https://cdn.example.com/zcode-ide/plugin/stable --allow-http
+```
+
+## 发布链路（维护者）
+
+一条命令完成版本检查、构建、manifest 签名、七牛上传与 npm 发布：
+
+```bash
+# 默认 dry-run：只读版本/环境并打印计划，不构建、不写文件、不上传
+node scripts/release.mjs
+
+# 只构建插件 zip（build-runtime + gradlew），不发布
+node scripts/release.mjs --build-only
+
+# 本地执行：构建（或复用）zip + 生成 manifest/sig，不上传
+node scripts/release.mjs --apply
+
+# 真正上传七牛 + 发布 npm（唯一的远端写入开关）
+node scripts/release.mjs --apply --push --npm
+
+# 复用 build/distributions 里最新的 zip（仍校验版本一致性）
+node scripts/release.mjs --apply --skip-build
+```
+
+版本唯一来源是 `scripts/npm/package.json` 的 `version`：同一版本同时作为
+插件版本、OSS 对象路径版本、`manifest.pluginVersion` 与 npm 包版本。
+构建使用 `./gradlew buildPlugin -PpluginVersion=<version>`，并校验 jar 内
+`META-INF/plugin.xml` 的 `<id>/<version>`；**不修改 package.json 的 version
+就不要发新版**（npm 同版本不可覆盖，`--npm` 发布前会检查远端并报错）。
+
+`--apply` 只做本地步骤（构建/复用 zip、写入
+`build/plugin-release/{zip, manifest.json, manifest.sig}`）；只有再加 `--push`
+才会写远端。`--allow-downgrade` 仅联调使用：允许 package 版本低于 gradle 版本、
+或复用与 package 版本不一致的 zip。签名私钥优先取 `RUNTIME_SIGNING_KEY`，
+否则读 `~/.zcode/keys/runtime-signing-private.pem`；脚本会校验 npm 包内置公钥与仓库公钥一致。
+
+七牛环境变量（`--apply --push` 必需）：
+
+| 变量 | 说明 |
+|---|---|
+| `QINIU_ACCESS_KEY` / `QINIU_SECRET_KEY` | 七牛密钥，绝不打印 |
+| `QINIU_BUCKET` | bucket 名称（默认 `zcode-ide`） |
+| `QINIU_DOMAIN` | CDN 根（生产必须 `https://`；HTTP 测试域名需 `--allow-http`） |
+| `QINIU_PREFIX` | 对象键前缀（默认 `zcode-ide`，必须与 manifest.archivePath 一致） |
+| `QINIU_UPLOAD_HOST` | 区域发现失败时的兜底上传域名（默认 `https://up-z2.qiniup.com`） |
+
+上传顺序固定：**zip → manifest.sig → manifest.json**（manifest 最后）。
+zip 使用内容寻址，可长期缓存（`Cache-Control: public, max-age=31536000, immutable`），
+同版本重发会写新的 key，不覆盖旧对象。manifest/sig 是可变指针（`no-cache`）：
+上传后逐对象 HEAD 对账，失败重试 3 次（1s/2s/4s）；zip 失败视为致命，
+manifest/sig 重试后仍不一致只警告，因为 zip 已成功且清单指向不可变对象。
+生产 CDN 需要支持刷新；测试域名刷新失败属已知情况。
+
+## 网络 / 离线注意事项
+
+- 安装器运行期只访问插件源与（首次）下载 zip；不访问 npm registry；
+- npm 包发布到**官方 registry** `https://registry.npmjs.org/`，
+  `npx zcode-idea` 默认即可解析本包及 `cac`/`yauzl`/`@inquirer/prompts` 依赖；
+- 发布认证沿用 `~/.npmrc`（或 `NODE_AUTH_TOKEN`）；`npm whoami --registry https://registry.npmjs.org/` 应返回账号名；
+- 内网无法访问官方 npm 时，可临时指定镜像，或用下面的本地 tarball 方式验证：
+  ```bash
+  npm_config_registry=https://registry.npmmirror.com npx zcode-idea
+  ```
+- 插件源为 HTTP 测试域名时，生产使用必须换成 HTTPS 自有域名；
+- 无法访问 CDN 时使用 `--zip` 本地包，或预先准备缓存文件。
+
+## 开发
+
+```bash
+cd scripts/npm
+npm install          # Node >= 18
+npm test             # node:test（含本地随机端口 HTTP 集成测试）
+npm pack --dry-run   # 查看 tarball（应约 33 KB，不含 zip）
+```
+
+不发布时直接用本地 tarball 跑（与 `npx zcode-idea` 行为一致）：
+
+```bash
+cd scripts/npm
+npm pack
+npx --yes ./zcode-idea-0.0.1.tgz --check --all          # 只看版本对比
+npx --yes ./zcode-idea-0.0.1.tgz --all --yes            # 下载并安装（--force 可重装）
+npx --yes ./zcode-idea-0.0.1.tgz --zip ../../build/distributions/zcode-ide-0.1.0.zip --all --yes
+```
+
+默认源是七牛测试域名（HTTP），首次安装会下载约 49MB；之后命中
+`~/.zcode/ide/plugin-cache/<sha256>.zip`，不会重复下载。
+
+依赖版本固定为 `cac@6.7.14`、`@inquirer/prompts@7.10.1`、`yauzl@3.4.0`，
+以匹配 `engines.node: ">=18"`（这两个包的最新大版本要求 Node >= 20）。