@gbits-jszx/gw-cli 2026.9.12-7 → 2026.9.12-9

package/README.md

@@ -1,18 +1,18 @@
 # @gbits-jszx/gw-cli
 
-面向多个网关项目的跨平台构建、运行和交付工具。项目从 `gw.project.yaml` 解析；`npm package/publish` 专用于维护 CLI 本身。
+面向多个网关项目的跨平台构建、运行和交付工具。项目从 `--project <路径>` 指定的 `gw.project.yaml` 解析；`build/run/test/smoke/image/chart/npm/publish` 必须显式传入该参数，`GW_PROJECT_FILE` 和目录自动发现不能替代。`npm build/package/publish` 专用于维护 CLI 本身。
 
 [PC 开发构建发布、WSL/云 VM 初始化部署更新](../../../docs/user-docs/CLI-MULTI-PROJECT.md)。公网 registry 为 `https://registry.npmjs.org/`，包内包含 Windows amd64 和 Linux amd64（含 WSL）二进制。
 
 打包过程和最终 `.tgz` 全部位于仓库根目录 `.gw-build/npm/`；源码目录不会生成 `bin/native` 或被 `npm version` 改写。
 
-`npm package` 会依次输出准备包、Windows/Linux 编译和 npm 压缩打包日志。编译期间每 5 秒报告已用时间，完成时显示各平台二进制大小、npm 文件清单、压缩包文件名、输出目录和总耗时；任何阶段失败都会保留原始错误并返回非零退出码。
+`npm build` 与 `npm package` 等价，从当前源码编译 Windows/Linux CLI 并生成 `.tgz`。编译期间每 5 秒报告已用时间，完成时显示各平台二进制大小、npm 文件清单、压缩包文件名、输出目录和总耗时；任何阶段失败都会保留原始错误并返回非零退出码。`npm publish` / `publish npm` 每次重新构建，并在默认自动编号下分配新的 npm 版本，不直接上传之前 build 的归档。
 
 ## 日期版本号
 
-npm、Image、Chart 统一使用 `yyyy.M.d-id`，例如 `2026.9.11-2` 表示 2026 年 9 月 11 日第 2 次构建。`npm package`、`npm publish` 和 `publish npm` 默认 `--version auto`，按执行机器的本地日期生成，序号从 1 开始、同日递增、跨日重置。也可用 `--version 2026.9.11-2` 指定版本，日期须有效，月、日和序号均不得带前导零。
+npm、Image、Chart 使用相同的 `yyyy.M.d-id` 格式，但按项目和制品类型独立编号，不要求三者同号。例如 `2026.9.11-2` 表示该项目、该类制品当天分配的第 2 个版本。`npm build`、`npm package`、`npm publish` 和 `publish npm` 默认 `--version auto`，按执行机器的本地日期生成，序号从 1 开始、同日递增、跨日重置。也可用 `--version 2026.9.11-2` 显式重建未发布版本，日期须有效，月、日和序号均不得带前导零。
 
-该格式可直接被 npm 解析为 SemVer：`yyyy.M.d` 是 major/minor/patch，`id` 是数字型 prerelease 标识。包内 `package.json` 的 `version`、`gwVersion` 和 Windows/Linux 二进制编译版本使用完全相同的字符串，不再做 `yyyy.Mdd.id` 映射。日常安装继续使用 `@latest`；精确复现使用完整版本号。由于它在 SemVer 中属于 prerelease，普通版本范围默认不会匹配，依赖方不要使用 `^2026.9.11`，应使用 `@latest` 或精确版本。
+该格式可直接被 npm 解析为 SemVer：`yyyy.M.d` 是 major/minor/patch，`id` 是数字型 prerelease 标识。CLI 在打包副本中自动同步 `package.json` 的 `version`、`gwVersion` 和 Windows/Linux 二进制编译版本，无需手工修改源码中的 `gwVersion`。日常安装继续使用 `@latest`；精确复现使用完整版本号。由于它在 SemVer 中属于 prerelease，普通版本范围默认不会匹配，依赖方不要使用 `^2026.9.11`，应使用 `@latest` 或精确版本。
 
 `npm publish` / `publish npm` 会自动向 npm 传入 `--tag latest`，明确把本次版本设为 `@latest`，同时满足 npm 对 prerelease 发布的显式 tag 要求。`--dry-run` 使用相同参数但不上传；`npm pack --dry-run` 只检查打包，不能替代发布检查。
 
@@ -22,22 +22,22 @@ npm、Image、Chart 统一使用 `yyyy.M.d-id`，例如 `2026.9.11-2` 表示 202
 
 ## 镜像 tag
 
-`image build` 默认 `--tag auto`，生成 `yyyy.M.d-id`，例如 `2026.9.10-1`。该格式同时满足 Docker tag 与 Helm SemVer，Image 和 Chart 在 Harbor 中可使用完全一致的版本字符串。日期按执行 CLI 的机器本地时间计算，序号从 1 起，同日递增、跨日重置。参数优先级为 `--tag` > `GW_IMAGE_TAG` > `auto`；自动和新显式版本使用新格式，已存在的 `yyyy.MM.dd.id` 仍可显式重建或推送。
+`image build` 默认 `--tag auto`，生成 `yyyy.M.d-id`，例如 `2026.9.10-1`。该格式同时满足 Docker tag 与 Helm SemVer，Image 与 Chart 各自编号；部署时分别传入实际镜像 tag 和 Chart 版本。日期按执行 CLI 的机器本地时间计算，序号从 1 起，同日递增、跨日重置。参数优先级为 `--tag` > `GW_IMAGE_TAG` > `auto`；自动和新显式版本使用新格式，已存在的 `yyyy.MM.dd.id` 仍可显式重建或推送。
 
 镜像与 npm 独立计数，编号同样写入用户级 `projects.yaml`。开始构建时即占号，失败也保留，但只有成功构建才更新该 repository 的最近可推送 tag。同一 `project-id` 的不同镜像 repository 共用镜像每日序号，各自保存最近成功构建。显式 tag 可用于本地重建；不查询 Harbor。换机器或 CI 多节点构建时，应统一分配并显式传入未发布 tag，不能覆盖已发布镜像。
 
 ```powershell
 # 自动编号，输出 Docker 构建日志及最终完整镜像名
-npx -y --prefer-online @gbits-jszx/gw-cli@latest image build
+npx -y --prefer-online @gbits-jszx/gw-cli@latest --project ./gw.project.yaml image build
 # 自动使用该 repository 最近一次成功构建的 tag，不生成新编号
-npx -y --prefer-online @gbits-jszx/gw-cli@latest image push
+npx -y --prefer-online @gbits-jszx/gw-cli@latest --project ./gw.project.yaml image push
 ```
 
-`image push` / `publish image` 的默认 `--tag auto` 会读取最近成功构建记录；没有记录时要求先 build 或显式传入 tag。优先级为 `--tag` > `GW_IMAGE_TAG` > 自动识别；为兼容已有本地镜像，显式推送仍接受旧 tag 格式。以上行为在源码修改发布后才进入 npm `@latest`，发布前用 `go run ./tools/cli image build` 验证。
+`image push` / `publish image` 的默认 `--tag auto` 会读取最近成功构建记录；没有记录时要求先 build 或显式传入 tag。优先级为 `--tag` > `GW_IMAGE_TAG` > 自动识别；为兼容已有本地镜像，显式推送仍接受旧 tag 格式。以上行为在源码修改发布后才进入 npm `@latest`，发布前用 `go run ./tools/cli --project ./gw.project.yaml image build` 验证。
 
 ## Chart 版本
 
-`chart package` 默认生成与镜像一致的 `yyyy.M.d-id`，例如 `2026.9.10-1`；Chart metadata、归档名和 Harbor OCI tag 不再二次映射或添加 project-id 前缀。`chart push` 默认复用 `projects.yaml` 中尚未发布且文件仍存在的精确归档；没有可复用包时自动分配下一版本、打包并推送。旧的 `{project-id}-yyyy.MM.dd.id`、`yyyy.MM.dd.id` 和合法 SemVer 仍可显式用于重建或回滚。
+`chart package` 独立生成 `yyyy.M.d-id`，例如 `2026.9.10-1`；Chart metadata、归档名和 Harbor OCI tag 不再二次映射或添加 project-id 前缀。`chart push` 默认复用 `projects.yaml` 中尚未发布且文件仍存在的精确归档；没有可复用包时自动分配下一版本、打包并推送。旧的 `{project-id}-yyyy.MM.dd.id`、`yyyy.MM.dd.id` 和合法 SemVer 仍可显式用于重建或回滚。镜像与 Chart 使用独立 OCI 仓库路径，示例见 [本地交付闭环](../../../docs/user-docs/LOCAL-PIPELINE.md)。
 
 ## 使用
 
