@gbits-jszx/gw-cli 2026.9.12-9 → 2026.9.13-2

package/README.md

@@ -1,6 +1,8 @@
 # @gbits-jszx/gw-cli
 
-面向多个网关项目的跨平台构建、运行和交付工具。项目从 `--project <路径>` 指定的 `gw.project.yaml` 解析；`build/run/test/smoke/image/chart/npm/publish` 必须显式传入该参数，`GW_PROJECT_FILE` 和目录自动发现不能替代。`npm build/package/publish` 专用于维护 CLI 本身。
+面向多个网关项目的跨平台构建、运行和交付工具。项目身份唯一来自显式 `--project-id <代号>`（或 `--project-id=<代号>`）；不需要 `gw.project.yaml`，不接受旧 `--project` 路径，也不从 `GW_PROJECT_FILE` 或用户凭据中的旧 ID 兜底。`npm build/package/publish` 专用于维护 CLI 本身，包名固定为 `@gbits-jszx/gw-cli`，项目代号只隔离版本账本。
+
+> 本文新接口尚未发布。已发布的 `@gbits-jszx/gw-cli@2026.9.12-9` 仍使用旧 `--project`；新示例使用 `go run ./tools/cli`。新版发布并核对版本后，再替换为 `npx -y --prefer-online @gbits-jszx/gw-cli@latest`。历史已执行命令见 [2026-09-12 发布实录](../../../docs/user-docs/GW-DEMO-RELEASE-2026-09-12.md)。
 
 [PC 开发构建发布、WSL/云 VM 初始化部署更新](../../../docs/user-docs/CLI-MULTI-PROJECT.md)。公网 registry 为 `https://registry.npmjs.org/`，包内包含 Windows amd64 和 Linux amd64（含 WSL）二进制。
 
@@ -18,7 +20,7 @@ npm、Image、Chart 使用相同的 `yyyy.M.d-id` 格式，但按项目和制品
 
 旧的 `yyyy.MM.dd.id` 仅保留为显式输入兼容，用于重建已经发布的旧包；新自动版本不会再生成旧格式。
 
-序号记录位于 `~/jszx-infra/.gw-cli/projects.yaml`，按 `project-id` 和制品类型隔离；打包开始即占用，失败和 dry-run 也占用一次，避免自动重用版本。同一用户目录下的并发自动打包不会重复分配，清理 `.gw-build` 或切换仓库副本不会重置编号。手动指定版本可用于重打包或在本地验证后发布；换机器或 CI 多节点并行时仍需统一分配并显式传入未发布版本。`GW_CLI_PROJECTS` 可覆盖账本路径。
+序号记录位于 `~/jszx-infra/.gw-cli/projects.yaml`，按 `project-id` 和制品类型隔离；打包开始即占用，失败和 dry-run 也占用一次，避免自动重用版本。同一用户目录下、同一项目的并发自动打包不会重复分配，清理 `.gw-build` 或切换仓库副本不会重置编号。手动指定版本可用于重打包或在本地验证后发布；换机器或 CI 多节点并行时仍需统一分配并显式传入未发布版本。`GW_CLI_PROJECTS` 可覆盖账本路径。npm 包名固定，不同项目代号的账本隔离不代表能向该包重复发布同一个版本；维护 CLI 应使用稳定代号，当前为 `gw-demo`。上一轮已发布 `2026.9.12-9` 的账本位于该代号下；更换代号必须迁移版本账本，不能靠换 ID 重置 npm 编号。
 
 ## 镜像 tag
 
@@ -28,77 +30,90 @@ npm、Image、Chart 使用相同的 `yyyy.M.d-id` 格式，但按项目和制品
 
 ```powershell
 # 自动编号，输出 Docker 构建日志及最终完整镜像名
-npx -y --prefer-online @gbits-jszx/gw-cli@latest --project ./gw.project.yaml image build
+go run ./tools/cli --project-id gw-demo image build
 # 自动使用该 repository 最近一次成功构建的 tag，不生成新编号
-npx -y --prefer-online @gbits-jszx/gw-cli@latest --project ./gw.project.yaml image push
+go run ./tools/cli --project-id gw-demo image push
 ```
 
-`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` 验证。
+`image push` / `publish image` 的默认 `--tag auto` 会读取最近成功构建记录；没有记录时要求先 build 或显式传入 tag。优先级为 `--tag` > `GW_IMAGE_TAG` > 自动识别；为兼容已有本地镜像，显式推送仍接受旧 tag 格式。默认仓库为 `<Harbor>/<Harbor项目>/<project-id>`，完整地址可用 `--repository` 或 `GW_IMAGE_REPOSITORY` 覆盖。
 
 ## 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 使用独立 OCI 仓库路径，示例见 [本地交付闭环](../../../docs/user-docs/LOCAL-PIPELINE.md)。
