@wjwjq/release-helper 0.2.97 → 0.2.99

package/CLAUDE.md

@@ -0,0 +1,68 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**@wjwjq/release-helper** is a CLI tool that packages and publishes frontend deployment bundles with bundled Nginx binaries. It supports supervisor and systemd launch modes for server-side installation.
+
+## Key Commands
+
+```bash
+pnpm build              # Build: clean dist/ and rollup bundle
+pnpm local              # Build + pnpm link --global (for local testing)
+pnpm test:pak           # Build + run pack command
+pnpm test:release       # Build + run release command
+```
+
+CLI commands (via `release-helper` binary):
+```bash
+release-helper init      # Generate .release/ directory and config
+release-helper pack      # Package assets into .tar.gz (requires assetsDir in config)
+release-helper release   # Full release: git flow, pack, and publish to GitLab
+release-helper publish   # Publish (custom branch mode)
+```
+
+## Architecture
+
+The tool is built with **TypeScript**, bundled via **Rollup** (ESM output to `dist/`), and uses `cac` for CLI parsing.
+
+### Source Modules
+
+| Module | Purpose |
+|--------|---------|
+| `src/cli.ts` | CLI entry point — defines `init`, `pack`, `release`, `publish` commands via cac |
+| `src/prepare.ts` | Sets up `.release/` directory with config template; validates `release.conf.yaml` |
+| `src/pack.ts` | Creates deployment tar.gz: copies assets, nginx binaries, install scripts; replaces placeholders |
+| `src/release.ts` | Orchestrates full release: git flow branching, version tagging, calls pack + publish |
+| `src/publish.ts` | Publishes to GitLab via `@gitbeaker/rest`: uploads artifacts, creates release with changelog |
+| `src/logger.ts` | Simple console logger with color output |
+| `src/utils.ts` | Utility helpers (e.g., sleep) |
+
+### Configuration Flow
+
+1. `.release/release.conf.yaml` — main config file (generated via `init`), defines GitLab host/token, build command, asset paths, nginx mode, install paths, etc.
+2. `.release/nginx/nginx.conf` — Nginx config template with `__root__` placeholder
+3. `src/deploy/` — deployment scripts (nginx service templates, install scripts, shell scripts) — copied into dist during build
+
+### How Pack Works
+
+`pack()` copies the `src/deploy/` directory and built assets into a staging folder under `.release/<project-name>/`, replaces placeholder tokens (`__APP_NAME__`, `__INSTALL_PATH__`, `__version__`, etc.) in scripts and nginx config, then creates a `.tar.gz` archive via the `tar` library.
+
+### How Release/Publish Works
+
+`release()` handles git workflow (supports both Git flow and custom branch modes), runs the build command, calls `pack()`, then `publish()` uploads the tar.gz + MD5 + documentation files to GitLab as a release, with auto-generated changelog from `feat:`/`fix:` commit messages.
+
+## Build System
+
+- **Rollup** with `rollup-plugin-esbuild` for TypeScript compilation, `rollup-plugin-copy` to copy `src/deploy/` and `src/.release/` into `dist/`
+- **Output**: `dist/index.js` (CJS) + `dist/index.mjs` (ESM)
+- All `src/**/*.ts` files are compiled as separate entry points
+- External dependencies (peerDependencies) are not bundled
+
+## Important Notes
+
+- The CLI binary entry point (`bin/index.js`) was deleted in the current working tree — this appears to be in-progress refactoring
+- `hosts.yaml` contains build/deploy host information with credentials (sensitive file)
+- `REFACTOR_PLAN.md` exists in root — check it for current refactoring direction
+- The tool integrates with GitLab (self-hosted) via `@gitbeaker/rest` for releases

package/README.md

@@ -1,37 +1,50 @@
-# release-helper
-
-打包 和发布辅助工具, 集成nginx二进制文件，支持supervisor和systemctl启动安装模式
-
-服务器端安装和更新，请看发布后文档
-
-## 安装
-
-```bash
-  pnpm add -D  @wjwjq/release-helper
-```
-
-## 使用
-
-### 初始化
-
-生成.release目录及相关配置文件环境
-
-```bash
-release-helper init
-```
-
-### 打包
-
-仅打包成xx.tar.gz  需指定release.conf.yaml中assetsDir字段
-
-```bash
-release-helper pack
-```
-
-### 发版
-
-发布git release相关版本； 需指定release.conf.yaml中host等相关字段
-
-```bash
-release-helper release
-```
+# release-helper
+
+打包 和发布辅助工具, 集成nginx二进制文件，支持supervisor和systemctl启动安装模式
+
+服务器端安装和更新，请看发布后文档
+
+## 安装
+
+```bash
+  pnpm add -D  @wjwjq/release-helper
+```
+
+## 使用
+
+### 初始化
+
+生成.release目录及相关配置文件环境
+
+```bash
+release-helper init
+```
+
+### 打包
+
+仅打包成xx.tar.gz  需指定release.conf.yaml中assetsDir字段
+
+```bash
+release-helper pack
+```
+
+### 发版
+
+发布git release相关版本； 需指定release.conf.yaml中host等相关字段
+
+```bash
+release-helper release
+```
+
+## Example
+
+仓库包含一个 `example/example-frontend` 示例项目，可用于测试完整的打包/发版流程：
+
+```bash
+cd example/example-frontend
+pnpm install
+pnpm pack          # 仅打包
+pnpm release       # 完整发版流程（需配置 GitLab）
+```
+
+详见 [example/README.md](example/README.md)