Metadata-Version: 2.4
Name: tomskit-cli
Version: 0.3.0
Summary: tomskit CLI: Create projects based on tomskit development framework, focusing on business logic
Author-email: aioai <tomskit@aioai.cc>
Requires-Python: >=3.12
Requires-Dist: argcomplete>=3.0.0
Requires-Dist: jinja2>=3.1.0
Description-Content-Type: text/markdown

# tomskit-cli

**tomskit CLI**：基于 tomskit 开发框架的项目脚手架工具，一键生成项目结构与常用组件，让你专注业务逻辑。

## 功能特性

- **创建新项目**：支持 FastAPI、Celery 或两者兼备的完整项目模板
- **添加模块**：在已有项目中快速生成完整模块（Model + Service + Controller + Schema）
- **添加组件**：按需添加 Celery 任务、FastAPI 扩展、独立 Service
- **数据库迁移**：为项目初始化 Alembic 迁移目录与配置
- **Claude Code 支持**：生成 CLAUDE.md 等 AI 辅助开发配置

## 安装

需要 Python 3.12+，推荐使用 [uv](https://docs.astral.sh/uv/) 或 pip：

```bash
# 使用 uv（推荐）
uv tool install tomskit-cli

# 或使用 pip
pip install tomskit-cli
```

安装后可直接使用 `tomskit` 命令。

## 快速开始

### 创建新项目

```bash
# 创建完整项目（FastAPI + Celery，默认）
tomskit init my-app

# 指定项目描述与类型
tomskit init my-app -d "我的后端服务" -t full

# 仅 FastAPI
tomskit init my-api -t fastapi

# 仅 Celery
tomskit init my-worker -t celery

# 指定输出目录
tomskit init my-app -o /path/to/output
```

**项目类型**（`-t` / `--type`）：

| 类型       | 说明                |
| ---------- | ------------------- |
| `full`     | FastAPI + Celery（默认） |
| `fastapi`  | 仅 FastAPI Web 应用 |
| `celery`   | 仅 Celery 异步任务  |

创建完成后，按终端提示执行：

```bash
cd my-app
uv sync
cp .env.example .env
# 编辑 .env 配置数据库和 Redis
```

### 在已有项目中添加内容

需在项目根目录（含 `main.py` 或 `app/`）下执行：

```bash
# 创建完整模块（Model + Service + Controller + Schema）
tomskit add module user

# 创建 Celery 异步任务
tomskit add task send_email

# 创建 FastAPI 扩展
tomskit add extension cache

# 创建独立 Service
tomskit add service payment
```

### 初始化数据库迁移

```bash
# 在当前目录对应的项目中初始化
tomskit migrations

# 指定项目目录
tomskit migrations -d /path/to/project
```

### 初始化 Claude Code 支持

```bash
tomskit claude init
# 可选：-d /path/to/project
```

会在项目根目录生成 `CLAUDE.md` 等文件，便于 AI 辅助开发。

## 命令一览

| 命令 | 说明 |
|------|------|
| `tomskit init <name>` | 创建新项目 |
| `tomskit add module <name>` | 添加完整模块 |
| `tomskit add task <name>` | 添加 Celery 任务 |
| `tomskit add extension <name>` | 添加 FastAPI 扩展 |
| `tomskit add service <name>` | 添加独立 Service |
| `tomskit migrations` | 初始化数据库迁移 |
| `tomskit claude init` | 初始化 Claude Code 支持 |

**通用选项**：

- `-y` / `--yes`：跳过交互提示，使用默认值
- `-d` / `--dir`：指定项目目录（在 `add`、`migrations`、`claude init` 等子命令中）
- `-o` / `--output`：`init` 时指定目标目录
- `-t` / `--type`：`init` 时指定项目类型（full / fastapi / celery）
- `-d` / `--description`：`init` 时指定项目描述

## Shell 自动补全

安装 [argcomplete](https://github.com/kislyuk/argcomplete) 后，可启用 Tab 补全：

**Bash**（写入 `~/.bashrc`）：

```bash
eval "$(register-python-argcomplete tomskit)"
```

**Zsh**（写入 `~/.zshrc`）：

```zsh
autoload -U bashcompinit
bashcompinit
eval "$(register-python-argcomplete tomskit)"
```

## 开发

```bash
# 克隆仓库后
cd tomskit-cli
uv sync

# 以可编辑方式运行
uv run tomskit --help
```

构建与发布见项目内 `Makefile`（如 `make build`、`make publish`）。

## 许可证与作者

- **作者**：aioai (ai@aioai.cc)
- **版本**：见 [pyproject.toml](pyproject.toml)