+`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://<Harbor>/<Harbor项目>/charts/<project-id>`，自动与镜像路径分离，无需另传 `/charts`；`--registry/--repository` 可覆盖 registry 和 OCI 父路径。
 
 ## 使用
 
-首次发布成功后，在 GW-Framework 项目根目录执行：
+在 GW-Framework 源码根目录执行以下命令；公开 npm 入口的切换条件见本文开头：
 
 ```powershell
-npx -y --prefer-online @gbits-jszx/gw-cli@latest --version
-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 --project ./gw.project.yaml smoke all
+go run ./tools/cli --version
+go run ./tools/cli --project-id gw-demo doctor
+go run ./tools/cli --project-id gw-demo test all
+go run ./tools/cli --project-id gw-demo build all
+go run ./tools/cli --project-id gw-demo run all
 ```
 
-`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` 声明检查地址。
-
+| 命令 | `--project-id` |
+|---|---|
+| `build/run/test`、`image/chart/npm/publish` 的实际操作 | 必填 |
+| `project show`、`deploy k3s/helm` 的实际操作，包括状态查询及 dry-run | 必填 |
+| 隐藏 `cleanup`，仅供 npm wrapper 回收本地资源 | 必填 |
+| `doctor` | 可选 |
+| 帮助和版本查询 | 不需要 |
+
+项目代号最长 63 字符，以小写字母开头，只含小写字母、数字和不连续的连字符，末尾为字母或数字。缺失、空值、非法值或重复参数均失败；两次相同值也不接受。源码从当前目录向上找最近 `go.mod`，不通过项目代号定位另一个仓库。
+
+`build`、`run`、`test` 统一接受 `core|mock|web|all`，固定映射 `./apps/core-gateway`、`./apps/mock-gateway`、`./apps/web-service`；构建和运行的 `all` 不包含 CLI。`test all` 在源码根目录执行 `go test ./...`，单目标执行对应 package 的测试子树。旧 manifest 自定义 app/package/build/run/test/health-url 不再生效。`smoke` 和整个 `dev` 入口已删除；Demo HTTP 与网络验收由 [`tests/gw-demo/`](../../../tests/gw-demo/) 项目脚本承担。
+
+基础默认值仍为 `tools/helm/default/values.yaml`；`--profile beta` / `--profile release` 选择 Chart 内 profile，`--values` 额外覆盖，未指定 profile 时只用基础默认值。`--release` 仅表示 Helm 实例名。
+
+本地 `run` 按合并后的 values 开启功能，默认关闭登录和 Hello；本地配置使用 `local.*`。启用 Demo 的 `run web/all --profile beta` 必须显式提供密码，推荐安全输入 `GW_LOGIN_PASSWORD`。非空环境变量优先于外部 values 的 `loginDemo.password`；两者都缺少时在启动资源前报错。没有内置登录密码，真实凭据不得提交到仓库。临时 PostgreSQL 每次随机生成密码，退出时回收。
+
 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` 直达入口保持兼容但从根帮助隐藏。
+根 `--help` 只展示下一层入口，并按颜色分为“本地 PC · 日常开发”“远程 VM · 日常部署”“高级命令 · 制品与维护”；各级命令沿用所属分组颜色，参数默认值使用洋红色突出。交互终端默认启用颜色；`GW_CLI_COLOR=always|never` 可强制开关，未强制开启时 `NO_COLOR` 会关闭颜色。集群操作唯一入口为 `deploy k3s` / `deploy helm`，包括 `deploy k3s restore/purge`；顶层 `k3s` / `helm` 已删除。
 
-`deploy k3s init` 在 WSL 或 Linux amd64 VM 内执行，无需源码或 Go；Windows 可先执行 `--dry-run` 预览：
-
-```sh
-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
+`deploy k3s init` 在 WSL 或 Linux amd64 VM 内执行，无需项目文件、源码或 Go。当前新接口未发布，无源码 VM 需使用本次源码构建并核对过版本的 Linux CLI；下面是 Windows 源码端的预览入口：
+
+```powershell
+go run ./tools/cli --project-id gw-demo deploy k3s init --dry-run
 ```
 
 目标机器需预先安装并运行 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 携带项目文件并注入凭据，不依赖全局当前项目。