@@ -45,35 +45,42 @@ npx -y --prefer-online @gbits-jszx/gw-cli@latest image push
 
 ```powershell
 npx -y --prefer-online @gbits-jszx/gw-cli@latest --version
-npx -y --prefer-online @gbits-jszx/gw-cli@latest doctor
-npx -y --prefer-online @gbits-jszx/gw-cli@latest build all
-npx -y --prefer-online @gbits-jszx/gw-cli@latest run all
+npx -y --prefer-online @gbits-jszx/gw-cli@latest --project ./gw.project.yaml doctor
+npx -y --prefer-online @gbits-jszx/gw-cli@latest --project ./gw.project.yaml test all
+npx -y --prefer-online @gbits-jszx/gw-cli@latest --project ./gw.project.yaml build all
+npx -y --prefer-online @gbits-jszx/gw-cli@latest --project ./gw.project.yaml run all
 # 另开终端
-npx -y --prefer-online @gbits-jszx/gw-cli@latest test all
+npx -y --prefer-online @gbits-jszx/gw-cli@latest --project ./gw.project.yaml smoke all
 ```
 
-`build`、`run`、`test` 统一接受 `core|mock|web|all`，`all` 只包含三个 app。`build`、`run` 需要源码和 Go，`run` 还需要 Docker（Windows 默认走 WSL）。npm 发布使用当前平台 npm；镜像命令优先使用当前平台 Docker，Windows 缺少 Docker 时转 WSL；Chart 推送在 Windows 默认走 WSL，可用 `--wsl=false` 切换。平台能力由 `doctor` 输出。
+`build`、`run`、`test`、`smoke` 统一接受 `core|mock|web|all`；`all` 的 app 目标集合不包含 CLI。Go 项目的 `test all` 在所选根目录执行 `go test ./...`，包含该项目的全部 Go 测试；单目标默认执行对应 package 的 `go test <package>/...`。项目可通过 `apps.*.test` 声明自定义测试，Go 项目的全量测试后也会执行这些命令。没有自定义测试命令、也没有有效 Go module/package 时会报错，不能用 `health-url` 代替。`smoke` 检查已启动的服务，沿用原服务检查的 `--url`、`--username`、`--password`、`--values`、`--profile` 参数；commands 项目通过 `health-url` 声明检查地址。
 
-`k3s init` 支持 Windows/WSL 和 Linux amd64 VM，无需源码或 Go：
+Go 项目的 `build`、`run`、`test` 需要源码和 Go，本仓库 `run` 还需要 Docker（Windows 默认走 WSL）。npm 发布使用当前平台 npm；镜像命令优先使用当前平台 Docker，Windows 缺少 Docker 时转 WSL；Chart 推送在 Windows 默认走 WSL，可用 `--wsl=false` 切换。平台能力由 `doctor` 输出。
+
+根 `--help` 只展示下一层入口，并按颜色分为“本地 PC · 日常开发”“远程 VM · 日常部署”“高级命令 · 制品与维护”；各级命令沿用所属分组颜色，参数默认值使用洋红色突出。交互终端默认启用颜色；`GW_CLI_COLOR=always|never` 可强制开关，未强制开启时 `NO_COLOR` 会关闭颜色。远程 VM 的推荐入口统一为 `deploy`，历史 `k3s`、`helm` 直达入口保持兼容但从根帮助隐藏。
+
+`deploy k3s init` 在 WSL 或 Linux amd64 VM 内执行，无需源码或 Go；Windows 可先执行 `--dry-run` 预览：
 
 ```sh
-npx -y --prefer-online @gbits-jszx/gw-cli@latest k3s init --dry-run
-npx -y --prefer-online @gbits-jszx/gw-cli@latest k3s init
+npx -y --prefer-online @gbits-jszx/gw-cli@latest --project ./gw.project.yaml deploy k3s init --dry-run
+npx -y --prefer-online @gbits-jszx/gw-cli@latest --project ./gw.project.yaml deploy k3s init
 ```
 
