|
1
|
# Claude — Boilerworks CLI |
|
2
|
|
|
3
|
Primary conventions doc: read this file, then the source code. |
|
4
|
|
|
5
|
This repo is the **Boilerworks CLI** — a Python package published to PyPI as `boilerworks`. |
|
6
|
It is NOT a web application. It is a command-line tool built with Click, Questionary, and Rich. |
|
7
|
|
|
8
|
--- |
|
9
|
|
|
10
|
## Stack |
|
11
|
|
|
12
|
- **Language**: Python 3.12+ |
|
13
|
- **CLI framework**: Click 8+ |
|
14
|
- **Interactive prompts**: Questionary 2+ |
|
15
|
- **Output**: Rich 13+ (tables, panels, progress bars) |
|
16
|
- **Manifest validation**: Pydantic v2 |
|
17
|
- **Template rendering**: string replacement (not Jinja2) |
|
18
|
- **Git operations**: subprocess (git CLI) + GitPython |
|
19
|
- **Config**: PyYAML 6+ |
|
20
|
- **Package manager**: uv (not pip) |
|
21
|
- **Lint + format**: Ruff (not flake8/black/isort) |
|
22
|
- **Tests**: pytest with coverage |
|
23
|
|
|
24
|
## Package layout |
|
25
|
|
|
26
|
``` |
|
27
|
boilerworks/ # Python package |
|
28
|
__init__.py # __version__ = "0.1.0" |
|
29
|
cli.py # Click group: setup, init, bootstrap, list |
|
30
|
wizard.py # Questionary prompts → boilerworks.yaml |
|
31
|
generator.py # Clone → render → wire → git init |
|
32
|
bootstrap.py # Terraform stub (v2) |
|
33
|
manifest.py # Pydantic models for boilerworks.yaml |
|
34
|
registry.py # Load + query templates.yaml |
|
35
|
renderer.py # String replacement in cloned files |
|
36
|
console.py # Rich output helpers |
|
37
|
data/ |
|
38
|
templates.yaml # All 26 templates with metadata |
|
39
|
tests/ |
|
40
|
conftest.py |
|
41
|
test_cli.py |
|
42
|
test_manifest.py |
|
43
|
test_registry.py |
|
44
|
test_renderer.py |
|
45
|
test_generator.py |
|
46
|
test_console.py |
|
47
|
test_wizard.py |
|
48
|
``` |
|
49
|
|
|
50
|
## Running locally |
|
51
|
|
|
52
|
```bash |
|
53
|
uv sync # install deps |
|
54
|
uv run boilerworks --help # verify install |
|
55
|
make lint # ruff check + format --check |
|
56
|
make test # pytest with coverage |
|
57
|
make format # ruff fix + format |
|
58
|
``` |
|
59
|
|
|
60
|
## Adding a template |
|
61
|
|
|
62
|
Edit `data/templates.yaml`. Add an entry following the existing schema. |
|
63
|
Run `make test` — `test_registry.py` will catch count mismatches. |
|
64
|
|
|
65
|
## Coding standards |
|
66
|
|
|
67
|
- Fully typed: all function signatures have type hints |
|
68
|
- Line length: 120 (ruff config in pyproject.toml) |
|
69
|
- `ruff check . && ruff format .` after every change |
|
70
|
- pytest coverage ≥ 80% |
|
71
|
- No TODOs, no stubs (bootstrap is intentionally a v2 stub — document it clearly) |
|
72
|
- No co-authorship messages in commits |
|
73
|
|
|
74
|
## Common patterns |
|
75
|
|
|
76
|
**Adding a CLI option**: edit `boilerworks/cli.py`, add `@click.option(...)` decorator |
|
77
|
|
|
78
|
**Adding a manifest field**: edit `boilerworks/manifest.py` (BoilerworksManifest model) |
|
79
|
|
|
80
|
**Adding a renderer rule**: edit `boilerworks/renderer.py` (`build_replacements` or `_SKIP_*`) |
|
81
|
|
|
82
|
**Adding a template to the catalogue**: edit `data/templates.yaml` |
|
83
|
|