Metadata-Version: 2.5
Name: forge-template
Version: 0.3.2
Summary: Copier template that scaffolds modern Python projects.
Project-URL: Homepage, https://github.com/Sandsy09/forge-template
Project-URL: Repository, https://github.com/Sandsy09/forge-template
Project-URL: Issues, https://github.com/Sandsy09/forge-template/issues
Author: Alex
License-Expression: MIT
License-File: LICENSE
Keywords: copier,engine,project,scaffold,template
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: packaging<27,>=26.3
Requires-Dist: pydantic<3,>=2.10
Description-Content-Type: text/markdown

# forge-template

A [Copier](https://copier.readthedocs.io/) template and public composition
engine for modern Python projects. The engine catalogue offers independent
**library** and **CLI Application** archetypes; the compatibility-preserving
direct-Copier path remains Library-only and supports `copier update` through
three-way merges.

## Quick start

The easiest way to use this template is via its companion CLI,
[`create-forge`](https://github.com/Sandsy09/create-forge):

```bash
uvx create-forge
```

You can also scaffold directly with Copier, without the CLI:

```bash
uvx copier copy gh:Sandsy09/forge-template your-project --trust
```

`--trust` is required — the scaffold runs a `_tasks` step (git init, first
commit) after copying files.

The public engine used by `create-forge --engine-preview` is also installable
directly — `pip install forge-template` or `uv add forge-template` — for clients that
consume [`docs/template-engine-api.md`](docs/template-engine-api.md)'s typed
discovery/validation/rendering API without going through Copier or
`create-forge` at all. The published wheel ships the engine facade and its
Foundation/component content only; this repository's own tooling
(`docs/adr/` checks, `copier.yml`/`template/` inspection) is not part of the
installable package — see
[ADR 0036](docs/adr/0036-publish-the-engine-to-pypi.md).

## Two repos

| Repo | Role |
| --- | --- |
| [`forge-template`](https://github.com/Sandsy09/forge-template) | This repo. The templates and side-effect-free composition engine. |
| [`create-forge`](https://github.com/Sandsy09/create-forge) | The CLI that scaffolds from it. |

They're kept separate because Copier resolves template versions from PEP 440
git tags on this repo — merging the two would tangle the CLI's own releases
with the template's.

## What you get

Answer a handful of questions (project name, build backend, license, Python
versions to support, ...) and the scaffold gives you a `src/`-layout package
with `pyproject.toml` (uv or Hatchling), ruff, mypy and/or pyright, pytest
with coverage, a `poe`-driven task runner, pre-commit hooks, GitHub Actions
CI, and optional docs (MkDocs) and changelog generation (git-cliff). The
question schema in [copier.yml](copier.yml) is the source of truth for
exactly what's asked and what each answer controls.

## Layout

```
forge-template/
├── copier.yml               Question schema for the scaffold
├── pyproject.toml           This repo's OWN tooling (not part of the scaffold)
├── src/, tests/              ^ same
├── docs/adr/                 Why this repo is shaped the way it is
├── scripts/                 verify-ci.sh: push scaffolded combos, watch CI
├── .github/workflows/       This repo's own CI + release automation
└── template/                Everything here becomes the generated project
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for the human workflow and
[CLAUDE.md](CLAUDE.md) for the invariants that keep `copier update` working
across projects generated at different points in this template's history; read
the latter before changing anything under `template/`. The
[canonical Forge vocabulary](docs/terminology.md) defines architectural terms,
the [Foundation guarantees](docs/foundation-guarantees.md) define the mandatory
outcomes every generated project receives, the
[Foundation scope](docs/foundation-scope.md) defines which concerns belong in
that baseline, the [Library archetype contract](docs/library-archetype.md)
defines the distributable-package additions composed over it, and the
[CLI Application archetype contract](docs/cli-application-archetype.md)
defines the implemented executable reference shape. The
[composition architecture review](docs/composition-architecture-review.md)
records the Stage 08 boundary corrections proven by both archetypes, and
the [Python support policy](docs/python-support.md) defines the
supported CPython window and lifecycle, the
[editor integration strategy](docs/editor-integration.md) keeps the baseline
and default profile editor-neutral, the
[configuration ownership conventions](docs/configuration-ownership.md) keep
runtime settings owner-local and explicitly injected, the
[environment-variable conventions](docs/environment-variables.md) define
owner-prefixed runtime inputs and explicit local dotenv behaviour, the
[structured logging capability](docs/structured-logging.md) defines
owner-local events and one entrypoint-owned logging configuration, the
[path and resource ownership conventions](docs/paths-and-resources.md) keep
runtime path and resource access owner-local and free of implicit process
context, the
[exception ownership conventions](docs/exception-ownership.md) keep
exceptions owner-local and require failures to be handled once rather than
silently dropped or logged repeatedly, the
[secret-handling safeguards](docs/secret-handling.md) keep secret-bearing
files out of version control without generating a mandatory scanner, the
[supply-chain provenance contract](docs/supply-chain-provenance.md) defines
desired SBOM and release-provenance behaviour without generating either yet,
the [GitHub Action pinning policy](docs/github-action-pinning.md) keeps remote
workflow dependencies immutable and maintainable, the
[ProjectSpec protocol](docs/project-spec.md) defines the strict, serialisable
generation request for the composition engine, the
[component manifest protocol](docs/component-manifests.md) defines strict
bundled metadata and compatibility for its component catalogue, the
[composition order contract](docs/composition-order.md) defines the
deterministic order that catalogue applies in, the
[file conflict and override rules](docs/file-conflicts.md) define its output
target, disposition, and collision-safety rules, the
[template variable contract](docs/template-variables.md) defines the rendered
variable namespace and component option vocabulary, the
[stable template-engine API](docs/template-engine-api.md) exposes typed,
side-effect-free discovery, validation, planning, and in-memory rendering, the
[generated-project validation contract](docs/generated-project-validation.md)
checks every rendered result before a client receives it, and
[docs/adr/](docs/adr/) records why significant decisions were made.

## License

MIT — see [LICENSE](LICENSE).
