@aweray/hsk-cli 0.2.2

package/README.md

@@ -0,0 +1,356 @@
+# HSK CLI
+
+> HSK CLI — 零配置公网预览工具。一键内网穿透、文件托管，支持 Windows / macOS / Linux 多平台。
+
+[![npm version](https://img.shields.io/npm/v/@aweray/hsk-cli)](https://www.npmjs.com/package/@aweray/hsk-cli)
+[![Node.js](https://img.shields.io/node/v/@aweray/hsk-cli)](https://nodejs.org/)
+[![License](https://img.shields.io/npm/l/@aweray/hsk-cli)](LICENSE)
+
+## Features
+
+- **多平台自动适配** — 自动检测操作系统和架构，下载对应原生客户端二进制
+- **内网穿透** — 一键将本地服务暴露到公网，支持前台/后台两种保活模式
+- **文件托管** — 上传本地文件或构建产物，获取公网下载链接
+- **构建部署** — `deploy` 命令一键完成 build → pack → upload
+- **AI 友好** — 支持 `--json` 结构化输出，便于 AI Agent 解析和自动化
+- **版本同步** — npm 包版本与原生二进制版本一致，自动匹配升级
+
+## Supported Platforms
+
+| Platform | Architectures |
+|----------|---------------|
+| macOS    | Intel (amd64), Apple Silicon (arm64) |
+| Linux    | amd64 |
+| Windows  | amd64 |
+
+## Installation
+
+**Requirements:** Node.js >= 14
+
+```bash
+# 全局安装
+npm install -g @aweray/hsk-cli
+
+# 或 npx 免安装运行
+npx @aweray/hsk-cli <command>
+```
+
+首次运行时，CLI 会自动检测当前平台并下载对应的原生客户端二进制到 `~/.hsk/bin/`。
+
+## Quick Start
+
+### 1. 预下载客户端
+
+```bash
+hsk-cli download
+```
+
+### 2. 启动内网穿透（前台保活）
+
+```bash
+hsk-cli tunnel --ip 127.0.0.1 --port 9000
+```
+
+按 `Ctrl+C` 停止隧道。
+
+### 3. 启动内网穿透（后台保活）
+
+```bash
+hsk-cli tunnel --ip 127.0.0.1 --port 9000 --detach
+```
+
+后台模式启动后 CLI 立即退出，隧道持续运行。使用 `tunnel list` / `tunnel stop` 管理。
+
+### 4. 文件托管
+
+```bash
+hsk-cli host ./document.pdf
+```
+
+### 5. 构建并部署项目
+
+```bash
+hsk-cli deploy
+```
+
+自动执行 `npm run build` → 打包 `dist/` → 上传到文件托管。
+
+---
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--format <format>` | 输出格式: `json`, `pretty`, `table`, `ndjson`, `csv` (默认: `pretty`) |
+| `--dry-run` | 预览模式，不执行实际操作 |
+| `--json` | `--format json` 的快捷方式 |
+
+---
+
+## Command Reference
+
+### Tunnel Management
+
+#### `tunnel` — 启动内网穿透
+
+```bash
+hsk-cli tunnel --ip <IP> --port <PORT> [options]
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--ip <ip>` | 是 | 本地服务 IP 地址 |
+| `--port <port>` | 是 | 本地服务端口（1-65535） |
+| `--arch <arch>` | 否 | 强制指定客户端架构: `win32`, `win64`, `macos-x64`, `macos-arm64`, `linux-x64`, `linux-arm64` |
+| `--force-download` | 否 | 强制重新下载客户端二进制 |
+| `--detach` | 否 | 后台模式，CLI 立即退出，隧道持续运行 |
+| `--json` | 否 | 以 JSON 格式输出 |
+
+#### `tunnel list` — 查看后台隧道
+
+```bash
+hsk-cli tunnel list
+```
+
+显示所有后台运行的隧道，包括 PID、本地目标、启动时间和日志路径。自动清理已停止隧道的残留记录。
+
+#### `tunnel stop` — 停止隧道
+
+```bash
+# 停止指定 PID
+hsk-cli tunnel stop --pid <PID>
+
+# 停止全部
+hsk-cli tunnel stop --all
+```
+
+### File Hosting
+
+#### `host` — 上传文件
+
+```bash
+hsk-cli host <filePath> [options]
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `<filePath>` | 是 | 本地文件路径 |
+| `--resource-id <id>` | 否 | 资源 ID（传入则更新已有资源） |
+| `--open` | 否 | 上传完成后自动打开浏览器进行认领 |
+| `--json` | 否 | 以 JSON 格式输出 |
+
+> **注意**: `host` 仅支持单文件。上传目录（如 build/dist）请使用 `deploy` 命令。
+
+### Deploy
+
+#### `deploy` — 构建并部署项目
+
+```bash
+hsk-cli deploy [options]
+```
+
+一键执行：**构建** → **打包** → **上传**。
+
+| Option | Description |
+|--------|-------------|
+| `--build-cmd <cmd>` | 构建命令（默认: `npm run build`） |
+| `--build-dir <dir>` | 构建输出目录（默认: `dist`） |
+| `--pack-output <file>` | 打包文件名（默认: `dist.zip`） |
+| `--no-build` | 跳过构建，直接打包上传现有目录 |
+| `--no-clean` | 上传后保留打包文件 |
+| `--resource-id <id>` | 更新已有资源 |
+| `--open` | 上传完成后自动打开浏览器 |
+| `--json` | 以 JSON 格式输出 |
+
+**配置优先级**: 命令行参数 > 项目 `package.json` 的 `hsk.deploy` > 全局 `~/.hsk/config.json` > 默认配置
+
+**项目配置示例（`package.json`）**:
+
+```json
+{
+  "scripts": {
+    "build": "vite build"
+  },
+  "hsk": {
+    "deploy": {
+      "buildCmd": "npm run build",
+      "buildDir": "dist",
+      "packOutput": "dist.zip",
+      "cleanAfterUpload": true
+    }
+  }
+}
+```
+
+### System
+
+#### `download` — 预下载客户端
+
+```bash
+hsk-cli download [--arch <arch>]
+```
+
+#### `update` — 更新客户端
+
+```bash
+hsk-cli update [--arch <arch>] [--force]
+```
+
+#### `platform` — 显示平台信息
+
+```bash
+hsk-cli platform
+```
+
+---
+
+## Examples
+
+### 启动内网穿透并管理
+
+```bash
+# 前台模式（按 Ctrl+C 停止）
+hsk-cli tunnel --ip 127.0.0.1 --port 9000
+
+# 后台模式
+hsk-cli tunnel --ip 127.0.0.1 --port 9000 --detach
+
+# 查看后台隧道
+hsk-cli tunnel list
+
+# 停止全部后台隧道
+hsk-cli tunnel stop --all
+```
+
+### 上传文件并自动认领
+
+```bash
+hsk-cli host ./report.pdf --open
+```
+
+### 跨平台预下载
+
+```bash
+# 在 macOS 上预下载 Linux 版本
+hsk-cli download --arch linux-x64
+```
+
+### JSON 输出（AI 友好）
+
+```bash
+hsk-cli tunnel --ip 127.0.0.1 --port 9000 --json
+hsk-cli host ./document.pdf --json
+```
+
+### 构建并部署
+
+```bash
+# 使用项目配置
+hsk-cli deploy
+
+# 命令行覆盖配置
+hsk-cli deploy --build-cmd "yarn build" --build-dir "build"
+
+# 跳过构建，直接上传
+hsk-cli deploy --no-build
+
+# 更新已有资源
+hsk-cli deploy --resource-id abc123 --open
+```
+
+---
+
+## Configuration
+
+### 项目配置（`package.json`）
+
+```json
+{
+  "hsk": {
+    "deploy": {
+      "buildCmd": "npm run build",
+      "buildDir": "dist",
+      "packOutput": "dist.zip",
+      "cleanAfterUpload": true
+    }
+  }
+}
+```
+
+### 全局配置（`~/.hsk/config.json`）
+
+```json
+{
+  "deploy": {
+    "buildCmd": "npm run build",
+    "buildDir": "dist",
+    "packOutput": "dist.zip",
+    "cleanAfterUpload": true
+  }
+}
+```
+
+### 环境变量
+
+| Variable | Description |
+|----------|-------------|
+| `HSK_DOWNLOAD_URL` | 客户端二进制下载基地址 |
+| `HSK_FILE_HOSTING_API` | Ticket API 完整 URL |
+| `HSK_FILE_HOSTING_TICKET_HOST` | Ticket 服务主机 |
+| `HSK_FILE_HOSTING_UPLOAD_HOST` | 上传服务主机 |
+| `HSK_FILE_HOSTING_UPLOAD_PORT` | 上传服务端口 |
+| `HSK_FILE_HOSTING_UPLOAD_SCHEME` | 上传服务协议 |
+
+---
+
+## Logs
+
+- **macOS / Linux**: `~/.hsk/logs/`
+- **Windows**: `%USERPROFILE%\.hsk\logs\`
+
+---
+
+## How It Works
+
+```
+┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
+│   hsk-cli npm   │ ──▶ │  versions.json │ ──▶ │  download binary  │
+│   package (node)│     │  (version map) │     │  ~/.hsk/bin/    │
+└─────────────────┘     └──────────────┘     └─────────────────┘
+         │
+         ▼
+┌─────────────────┐
+│  native binary  │  ← 实际执行内网穿透/文件托管
+│  (cross-platform)│
+└─────────────────┘
+```
+
+- **npm 包**（启动器）：提供命令行接口、平台检测、自动下载、版本管理
+- **versions.json**：定义 npm 包版本与原生二进制版本的映射关系
+- **原生二进制**：按平台编译（Go/Rust/C++），实际执行网络穿透和文件传输
+
+---
+
+## Notes
+
+- During installation, the package automatically downloads the appropriate native binary for your operating system and architecture.
+- The CLI caches downloaded binaries in `~/.hsk/bin/`. No manual setup is required after installation.
+- The npm package version and native binary version are kept in sync. When you update the npm package, the corresponding binary will be downloaded automatically.
+- **前台模式（默认）**: CLI 启动客户端二进制作为子进程，实时输出日志，捕获到公网地址后持续运行。按 `Ctrl+C` 发送 `SIGTERM` 优雅停止。
+- **后台模式（`--detach`）**: CLI 启动子进程后使用 `detached: true` 解除父子绑定，立即退出。子进程在后台独立运行，日志写入 `~/.hsk/logs/`，PID 记录保存到 `~/.hsk/pids/`.
+- **Deploy**: `hsk-cli deploy` 执行 `build` → `pack` → `upload` 三步。打包使用系统原生 `zip`（macOS/Linux）或 PowerShell `Compress-Archive`（Windows），无需额外依赖.
+- Enable `--dry-run` to preview operations without executing them.
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](c) for guidelines.
+
+## License
+
+Copyright (c) 2026 Oray Inc. All rights reserved.