Metadata-Version: 2.4
Name: sprout-files
Version: 0.2.1
Summary: Template-driven file and directory generator for project workflows
Author-email: frostime <frostime@foxmail.com>
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0.3
Description-Content-Type: text/markdown

# sprout CLI (v0.1)

`sprout` 是一个项目内模板驱动的文件/目录生成 CLI，面向 Agent 协同开发场景。

## 核心特性

- 发现规则：从当前目录向上查找首个 `.sprout/`（类似 `.git`）
- 命令包目录：`.sprout/commands/<command>/`
- 默认 authoring 格式：YAML（便于注释、示例和值说明）
- 输入模式：默认参数输入；`-i/--interactive` 才进入交互
- 基础类型：`string` / `number` / `enum`（`number` 支持可选 `min/max`）
- 插值语法：`{{name}}`（仅纯文本替换，不支持逻辑流）
- 冲突策略：`fail` / `overwrite` / `skip` / `rename`
- `init` 支持自定义骨架、可选示例命令包，并生成项目内 `sprout-authoring` Skill 文档
- 运行时兼容 `yaml` / `yml` / `toml` / `json` 配置与 manifest

## 快速开始

```bash
# 0) 可选：安装 YAML 支持（推荐）
uv add --optional yaml
# 或使用 pip: pip install pyyaml

# 1) 初始化
sprout init --with-examples

# 2) 查看命令
sprout list --all

# 3) 执行命令（默认参数模式，使用 = 连接键值）
sprout new issue name=my-task type=bug

# 4) 交互模式（程序会提示输入缺失的参数）
sprout new issue -i
# 程序提示: name: 
# 你输入: my-task
# 程序提示: type choices=['bug', 'feat', 'refactor'] [default=bug]:
# 你输入: bug (或直接回车使用默认值)

# 5) 预览模式（不实际创建文件）
sprout new issue name=test type=feat --dry-run
```

## 命令

```bash
sprout init [--profile minimal|docs] [--profile-file ./profile.json] [--with-examples]
sprout list [--all]
sprout doctor
sprout new <command> [key=value ...] [--set key=value] [-i|--interactive] [--conflict fail|overwrite|skip|rename]
```

## `.sprout/` 结构

```text
.sprout/
  config.yaml
  commands/
    issue/
      manifest.yaml
      issue.md
  skills/
    sprout-authoring/
      SKILL.md
```

## 如何填写 `.sprout/config.yaml`

```yaml
# sprout project defaults
version: 1

# Default conflict policy for generated assets.
# Allowed: fail | overwrite | skip | rename
conflict: fail
```

字段说明：
- `version`：整数，当前固定为 `1`
- `conflict`：项目级默认冲突策略；可选 `fail` / `overwrite` / `skip` / `rename`

## 如何填写 `manifest.yaml`

```yaml
name: issue
description: Create issue

# Optional per-command conflict override.
# If omitted, sprout uses `.sprout/config.yaml`.
conflict: fail

inputs:
  - name: name
    type: string
    required: true
    description: Issue slug

  - name: type
    type: enum
    enum:
      - bug
      - feat
      - refactor
    default: bug
    description: Issue category

  - name: priority
    type: number
    required: false
    min: 1
    max: 5
    default: 3
    description: Optional priority

assets:
  - type: dir
    path: issues

  - type: file
    path: issues/{{YY}}-{{MM}}-{{DD}}_{{name}}.md
    template: issue.md
```

### 字段说明

#### `inputs[*]`
- `name`：必填，且在同一命令内唯一
- `type`：`string` / `number` / `enum`
- `required`：可选，默认 `true`
- `description`：可选，但建议填写，方便 Agent 理解用途
- `default`：可选默认值
- `enum`：当 `type: enum` 时必填
- `min` / `max`：仅 `number` 类型可用

#### `assets[*]`
- `type`：`dir` 或 `file`
- `path`：项目内相对路径
- `template`：文件资产引用的模板文件，路径相对当前命令目录
- `content`：简单文件可直接内联内容；与 `template` 二选一即可

## 变量上下文

除了输入变量，内置时间变量：

- `YYYY`, `YY`, `MM`, `DD`
- `hh`, `mm`, `ss`
- `date`, `time`, `datetime`, `timestamp`

## 冲突策略说明

当生成的文件或目录已存在时，sprout 会根据冲突策略处理：

- `fail`（默认）：报错并停止
- `skip`：跳过已存在的文件
- `overwrite`：覆盖已存在的文件
- `rename`：重命名新文件（添加 `_02`、`_03` 等后缀）

**目录特殊处理**：目录被视为容器而非内容，已存在的目录会自动复用（REUSE），不受冲突策略影响。只有文件冲突才会应用冲突策略。

示例：
```bash
# 第一次执行
sprout new issue name=test type=bug
# 输出：
#   + CREATE issues
#   + CREATE issues/26-04-11_test.md

# 第二次执行（目录已存在）
sprout new issue name=another type=feat
# 输出：
#   = REUSE issues              # 目录自动复用
#   + CREATE issues/26-04-11_another.md

# 第三次执行（文件冲突）
sprout new issue name=another type=feat
# 输出：
#   Error: Target already exists: issues/26-04-11_another.md
#   Hint: Use --conflict=skip or --conflict=overwrite
```

## Agent authoring 建议

如果让 Agent 帮你写 `.sprout`，先让它读取：

- `.sprout/skills/sprout-authoring/SKILL.md`

然后先对齐：
1. 命令目的
2. 输入字段及类型
3. 输出文件/目录
4. 冲突策略

不要一上来直接让 Agent 写 manifest。

## 常见问题

- **找不到项目模板根**：确认当前目录或父目录存在 `.sprout/`
- **命令不可用**：执行 `sprout doctor` 检查 invalid/conflict 报告
- **YAML 无法读取**：安装 `PyYAML`，或继续使用 TOML / JSON
