# cookiecutter-mgf-project

A [Cookiecutter](https://www.cookiecutter.io/) template for new
projects that want `mgf-common`'s standards day-one — typed
exceptions, structured logging, OpenTelemetry tracing, the
four-gate CI bar (ruff + mypy --strict + pytest with
filterwarnings=error + lint-imports), and a `docs/CLAUDE.md`
that auto-loads in Claude Code so the engineering standards
are at hand for every session.

This is the from-scratch alternative to `mgf-common
init-project`. Use whichever fits your workflow:

| Scenario | Tool |
|---|---|
| You already have an empty / partial project directory | `mgf-common init-project --name <slug> --kind <kind>` |
| You want a fully scaffolded project tree (pyproject + src + tests + docs) generated for you in one shot | `cookiecutter gh:magogi-admin/mgf_common --directory templates/cookiecutter-mgf-project` |

## What it generates

```
my-app/                              <- {{cookiecutter.project_slug}}
├── .claude/
│   └── settings.json                <- safe Claude permission defaults
├── docs/
│   └── CLAUDE.md                    <- auto-loaded by Claude Code
├── src/
│   └── my_app/                      <- {{cookiecutter.package_name}}
│       ├── __init__.py
│       ├── __main__.py              <- bootstrap()-shaped entry point
│       └── py.typed
├── tests/
│   ├── __init__.py
│   ├── conftest.py                  <- bootstrap_for_test fixture
│   └── test_smoke.py
├── .gitignore
├── LICENSE
├── README.md
└── pyproject.toml                   <- four gates pre-configured
```

The generated `pyproject.toml` declares `mgf-common` as a
dependency (pinned via the `mgf_common_pin` cookiecutter
variable, default `>=0.12,<0.13`) and configures all four
gates (ruff / mypy --strict / pytest filterwarnings=error +
coverage / import-linter).

## Usage

```bash
# Install cookiecutter once.
pip install --user cookiecutter

# Generate a project from this template.
cookiecutter \
    gh:magogi-admin/mgf_common \
    --directory templates/cookiecutter-mgf-project

# Or from a local clone.
cookiecutter ./mgf_common/templates/cookiecutter-mgf-project
```

You'll be prompted for:

- `project_name` — human-readable name (e.g. "My Awesome App").
- `project_slug` — defaults to a kebab-case form of the name.
- `package_name` — defaults to a snake_case form of the slug.
- `description` — one-sentence project description.
- `author_name` / `author_email` — for `pyproject.toml`.
- `python_version` — minimum supported (default 3.11).
- `license` — pick from MIT / Apache-2.0 / BSD-3-Clause / Proprietary.
- `mgf_common_pin` — version range (default `>=0.12,<0.13`).

## Post-generation

1. `cd <project_slug>`
2. `git init && git add -A && git commit -m "initial: <project_slug>"`
3. `uv sync` (or `pip install -e ".[dev]"`)
4. Run all four gates:
   ```
   uv run ruff check
   uv run mypy --strict src/
   uv run pytest
   uv run lint-imports
   ```
5. Open in Claude Code — `docs/CLAUDE.md` auto-loads.

## License

The template itself is MIT (matching mgf-common). The license
that lands in the generated project is your choice via the
`license` cookiecutter variable.
