From 963a81335fbcfedb2d23dba7fff78d4e3f32f891 Mon Sep 17 00:00:00 2001 From: huangshan Date: Sun, 19 Apr 2026 21:20:51 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E7=BB=84=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E7=BB=93=E6=9E=84=EF=BC=8C=E6=8C=89=E8=AF=AD=E8=A8=80=E5=92=8C?= =?UTF-8?q?=E4=B8=BB=E9=A2=98=E6=8B=86=E5=88=86=E5=88=B0=20docs/=20?= =?UTF-8?q?=E7=9B=AE=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 将 README 中的详细文档拆分到 docs/zh/ 和 docs/en/ 目录 - 新增 docs/zh/: 01-installation, 02-usage, 03-development, 04-contributing - 新增 docs/en/: 01-installation, 02-usage, 03-development, 04-contributing - 精简 README.zh.md，英文文档迁移至 docs/en/ - 删除 README.en.md（内容已迁移） - 更新 AGENTS.md 添加文档目录说明 - 删除过时的发布自动化设计文档 --- AGENTS.md | 3 +- README.en.md | 224 --------- README.md | 23 +- README.zh.md | 190 +------ docs/en/01-installation.md | 35 ++ docs/en/02-usage.md | 56 +++ docs/en/03-development.md | 23 + docs/en/04-contributing.md | 18 + .../plans/2026-04-18-release-automation.md | 474 ------------------ .../2026-04-18-release-automation-design.md | 93 ---- docs/zh/01-installation.md | 35 ++ docs/zh/02-usage.md | 67 +++ docs/zh/03-development.md | 24 + docs/zh/04-contributing.md | 18 + 14 files changed, 306 insertions(+), 977 deletions(-) delete mode 100644 README.en.md create mode 100644 docs/en/01-installation.md create mode 100644 docs/en/02-usage.md create mode 100644 docs/en/03-development.md create mode 100644 docs/en/04-contributing.md delete mode 100644 docs/superpowers/plans/2026-04-18-release-automation.md delete mode 100644 docs/superpowers/specs/2026-04-18-release-automation-design.md create mode 100644 docs/zh/01-installation.md create mode 100644 docs/zh/02-usage.md create mode 100644 docs/zh/03-development.md create mode 100644 docs/zh/04-contributing.md diff --git a/AGENTS.md b/AGENTS.md index b4bde2d..f060f56 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,9 +1,10 @@ -# Repository Guidelines +# Repository Guidelines ## 项目结构与模块组织 - Rust 核心：入口在 `src/bin/ziro.rs`；`src/cli/`（`args.rs` 参数定义，`handlers.rs` 命令分发）；`src/core/`（`port/` 端口扫描，`process/` 进程终止，`fs_ops/` 文件删除与安全校验，`top/` 监控）；`src/platform/`（`term.rs` 终端/环境配置，`encoding.rs` Windows UTF-8 初始化）；`src/ui/`（`render.rs` 输出、交互，`theme.rs` 颜色，`icons.rs` 图标）。 - Node 分发层：`bin/ziro.js` 作为 npm 启动代理，`scripts/install.js`+`detect-platform.js` 下载发布产物，`package.json` 声明元数据。 - 发行/工具：`target/` 存放构建产物（已忽略），`.github/` 存放 CI/发布配置。 +- **文档说明**：详细文档存放在 `docs/zh/` (中文) 和 `docs/en/` (英文) 目录下，按模块（安装、使用、开发、贡献）拆分。 ## 构建、测试与开发命令 - `cargo build --release`：生成优化二进制到 `target/release/ziro`。 diff --git a/README.en.md b/README.en.md deleted file mode 100644 index 8a8b22a..0000000 --- a/README.en.md +++ /dev/null @@ -1,224 +0,0 @@ -# Ziro - -
- -A fast, cross-platform port management tool - -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![Crates.io](https://img.shields.io/crates/v/ziro.svg)](https://crates.io/crates/ziro) -[![npm](https://img.shields.io/npm/v/@ithinku/ziro.svg)](https://www.npmjs.com/package/@ithinku/ziro) - -[English](README.en.md) | [简体中文](README.zh.md) - -
- -## Introduction - -Ziro is a powerful command-line tool for quickly finding and managing processes that occupy ports. Supports Windows, Linux, and macOS platforms. - -### Core Features - -- 🔍 **Quick Search** - Instantly find processes occupying specified ports -- 🎯 **Batch Kill** - Support terminating processes on multiple ports simultaneously -- 📊 **Detailed Information** - Display process PID, name, command, CPU and memory usage -- 🎨 **Beautiful Interface** - Colored output and table display for better visual experience -- 💬 **Interactive Selection** - Interactive selection and confirmation before terminating processes -- 🌍 **Cross-Platform** - Supports Windows, Linux, and macOS - -## Installation - -### Using Cargo (Rust Users) - -```bash -cargo install ziro -``` - -### Using npm (Node.js Users) - -```bash -npm install -g @ithinku/ziro -``` - -Or use other package managers: - -```bash -# Using yarn -yarn global add @ithinku/ziro - -# Using pnpm -pnpm add -g @ithinku/ziro -``` - -## Usage - -### Find Process Occupying a Port - -```bash -# Find process occupying port 8080 -ziro find 8080 -``` - -Output example: -``` -Found process occupying port: - Port: 8080 - PID: 12345 - Name: node - Command: node server.js - CPU: 2.3% - Memory: 128 MB -``` - -### Kill Process Occupying a Port - -```bash -# Kill process occupying port 8080 -ziro kill 8080 - -# Kill processes on multiple ports -ziro kill 8080 3000 5000 -``` - -The program will display all found processes, allowing you to interactively select which processes to terminate and confirm before termination. - -### List All Port Occupancy - -```bash -ziro list -``` - -Output example: -``` -Current port occupancy: -╭──────┬───────┬──────────┬─────────────────────────┬───────┬────────╮ -│ Port │ PID │ Name │ Command │ CPU │ Memory │ -├──────┼───────┼──────────┼─────────────────────────┼───────┼────────┤ -│ 3000 │ 12345 │ node │ node app.js │ 1.2% │ 95 MB │ -│ 8080 │ 23456 │ python │ python -m http.server │ 0.5% │ 45 MB │ -│ 5432 │ 34567 │ postgres │ /usr/bin/postgres │ 3.1% │ 256 MB │ -╰──────┴───────┴──────────┴─────────────────────────┴───────┴────────╯ -``` - -### Check File/Directory Lock - -```bash -# Check a single file -ziro who C:\path\file.txt - -# Check multiple paths -ziro who .\logs .\data\app.db -``` - -The output reports whether the path is locked and shows related processes when available. - -## Command Reference - -``` -Ziro - Cross-platform port management tool - -Usage: - ziro - -Commands: - find Find process occupying specified port - kill ... Kill processes occupying specified ports (multiple allowed) - list List all port occupancy - who ... Check processes occupying a file or directory - help Show help information - -Options: - -h, --help Show help information - -V, --version Show version information -``` - -## Platform Support - -| Operating System | Architecture | Status | -|-----------------|--------------|--------| -| Windows | x64 | ✅ Fully Supported | -| Linux | x64 | ✅ Fully Supported | -| Linux | arm64 | ✅ Fully Supported | -| macOS | x64 | ✅ Fully Supported | -| macOS | arm64 | ✅ Fully Supported | - -## Tech Stack - -- **Core Language**: Rust -- **CLI Parsing**: clap -- **System Info**: sysinfo -- **Interactive UI**: inquire -- **Colored Output**: colored - -## Development - -### Build Project - -```bash -# Clone repository -git clone https://github.com/Protagonistss/ziro.git -cd ziro - -# Build -cargo build --release - -# Run -cargo run -- find 8080 -``` - -### Run Tests - -```bash -cargo test -``` - -### Code Formatting - -```bash -cargo fmt -``` - -### Code Linting - -```bash -cargo clippy -``` - -## Contributing - -Contributions are welcome! Feel free to submit Issues or Pull Requests. - -### Contribution Guidelines - -1. Fork this project -2. Create a feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'feat: add amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Create a Pull Request - -## License - -This project is open source under the [MIT License](LICENSE). - -## Acknowledgments - -Thanks to all contributors and users for their support! - -## Related Projects - -- [fkill](https://github.com/sindresorhus/fkill) - Node.js version of process termination tool -- [lsof](https://github.com/lsof-org/lsof) - Unix system file and network connection viewing tool - -## Changelog - -See [CHANGELOG.md](CHANGELOG.md) for version history. - ---- - -
- -**If this project helps you, please give it a ⭐️** - -Made with ❤️ by [huangshan](https://github.com/Protagonistss) - -
- diff --git a/README.md b/README.md index f9f1cf4..21d5663 100644 --- a/README.md +++ b/README.md @@ -4,18 +4,20 @@ A fast, cross-platform port management tool -一个快速、跨平台的端口管理工具 - [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Crates.io](https://img.shields.io/crates/v/ziro.svg)](https://crates.io/crates/ziro) [![npm](https://img.shields.io/npm/v/@ithinku/ziro.svg)](https://www.npmjs.com/package/@ithinku/ziro) **Choose Language / 选择语言:** -[🇺🇸 English](README.en.md) | [🇨🇳 简体中文](README.zh.md) +[🇺🇸 English](README.md) | [🇨🇳 简体中文](README.zh.md) +## Introduction + +Ziro is a powerful command-line tool for quickly finding and managing processes that occupy ports. Supports Windows, Linux, and macOS platforms. + ## Quick Start ### Install @@ -30,7 +32,7 @@ cargo install ziro npm install -g @ithinku/ziro ``` -### Usage +### Basic Usage ```bash # Find process on port 8080 @@ -38,13 +40,16 @@ ziro find 8080 # Kill process on port 8080 ziro kill 8080 +``` -# List all ports -ziro list +## Documentation -# Check file/directory lock -ziro who C:\path\file.txt -``` +For full details, please refer to our detailed documentation: + +- [Installation Guide](docs/en/01-installation.md) +- [Usage Guide](docs/en/02-usage.md) +- [Development Guide](docs/en/03-development.md) +- [Contributing Guide](docs/en/04-contributing.md) --- diff --git a/README.zh.md b/README.zh.md index d553329..a243dda 100644 --- a/README.zh.md +++ b/README.zh.md @@ -8,7 +8,9 @@ [![Crates.io](https://img.shields.io/crates/v/ziro.svg)](https://crates.io/crates/ziro) [![npm](https://img.shields.io/npm/v/@ithinku/ziro.svg)](https://www.npmjs.com/package/@ithinku/ziro) -[English](README.en.md) | [简体中文](README.zh.md) +**Choose Language / 选择语言:** + +[🇺🇸 English](README.md) | [🇨🇳 简体中文](README.zh.md) @@ -16,201 +18,38 @@ Ziro 是一个强大的命令行工具，用于快速查找和管理占用端口的进程。支持 Windows、Linux 和 macOS 平台。 -### 核心特性 - -- 🔍 **快速查找** - 即时查找占用指定端口的进程 -- 🎯 **批量终止** - 支持同时终止多个端口的进程 -- 📊 **详细信息** - 显示进程 PID、名称、命令、CPU 和内存使用情况 -- 🎨 **美观界面** - 彩色输出和表格展示，提供更好的视觉体验 -- 💬 **交互式选择** - 终止进程前可交互式选择和确认 -- 🌍 **跨平台** - 支持 Windows、Linux 和 macOS - -## 安装 +## 极简快速开始 -### 使用 Cargo（Rust 用户） +### 安装 +**Cargo:** ```bash cargo install ziro ``` -### 使用 npm（Node.js 用户） - +**npm:** ```bash npm install -g @ithinku/ziro ``` -或使用其他包管理器： - -```bash -# 使用 yarn -yarn global add @ithinku/ziro - -# 使用 pnpm -pnpm add -g @ithinku/ziro -``` - -## 使用方法 - -### 查找占用端口的进程 +### 基础用法 ```bash # 查找占用 8080 端口的进程 ziro find 8080 -``` - -输出示例： -``` -找到占用端口的进程： - 端口: 8080 - PID: 12345 - 名称: node - 命令: node server.js - CPU: 2.3% - 内存: 128 MB -``` -### 终止占用端口的进程 - -```bash # 终止占用 8080 端口的进程 ziro kill 8080 - -# 终止多个端口的进程 -ziro kill 8080 3000 5000 -``` - -程序会显示找到的所有进程，让你交互式地选择要终止的进程，并在终止前进行确认。 - -### 列出所有端口占用情况 - -```bash -ziro list -``` - -输出示例： -``` -当前端口占用情况： -╭──────┬───────┬──────────┬─────────────────────────┬───────┬────────╮ -│ 端口 │ PID │ 名称 │ 命令 │ CPU │ 内存 │ -├──────┼───────┼──────────┼─────────────────────────┼───────┼────────┤ -│ 3000 │ 12345 │ node │ node app.js │ 1.2% │ 95 MB │ -│ 8080 │ 23456 │ python │ python -m http.server │ 0.5% │ 45 MB │ -│ 5432 │ 34567 │ postgres │ /usr/bin/postgres │ 3.1% │ 256 MB │ -╰──────┴───────┴──────────┴─────────────────────────┴───────┴────────╯ -``` - -### 查看文件/目录占用 - -```bash -# 查看单个文件 -ziro who C:\path\file.txt - -# 查看多个路径 -ziro who .\logs .\data\app.db ``` -输出会显示是否被占用，并在可用时列出相关进程。 +## 详细文档 -## 命令参考 - -``` -Ziro - 跨平台端口管理工具 - -使用方法: - ziro - -命令: - find 查找占用指定端口的进程 - kill ... 终止占用指定端口的进程（可指定多个） - list 列出所有端口占用情况 - who ... 查找占用指定文件或目录的进程 - help 显示帮助信息 - -选项: - -h, --help 显示帮助信息 - -V, --version 显示版本信息 -``` +欲了解更多信息，请查阅详细文档： -## 平台支持 - -| 操作系统 | 架构 | 支持状态 | -|---------|------|---------| -| Windows | x64 | ✅ 完全支持 | -| Linux | x64 | ✅ 完全支持 | -| Linux | arm64| ✅ 完全支持 | -| macOS | x64 | ✅ 完全支持 | -| macOS | arm64| ✅ 完全支持 | - -## 技术栈 - -- **核心语言**: Rust -- **命令行解析**: clap -- **系统信息**: sysinfo -- **交互界面**: inquire -- **彩色输出**: colored - -## 开发 - -### 构建项目 - -```bash -# 克隆仓库 -git clone https://github.com/Protagonistss/ziro.git -cd ziro - -# 构建 -cargo build --release - -# 运行 -cargo run -- find 8080 -``` - -### 运行测试 - -```bash -cargo test -``` - -### 代码格式化 - -```bash -cargo fmt -``` - -### 代码检查 - -```bash -cargo clippy -``` - -## 贡献 - -欢迎贡献！请随意提交 Issue 或 Pull Request。 - -### 贡献指南 - -1. Fork 本项目 -2. 创建特性分支 (`git checkout -b feature/amazing-feature`) -3. 提交更改 (`git commit -m 'feat: add amazing feature'`) -4. 推送到分支 (`git push origin feature/amazing-feature`) -5. 创建 Pull Request - -## 许可证 - -本项目基于 [MIT License](LICENSE) 开源。 - -## 致谢 - -感谢所有贡献者和使用者的支持！ - -## 相关项目 - -- [fkill](https://github.com/sindresorhus/fkill) - Node.js 版本的进程终止工具 -- [lsof](https://github.com/lsof-org/lsof) - Unix 系统的文件和网络连接查看工具 - -## 更新日志 - -查看 [CHANGELOG.md](CHANGELOG.md) 了解版本历史。 +- [安装指南](docs/zh/01-installation.md) +- [使用指南](docs/zh/02-usage.md) +- [开发指南](docs/zh/03-development.md) +- [贡献指南](docs/zh/04-contributing.md) --- @@ -221,4 +60,3 @@ cargo clippy Made with ❤️ by [huangshan](https://github.com/Protagonistss) - diff --git a/docs/en/01-installation.md b/docs/en/01-installation.md new file mode 100644 index 0000000..262b7bd --- /dev/null +++ b/docs/en/01-installation.md @@ -0,0 +1,35 @@ +# Installation Guide + +## Installation + +### Using Cargo (Rust Users) + +```bash +cargo install ziro +``` + +### Using npm (Node.js Users) + +```bash +npm install -g @ithinku/ziro +``` + +Or use other package managers: + +```bash +# Using yarn +yarn global add @ithinku/ziro + +# Using pnpm +pnpm add -g @ithinku/ziro +``` + +## Platform Support + +| Operating System | Architecture | Status | +|-----------------|--------------|--------| +| Windows | x64 | ✅ Fully Supported | +| Linux | x64 | ✅ Fully Supported | +| Linux | arm64 | ✅ Fully Supported | +| macOS | x64 | ✅ Fully Supported | +| macOS | arm64 | ✅ Fully Supported | diff --git a/docs/en/02-usage.md b/docs/en/02-usage.md new file mode 100644 index 0000000..2982cb8 --- /dev/null +++ b/docs/en/02-usage.md @@ -0,0 +1,56 @@ +# Usage Guide + +### Find Process Occupying a Port + +```bash +# Find process occupying port 8080 +ziro find 8080 +``` + +### Kill Process Occupying a Port + +```bash +# Kill process occupying port 8080 +ziro kill 8080 + +# Kill processes on multiple ports +ziro kill 8080 3000 5000 +``` + +The program will display all found processes, allowing you to interactively select which processes to terminate and confirm before termination. + +### List All Port Occupancy + +```bash +ziro list +``` + +### Check File/Directory Lock + +```bash +# Check a single file +ziro who C:\path\file.txt + +# Check multiple paths +ziro who .\logs .\data\app.db +``` + +## Command Reference + +``` +Ziro - Cross-platform port management tool + +Usage: + ziro + +Commands: + find Find process occupying specified port + kill ... Kill processes occupying specified ports (multiple allowed) + list List all port occupancy + who ... Check processes occupying a file or directory + help Show help information + +Options: + -h, --help Show help information + -V, --version Show version information +``` diff --git a/docs/en/03-development.md b/docs/en/03-development.md new file mode 100644 index 0000000..ac58a1d --- /dev/null +++ b/docs/en/03-development.md @@ -0,0 +1,23 @@ +# Development Guide + +## Tech Stack + +- **Core Language**: Rust +- **CLI Parsing**: clap +- **System Info**: sysinfo +- **Interactive UI**: inquire +- **Colored Output**: colored + +## Project Structure +- Rust Core: Entry is `src/bin/ziro.rs`; `src/cli/` (args definition, handlers); `src/core/` (port scanning, process killing, fs_ops, top); `src/platform/` (term, encoding); `src/ui/` (render, theme, icons). +- Node Distribution: `bin/ziro.js` acts as npm startup proxy, `scripts/install.js` downloads platform binaries. + +## Build and Test +- `cargo build --release`: Build optimized binary to `target/release/ziro`. +- `cargo run -- `: Local debugging. +- `cargo test`: Run all unit/integration tests. +- `cargo fmt` & `cargo clippy -- -D warnings`: Formatting and static checking. + +## Coding Style +- Rust 2024 Edition. +- Error handling primarily uses `anyhow::Result`. UI logic is centralized in `src/ui/render.rs`. diff --git a/docs/en/04-contributing.md b/docs/en/04-contributing.md new file mode 100644 index 0000000..068a22f --- /dev/null +++ b/docs/en/04-contributing.md @@ -0,0 +1,18 @@ +# Contributing Guide + +Contributions are welcome! Feel free to submit Issues or Pull Requests. + +### Commit and PR Guidelines +- Git history uses Conventional Commits (`feat(core): ...`, `refactor(term): ...`). +- PR should contain: Change summary, test commands & results, affected command examples, UI screenshots if applicable, and linked issues. + +### Contribution Guidelines +1. Fork this project +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'feat: add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Create a Pull Request + +## Related Projects +- [fkill](https://github.com/sindresorhus/fkill) - Node.js version of process termination tool +- [lsof](https://github.com/lsof-org/lsof) - Unix system file and network connection viewing tool diff --git a/docs/superpowers/plans/2026-04-18-release-automation.md b/docs/superpowers/plans/2026-04-18-release-automation.md deleted file mode 100644 index 71ecb55..0000000 --- a/docs/superpowers/plans/2026-04-18-release-automation.md +++ /dev/null @@ -1,474 +0,0 @@ -# Release Automation Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Automate the release process via a single GitHub Actions `workflow_dispatch` trigger that handles version bump, CHANGELOG, build, checksums, and publish. - -**Architecture:** Replace the current tag-triggered release workflow with a `workflow_dispatch`-driven pipeline. A new `prepare` job validates input, syncs versions, generates CHANGELOG, commits, and creates the tag. Existing build/publish jobs remain with reliability fixes. - -**Tech Stack:** GitHub Actions, bash, npm, cargo - ---- - -### Task 1: Add release profile to Cargo.toml - -**Files:** -- Modify: `Cargo.toml` (append section at end) - -- [ ] **Step 1: Add `[profile.release]` section** - -Append to `Cargo.toml` after the `[lints.clippy]` section: - -```toml -[profile.release] -opt-level = "z" -lto = true -strip = true -panic = "abort" -codegen-units = 1 -``` - -- [ ] **Step 2: Verify build succeeds** - -Run: `cargo build --release` -Expected: Compiles without errors - -- [ ] **Step 3: Commit** - -```bash -git add Cargo.toml -git commit -m "chore(release): add optimized release profile" -``` - ---- - -### Task 2: Create rust-toolchain.toml - -**Files:** -- Create: `rust-toolchain.toml` - -- [ ] **Step 1: Create file** - -```toml -[toolchain] -channel = "1.88.0" -``` - -- [ ] **Step 2: Verify local toolchain matches** - -Run: `rustc --version` -Expected: `rustc 1.88.0 ...` - -- [ ] **Step 3: Commit** - -```bash -git add rust-toolchain.toml -git commit -m "chore: pin Rust toolchain to 1.88.0" -``` - ---- - -### Task 3: Rewrite release.yml — prepare job - -**Files:** -- Modify: `.github/workflows/release.yml` (full rewrite) - -This task replaces the entire `release.yml` with a new workflow. Write the complete file. - -- [ ] **Step 1: Write the new workflow file** - -Replace the entire content of `.github/workflows/release.yml` with: - -```yaml -name: Release - -on: - push: - tags: - - 'v*' - workflow_dispatch: - inputs: - version: - description: 'Version to release (e.g. 0.0.22)' - required: true - type: string - -env: - CARGO_TERM_COLOR: always - -permissions: - contents: write - -jobs: - prepare: - name: Prepare Release - if: github.event_name == 'workflow_dispatch' - runs-on: ubuntu-latest - outputs: - version: ${{ steps.version.outputs.version }} - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 - token: ${{ secrets.GITHUB_TOKEN }} - - - name: Validate version format - run: | - VERSION="${{ github.event.inputs.version }}" - if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then - echo "Error: Invalid version format '$VERSION'. Expected semver (e.g. 0.0.22)" - exit 1 - fi - - - name: Check version not already tagged - run: | - VERSION="${{ github.event.inputs.version }}" - if git tag -l "v$VERSION" | grep -q .; then - echo "Error: Tag v$VERSION already exists" - exit 1 - fi - - - name: Update Cargo.toml version - run: | - VERSION="${{ github.event.inputs.version }}" - sed -i "s/^version = \".*\"/version = \"$VERSION\"/" Cargo.toml - echo "Updated Cargo.toml to $VERSION" - - - name: Update package.json version - run: | - VERSION="${{ github.event.inputs.version }}" - npm version "$VERSION" --no-git-tag-version - echo "Updated package.json to $VERSION" - - - name: Verify versions match - run: | - CARGO_VERSION=$(grep '^version' Cargo.toml | head -1 | sed 's/version = "\(.*\)"/\1/') - NPM_VERSION=$(grep '"version"' package.json | head -1 | sed 's/.*"version": "\(.*\)".*/\1/') - if [ "$CARGO_VERSION" != "$NPM_VERSION" ]; then - echo "Error: Version mismatch after update! Cargo: $CARGO_VERSION, npm: $NPM_VERSION" - exit 1 - fi - echo "Versions synchronized: $CARGO_VERSION" - - - name: Generate CHANGELOG - run: | - VERSION="${{ github.event.inputs.version }}" - LAST_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "") - - echo "## v$VERSION ($(date +%Y-%m-%d))" > /tmp/changelog_entry.md - echo "" >> /tmp/changelog_entry.md - - if [ -n "$LAST_TAG" ]; then - echo "Changes since $LAST_TAG:" >> /tmp/changelog_entry.md - echo "" >> /tmp/changelog_entry.md - git log "$LAST_TAG"..HEAD --pretty=format:"- %s (%h)" >> /tmp/changelog_entry.md - else - echo "Initial release" >> /tmp/changelog_entry.md - fi - echo "" >> /tmp/changelog_entry.md - echo "" >> /tmp/changelog_entry.md - - # Prepend to existing CHANGELOG.md - if [ -f CHANGELOG.md ]; then - cat /tmp/changelog_entry.md CHANGELOG.md > /tmp/changelog_new.md - mv /tmp/changelog_new.md CHANGELOG.md - else - cat /tmp/changelog_entry.md > CHANGELOG.md - fi - - - name: Commit and tag - run: | - VERSION="${{ github.event.inputs.version }}" - git config user.name "github-actions[bot]" - git config user.email "github-actions[bot]@users.noreply.github.com" - git add Cargo.toml package.json CHANGELOG.md - git commit -m "chore(release): v$VERSION" - git tag "v$VERSION" - git push origin HEAD:${{ github.ref_name }} --tags - - - name: Output version - id: version - run: echo "version=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT - - create-release: - name: Create Release - needs: [prepare] - if: always() && (needs.prepare.result == 'success' || github.event_name == 'push') - runs-on: ubuntu-latest - outputs: - version: ${{ steps.get_version.outputs.version }} - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Get version - id: get_version - run: | - if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then - echo "version=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT - echo "tag=v${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT - else - echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT - echo "tag=${GITHUB_REF}" >> $GITHUB_OUTPUT - fi - - - name: Create Release - id: create_release - uses: softprops/action-gh-release@v2 - with: - tag_name: ${{ steps.get_version.outputs.tag }} - name: Release v${{ steps.get_version.outputs.version }} - draft: false - prerelease: false - generate_release_notes: true - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - build: - name: Build - ${{ matrix.platform.name }} - needs: create-release - runs-on: ${{ matrix.platform.runner }} - strategy: - fail-fast: false - matrix: - platform: - - name: Windows x64 - os: windows - arch: x86_64 - runner: windows-latest - target: x86_64-pc-windows-msvc - binary_name: ziro.exe - asset_name: ziro-windows-x86_64.zip - - - name: Linux x64 - os: linux - arch: x86_64 - runner: ubuntu-latest - target: x86_64-unknown-linux-gnu - binary_name: ziro - asset_name: ziro-linux-x86_64.zip - - - name: Linux ARM64 - os: linux - arch: aarch64 - runner: ubuntu-latest - target: aarch64-unknown-linux-gnu - binary_name: ziro - asset_name: ziro-linux-aarch64.zip - - - name: macOS x64 - os: macos - arch: x86_64 - runner: macos-latest - target: x86_64-apple-darwin - binary_name: ziro - asset_name: ziro-macos-x86_64.zip - - - name: macOS ARM64 - os: macos - arch: aarch64 - runner: macos-latest - target: aarch64-apple-darwin - binary_name: ziro - asset_name: ziro-macos-aarch64.zip - - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Setup Rust - uses: dtolnay/rust-toolchain@stable - with: - targets: ${{ matrix.platform.target }} - - - name: Install cross-compilation tools (Linux ARM64) - if: matrix.platform.target == 'aarch64-unknown-linux-gnu' - run: | - sudo apt-get update - sudo apt-get install -y gcc-aarch64-linux-gnu - - - name: Build (Linux ARM64) - if: matrix.platform.target == 'aarch64-unknown-linux-gnu' - shell: bash - run: | - export CC=aarch64-linux-gnu-gcc - export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc - cargo build --release --target ${{ matrix.platform.target }} - - - name: Build (Other platforms) - if: matrix.platform.target != 'aarch64-unknown-linux-gnu' - run: cargo build --release --target ${{ matrix.platform.target }} - - - name: Package binary - id: package - shell: bash - run: | - mkdir -p release-package - cp target/${{ matrix.platform.target }}/release/${{ matrix.platform.binary_name }} release-package/ziro${{ matrix.platform.os == 'windows' && '.exe' || '' }} - - if [ "${{ matrix.platform.os }}" != "windows" ]; then - chmod +x release-package/ziro - fi - - cd release-package - if [ "${{ matrix.platform.os }}" = "windows" ]; then - 7z a ../${{ matrix.platform.asset_name }} ziro.exe - else - zip ../${{ matrix.platform.asset_name }} ziro - fi - - - name: Generate SHA256 checksum - shell: bash - run: | - if [ "${{ matrix.platform.os }}" = "windows" ]; then - certutil -hashfile ${{ matrix.platform.asset_name }} SHA256 > ${{ matrix.platform.asset_name }}.sha256 - # Clean up certutil output to just the hash - sed -n '2p' ${{ matrix.platform.asset_name }}.sha256 | tr -d ' \r\n' > ${{ matrix.platform.asset_name }}.sha256.tmp - echo " ${{ matrix.platform.asset_name }}" >> ${{ matrix.platform.asset_name }}.sha256.tmp - mv ${{ matrix.platform.asset_name }}.sha256.tmp ${{ matrix.platform.asset_name }}.sha256 - else - shasum -a 256 ${{ matrix.platform.asset_name }} > ${{ matrix.platform.asset_name }}.sha256 - fi - - - name: Upload Release Assets - uses: softprops/action-gh-release@v2 - with: - tag_name: ${{ needs.create-release.outputs.version }} - files: | - ${{ matrix.platform.asset_name }} - ${{ matrix.platform.asset_name }}.sha256 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - publish-crates: - name: Publish to crates.io - needs: [create-release, build] - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Setup Rust - uses: dtolnay/rust-toolchain@stable - - - name: Publish to crates.io - run: cargo publish --token ${{ secrets.CARGO_TOKEN }} - - publish-npm: - name: Publish to npm - needs: [create-release, build] - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: '20' - registry-url: 'https://registry.npmjs.org' - - - name: Publish to npm - run: npm publish - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} -``` - -- [ ] **Step 2: Validate YAML syntax** - -Run: `python -c "import yaml; yaml.safe_load(open('.github/workflows/release.yml'))"` -Expected: No output (valid YAML) - -- [ ] **Step 3: Commit** - -```bash -git add .github/workflows/release.yml -git commit -m "feat(ci): rewrite release workflow with workflow_dispatch and checksums" -``` - ---- - -### Task 4: Update ci.yml to use rust-toolchain.toml - -**Files:** -- Modify: `.github/workflows/ci.yml` - -- [ ] **Step 1: Remove pinned version from ci.yml, rely on rust-toolchain.toml** - -Replace all occurrences of `dtolnay/rust-toolchain@1.88.0` with `dtolnay/rust-toolchain@stable` — the `rust-toolchain.toml` file will pin the actual version. This is already the case for the release workflow. The CI should also be consistent. - -Actually, looking at it again: CI pins `1.88.0` via the action. With `rust-toolchain.toml` at project root, `dtolnay/rust-toolchain@stable` will read it and install `1.88.0`. So we can simplify. - -Replace in `.github/workflows/ci.yml`: - -```yaml - - name: Setup Rust - uses: dtolnay/rust-toolchain@1.88.0 -``` - -with: - -```yaml - - name: Setup Rust - uses: dtolnay/rust-toolchain@stable -``` - -(appears 3 times in the file) - -- [ ] **Step 2: Commit** - -```bash -git add .github/workflows/ci.yml -git commit -m "chore(ci): use rust-toolchain.toml for version pinning" -``` - ---- - -### Task 5: Update Cargo.toml description to English - -**Files:** -- Modify: `Cargo.toml:7` - -- [ ] **Step 1: Replace Chinese description** - -Change line 7 in `Cargo.toml`: - -``` -description = "跨平台端口管理工具 - 快速查找和终止占用端口的进程" -``` - -to: - -``` -description = "Cross-platform port management tool - quickly find and kill processes occupying ports" -``` - -This is needed because `cargo publish` publishes to crates.io which requires English metadata. - -- [ ] **Step 2: Verify build** - -Run: `cargo build` -Expected: Compiles without errors - -- [ ] **Step 3: Commit** - -```bash -git add Cargo.toml -git commit -m "chore: translate package description to English" -``` - ---- - -## Self-Review Checklist - -- [x] **Spec coverage:** Each section in the design doc maps to a task: - - `workflow_dispatch` trigger → Task 3 - - Version sync (Cargo.toml + package.json) → Task 3 (prepare job) - - CHANGELOG generation → Task 3 (prepare job) - - `continue-on-error` removal → Task 3 (publish jobs) - - SHA256 checksums → Task 3 (build job) - - `rust-toolchain.toml` → Task 2 - - `[profile.release]` → Task 1 -- [x] **Placeholder scan:** No TBD, TODO, or vague steps. All code shown in full. -- [x] **Type consistency:** All YAML references (outputs, env vars) are consistent across jobs. diff --git a/docs/superpowers/specs/2026-04-18-release-automation-design.md b/docs/superpowers/specs/2026-04-18-release-automation-design.md deleted file mode 100644 index 2cfef06..0000000 --- a/docs/superpowers/specs/2026-04-18-release-automation-design.md +++ /dev/null @@ -1,93 +0,0 @@ -# Release Automation Design - -## Context - -Current release process is fully manual: edit version in `Cargo.toml` + `package.json`, commit, create git tag, push tag to trigger CI. This is error-prone (version desync, stale CHANGELOG, silent publish failures). The goal is to automate the entire flow via a single GitHub Actions `workflow_dispatch` trigger. - -## Design - -### Trigger - -Replace the current `v*` tag trigger with `workflow_dispatch` in `release.yml`: - -```yaml -on: - workflow_dispatch: - inputs: - version: - description: 'Version to release (e.g. 0.0.22)' - required: true - type: string -``` - -Also keep `push tags: v*` as a secondary trigger for backwards compatibility. - -### Jobs - -**Job 1: `prepare`** (runs on `ubuntu-latest`) -1. Validate input version format (semver regex) -2. Check the version doesn't already exist as a git tag -3. Update `Cargo.toml` version via `sed` -4. Update `package.json` version via `npm version --no-git-tag-version` -5. Generate CHANGELOG from git log since last tag -6. Commit changes, create tag `v{version}`, push to repo -7. Output the tag for downstream jobs - -**Job 2: `build`** (matrix, same 5 targets as current) -1. Build release binary with optimized `[profile.release]` (see below) -2. Package into zip -3. Generate SHA256 checksum file -4. Upload artifacts - -**Job 3: `release`** (depends on `prepare` + `build`) -1. Download all artifacts -2. Create GitHub Release with auto-generated notes + CHANGELOG content -3. Upload all zip files + checksum files as release assets - -**Job 4: `publish-crates`** (depends on `release`) -1. Run `cargo publish` — **remove `continue-on-error`** -2. Fail the workflow if publish fails - -**Job 5: `publish-npm`** (depends on `release`) -1. Run `npm publish` — **remove `continue-on-error`** -2. Fail the workflow if publish fails - -### Release Profile Optimization - -Add to `Cargo.toml`: - -```toml -[profile.release] -opt-level = "z" # Optimize for size -lto = true # Link-Time Optimization -strip = true # Strip debug symbols -panic = "abort" # Smaller panic handler -codegen-units = 1 # Better optimization at cost of compile time -``` - -### rust-toolchain.toml - -Create `rust-toolchain.toml` at project root to pin Rust version locally (matching CI's `1.88.0`): - -```toml -[toolchain] -channel = "1.88.0" -``` - -### CHANGELOG Generation - -Simple approach: extract commits since last tag using `git log --oneline v0.0.21..HEAD`, group by conventional commit prefix (`feat`, `fix`, `chore`, etc.), and append to `CHANGELOG.md`. - -### Files to Modify - -| File | Change | -|------|--------| -| `.github/workflows/release.yml` | Rewrite: add `workflow_dispatch`, `prepare` job, checksums, remove `continue-on-error` | -| `Cargo.toml` | Add `[profile.release]` section | -| `rust-toolchain.toml` | New file: pin Rust 1.88.0 | - -### Verification - -1. Push to dev branch, verify CI still passes (lint + test + version check) -2. Manually trigger `workflow_dispatch` with a test version -3. Verify: version synced in both files, tag created, Release published with checksums, crates.io/npm publish attempted diff --git a/docs/zh/01-installation.md b/docs/zh/01-installation.md new file mode 100644 index 0000000..a0055d4 --- /dev/null +++ b/docs/zh/01-installation.md @@ -0,0 +1,35 @@ +# 安装指南 + +## 安装 + +### 使用 Cargo（Rust 用户） + +```bash +cargo install ziro +``` + +### 使用 npm（Node.js 用户） + +```bash +npm install -g @ithinku/ziro +``` + +或使用其他包管理器： + +```bash +# 使用 yarn +yarn global add @ithinku/ziro + +# 使用 pnpm +pnpm add -g @ithinku/ziro +``` + +## 平台支持 + +| 操作系统 | 架构 | 支持状态 | +|---------|------|---------| +| Windows | x64 | ✅ 完全支持 | +| Linux | x64 | ✅ 完全支持 | +| Linux | arm64| ✅ 完全支持 | +| macOS | x64 | ✅ 完全支持 | +| macOS | arm64| ✅ 完全支持 | diff --git a/docs/zh/02-usage.md b/docs/zh/02-usage.md new file mode 100644 index 0000000..4b1e325 --- /dev/null +++ b/docs/zh/02-usage.md @@ -0,0 +1,67 @@ +# 使用指南 + +### 查找占用端口的进程 + +```bash +# 查找占用 8080 端口的进程 +ziro find 8080 +``` + +输出示例： +``` +找到占用端口的进程： + 端口: 8080 + PID: 12345 + 名称: node + 命令: node server.js + CPU: 2.3% + 内存: 128 MB +``` + +### 终止占用端口的进程 + +```bash +# 终止占用 8080 端口的进程 +ziro kill 8080 + +# 终止多个端口的进程 +ziro kill 8080 3000 5000 +``` + +程序会显示找到的所有进程，让你交互式地选择要终止的进程，并在终止前进行确认。 + +### 列出所有端口占用情况 + +```bash +ziro list +``` + +### 查看文件/目录占用 + +```bash +# 查看单个文件 +ziro who C:\path\file.txt + +# 查看多个路径 +ziro who .\logs .\data\app.db +``` + +## 命令参考 + +``` +Ziro - 跨平台端口管理工具 + +使用方法: + ziro + +命令: + find 查找占用指定端口的进程 + kill ... 终止占用指定端口的进程（可指定多个） + list 列出所有端口占用情况 + who ... 查找占用指定文件或目录的进程 + help 显示帮助信息 + +选项: + -h, --help 显示帮助信息 + -V, --version 显示版本信息 +``` diff --git a/docs/zh/03-development.md b/docs/zh/03-development.md new file mode 100644 index 0000000..809ca2d --- /dev/null +++ b/docs/zh/03-development.md @@ -0,0 +1,24 @@ +# 开发指南 + +## 技术栈 + +- **核心语言**: Rust +- **命令行解析**: clap +- **系统信息**: sysinfo +- **交互界面**: inquire +- **彩色输出**: colored + +## 项目结构与模块组织 +- Rust 核心：入口在 `src/bin/ziro.rs`；`src/cli/`（`args.rs` 参数定义，`handlers.rs` 命令分发）；`src/core/`（`port/` 端口扫描，`process/` 进程终止，`fs_ops/` 文件删除与安全校验，`top/` 监控）；`src/platform/`（`term.rs` 终端/环境配置，`encoding.rs` Windows UTF-8 初始化）；`src/ui/`（`render.rs` 输出、交互，`theme.rs` 颜色，`icons.rs` 图标）。 +- Node 分发层：`bin/ziro.js` 作为 npm 启动代理，`scripts/install.js`+`detect-platform.js` 下载发布产物，`package.json` 声明元数据。 + +## 构建、测试与开发命令 +- `cargo build --release`：生成优化二进制到 `target/release/ziro`。 +- `cargo run -- <子命令>`：本地调试，例如 `cargo run -- find 8080`。 +- `cargo test`：运行所有单元/集成测试。 +- `cargo fmt` 与 `cargo clippy -- -D warnings`：格式化并做静态检查。 + +## 代码风格与测试指引 +- Rust 2024 Edition，四空格缩进。模块/函数使用 snake_case，类型/枚举用 PascalCase。 +- 错误返回以 `anyhow::Result` 为主；终端输出逻辑集中于 `src/ui/render.rs`。 +- 测试：新增功能需补充 `#[cfg(test)] mod tests`。涉及端口和文件删除的测试请使用临时资源并在 `drop` 后清理。 diff --git a/docs/zh/04-contributing.md b/docs/zh/04-contributing.md new file mode 100644 index 0000000..439c6cf --- /dev/null +++ b/docs/zh/04-contributing.md @@ -0,0 +1,18 @@ +# 贡献指南 + +欢迎贡献！请随意提交 Issue 或 Pull Request。 + +### 提交与 PR 规范 +- Git 历史采用接近 Conventional Commits：`feat(core): ...`、`refactor(term): ...`、`chore(version): ...`。保持相同前缀+作用域+动宾短语。 +- PR 需包含：变更摘要、测试命令与结果、受影响的命令示例或兼容性说明、终端 UI 截图/录屏（如有）、关联 Issue；尽量保持中英文用户提示一致。 + +### 贡献流程 +1. Fork 本项目 +2. 创建特性分支 (`git checkout -b feature/amazing-feature`) +3. 提交更改 (`git commit -m 'feat: add amazing feature'`) +4. 推送到分支 (`git push origin feature/amazing-feature`) +5. 创建 Pull Request + +## 相关项目 +- [fkill](https://github.com/sindresorhus/fkill) - Node.js 版本的进程终止工具 +- [lsof](https://github.com/lsof-org/lsof) - Unix 系统的文件和网络连接查看工具