-目标机器需预先安装并运行 k3s、安装 Helm，并允许当前用户访问 kubeconfig。Windows 默认走 `Ubuntu-24.04` WSL，Linux 直接执行；不自动安装 k3s 或 Helm。PostgreSQL 参数使用 `--pgsql-*`，数据库名为 `--pgsql-dbname`。已有密码分别复用，首次业务及管理员密码人工输入，危险修改需二次确认，缺少 Docker 登录配置时跳过 imagePullSecret。完整说明见 [k3s 初始化](../../../docs/user-docs/K3S-INIT.md)。源码修改发布后才会进入 npm `@latest`。
+目标机器需预先安装并运行 k3s、安装 Helm，并允许当前用户访问 kubeconfig；不自动安装 k3s 或 Helm。PostgreSQL 参数使用 `--pgsql-*`，数据库名为 `--pgsql-dbname`。已有密码分别复用，首次业务及管理员密码人工输入，危险修改需二次确认。imagePullSecret 来自执行机器的 Docker `auths`，缺少有效凭据时跳过，不能由 Chart 的 Helm 登录替代。完整说明见 [k3s 初始化](../../../docs/user-docs/K3S-INIT.md)。源码修改发布后才会进入 npm `@latest`。
 
 ## 发布凭据
 
 项目身份、交付地址与部署目标声明在项目 `gw.project.yaml`；帮助和版本不创建配置。用户 `~/jszx-infra/.gw-cli/config.yaml` 仅保存发布凭据，`projects.yaml` 按项目记录制品版本。CI 携带项目文件并注入凭据，不依赖全局当前项目。
 
 ```powershell
-npx -y --prefer-online @gbits-jszx/gw-cli@latest publish npm --version 2026.9.11-2
-npx -y --prefer-online @gbits-jszx/gw-cli@latest publish image
-npx -y --prefer-online @gbits-jszx/gw-cli@latest publish chart
+npx -y --prefer-online @gbits-jszx/gw-cli@latest --project ./gw.project.yaml publish npm
+npx -y --prefer-online @gbits-jszx/gw-cli@latest --project ./gw.project.yaml publish image
+npx -y --prefer-online @gbits-jszx/gw-cli@latest --project ./gw.project.yaml publish chart --repository jszx-infra/charts --wsl=false
 ```
 
 缺少 npm Token 或 Harbor Robot 账号/密码时，CLI 会询问并自动保存到 `~/jszx-infra/.gw-cli/config.yaml`；可用 `GW_CLI_CONFIG` 覆盖位置。已有配置不重复询问。命令参数、`NODE_AUTH_TOKEN` / `GW_HARBOR_USERNAME` / `GW_HARBOR_PASSWORD` 优先于用户配置。
+
+`helm install` 拉取 OCI Chart 时先复用 Helm 原生登录或公共访问；只有确认认证失败才补齐 Harbor 账密，隐藏密码输入、保存后通过 stdin 登录。支持 `--username` / `--password` 和 `GW_HARBOR_USERNAME` / `GW_HARBOR_PASSWORD`，也支持 `--helm-registry-config` / `HELM_REGISTRY_CONFIG` 指定执行机器的 Helm 凭据文件。网络、版本不存在等错误直接报告；`--dry-run` 不探测、不登录、不询问账密。
 
 Token 和密码在终端中不回显。配置文件保存明文凭据，Unix 下目录/文件权限为 0700/0600，Windows 使用用户目录 ACL。网关服务不读取此文件。
 
@@ -83,15 +90,15 @@ Token 和密码在终端中不回显。配置文件保存明文凭据，Unix 下
 
 ```powershell
 # 自动使用当天序号，终端会打印版本和文件名
-go run ./tools/cli npm package
+go run ./tools/cli --project ./gw.project.yaml npm build
 # 或显式指定版本
-go run ./tools/cli npm package --version 2026.9.11-2
+go run ./tools/cli --project ./gw.project.yaml npm package --version 2026.9.11-2
 npx -y --package ./.gw-build/npm/gbits-jszx-gw-cli-2026.9.11-2.tgz gw-cli --version
-npx -y --package ./.gw-build/npm/gbits-jszx-gw-cli-2026.9.11-2.tgz gw-cli build all
+npx -y --package ./.gw-build/npm/gbits-jszx-gw-cli-2026.9.11-2.tgz gw-cli --project ./gw.project.yaml build all
 # 只检查发布包，不上传、不询问 Token
-go run ./tools/cli publish npm --dry-run
-# 真正发布：输入具备 @gbits-jszx/gw-cli 发布权限的 npm Token
-go run ./tools/cli publish npm --version 2026.9.11-2
+go run ./tools/cli --project ./gw.project.yaml publish npm --dry-run
+# 真正发布：重新构建并自动编号，输入具备发布权限的 npm Token
+go run ./tools/cli --project ./gw.project.yaml publish npm
 ```
 
 发布后的版本号不可复用。这里的 `gw-cli` 是包内命令名，公网下载始终使用 scoped 包 `@gbits-jszx/gw-cli`。

package/package.json

@@ -9,12 +9,12 @@
   "files": [
     "bin"
   ],
-  "gwVersion": "2026.9.12-7",
+  "gwVersion": "2026.9.12-9",
   "license": "MIT",
   "name": "@gbits-jszx/gw-cli",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "version": "2026.9.12-7"
+  "version": "2026.9.12-9"
 }