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

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

@@ -1,12 +1,17 @@
 # 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
+- Raise the Copier floor past the destination-escape advisories (#146)
 
 ### Documentation
 

{create_forge-0.3.1 → create_forge-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: create-forge
-Version: 0.3.1
+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
@@ -20,7 +20,8 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Code Generators
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: copier<10,>=9.15.2
+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

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

@@ -41,6 +41,7 @@ format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
 - [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.1 → create_forge-0.3.2}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "create-forge"
-version = "0.3.1"
+version = "0.3.2"
 description = "Scaffold modern Python projects from maintained templates."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -29,11 +29,13 @@ 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. The lower bound clears
-    # every published Copier advisory -- the destination-escape set fixed
-    # through 9.14.1, and one patch further to 9.15.2 for a clean rule. See
-    # ADR 0038 and docs/engine-updates.md.
-    "copier>=9.15.2,<10",
+    # 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
@@ -43,6 +45,11 @@ dependencies = [
     "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]

{create_forge-0.3.1 → create_forge-0.3.2}/src/create_forge/cli.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import re
 import shutil
 import subprocess
 import sys
@@ -42,7 +43,14 @@ from create_forge.prompts import (
     slugify,
 )
 from create_forge.registry import load_registry
-from create_forge.runner import ScaffoldError, ScaffoldRequest, scaffold, update
+from create_forge.runner import (
+    ScaffoldError,
+    ScaffoldRequest,
+    cache_probe,
+    copier_cache_location,
+    scaffold,
+    update,
+)
 from create_forge.sources import SourceError, display_source, validate_source
 from create_forge.spec import (
     DESCRIPTOR_KIND,
@@ -1050,6 +1058,30 @@ class ConfigSummary:
     keys: list[str]
 
 
+@dataclass(frozen=True, slots=True)
+class CopierCache:
+    """Copier's git-mirror cache location and whether create-forge could use
+    it -- see docs/engine-resolution.md's diagnostics contract. `writable` is
+    the only field that can fail a `doctor` check; the rest are facts.
+    """  # noqa: D205
+
+    path: str
+    override: bool
+    exists: bool
+    writable: bool
+
+
+@dataclass(frozen=True, slots=True)
+class UvStatus:
+    """The `uv` create-forge would actually run, and the one the `engine`
+    extra declares -- distinct facts that can legitimately differ.
+    """  # noqa: D205
+
+    path: str | None
+    version: str | None
+    package: str | None
+
+
 @dataclass(frozen=True, slots=True)
 class Diagnostics:
     """Everything `doctor` reports, gathered once so the table and `--json`
@@ -1061,6 +1093,8 @@ class Diagnostics:
     platform: str
     integration: Integration
     config: ConfigSummary
+    copier_cache: CopierCache
+    uv: UvStatus
     checks: list[Check]
 
     @property
@@ -1069,6 +1103,73 @@ class Diagnostics:
         return all(check.passed for check in self.checks if not check.informational)
 
 
+def _tooling_diagnostics(checks: list[Check]) -> tuple[CopierCache, UvStatus]:
+    """Append the tooling rows and return the structured facts.
+
+    The git / uv / Copier-cache rows land in `checks`; the cache and uv facts
+    `doctor --json` reports alongside them come back as dataclasses.
+    """
+    git_found = shutil.which("git")
+    checks.append(
+        Check(
+            "git",
+            bool(git_found),
+            git_found or "not on PATH — required to clone templates",
+        )
+    )
+
+    uv_found = shutil.which("uv")
+    uv_version = _uv_version(uv_found)
+    checks.append(
+        Check(
+            "uv",
+            bool(uv_found),
+            f"{uv_version} ({uv_found})"
+            if uv_found and uv_version
+            else uv_found or "not on PATH — required by generated projects",
+        )
+    )
+
+    cache = copier_cache_location()
+    probe = cache_probe(cache)
+    checks.append(
+        Check(
+            "copier cache",
+            True,
+            f"{cache.path} "
+            + (
+                "(COPIER_CACHE_DIR override)"
+                if cache.overridden
+                else "(default location)"
+            ),
+            informational=True,
+        )
+    )
+    checks.append(
+        Check(
+            "copier cache writable",
+            probe.writable,
+            "writable"
+            if probe.writable
+            else "not writable — set COPIER_CACHE_DIR to a writable directory",
+        )
+    )
+
+    return (
+        CopierCache(
+            path=str(cache.path),
+            override=cache.overridden,
+            exists=probe.exists,
+            writable=probe.writable,
+        ),
+        UvStatus(
+            path=uv_found,
+            version=uv_version,
+            package=_optional_dist_version("uv"),
+        ),
+    )
+
+
 def _gather_diagnostics() -> Diagnostics:
     """Run every doctor check and collect every reportable fact.
 
@@ -1091,12 +1192,7 @@ def _gather_diagnostics() -> Diagnostics:
     python_version = f"{py.major}.{py.minor}.{py.micro}"
     check(py >= (3, 11), "Python 3.11+", python_version)
 
-    for tool, why in (
-        ("git", "required to clone templates"),
-        ("uv", "required by generated projects"),
-    ):
-        found = shutil.which(tool)
-        check(bool(found), tool, found or f"not on PATH — {why}")
+    copier_cache, uv_status = _tooling_diagnostics(checks)
 
     if shutil.which("git"):
         name = _git_config("user.name")
@@ -1171,10 +1267,38 @@ def _gather_diagnostics() -> Diagnostics:
             template_ref=None,
         ),
         config=ConfigSummary(path=str(config_path()), keys=config_keys),
+        copier_cache=copier_cache,
+        uv=uv_status,
         checks=checks,
     )
 
 
+def _uv_version(uv_path: str | None) -> str | None:
+    """The version `uv --version` reports, or None when it can't be trusted.
+
+    `uv --version` prints e.g. `uv 0.12.10`. Only a token that looks like a
+    version is returned, so nothing arbitrary from the subprocess can reach
+    `doctor`'s output.
+    """
+    if not uv_path:
+        return None
+    try:
+        result = subprocess.run(  # noqa: S603
+            [uv_path, "--version"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=5,
+        )
+    except (OSError, subprocess.TimeoutExpired):  # pragma: no cover
+        return None
+    match result.stdout.split():
+        case [_, token, *_] if re.fullmatch(r"[0-9][0-9A-Za-z.+-]*", token):
+            return token
+        case _:
+            return None
+
+
 def _render_diagnostics_table(diagnostics: Diagnostics, target: Console) -> None:
     """Render `doctor`'s checks as the human-facing Rich table."""
     passed_marker, failed_marker = _markers(target)
@@ -1219,6 +1343,17 @@ def _diagnostics_payload(diagnostics: Diagnostics) -> dict[str, object]:
             "template_ref": integration.template_ref,
         },
         "config": {"path": diagnostics.config.path, "keys": diagnostics.config.keys},
+        "copier_cache": {
+            "path": diagnostics.copier_cache.path,
+            "override": diagnostics.copier_cache.override,
+            "exists": diagnostics.copier_cache.exists,
+            "writable": diagnostics.copier_cache.writable,
+        },
+        "uv": {
+            "path": diagnostics.uv.path,
+            "version": diagnostics.uv.version,
+            "package": diagnostics.uv.package,
+        },
         "checks": [
             {"name": c.name, "ok": c.passed, "detail": c.detail}
             for c in diagnostics.checks

{create_forge-0.3.1 → create_forge-0.3.2}/src/create_forge/runner.py

@@ -2,12 +2,20 @@
 
 Copier's Python API is public but not versioned as strictly as its CLI, so this
 module is the single place that touches it. Pin copier narrowly in
-pyproject.toml (`copier>=9.15.2,<10`) and this file is the only thing that
+pyproject.toml (`copier>=9.16,<10`) and this file is the only thing that
 needs attention on a major bump.
+
+`copier_cache_location` also models one piece of documented Copier behaviour --
+where the git-mirror cache lives and how `COPIER_CACHE_DIR` overrides it, added
+in Copier 9.16 -- so `doctor` can report it and a cache failure can be
+explained instead of misattributed to the network. `tests/test_copier_cache.py`
+pins that model against Copier's own private resolver so a drift fails CI.
 """
 
 from __future__ import annotations
 
+import os
+import tempfile
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -15,6 +23,7 @@ from typing import TYPE_CHECKING
 import yaml
 from copier import run_copy, run_update
 from copier.errors import CopierError
+from platformdirs import user_cache_dir
 from plumbum.commands.processes import ProcessExecutionError
 
 from create_forge import staging
@@ -34,6 +43,76 @@ _PROCESS_FAILURE_MESSAGE = (
     "access, and Git credentials, then retry."
 )
 
+COPIER_CACHE_ENV_VAR = "COPIER_CACHE_DIR"
+
+_CACHE_FAILURE_SIGNAL = "not a git repository"
+
+
+@dataclass(frozen=True, slots=True)
+class CacheLocation:
+    """Where Copier stores its git-mirror cache, and how it was chosen."""
+
+    path: Path
+    overridden: bool
+    """True when COPIER_CACHE_DIR selected the path, not the default."""
+
+
+@dataclass(frozen=True, slots=True)
+class CacheProbe:
+    """Whether Copier's cache directory exists and accepts writes."""
+
+    exists: bool
+    writable: bool
+
+
+def copier_cache_location() -> CacheLocation:
+    """Resolve Copier's cache directory by its own documented rule.
+
+    Copier uses `COPIER_CACHE_DIR` verbatim when it is set and non-empty,
+    otherwise `<platformdirs user cache for "copier">/git`. This mirrors
+    `copier._vcs._get_cache_dir`, which is private and has moved between
+    supported releases; `tests/test_copier_cache.py` pins the two together so
+    a drift fails CI rather than silently misreporting in `doctor`.
+    """
+    override = os.environ.get(COPIER_CACHE_ENV_VAR)
+    if override:
+        return CacheLocation(path=Path(override), overridden=True)
+    default = Path(user_cache_dir("copier", appauthor=False)) / "git"
+    return CacheLocation(path=default, overridden=False)
+
+
+def _write_probe(directory: Path) -> None:
+    """Create and immediately remove a uniquely named file in `directory`."""
+    fd, name = tempfile.mkstemp(dir=directory, prefix=".create-forge-probe-")
+    os.close(fd)
+    Path(name).unlink(missing_ok=True)
+
+
+def cache_probe(location: CacheLocation) -> CacheProbe:
+    """Report whether Copier could use `location` without changing it.
+
+    Never creates the cache directory: when it is absent, the deepest existing
+    ancestor is probed instead, because that is what Copier's own
+    `mirror.parent.mkdir(parents=True)` writes into. The probe creates a
+    uniquely named file and deletes it immediately -- it never reads, writes,
+    or lists a `<sha>.git` mirror, and leaves nothing persistent behind.
+
+    `os.access` is deliberately not used: on Windows it ignores ACLs and
+    reports a locked-down corporate cache directory as writable, which is the
+    exact condition this probe exists to catch.
+    """
+    exists = location.path.is_dir()
+    probe_dir = location.path
+    while not probe_dir.is_dir():
+        if probe_dir.parent == probe_dir:
+            return CacheProbe(exists=exists, writable=False)
+        probe_dir = probe_dir.parent
+    try:
+        _write_probe(probe_dir)
+    except OSError:
+        return CacheProbe(exists=exists, writable=False)
+    return CacheProbe(exists=exists, writable=True)
+
 
 @dataclass(frozen=True, slots=True)
 class ScaffoldRequest:
@@ -89,6 +168,16 @@ def scaffold(request: ScaffoldRequest) -> None:
             )
         except (CopierError, ProcessExecutionError) as exc:
             raise ScaffoldError(_explain(exc)) from exc
+        except OSError as exc:
+            # ProcessExecutionError is itself an OSError subclass, so it stays
+            # matched by the clause above. This one is Copier failing to
+            # create or use its cache directory directly (Copier >=9.16) -- a
+            # redirected or ACL-restricted cache on a managed machine surfaces
+            # here, before git runs. Errors outside the cache path are not
+            # ours to translate.
+            if (message := _explain_cache_os_error(exc)) is None:
+                raise
+            raise ScaffoldError(message) from exc
 
 
 def update(project: Path, *, vcs_ref: str | None = None, dry_run: bool = False) -> None:
@@ -143,6 +232,60 @@ def update(project: Path, *, vcs_ref: str | None = None, dry_run: bool = False)
         )
     except (CopierError, ProcessExecutionError) as exc:
         raise ScaffoldError(_explain(exc)) from exc
+    except OSError as exc:
+        # See scaffold(): a cache-directory failure Copier raises directly,
+        # not through git. Everything else re-raises untouched.
+        if (message := _explain_cache_os_error(exc)) is None:
+            raise
+        raise ScaffoldError(message) from exc
+
+
+def _cache_failure_message(cache_path: Path) -> str:
+    """Recovery guidance for an unusable Copier cache, naming only our own
+    resolved path -- never any part of the process output that revealed it.
+    """  # noqa: D205
+    return (
+        f"Copier's template cache at {cache_path} is not usable.\n"
+        "  This is common on managed machines where the cache location is "
+        "redirected or restricted.\n"
+        "  Point Copier at a fresh, writable directory and retry -- do not "
+        "delete the existing one:\n"
+        '    PowerShell:  $env:COPIER_CACHE_DIR = "C:\\forge-cache"\n'
+        '    bash/zsh:    export COPIER_CACHE_DIR="$HOME/.cache/forge-copier"'
+    )
+
+
+def _under_cache_dir(candidate: object, cache_path: Path) -> bool:
+    """True when `candidate` is a string path at or below `cache_path`."""
+    if not isinstance(candidate, str):
+        return False
+    return os.path.normcase(candidate).startswith(os.path.normcase(str(cache_path)))
+
+
+def _looks_like_cache_git_failure(exc: ProcessExecutionError, cache_path: Path) -> bool:
+    """True only for a git failure that reports a missing repository *and*
+    names the cache directory -- not for auth, network, or missing-source
+    failures that merely happen to run against a cache path in argv.
+    """  # noqa: D205
+    if _CACHE_FAILURE_SIGNAL not in (exc.stderr or "").lower():
+        return False
+    if os.path.normcase(str(cache_path)) in os.path.normcase(exc.stderr or ""):
+        return True
+    return any(_under_cache_dir(arg, cache_path) for arg in exc.argv or [])
+
+
+def _explain_cache_os_error(exc: OSError) -> str | None:
+    """Explain an OS error Copier raised while preparing its cache directory.
+
+    Returns None for any error whose filename is not under the resolved cache
+    directory, so the caller re-raises it untouched -- create-forge only owns
+    a failure at the cache path it can name.
+    """
+    cache_path = copier_cache_location().path
+    names = (exc.filename, getattr(exc, "filename2", None))
+    if any(_under_cache_dir(name, cache_path) for name in names):
+        return _cache_failure_message(cache_path)
+    return None
 
 
 def _explain(exc: CopierError | ProcessExecutionError) -> str:
@@ -155,7 +298,14 @@ def _explain(exc: CopierError | ProcessExecutionError) -> str:
         # The raw exception contains argv, stdout and stderr. In addition to
         # being too implementation-specific for users, argv may contain
         # credentials embedded in a template URL, so none of it is displayed.
-        return _PROCESS_FAILURE_MESSAGE
+        # Only fixed signals are read out of it, and only create-forge's own
+        # resolved cache path is ever shown.
+        cache = copier_cache_location()
+        return (
+            _cache_failure_message(cache.path)
+            if _looks_like_cache_git_failure(exc, cache.path)
+            else _PROCESS_FAILURE_MESSAGE
+        )
 
     text = str(exc)
     lowered = text.lower()

{create_forge-0.3.1 → create_forge-0.3.2}/tests/installed_client.py

@@ -33,7 +33,7 @@ if TYPE_CHECKING:
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 
-CLIENT_VERSION = "0.3.1"
+CLIENT_VERSION = "0.3.2"
 ENGINE_VERSION = "0.4.1"
 DEFAULT_PYTHON = "3.13"
 SUBPROCESS_TIMEOUT = 1800

{create_forge-0.3.1 → create_forge-0.3.2}/tests/test_cli.py

@@ -66,6 +66,9 @@ def _isolated_config(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
     _clean_forge_env, extended to also isolate the file path.
     """
     monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+    # doctor now probes Copier's cache directory; keep that off the real
+    # user cache the same way config is kept off the real config file.
+    monkeypatch.setenv("COPIER_CACHE_DIR", str(tmp_path / "copier-cache"))
     for field in UserConfig.model_fields:
         monkeypatch.delenv(f"FORGE_{field.upper()}", raising=False)
     return config_path()
@@ -235,6 +238,56 @@ def test_doctor_json_exits_1_when_a_check_fails(
     assert registry_check["ok"] is False
 
 
+def test_doctor_reports_the_copier_cache_and_uv(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """ADR 0039 / docs/engine-resolution.md diagnostics contract: `doctor`
+    names Copier's cache directory, whether COPIER_CACHE_DIR overrides it, and
+    whether it is writable, plus the `uv` binary it would actually run.
+    """
+    monkeypatch.setattr(cli_module, "_git_config", lambda _key: "test")
+    override = tmp_path / "cache dir"
+    override.mkdir()
+    monkeypatch.setenv("COPIER_CACHE_DIR", str(override))
+
+    result = runner.invoke(app, ["doctor", "--json"])
+
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["copier_cache"] == {
+        "path": str(override),
+        "override": True,
+        "exists": True,
+        "writable": True,
+    }
+    assert set(payload["uv"]) == {"path", "version", "package"}
+    assert "copier cache" in result.output  # informational row in the table too
+
+
+def test_doctor_fails_when_the_copier_cache_is_unwritable(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """An unwritable cache means the environment genuinely cannot scaffold, so
+    the check fails and `doctor` exits 1 -- the schema stays additive, only
+    the boolean flips.
+    """
+    monkeypatch.setattr(cli_module, "_git_config", lambda _key: "test")
+    monkeypatch.setattr(
+        cli_module,
+        "cache_probe",
+        lambda _location: runner_module.CacheProbe(exists=True, writable=False),
+    )
+
+    result = runner.invoke(app, ["doctor", "--json"])
+
+    assert result.exit_code == 1
+    payload = json.loads(result.output)
+    assert payload["ok"] is False
+    assert payload["copier_cache"]["writable"] is False
+    check = next(c for c in payload["checks"] if c["name"] == "copier cache writable")
+    assert check["ok"] is False
+
+
 def test_doctor_survives_a_console_that_cannot_encode_check_marks(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None: