Metadata-Version: 2.4
Name: shipcli
Version: 0.0.1
Summary: Pure Python CLI scaffold and delivery tool.
Author: CaffeineOddity
License-Expression: MIT
Keywords: cli,scaffold,pyinstaller,release,tooling
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0; extra == "build"
Provides-Extra: publish
Requires-Dist: twine>=5.1.0; extra == "publish"
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: pytest>=9.0.0; extra == "dev"
Dynamic: license-file

# shipcli

`shipcli` 是一个纯 Python 的 CLI 脚手架与交付工具，用来初始化、构建、发布、安装和升级命令行项目。

## 特性

- 用 `shipcli init <path>` 快速生成新的 Python CLI 项目
- 用 `shipcli build` / `shipcli build --release` 生成 dev 或 release 版的 wheel/sdist 分发文件
- 用 `shipcli publish` 把 release 版本发布到 GitHub Release 或 PyPI
- `shipcli upgrade` / `uninstall` 只管 shipcli 自身；项目 CLI（如 demo-cli）用其自带命令管理
- 默认以当前目录作为项目目录，也支持 `--project <path>` 跨目录操作
- 初始化后的项目默认包含 `help`、`version`、`upgrade`、`uninstall` 命令示例

## 命令作用范围

| 命令 | 作用对象 |
|------|---------|
| `init` / `build` / `install` / `publish` | 目标项目（当前目录或 `--project`，如 demo-cli） |
| `upgrade` / `uninstall` | shipcli 自身 |

若要升级或卸载某个项目 CLI（如 demo-cli），应先 `install` 安装它，再用其自带命令：`demo-cli upgrade` / `demo-cli uninstall`。

## 安装

### 首次安装（开发）

shipcli 未发布到 PyPI 前，从本地仓库安装：

```bash
git clone <your-repo-url>
cd shipcli
python3 -m pip install -e .   # editable 安装，改代码即生效
```

安装完成后：

```bash
shipcli --help
shipcli --version             # 形如：shipcli 0.0.1 (editable)
```

`--version` / `--help` 会标注当前安装形态：`editable`（editable 安装）、`installed`（pip 正式安装）、`binary`（PyInstaller 二进制）。

### 安装 build 产物

`shipcli build` 产出 wheel/sdist 后，可直接装本地 wheel（模拟用户从 PyPI 安装）：

```bash
shipcli build --release
python3 -m pip install .build/dist/0.0.1/dist/*.whl
```

## 快速开始

```bash
shipcli init demo-cli

cd demo-cli
shipcli build                    # dev 构建，产出 <version>.devN
shipcli build --release          # release 构建，产出发布版 wheel/sdist
shipcli publish --github --pypi  # 发布到 GitHub Release + PyPI
```

也支持不切目录，直接指定目标项目：

```bash
shipcli build --project ./demo-cli
shipcli publish --project ./demo-cli --github --github-repo owner/demo-cli
```

## 构建

`shipcli build` 产出标准的 Python 分发文件（wheel/sdist），不再依赖 PyInstaller：

- **dev 构建**（`shipcli build`）：版本号 `<base>.devN`（如 `0.0.1.dev1`），build 号自动 +1。用于本地验证。
- **release 构建**（`shipcli build --release`）：版本号取配置中的 `version`（如 `0.0.1`）。
- **版本递增**（`--increase <major|minor|patch>`）：构建前把版本号指定位 +1（低位归零）并重置 build，可与 `--release` 同用。

版本号唯一真源是 `build.config.json` 的 `version`；release 构建会自动同步到 `pyproject.toml`，构建时会写入包 `__init__.py` 的 `__version__`。

```bash
shipcli build                              # dev 构建
shipcli build --release                    # release 构建
shipcli build --increase patch             # patch+1 后 dev 构建
shipcli build --increase minor --release   # minor+1 后 release 构建
```

产物目录结构：

```text
.build/dist/<version>/dist/
├── <name>-<version>-py3-none-any.whl
└── <name>-<version>.tar.gz
```

## 升级 shipcli 自身

```bash
shipcli upgrade                       # 从 PyPI 升级到最新发布版
shipcli upgrade --version 0.0.1       # 从 PyPI 升级到指定发布版
shipcli upgrade --local .             # 从本地项目 build 产物升级（取最新版本）
shipcli upgrade --local . --version 0.0.1.dev1   # 指定本地 build 产物版本
shipcli uninstall                     # 卸载 shipcli（pip 卸载 + 清理本地痕迹）
```

dev 版不上 PyPI，仅本地安装/升级：先 `shipcli build` 产出 dev wheel，再用 `shipcli upgrade --local .` 装上。

## 发布

- `shipcli publish` 只做发布，不负责构建
- 发布前先执行 `shipcli build --release`
- 发布到 GitHub Release：上传 wheel/sdist 及各自的 `.sha256` 校验文件
- 发布到 PyPI：上传 wheel/sdist
- GitHub 凭证只从环境变量读取：`SHIPCLI_GITHUB_TOKEN` 或 `GITHUB_TOKEN`
- GitHub 仓库可通过 `--github-repo` 传入，或设置 `SHIPCLI_GITHUB_REPO` / `GITHUB_REPOSITORY`
- PyPI 凭证只从环境变量读取：`SHIPCLI_PYPI_TOKEN`，也兼容现有 `TWINE_PASSWORD`
- `publish` 只支持 release 版本，不接受 dev 版本

```bash
cd demo-cli

# 发布本地已构建的 release 分发文件到 GitHub Release + PyPI
shipcli build --release
SHIPCLI_GITHUB_TOKEN=... SHIPCLI_PYPI_TOKEN=... \
shipcli publish --github --pypi --github-repo owner/demo-cli
```

## 初始化后的目录结构

执行 `shipcli init demo-cli` 后，默认会生成：

```text
demo-cli/
├── build.config.json
├── README.md
├── demo_cli/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py
│   └── commands/
│       ├── __init__.py
│       ├── help.py
│       ├── version.py
│       ├── upgrade.py
│       └── uninstall.py
└── tests/
    └── test_cli.py
```

## 开发验证

```bash
python3 -m pytest
shipcli build --release
```
