Metadata-Version: 2.5
Name: py_wlcli
Version: 0.8.1
Summary: wl_cli - Python项目
Project-URL: Homepage, https://gitlab.gewinnrobo.com/Humuyuan/wl-cli
Project-URL: Issues, https://gitlab.gewinnrobo.com/Humuyuan/wl-cli/-/issues
Author-email: WL Admin <wl.admin@example.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: pre-commit>=4.5.1
Requires-Dist: toml>=0.10.2
Requires-Dist: tqdm>=4.66.0
Provides-Extra: dev
Requires-Dist: mypy>=1.18.2; extra == 'dev'
Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
Requires-Dist: ruff==0.15.21; extra == 'dev'
Requires-Dist: twine>=6.2.0; extra == 'dev'
Requires-Dist: types-toml>=0.10.8.20240310; extra == 'dev'
Requires-Dist: types-tqdm>=4.67.0.20250809; extra == 'dev'
Provides-Extra: lfs
Requires-Dist: pyyaml>=6.0.0; extra == 'lfs'
Requires-Dist: watchdog>=6.0.0; extra == 'lfs'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'test'
Requires-Dist: pytest-cov>=7.0.0; extra == 'test'
Requires-Dist: pytest>=9.0.3; extra == 'test'
Requires-Dist: pyyaml>=6.0.0; extra == 'test'
Requires-Dist: watchdog>=6.0.0; extra == 'test'
Description-Content-Type: text/markdown

# wl_cli（`wl` CLI）

`wl_cli` 是一个以 Click 构建的命令行工具（入口 `wl`），面向 Python 项目的初始化、构建、
测试、格式化、lint、清理与质量门等日常开发工作流。发行物是纯 Python wheel
（`py3-none-any`），安装与运行都不需要 Rust 工具链；Rust 扩展是可选的诊断件，
缺失时自动回落纯 Python 实现。

## 功能概览

| 命令 | 用途 |
|------|------|
| `wl init` | 初始化项目环境（Git、虚拟环境、i18n、Rust 子模块等） |
| `wl build` | 执行构建任务，支持 Python 包构建与分发 |
| `wl test` | 运行测试（支持缓存、覆盖率、逐步模式） |
| `wl format` | 格式化 Python 与 Rust 代码 |
| `wl lint` | 代码质量检查（ruff/mypy 等） |
| `wl clean` | 清理构建产物与临时文件 |
| `wl debug` | （已弃用）质量门 — 改用 `wl test -s` 与 `wl format -s` |
| `wl self` | 自管理命令 |

命令行别名：`b`→build、`c`→clean、`f`→format、`i`→init。
完整命令参考见 [CLI_COMMANDS.md](https://github.com/CharlieZi/wl-cli/blob/main/CLI_COMMANDS.md)。

## 环境要求

- Python >= 3.11（纯 Python 路径，安装与运行都不需要 Rust/cargo）
- 包管理器推荐 [uv](https://docs.astral.sh/uv/)

### 平台支持矩阵

| 平台 | 架构 | 支持 |
|------|------|------|
| macOS | x86_64 / arm64 | ✅ |
| Linux（glibc） | x86_64 / aarch64 | ✅ |
| Linux（musl） | x86_64 / aarch64 | ✅ |
| Windows | x64 / arm64 | ✅ |

同一个 `py3-none-any` wheel 覆盖以上全部平台。平台报告由
`wl_cli.platform.platform_payload()` 统一产出
（`platform` / `python` / `native_extension` / `supported` / `reason`），
其中 `native_extension` 只作诊断——Rust 扩展可选，缺失不影响 `supported`。

## 安装

### 稳定版（PyPI）

```bash
pip install py-wlcli
```

按需安装可选 extra：`pip install "py-wlcli[lfs]"`（LFS watch）、
`pip install "py-wlcli[test]"`（测试套件）、`pip install "py-wlcli[dev]"`（开发工具）。
详见[安装文档](https://github.com/CharlieZi/wl-cli/blob/main/docs/user/installation.md)。

### 开发版（从源码）

```bash
# 以 GitLab 为主仓（origin），GitHub 为镜像
git clone https://gitlab.gewinnrobo.com/Humuyuan/wl-cli.git
cd wl_cli
uv pip install -e ".[dev,test]"
```

GitHub 镜像：<https://github.com/CharlieZi/wl-cli.git>

## 快速开始

```bash
wl --help       # 查看帮助
wl init         # 初始化项目
wl build        # 构建
wl test         # 运行测试
wl format       # 格式化代码
wl lint         # 代码质量检查
```

## 测试与质量门

```bash
wl test              # 运行全部测试
wl test --cover      # 覆盖率（阈值 70%）
wl test -s           # 逐个测试文件运行，首个失败即停
pytest tests/ -v     # 指定文件（pytest 直跑）
```

提交前请确保 pre-commit 通过（ruff、codespell、lockfile 一致性等）。
开发约束详见 [CLAUDE.md](https://github.com/CharlieZi/wl-cli/blob/main/CLAUDE.md)，
贡献流程见 [CONTRIBUTING.md](https://github.com/CharlieZi/wl-cli/blob/main/CONTRIBUTING.md)。

## 文档

- [CLI_COMMANDS.md](https://github.com/CharlieZi/wl-cli/blob/main/CLI_COMMANDS.md) — 命令参考
- [CONTEXT.md](https://github.com/CharlieZi/wl-cli/blob/main/CONTEXT.md) — 架构术语（Click 迁移语境）
- [docs/](https://github.com/CharlieZi/wl-cli/tree/main/docs) — 设计、ADR、章节与 CICD/发布文档
- [安装文档](https://github.com/CharlieZi/wl-cli/blob/main/docs/user/installation.md) — 安装细节与 shell 补全

## 架构速览

Click CLI（[src/wl_cli/cli_click.py](https://github.com/CharlieZi/wl-cli/blob/main/src/wl_cli/cli_click.py)
经 `setup_commands()` 直接注册）→ 各命令实现（`commands/<group>/`）→ 业务逻辑。
Rust 扩展是可选的诊断件：`src/wl_cli/lib/rust_utils.py` 在 `wl_cli_native`
不可用时回落纯 Python；发行 wheel 不包含任何原生二进制。
架构演进背景见 [Click 迁移设计](https://github.com/CharlieZi/wl-cli/blob/main/docs/superpowers/specs/2026-06-02-full-click-migration-design.md)。

## 许可证

MIT，见 [LICENSE](https://github.com/CharlieZi/wl-cli/blob/main/LICENSE)。
