create-forge 0.3.0__tar.gz → 0.3.2__tar.gz

{create_forge-0.3.0 → create_forge-0.3.2}/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
 Generated by git-cliff from Conventional Commits.
+## [0.3.2] - 2026-09-08
+
+### Features
+
+- Diagnose the Copier template cache
+## [0.3.1] - 2026-09-08
+
+### Bug Fixes
+
+- Prevent template source credentials from reaching CLI output (#144)
+- Raise the Copier floor past the destination-escape advisories (#146)
+
+### Documentation
+
+- Publish 0.3.0 and close the Data Science roadmap (#130)
+- Add shared Forge user guide and simplify README (#131)
 ## [0.3.0] - 2026-09-05
 
 ### Bug Fixes

create_forge-0.3.2/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.5
+Name: create-forge
+Version: 0.3.2
+Summary: Scaffold modern Python projects from maintained templates.
+Project-URL: Homepage, https://github.com/Sandsy09/create-forge
+Project-URL: Repository, https://github.com/Sandsy09/create-forge
+Project-URL: Issues, https://github.com/Sandsy09/create-forge/issues
+Project-URL: Changelog, https://github.com/Sandsy09/create-forge/blob/main/CHANGELOG.md
+Author: Alex
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cookiecutter,copier,project,scaffold,template
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: copier<10,>=9.16
+Requires-Dist: platformdirs>=4.3.6
+Requires-Dist: pydantic>=2.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13.9
+Requires-Dist: typer>=0.16
+Provides-Extra: engine
+Requires-Dist: forge-template<0.5,>=0.4.1; extra == 'engine'
+Requires-Dist: uv<0.13,>=0.12; extra == 'engine'
+Description-Content-Type: text/markdown
+
+# create-forge
+
+[![CI](https://github.com/Sandsy09/create-forge/actions/workflows/ci.yml/badge.svg)](https://github.com/Sandsy09/create-forge/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/create-forge)](https://pypi.org/project/create-forge/)
+
+Create Python projects with packaging, quality checks, and a useful starting
+structure already in place.
+
+```bash
+uvx create-forge new
+```
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/), Git,
+and Python 3.11+ (uv can install Python for you). Configure your Git author
+name and email before generating a default Library project: generation
+creates local commits.
+
+**[Read the Forge user guide](https://sandsy09.github.io/create-forge/)**
+for walkthroughs, template choices, and troubleshooting.
+
+## How the repositories fit together
+
+| Repository | What it provides |
+| --- | --- |
+| **create-forge** | The CLI: prompts, project creation, updates, and diagnostics. |
+| [forge-template](https://github.com/Sandsy09/forge-template) | The project templates and composition engine used to generate files. |
+
+You normally use the CLI without cloning either repository. Generated
+projects do not depend on either Forge package at runtime.
+
+## Create your first project
+
+```bash
+uvx create-forge new "My Library"
+cd my-library
+uv run poe check
+```
+
+The default workflow creates an installable Library with a `src/` layout,
+uv, Ruff, pytest with coverage, mypy and/or pyright, pre-commit hooks, and
+GitHub Actions CI. Choose your build backend, versioning, license, and
+dependency-update tooling. MkDocs documentation is optional.
+
+The template is rendered by [Copier](https://copier.readthedocs.io/), which
+also supports bringing later template improvements into existing projects.
+
+## Install and manage the tool
+
+Use `uvx` for occasional runs, or install a persistent command:
+
+```bash
+uv tool install create-forge
+create-forge new
+uv tool upgrade create-forge
+```
+
+If the command is not on your PATH, run `uv tool update-shell` and restart
+your terminal.
+
+### Choose a CLI version
+
+```bash
+uvx create-forge@latest new
+uvx create-forge@0.3.0 new
+uv tool install "create-forge==0.3.0"
+```
+
+Plain `uvx create-forge` can reuse a cached or persistently installed
+version; `@latest` explicitly requests the latest release. Tool upgrades
+respect the constraints used at installation, so an exact pin stays pinned.
+To return to the latest release, run `uv tool install create-forge@latest`.
+See [installation and versions](https://sandsy09.github.io/create-forge/installation/).
+
+## Everyday usage
+
+| Command | Purpose |
+| --- | --- |
+| `uvx create-forge new` | Create a project interactively. |
+| `uvx create-forge list` | List the bundled Copier templates. |
+| `uvx create-forge update` | Update a Copier-generated project from its directory. |
+| `uvx create-forge doctor` | Diagnose Python, Git, uv, and package compatibility. |
+| `uvx create-forge config init` | Create an optional configuration file. |
+| `uvx create-forge config show` | Show resolved configuration and its sources. |
+
+For scripts and CI, provide a project name and skip questions with `--yes`:
+
+```bash
+uvx create-forge new "My Library" --yes --data github_org=your-org --data build_backend=hatchling --data versioning=vcs
+```
+
+Use `--path` to choose the destination and repeat `--data key=value` to
+preset answers. Run `uvx create-forge new --help` for the default workflow's
+options. Saved author details, GitHub organisation, and preferred template
+are covered in the [CLI guide](https://sandsy09.github.io/create-forge/cli/).
+
+### Choose a template version or source
+
+```bash
+uvx create-forge new "My Library" --template library --ref v0.4.1
+uvx create-forge new "Custom Project" --template-url https://github.com/you/your-template
+```
+
+`--ref` selects a Git revision in the **template repository**. It does not
+select the CLI version. Without it, Copier uses the latest suitable release
+tag. The bundled registry currently offers Library; upgrade the CLI to
+receive registry changes.
+
+Templates can execute code through generation and update tasks. Use custom
+sources only when you trust their content; `--yes` also skips the custom
+template confirmation.
+
+### Update a generated project
+
+From a clean, committed Copier-generated project:
+
+```bash
+uvx create-forge update --dry-run
+uvx create-forge update
+uv run poe check
+```
+
+Keep `.copier-answers.yml` committed. Review the resulting diff and resolve
+conflicts before committing. A dry run validates the update without applying
+it; it does not produce a file-by-file diff. Use `update --ref v0.4.1` to
+target a particular template version.
+
+## Preview: more project types and capabilities
+
+The `0.3.0` CLI also provides an opt-in engine preview using
+`forge-template>=0.4.1,<0.5`. These options are currently hidden from help.
+
+| Project type | Use it for |
+| --- | --- |
+| Library | A distributable Python package with a choice of packaging modes. |
+| CLI Application | A Typer application with a console command and tests. |
+| Data Science | A Python package with a starter notebook and Jupyter tooling. |
+
+Add **Jupyter** for notebook development or **Scientific Python** for NumPy,
+pandas, Matplotlib, and scikit-learn. Data Science requires Jupyter;
+Scientific Python is optional. These capabilities can also accompany the
+other preview archetypes.
+
+```bash
+uvx --from "create-forge[engine]==0.3.0" create-forge new "My Analysis" --engine-preview --archetype data-science --capability jupyter --yes --data license=mit
+cd my-analysis
+uv run --locked poe check
+uv run poe notebook
+```
+
+For regular preview use, install with `uv tool install "create-forge[engine]"`.
+The [project guide](https://sandsy09.github.io/create-forge/projects/) explains
+each type's output and links to complete recipes.
+
+**Preview projects do not support `create-forge update`.** Their shared
+tooling differs from the default Copier template; the preview does not
+generate its CI workflows or install Git hooks. `--template`,
+`--template-url`, and `--ref` apply only to the Copier workflow.
+
+## What's next
+
+The Foundation and Data Science roadmaps are complete. Making the engine
+the default generation workflow is a planned direction with no scheduled
+release. Follow [open work](https://github.com/Sandsy09/create-forge/issues)
+and [releases](https://github.com/Sandsy09/create-forge/releases) for updates,
+or suggest a project type, capability, or guide you would find useful.
+
+## Feedback and contributing
+
+- [Report a CLI problem or suggest a feature](https://github.com/Sandsy09/create-forge/issues/new/choose).
+- [Request or correct documentation](https://github.com/Sandsy09/create-forge/issues/new?template=documentation.yml).
+- [Report generated-content or capability problems](https://github.com/Sandsy09/forge-template/issues/new/choose).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development and PR checks, and
+the [reference index](https://sandsy09.github.io/create-forge/reference/) for
+engine APIs and architecture documents. Report vulnerabilities through
+[SECURITY.md](SECURITY.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

create_forge-0.3.2/README.md

@@ -0,0 +1,180 @@
+# create-forge
+
+[![CI](https://github.com/Sandsy09/create-forge/actions/workflows/ci.yml/badge.svg)](https://github.com/Sandsy09/create-forge/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/create-forge)](https://pypi.org/project/create-forge/)
+
+Create Python projects with packaging, quality checks, and a useful starting
+structure already in place.
+
+```bash
+uvx create-forge new
+```
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/), Git,
+and Python 3.11+ (uv can install Python for you). Configure your Git author
+name and email before generating a default Library project: generation
+creates local commits.
+
+**[Read the Forge user guide](https://sandsy09.github.io/create-forge/)**
+for walkthroughs, template choices, and troubleshooting.
+
+## How the repositories fit together
+
+| Repository | What it provides |
+| --- | --- |
+| **create-forge** | The CLI: prompts, project creation, updates, and diagnostics. |
+| [forge-template](https://github.com/Sandsy09/forge-template) | The project templates and composition engine used to generate files. |
+
+You normally use the CLI without cloning either repository. Generated
+projects do not depend on either Forge package at runtime.
+
+## Create your first project
+
+```bash
+uvx create-forge new "My Library"
+cd my-library
+uv run poe check
+```
+
+The default workflow creates an installable Library with a `src/` layout,
+uv, Ruff, pytest with coverage, mypy and/or pyright, pre-commit hooks, and
+GitHub Actions CI. Choose your build backend, versioning, license, and
+dependency-update tooling. MkDocs documentation is optional.
+
+The template is rendered by [Copier](https://copier.readthedocs.io/), which
+also supports bringing later template improvements into existing projects.
+
+## Install and manage the tool
+
+Use `uvx` for occasional runs, or install a persistent command:
+
+```bash
+uv tool install create-forge
+create-forge new
+uv tool upgrade create-forge
+```
+
+If the command is not on your PATH, run `uv tool update-shell` and restart
+your terminal.
+
+### Choose a CLI version
+
+```bash
+uvx create-forge@latest new
+uvx create-forge@0.3.0 new
+uv tool install "create-forge==0.3.0"
+```
+
+Plain `uvx create-forge` can reuse a cached or persistently installed
+version; `@latest` explicitly requests the latest release. Tool upgrades
+respect the constraints used at installation, so an exact pin stays pinned.
+To return to the latest release, run `uv tool install create-forge@latest`.
+See [installation and versions](https://sandsy09.github.io/create-forge/installation/).
+
+## Everyday usage
+
+| Command | Purpose |
+| --- | --- |
+| `uvx create-forge new` | Create a project interactively. |
+| `uvx create-forge list` | List the bundled Copier templates. |
+| `uvx create-forge update` | Update a Copier-generated project from its directory. |
+| `uvx create-forge doctor` | Diagnose Python, Git, uv, and package compatibility. |
+| `uvx create-forge config init` | Create an optional configuration file. |
+| `uvx create-forge config show` | Show resolved configuration and its sources. |
+
+For scripts and CI, provide a project name and skip questions with `--yes`:
+
+```bash
+uvx create-forge new "My Library" --yes --data github_org=your-org --data build_backend=hatchling --data versioning=vcs
+```
+
+Use `--path` to choose the destination and repeat `--data key=value` to
+preset answers. Run `uvx create-forge new --help` for the default workflow's
+options. Saved author details, GitHub organisation, and preferred template
+are covered in the [CLI guide](https://sandsy09.github.io/create-forge/cli/).
+
+### Choose a template version or source
+
+```bash
+uvx create-forge new "My Library" --template library --ref v0.4.1
+uvx create-forge new "Custom Project" --template-url https://github.com/you/your-template
+```
+
+`--ref` selects a Git revision in the **template repository**. It does not
+select the CLI version. Without it, Copier uses the latest suitable release
+tag. The bundled registry currently offers Library; upgrade the CLI to
+receive registry changes.
+
+Templates can execute code through generation and update tasks. Use custom
+sources only when you trust their content; `--yes` also skips the custom
+template confirmation.
+
+### Update a generated project
+
+From a clean, committed Copier-generated project:
+
+```bash
+uvx create-forge update --dry-run
+uvx create-forge update
+uv run poe check
+```
+
+Keep `.copier-answers.yml` committed. Review the resulting diff and resolve
+conflicts before committing. A dry run validates the update without applying
+it; it does not produce a file-by-file diff. Use `update --ref v0.4.1` to
+target a particular template version.
+
+## Preview: more project types and capabilities
+
+The `0.3.0` CLI also provides an opt-in engine preview using
+`forge-template>=0.4.1,<0.5`. These options are currently hidden from help.
+
+| Project type | Use it for |
+| --- | --- |
+| Library | A distributable Python package with a choice of packaging modes. |
+| CLI Application | A Typer application with a console command and tests. |
+| Data Science | A Python package with a starter notebook and Jupyter tooling. |
+
+Add **Jupyter** for notebook development or **Scientific Python** for NumPy,
+pandas, Matplotlib, and scikit-learn. Data Science requires Jupyter;
+Scientific Python is optional. These capabilities can also accompany the
+other preview archetypes.
+
+```bash
+uvx --from "create-forge[engine]==0.3.0" create-forge new "My Analysis" --engine-preview --archetype data-science --capability jupyter --yes --data license=mit
+cd my-analysis
+uv run --locked poe check
+uv run poe notebook
+```
+
+For regular preview use, install with `uv tool install "create-forge[engine]"`.
+The [project guide](https://sandsy09.github.io/create-forge/projects/) explains
+each type's output and links to complete recipes.
+
+**Preview projects do not support `create-forge update`.** Their shared
+tooling differs from the default Copier template; the preview does not
+generate its CI workflows or install Git hooks. `--template`,
+`--template-url`, and `--ref` apply only to the Copier workflow.
+
+## What's next
+
+The Foundation and Data Science roadmaps are complete. Making the engine
+the default generation workflow is a planned direction with no scheduled
+release. Follow [open work](https://github.com/Sandsy09/create-forge/issues)
+and [releases](https://github.com/Sandsy09/create-forge/releases) for updates,
+or suggest a project type, capability, or guide you would find useful.
+
+## Feedback and contributing
+
+- [Report a CLI problem or suggest a feature](https://github.com/Sandsy09/create-forge/issues/new/choose).
+- [Request or correct documentation](https://github.com/Sandsy09/create-forge/issues/new?template=documentation.yml).
+- [Report generated-content or capability problems](https://github.com/Sandsy09/forge-template/issues/new/choose).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development and PR checks, and
+the [reference index](https://sandsy09.github.io/create-forge/reference/) for
+engine APIs and architecture documents. Report vulnerabilities through
+[SECURITY.md](SECURITY.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

{create_forge-0.3.0 → create_forge-0.3.2}/docs/adr/README.md

@@ -36,6 +36,12 @@ format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
 - [0031 — Adopt the reviewed forge-template 0.4.1 release](0031-adopt-the-reviewed-forge-template-0-4-1-release.md)
 - [0032 — Validate Data Science through the installed create-forge candidate](0032-validate-installed-data-science-generation.md)
 - [0033 — Complete the rollout regression and failure matrix at the installed boundary](0033-complete-rollout-regression-validation.md)
+- [0034 — Publish create-forge 0.3.0 and close the Data Science roadmap](0034-publish-0-3-0-and-close-roadmap-v2.md)
+- [0035 — Shared Forge user documentation](0035-shared-forge-user-documentation.md)
+- [0036 — Keep credentials out of template sources and CLI diagnostics](0036-template-source-credentials.md)
+- [0037 — Pin external Actions to reviewed commits and scope permissions per job](0037-immutable-workflow-actions.md)
+- [0038 — Raise the Copier floor past the destination-escape advisories and hold uv](0038-dependency-floor-review.md)
+- [0039 — Diagnose the Copier template cache](0039-copier-cache-diagnostics.md)
 
 Add a new record by copying the most recent one and incrementing the number.
 Records are immutable: supersede them rather than editing.

{create_forge-0.3.0 → create_forge-0.3.2}/docs/roadmap-v2/README.md

@@ -31,7 +31,9 @@ Provider Stage 14 is complete and published the reviewed
 `>=0.4.1,<0.5` lower bound and prepares create-forge `0.3.0`; CF-14.02
 (ADR 0032) completes installed-console Data Science validation, and CF-14.03
 (ADR 0033) completes the installed regression and failure matrix. CF-14.04
-publishes the client and closes the Stage 14 milestones.
+(ADR 0034) published create-forge `0.3.0` to PyPI, verified the released pair,
+and closed CF-EPIC-14 and both Stage 13 and Stage 14 milestones. **The Data
+Science roadmap is complete in both repositories.**
 
 ## Repository roles
 

{create_forge-0.3.0 → create_forge-0.3.2}/docs/roadmap-v2/roadmap/14-data-science-validation-and-rollout/README.md

@@ -19,8 +19,11 @@ installed create-forge candidate under
 [ADR 0032](../../../adr/0032-validate-installed-data-science-generation.md).
 CF-14.03 completes the installed regression and failure matrix under
 [ADR 0033](../../../adr/0033-complete-rollout-regression-validation.md).
-CF-14.04 is the only remaining child: it publishes create-forge `0.3.0` and
-closes the Stage 14 milestones.
+CF-14.04 published create-forge `0.3.0` to PyPI and closed CF-EPIC-14 and both
+Stage 13 and Stage 14 milestones under
+[ADR 0034](../../../adr/0034-publish-0-3-0-and-close-roadmap-v2.md). All four
+children are complete; the Data Science roadmap is closed in both
+repositories.
 
 ## Child sequence
 
@@ -60,8 +63,14 @@ create-forge then completes client rollout:
    [rollout regression and failure validation](https://github.com/Sandsy09/create-forge/blob/main/docs/rollout-regression-validation.md)
    record.
 4. [CF-14.04 / create-forge#114](https://github.com/Sandsy09/create-forge/issues/114)
-   publishes create-forge 0.3.0 and completes roadmap v2; it remains blocked
-   only by CF-14.03.
+   publishes create-forge 0.3.0 and completes roadmap v2. **Complete** under
+   [ADR 0034](../../../adr/0034-publish-0-3-0-and-close-roadmap-v2.md):
+   `create-forge` and `create-forge[engine]` `0.3.0` are on PyPI, tag `v0.3.0`
+   is released, the published pair generates and checks every archetype and the
+   engine-less default Copier path, and both Stage 13 and Stage 14 milestones
+   are closed. Canonical
+   [release 0.3.0 validation](https://github.com/Sandsy09/create-forge/blob/main/docs/release-0-3-0-validation.md)
+   record.
 
 ## Entry criteria
 

{create_forge-0.3.0 → create_forge-0.3.2}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "create-forge"
-version = "0.3.0"
+version = "0.3.2"
 description = "Scaffold modern Python projects from maintained templates."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -29,12 +29,27 @@ classifiers = [
 
 dependencies = [
     # Pinned to a major: the Python API is public but evolves faster than the
-    # CLI. runner.py is the only module that touches it.
-    "copier>=9.4,<10",
-    "typer>=0.15",
+    # CLI. runner.py is the only module that touches it. The lower bound was
+    # raised past the destination-escape advisories to 9.15.2 (ADR 0038), then
+    # to 9.16 (ADR 0039): 9.16 is the first release with the git-mirror cache
+    # and COPIER_CACHE_DIR that runner.py models and `doctor` reports -- a
+    # required-behaviour move, not an advisory one. The whole >=9.16 range is
+    # advisory-free. See docs/engine-updates.md.
+    "copier>=9.16,<10",
+    # >=0.16: typer 0.15.0-0.15.3 declare an uncapped click and break against
+    # click >=8.2 (TyperArgument.make_metavar), and 0.15.4 pins click <8.2.
+    # 0.16.0 is the first release that works with current click. The CI
+    # `floor` job (ADR 0038) is what caught the stale >=0.15 bound.
+    "typer>=0.16",
     "questionary>=2.0",
     "pydantic>=2.10",
     "rich>=13.9",
+    "pyyaml>=6.0",
+    # runner.py resolves Copier's cache directory by Copier's own documented
+    # rule (COPIER_CACHE_DIR, else the platformdirs user cache). Pinned to the
+    # bound Copier itself declares so it adds no resolution pressure and the
+    # CI `floor` job sees the version Copier's own floor would (ADR 0039).
+    "platformdirs>=4.3.6",
 ]
 
 [project.optional-dependencies]
@@ -47,7 +62,9 @@ dependencies = [
 # call. src/create_forge/engine.py is the only module that imports it;
 # src/create_forge/compat.py holds the range itself so cli.py's `doctor` can
 # report it without importing the engine. ADR 0021 adds bounded uv to finalise
-# the engine render's dynamic lockfile.
+# the engine render's dynamic lockfile; ADR 0038 reviewed that `uv` floor
+# against the advisory record and held it -- the whole `>=0.12,<0.13` range is
+# already advisory-free.
 engine = ["forge-template>=0.4.1,<0.5", "uv>=0.12,<0.13"]
 
 [project.scripts]
@@ -60,6 +77,7 @@ Issues = "https://github.com/Sandsy09/create-forge/issues"
 Changelog = "https://github.com/Sandsy09/create-forge/blob/main/CHANGELOG.md"
 
 [dependency-groups]
+docs = ["mkdocs>=1.6,<2", "mkdocs-material>=9.5,<10"]
 lint = ["ruff>=0.14", "pre-commit>=4.0"]
 test = [
     "pytest>=8.3",
@@ -71,6 +89,7 @@ test = [
 ]
 typecheck = ["mypy>=1.14", "types-PyYAML>=6.0"]
 dev = [
+    { include-group = "docs" },
     { include-group = "lint" },
     { include-group = "test" },
     { include-group = "typecheck" },
@@ -179,6 +198,8 @@ test = "pytest -m 'not network and not e2e'"
 "test:e2e" = "pytest -m e2e"
 check = ["format:check", "lint", "typecheck", "test"]
 changelog = "git-cliff --output CHANGELOG.md"
+docs = "mkdocs serve"
+"docs:build" = "mkdocs build --strict"
 
 # Verifies templates.toml actually ships in the wheel. This is the failure
 # that passes every local test and breaks on first uvx run. Builds into a
@@ -191,6 +212,12 @@ changelog = "git-cliff --output CHANGELOG.md"
 # via tests/test_adr.py; this is the standalone entry point.
 "check:adr" = "python scripts/adr.py"
 
+# Verifies every workflow pins its external actions to a full commit SHA and
+# keeps write permissions off the workflow level (ADR 0037). Also runs inside
+# the fast test suite via tests/test_workflows.py; this is the standalone
+# entry point -- see scripts/check_workflows.py.
+"check:workflows" = "python scripts/check_workflows.py"
+
 # Reconciles a repo's GitHub labels against .github/labels.toml. Idempotent:
 # `gh label create --force` creates or updates. Pass extra args after `--`,
 # e.g. `uv run poe labels:sync --dry-run` or `--repo OWNER/NAME --prune`