create-forge 0.2.0__py3-none-any.whl

create_forge/staging.py

@@ -0,0 +1,180 @@
+"""Filesystem orchestration shared by the Copier and engine generation paths.
+
+Deliberately engine-free: nothing here imports `forge_template`, not even
+under `TYPE_CHECKING`. That keeps this module in the wheel and in the fast
+test suite with no `engine` dependency group installed, and lets it serve
+both `runner.scaffold()` (Copier writes straight to the destination; this
+module only cleans up after a failure) and `pipeline.finalise_generation_request()`
+(the engine path; this module stages and atomically finalises). See
+[ADR 0015](../../docs/adr/0015-staged-filesystem-generation.md) and the
+canonical [filesystem generation contract](../../docs/filesystem-generation.md)
+for why the two paths differ and what each guarantees.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import shutil
+import tempfile
+import warnings
+from pathlib import Path, PurePosixPath
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+_STAGING_PREFIX = ".create-forge-"
+
+
+class StagingError(Exception):
+    """A filesystem operation failed in a way the user can act on."""
+
+
+class DestinationConflictError(StagingError):
+    """The destination already exists and is not empty."""
+
+
+def ensure_available(dst: Path) -> None:
+    """Reject a destination that already exists and has content.
+
+    Cheap and side-effect free -- callers run this before any compatibility
+    check or write, so an obvious conflict is reported before anything else
+    is attempted.
+    """
+    if dst.exists() and any(dst.iterdir()):
+        msg = f"{dst} already exists and is not empty"
+        raise DestinationConflictError(msg)
+
+
+def _safe_relative_path(root: Path, target: str) -> Path:
+    """Resolve one project-relative target under `root`, refusing escapes.
+
+    Targets are engine-owned strings using forward slashes (`RenderedFile`
+    documents them as project-relative). `PurePosixPath` parses them
+    platform-independently before `Path` joins them, so a target containing
+    backslashes is treated as a literal filename component, never as a
+    Windows separator.
+    """
+    posix_target = PurePosixPath(target)
+    if posix_target.is_absolute() or posix_target.drive:
+        msg = f"refusing to write outside the staging directory: {target!r}"
+        raise StagingError(msg)
+    if ".." in posix_target.parts:
+        msg = f"refusing to write outside the staging directory: {target!r}"
+        raise StagingError(msg)
+
+    resolved_root = root.resolve()
+    destination = (root / Path(*posix_target.parts)).resolve()
+    if destination != resolved_root and resolved_root not in destination.parents:
+        msg = f"refusing to write outside the staging directory: {target!r}"
+        raise StagingError(msg)
+    return destination
+
+
+def write_files(root: Path, files: Iterable[tuple[str, bytes]]) -> None:
+    """Write each (target, content) pair under `root`, creating parents.
+
+    Every target is validated before anything is written -- an absolute
+    path, a drive-qualified path, or a `..` segment anywhere in a single
+    target aborts the whole call with nothing written by it.
+    """
+    resolved: list[tuple[Path, bytes]] = [
+        (_safe_relative_path(root, target), content) for target, content in files
+    ]
+    for path, content in resolved:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            path.write_bytes(content)
+        except OSError as exc:
+            msg = f"could not write {path}: {exc}"
+            raise StagingError(msg) from exc
+
+
+def _on_rm_error(func: object, path: str, exc_info: object) -> None:
+    """`shutil.rmtree` error handler: clear read-only and retry once.
+
+    Accepted as both 3.12+'s `onexc` and 3.11's `onerror` -- both call the
+    handler with three positional arguments; the third (`exc_info`) is
+    unused by either signature this implements.
+    """
+    del exc_info
+    target = Path(path)
+    target.chmod(0o700)
+    if callable(func):
+        func(path)
+
+
+def _remove_tree(path: Path) -> None:
+    """Best-effort recursive removal that clears read-only files first.
+
+    Never raises: a failed cleanup must not mask the original error that
+    triggered it, so a residual directory is reported as a warning instead.
+    """
+    if not path.exists():
+        return
+    try:
+        try:
+            # `onexc` only exists from Python 3.12; mypy is pinned to the 3.11
+            # stub (pyproject.toml's python_version), so this call needs an
+            # explicit ignore regardless of the interpreter mypy itself runs
+            # under.
+            shutil.rmtree(path, onexc=_on_rm_error)  # type: ignore[call-arg]
+        except TypeError:
+            shutil.rmtree(path, onerror=_on_rm_error)
+    except OSError as exc:
+        warnings.warn(f"could not remove {path}: {exc}", RuntimeWarning, stacklevel=2)
+
+
+@contextlib.contextmanager
+def staged(dst: Path) -> Iterator[Path]:
+    """Yield a staging directory adjacent to `dst`; finalise by atomic rename.
+
+    The staging directory is created next to `dst` with `tempfile.mkdtemp`,
+    not under the system temp directory -- same-volume placement is what
+    makes the finalising `Path.rename` an atomic directory rename on both
+    NTFS and POSIX rather than a copy. There is deliberately no cross-volume
+    copy fallback: that would silently trade the atomicity guarantee for
+    availability, so a cross-volume destination fails instead.
+
+    On success, an existing *empty* `dst` is removed first -- `os.rename`
+    will not replace a directory on Windows. On any exception, the staging
+    tree is removed and the original error propagates; `dst` is left exactly
+    as it was found.
+    """
+    ensure_available(dst)
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    staging_dir = Path(tempfile.mkdtemp(prefix=_STAGING_PREFIX, dir=dst.parent))
+
+    try:
+        yield staging_dir
+        if dst.exists():
+            dst.rmdir()
+        try:
+            staging_dir.rename(dst)
+        except OSError as exc:
+            msg = f"could not move {staging_dir} into place at {dst}: {exc}"
+            raise StagingError(msg) from exc
+    except BaseException:
+        _remove_tree(staging_dir)
+        raise
+
+
+@contextlib.contextmanager
+def discard_on_failure(dst: Path) -> Iterator[None]:
+    """Remove `dst` on failure, but only if this call is what created it.
+
+    Used around the Copier path, which writes straight to `dst` and cannot
+    safely be staged: templates run `_tasks` (`uv sync`, `pre-commit
+    install`) that bake `dst`'s absolute path into `.venv/pyvenv.cfg`,
+    console-script shims, and `.git/hooks/pre-commit`. Renaming a completed
+    Copier output afterward would silently break all three, so this context
+    manager only ever cleans up a failure at the path Copier already used --
+    it never stages or moves anything.
+    """
+    pre_existing = dst.exists()
+    try:
+        yield
+    except BaseException:
+        if not pre_existing:
+            _remove_tree(dst)
+        raise

create_forge/templates.toml

@@ -0,0 +1,121 @@
+# Bundled template registry.
+#
+# Adding a template here requires a new CLI release. Validated at import time by
+# the Pydantic models in models.py, and in CI by tests/test_registry.py.
+#
+# Every `key` below must match a question in forge-template's copier.yml
+# (invariant 1 in CLAUDE.md — Copier silently drops unknown `data` keys, so a
+# typo here produces a scaffold that looks fine and is subtly wrong). Audited
+# against forge-template@v0.1.1. Questions deliberately left unasked and
+# falling through to their copier.yml default via runner.py's `defaults=True`:
+# package_name, repo_name, repo_url, author_name, author_email,
+# codeowners_team, python_all, python_version, python_min_version,
+# python_matrix, versioning_resolved, initial_version, coverage_fail_under,
+# dependency_updates, changelog_tool. All of them have a default, so this is
+# safe — a test guarding it is tracked as a follow-up issue.
+
+default_template = "library"
+
+[[templates]]
+id = "library"
+name = "Library"
+description = "An installable Python package. src layout, no service scaffolding."
+url = "https://github.com/Sandsy09/forge-template"
+status = "stable"
+
+  # ---- identity -------------------------------------------------------------
+
+  [[templates.prompts]]
+  key = "project_name"
+  kind = "text"
+  message = "Project name"
+  help = "Human readable, e.g. 'Credit Risk Utils'"
+
+  [[templates.prompts]]
+  key = "project_description"
+  kind = "text"
+  message = "Short description"
+
+  [[templates.prompts]]
+  key = "github_org"
+  kind = "text"
+  message = "GitHub organisation"
+  help = "Pre-filled from your forge config if set"
+
+  [[templates.prompts]]
+  key = "license"
+  kind = "select"
+  message = "License"
+
+    [[templates.prompts.choices]]
+    value = "proprietary"
+    label = "Proprietary"
+    hint = "internal use only"
+
+    [[templates.prompts.choices]]
+    value = "mit"
+    label = "MIT"
+
+    [[templates.prompts.choices]]
+    value = "apache-2.0"
+    label = "Apache-2.0"
+
+  # ---- the one question that constrains another -----------------------------
+
+  [[templates.prompts]]
+  key = "build_backend"
+  kind = "select"
+  message = "Build backend"
+
+    [[templates.prompts.choices]]
+    value = "uv_build"
+    label = "uv_build"
+    hint = "simplest; static version only"
+
+    [[templates.prompts.choices]]
+    value = "hatchling"
+    label = "Hatchling"
+    hint = "required for git-tag versioning"
+
+  [[templates.prompts]]
+  key = "versioning"
+  kind = "select"
+  message = "Version source"
+  depends_on = { build_backend = "hatchling" }
+
+    [[templates.prompts.choices]]
+    value = "static"
+    label = "Static in pyproject.toml"
+    hint = "explicit; uv version works"
+
+    [[templates.prompts.choices]]
+    value = "vcs"
+    label = "Git tags (hatch-vcs)"
+    hint = "tag and version cannot disagree"
+
+  # ---- tooling --------------------------------------------------------------
+
+  [[templates.prompts]]
+  key = "type_checking"
+  kind = "select"
+  message = "Type checker"
+
+    [[templates.prompts.choices]]
+    value = "mypy"
+    label = "mypy"
+    hint = "recommended default"
+
+    [[templates.prompts.choices]]
+    value = "pyright"
+    label = "pyright"
+
+    [[templates.prompts.choices]]
+    value = "both"
+    label = "Both"
+    hint = "strictest; two ignore dialects to manage"
+
+  [[templates.prompts]]
+  key = "use_docs"
+  kind = "confirm"
+  message = "Include a MkDocs documentation site?"
+  default = false

create_forge-0.2.0.dist-info/METADATA

@@ -0,0 +1,207 @@
+Metadata-Version: 2.5
+Name: create-forge
+Version: 0.2.0
+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.4
+Requires-Dist: pydantic>=2.10
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13.9
+Requires-Dist: typer>=0.15
+Provides-Extra: engine
+Requires-Dist: forge-template<0.4,>=0.3.1; 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)
+
+Scaffold modern Python projects from maintained templates — and pull template
+improvements back into projects you generated months ago.
+
+```bash
+uvx create-forge new
+```
+
+No install step. Requires [uv](https://docs.astral.sh/uv/) and git.
+
+## Why
+
+Most project generators are fire-and-forget: you scaffold once, and from that
+moment your project drifts away from the template. Six months later the template
+has better lint rules, a security fix in CI, and a newer toolchain — and no path
+to get any of it into projects already in the wild.
+
+create-forge is built on [Copier](https://copier.readthedocs.io/), which does a
+three-way merge between the template version your project was generated from and
+the latest one. Local edits survive; template changes arrive.
+
+```bash
+uvx create-forge update
+```
+
+## What you get
+
+Every generated project ships with:
+
+- **[uv](https://docs.astral.sh/uv/)** for packaging and dependency management
+- **[Ruff](https://docs.astral.sh/ruff/)** for linting and formatting
+- **mypy** or **pyright** (or both) for type checking
+- **pytest** with coverage
+- **pre-commit** hooks, including Conventional Commits enforcement
+- **GitHub Actions** CI, with a test matrix across your supported Python versions
+- **Renovate** or **Dependabot** for dependency updates
+- `README`, `CONTRIBUTING`, `SECURITY`, `CHANGELOG`, issue and PR templates
+- Optionally: a MkDocs documentation site and ADR scaffolding
+
+Choices you make at scaffold time — build backend, versioning strategy, license,
+type checker — are remembered, so updates respect them.
+
+## Usage
+
+```bash
+# Interactive
+uvx create-forge new
+
+# Named up front
+uvx create-forge new "Credit Risk Utils"
+
+# Non-interactive, for scripts and CI
+uvx create-forge new "My Lib" --yes \
+  --data build_backend=hatchling \
+  --data versioning=vcs \
+  --data type_checking=both
+```
+
+| Command | What it does |
+| --- | --- |
+| `new` | Create a project |
+| `list` | Show available templates |
+| `update` | Pull template changes into an existing project |
+| `doctor` | Check your environment can scaffold and update |
+| `config` | Inspect or initialise your saved configuration |
+
+Useful flags on `new`: `--template/-t`, `--path/-p`, `--data/-d`, `--yes/-y`,
+`--ref`, `--dry-run`.
+
+## Configuration
+
+Optional. Saves retyping the same answers:
+
+```toml
+# ~/.config/create-forge/config.toml
+author_name = "Your Name"
+author_email = "you@example.com"
+github_org = "your-org"
+default_template = "library"
+```
+
+`create-forge config init` writes a commented starter file at that path
+without overwriting one that already exists. `create-forge config show`
+prints the resolved values and where each came from.
+
+`github_org` pre-fills its prompt — you're still asked, just with the answer
+already typed in. `author_name` and `author_email` aren't prompted for at all,
+so a configured value is applied directly. `default_template` picks which
+template `new` offers first, interactively or under `--yes`.
+
+Every key can be overridden with an environment variable —
+`FORGE_GITHUB_ORG` and so on — or a command line flag. Precedence is
+config < environment < `--data` < an interactive answer.
+
+## Templates
+
+Run `create-forge list` for what your installed version offers. The registry is
+bundled with each release, so new templates arrive when you update the tool.
+
+To use your own template:
+
+```bash
+uvx create-forge new --template-url https://github.com/you/your-template
+```
+
+This describes the released v0.1.x architecture. Forge has accepted a future
+[public-engine integration contract](docs/integration-contract.md) in which a
+versioned `forge-template` package owns discovery and rendering. Its strict
+[ProjectSpec protocol v1](https://github.com/Sandsy09/forge-template/blob/main/docs/project-spec.md)
+and [component manifest protocol v1](https://github.com/Sandsy09/forge-template/blob/main/docs/component-manifests.md)
+are now implemented behind the canonical
+[stable template-engine API](https://github.com/Sandsy09/forge-template/blob/main/docs/template-engine-api.md)
+([ADR 0029](https://github.com/Sandsy09/forge-template/blob/main/docs/adr/0029-stable-template-engine-api.md)).
+The accepted
+[Library archetype contract](https://github.com/Sandsy09/forge-template/blob/main/docs/library-archetype.md)
+defines the first production component, implemented on `forge-template/main`
+and released at `0.3.0`. The accepted
+[CLI Application archetype contract](https://github.com/Sandsy09/forge-template/blob/main/docs/cli-application-archetype.md)
+selects the optionless engine-owned `cli` archetype and derives its console
+command from `ProjectSpec.project.repository_name`;
+[FT-08.04](https://github.com/Sandsy09/forge-template/issues/4) implemented
+it in the same `0.3.0` release, and
+[CF-08.02](https://github.com/Sandsy09/create-forge/issues/10) exposes both
+archetypes behind the hidden `new --engine-preview` flag's `--archetype`
+option. Neither change alters this CLI's default `new` answers, registry, or
+released dependency surface.
+The engine now also defines in-memory
+[generated-project validation](https://github.com/Sandsy09/forge-template/blob/main/docs/generated-project-validation.md)
+([ADR 0030](https://github.com/Sandsy09/forge-template/blob/main/docs/adr/0030-generated-project-validation.md))
+before rendered output is returned; `render_project` already calls it before
+`--engine-preview` receives a result.
+This repository now depends on a real, released `forge-template` range —
+`>=0.3.1,<0.4`, published to PyPI as the optional `engine` extra
+(`pip install 'create-forge[engine]'`; [#9](https://github.com/Sandsy09/create-forge/issues/9),
+[ADR 0018](docs/adr/0018-pypi-distribution-and-the-first-engine-range.md)) —
+rather than a development-only pin. That range is reachable only behind
+`--engine-preview`; the current registry and `--template-url` behaviour
+remain unchanged until the complete, tested cutover is released — at which
+point `--engine-source`/`--engine-ref` (see the
+[engine resolution contract](docs/engine-resolution.md)) take over this role,
+not `--template-url`.
+
+## Security
+
+**create-forge executes code from the template it clones.** Copier templates can
+declare post-generation tasks, and this tool runs them — that is how a generated
+project arrives already git-initialised with hooks installed.
+
+The template addresses are compiled into each release rather than fetched at
+runtime or read from user configuration, so the only code trusted by default is
+code published alongside the tool. `--template-url` bypasses that, and prompts
+for confirmation before doing so. Point it only at repositories you trust.
+
+Report vulnerabilities per [SECURITY.md](SECURITY.md) rather than in a public
+issue.
+
+## Using this at work
+
+In v0.1.x, organisations needing custom executable templates can fork this
+repository, point the bundled registry at their own templates, and maintain it
+internally. The accepted target makes a downstream client of the
+`forge-template` public engine the preferred route for organisation defaults
+and constraints. Forks remain appropriate for genuinely custom executable
+template content; see the [integration contract](docs/integration-contract.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and pull requests welcome.
+Significant design decisions are recorded in [docs/adr/](docs/adr/).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

create_forge-0.2.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+create_forge/__init__.py,sha256=2-hcPocqdDwT8xkrvZvaPhX8sCqs-lRWxW2KfRfTOjs,65
+create_forge/cli.py,sha256=naFa_KDve7K0qF-bZ3RmiWbjw0uoWddoP8bJk0URE74,26882
+create_forge/compat.py,sha256=CoeKBnouR4DeXSCGwL3hnf3BExnVLvc0OGtw0_xbnUY,2127
+create_forge/config.py,sha256=D0C4hMBiUKN-AORhWkXM7U7ldwJcd4WWD06hdY4WV6w,4017
+create_forge/engine.py,sha256=SX2bYqySTiiDLMzZSOyz6Qjh3EHDcXERTpNPZEi-bco,8953
+create_forge/models.py,sha256=uBx5yimdIErNbX6mwn_0JSy-LS3b5_YBCfDjN22pPb4,4949
+create_forge/pipeline.py,sha256=CfhsjvYicmUOHRIRrenionx6-vqDrEPP7XUeBAhntq0,5930
+create_forge/prompts.py,sha256=PjPXNieMQssOFhshHXf78bG6S29lSF-wHLrAQrVK-Qo,6898
+create_forge/registry.py,sha256=a3K0MWizORB0ghpjhBYlOCn_1kScglJYsJcKRQfWTlo,1144
+create_forge/runner.py,sha256=KvvgxMVWcBOyXU4B0ZYKsMRJ_g5DbYjUhLds3vEz-kI,5572
+create_forge/spec.py,sha256=lhAadGUMdp6mqdLh_ZeyWSqj8Hwla_OkYfRwPsPxP9Y,7620
+create_forge/staging.py,sha256=7PDW_k8J6OY6O9Tpp2ujp2R8n7IJY1p1pgx1yYYAwj4,7014
+create_forge/templates.toml,sha256=xjvgPGVGW9Q5td5GkbcI0Ake2oSetEA_S9r8BFwhdGY,3433
+create_forge-0.2.0.dist-info/METADATA,sha256=6NTcfq__WoaJtxWZpXJ9hW63RiwY7cK4kGJD7nopcpY,8814
+create_forge-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+create_forge-0.2.0.dist-info/entry_points.txt,sha256=KG4OcDHGWvh9JZKoeDJL3WcTlTN8Nj3q0Huq2WLrt7M,54
+create_forge-0.2.0.dist-info/licenses/LICENSE,sha256=PuaS9iQNMxQolcG-Im2lGUD5wzytHvnOcmvhceUau-o,1067
+create_forge-0.2.0.dist-info/RECORD,,

create_forge-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

create_forge-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+create-forge = create_forge.cli:app

create_forge-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Sands
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.