+项目身份仅来自 `--project-id`，默认交付地址和资源名称从代号推导。Harbor 端点按对应命令支持的参数 > `GW_HARBOR_REGISTRY/GW_HARBOR_PROJECT` > 用户配置端点 > `szharbor.g-bits.com/jszx-infra` 默认值解析。用户 `~/jszx-infra/.gw-cli/config.yaml` 保存凭据及其端点，不保存当前项目；`projects.yaml` 按项目记录制品版本。CI 显式传代号并注入凭据，无需携带项目清单。帮助和版本查询不创建配置。
+
+Namespace/应用 Release 默认代号，PG Release 默认 `<代号>-pg`，数据库名/用户名将 `-` 转为 `_`，数据库连接 Secret 默认 `<代号>-database`。超长 Release/资源名自动缩短并保留确定性哈希；Namespace 和制品地址保留完整代号。kubeconfig/context 默认 `/etc/rancher/k3s/k3s.yaml` / `default`，可通过现有参数及环境变量覆盖。已有资源应显式保留原目标，不能覆盖 DataGateway `dg-dev`。详细迁移表见[多项目 CLI 指南](../../../docs/user-docs/CLI-MULTI-PROJECT.md)。
 
 ```powershell
-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
+go run ./tools/cli --project-id gw-demo publish npm
+go run ./tools/cli --project-id gw-demo publish image
+go run ./tools/cli --project-id gw-demo publish chart --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` 不探测、不登录、不询问账密。
 
+`deploy 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。网关服务不读取此文件。
 
-## 首次发布与本地验证
+## 源码打包与本地验证
 
-2026-09-09 查询公网 `@gbits-jszx/gw-cli` 返回 404；首次发布前直接运行源码 CLI：
+已有公开 npm 包；本次 `--project-id` 改造需先从当前源码打包验证，再按授权发布新版。以下 npm 操作继续使用已有版本账本对应的维护代号 `gw-demo`：
 
 ```powershell
 # 自动使用当天序号，终端会打印版本和文件名
-go run ./tools/cli --project ./gw.project.yaml npm build
-# 或显式指定版本
-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 --project ./gw.project.yaml build all
+go run ./tools/cli --project-id gw-demo npm build
+# 把占位文件名替换为本次 build 实际输出的文件名；这里使用本地新包
+$gwNpmArchive = './.gw-build/npm/<本次输出的文件名>.tgz'
+npx -y --package $gwNpmArchive gw-cli --version
+npx -y --package $gwNpmArchive gw-cli --project-id gw-demo project show
 # 只检查发布包，不上传、不询问 Token
-go run ./tools/cli --project ./gw.project.yaml publish npm --dry-run
-# 真正发布：重新构建并自动编号，输入具备发布权限的 npm Token
-go run ./tools/cli --project ./gw.project.yaml publish npm
+go run ./tools/cli --project-id gw-demo publish npm --dry-run
+# 获得发布授权后执行：重新构建并自动编号，输入具备发布权限的 npm Token
+go run ./tools/cli --project-id gw-demo publish npm
 ```
 
 发布后的版本号不可复用。这里的 `gw-cli` 是包内命令名，公网下载始终使用 scoped 包 `@gbits-jszx/gw-cli`。

package/bin/gw-cli.js

@@ -31,13 +31,16 @@ const selection = [];
 const command = [];
 const cliArgs = process.argv.slice(2);
 let helpOnly = false;
+let invalidSelection = false;
 for (let i = 0; i < cliArgs.length; i++) {
   const arg = cliArgs[i];
   if (arg === '--help' || arg === '-h') helpOnly = true;
-  if (arg === '--project') {
-    selection.push(arg, cliArgs[++i]);
-  } else if (arg.startsWith('--project=')) {
-    selection.push(arg);
+  if (arg === '--' || arg === '--project' || arg.startsWith('--project=')) invalidSelection = true;
+  if (arg === '--project-id' || arg.startsWith('--project-id=')) {
+    const value = arg === '--project-id' ? cliArgs[++i] : arg.slice('--project-id='.length);
+    if (selection.length > 0 || !value || value.length > 63 || !/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(value)) invalidSelection = true;
+    if (arg === '--project-id') selection.push(arg, value);
+    else selection.push(arg);
   } else {
     command.push(arg);
   }
@@ -59,7 +62,7 @@ child.on('exit', (code) => {
   // Run after the child exits; invoking Docker while a Windows Ctrl+C event is
   // active can interrupt the cleanup subprocess itself.
   // A test/build/publish in another terminal must not remove run all's DB.
-  if (!helpOnly && command[0] === 'run' && ['core', 'mock', 'web', 'all'].includes(command[1]) && Number.isInteger(child.pid) && child.pid > 0) {
+  if (!helpOnly && !invalidSelection && selection.length > 0 && command[0] === 'run' && ['core', 'mock', 'web', 'all'].includes(command[1]) && Number.isInteger(child.pid) && child.pid > 0) {
     spawnSync(binary, [...selection, 'cleanup', '--owner-pid', String(child.pid)], { stdio: 'inherit', windowsHide: true });
   }
   process.exit(code === null ? 1 : code);

package/package.json

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