gz-cli-front 0.0.0-stage → 1.0.1-beta.0

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
-
-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.
+# gz-cli-front
+
+一个轻量级的现代前端脚手架工具，通过远程模板创建项目。
+
+npm 包名为 `gz-cli-front`，安装后使用 `gz-cli` 命令。
+
+版本变化见 [更新日志](CHANGELOG.md)。
+
+## 安装
+
+```bash
+npm install -g gz-cli-front
+```
+
+## 使用
+
+```bash
+gz-cli init [project-name]
+```
+
+也可以不全局安装，直接运行：
+
+```bash
+npx gz-cli-front init demo-app
+```
+
+`create` 命令仍可使用，例如 `gz-cli create demo-app`。
+同时保留 `gz-cli-front` 作为兼容命令，两者执行相同逻辑；新包不注册旧的 `gg-cli` 命令。
+
+从旧包迁移时可执行：
+
+```bash
+npm uninstall -g @chenhui996/gg-cli
+npm install -g gz-cli-front
+gz-cli --version
+gz-cli init demo-app
+```
+
+切换 CLI 后，新建项目会使用当前远程模板；已有业务项目不会自动迁移。
+
+可通过 `--pm` 指定本次初始化使用的包管理器：
+
+```bash
+gz-cli init demo-app --pm npm
+gz-cli init demo-app --pm pnpm
+gz-cli init demo-app --pm yarn
+```
+
+未指定时，CLI 会按 `pnpm`、`yarn`、`npm` 的顺序检测当前环境；都未检测到时默认使用 `npm`。模板注册表不包含包管理器配置。
+
+### 网络代理
+
+CLI 会自动读取当前系统代理，不绑定具体代理工具、地址或端口。代理优先级如下：
+
+```text
+--no-proxy 强制直连
+--proxy 参数
+HTTP_PROXY / HTTPS_PROXY / NO_PROXY
+操作系统代理
+无代理直连
+```
+
+临时指定代理或强制直连：
+
+```bash
+gz-cli init demo-app --proxy http://proxy-host:port
+gz-cli init demo-app --no-proxy
+```
+
+系统代理检测支持 Windows、macOS 和 Linux。代理相关日志只显示网络路径，不输出代理地址、账号或密码。
+
+### 模板缓存
+
+模板注册仓库和模板仓库会浅克隆并缓存到 `~/.gz-cli-front/cache`，减少重复创建项目时的网络等待。需要忽略缓存并获取最新内容时执行：
+
+```bash
+gz-cli init demo-app --refresh
+```
+
+注册表缓存有效期为 5 分钟，`latest` 模板缓存有效期为 10 分钟；指定版本的模板缓存可以长期复用。远程暂时不可用时，未指定 `--refresh` 会回退到已有缓存。
+
+模板注册仓库和模板仓库均为公共仓库，默认通过配置中的 HTTPS 地址直接下载，无需配置 GitHub Token 或 SSH Key。Git 操作设有超时并支持网络代理；如显式配置 SSH clone URL，仍会使用本机 SSH Agent。
+
+可通过 `GZ_CLI_FRONT_CACHE_DIR` 指定缓存目录，通过 `GZ_CLI_FRONT_DEBUG=1` 开启网络和模板调试日志。新包不读取旧的 `GG_CLI_*` 环境变量，也不复用旧包的默认缓存目录。
+
+模板注册仓库由 `config/gz-cli-front.config.json` 管理，现有远程仓库地址保持不变：
+
+```json
+{
+  "templateRegistry": {
+    "source": "git",
+    "url": "https://github.com/gz-fronted/gg-cli-template-register.git",
+    "file": "templates.json"
+  }
+}
+```
+
+注册表中的每个模板使用独立仓库，例如：
+
+```json
+[
+  {
+    "name": "main-app",
+    "label": "主应用模板",
+    "description": "Garfish 主应用模板",
+    "type": "main",
+    "source": "git",
+    "url": "https://github.com/your-org/gg-cli-template-main-app.git",
+    "version": "latest"
+  },
+  {
+    "name": "micro-app",
+    "label": "微应用模板",
+    "description": "Garfish 微应用模板",
+    "type": "micro",
+    "source": "git",
+    "url": "https://github.com/your-org/gg-cli-template-micro-app.git",
+    "version": "latest"
+  }
+]
+```
+
+公共仓库建议使用 `source: "git"` 和 HTTPS clone URL，避免要求使用者配置 SSH Key。CLI 会按配置的协议执行浅克隆；`source` 仍兼容 `github`、`gitlab` 和 `git`，旧的 GitHub `repo` 配置也可继续使用。
+
+### Git 仓库访问测试
+
+发版前可以在本机验证 Git 仓库访问失败时的错误提示，不会修改全局 Git 配置：
+
+```bash
+npm run test:auth-error
+```
+
+该脚本使用独立缓存和模拟失败的 Git 命令运行构建后的 CLI，要求在超时前返回明确错误。正常访问链路仍使用以下命令验证：
+
+```bash
+npm run build
+node dist/index.js init --refresh
+```
+
+发版前统一执行：
+
+```bash
+npm run test:release
+```
+
+该命令会依次验证构建、命令入口及参数、HTTPS Git 兼容性、公共注册仓库访问、失败错误提示和 npm 发布包内容。
+
+如果已经手动执行过 `npm run build`，可以只验证构建产物和 Git 场景：
+
+```bash
+npm run test:smoke
+```
+
+## 发布到 npm
+
+本包以 `gz-cli-front` 为独立包名，初始版本为 `1.0.0`，不会覆盖或更新旧的 `@chenhui996/gg-cli` 包。
+
+首次发布前，确认包名尚未被占用，并登录有发布权限的 npm 账号：
+
+```bash
+npm view gz-cli-front --registry=https://registry.npmjs.org/
+npm login --registry=https://registry.npmjs.org/
+npm whoami --registry=https://registry.npmjs.org/
+```
+
+查询返回 E404 表示未找到该包；网络或认证错误不能作为包名可用的判断依据。最终能否发布以 npm 的校验结果为准。
+
+安装依赖并验证：
+
+```bash
+npm ci
+npm run test:release
+```
+
+确认通过后发布：
+
+```bash
+npm publish --registry=https://registry.npmjs.org/
+```
+
+发布时会自动通过 `prepublishOnly` 再运行一次发布验证。发布内容包括 `bin`、构建后的 `dist`、包信息和 README，不包含 `src/template` 中的本地模板。
+
+发布后可验证：
+
+```bash
+npm view gz-cli-front version --registry=https://registry.npmjs.org/
+npx --registry=https://registry.npmjs.org/ gz-cli-front@1.0.0 --version
+```

package/bin/gz-cli-front.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';

package/dist/config/gz-cli-front.config.json

@@ -0,0 +1,7 @@
+{
+  "templateRegistry": {
+    "source": "git",
+    "url": "https://github.com/gz-fronted/gg-cli-template-register.git",
+    "file": "templates.json"
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }