create-forge 0.2.0__tar.gz → 0.2.1__tar.gz

{create_forge-0.2.0 → create_forge-0.2.1}/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 
 Generated by git-cliff from Conventional Commits.
+## [0.2.1] - 2026-08-31
+
+### Bug Fixes
+
+- Generate engine project lockfiles
+
+### Refactor
+
+- Derive component options from discovery, not an archetype list (#92)
+
+### Testing
+
+- Extend end-to-end generation to the public engine (#93)
 ## [0.2.0] - 2026-08-30
 
 ### Documentation
@@ -36,7 +49,7 @@ Generated by git-cliff from Conventional Commits.
 - Implement the shared create pipeline behind an opt-in engine flag (#83)
 - Stage and finalise generation without leaving partials (#84)
 - Expose the CLI Application archetype through the engine path (#89)
-- Publish to PyPI and assign the first bounded engine range
+- Publish to PyPI and assign the first bounded engine range (#90)
 
 ### Testing
 

{create_forge-0.2.0 → create_forge-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: create-forge
-Version: 0.2.0
+Version: 0.2.1
 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
@@ -27,6 +27,7 @@ Requires-Dist: rich>=13.9
 Requires-Dist: typer>=0.15
 Provides-Extra: engine
 Requires-Dist: forge-template<0.4,>=0.3.1; extra == 'engine'
+Requires-Dist: uv<0.13,>=0.12; extra == 'engine'
 Description-Content-Type: text/markdown
 
 # create-forge
@@ -158,13 +159,22 @@ it in the same `0.3.0` release, and
 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 Stage 08
+[composition architecture review](https://github.com/Sandsy09/forge-template/blob/main/docs/composition-architecture-review.md)
+is released in `forge-template 0.3.2`. On the engine-preview path,
+`create-forge 0.2.1` now finalises the validated in-memory render with
+`uv lock --directory <staging-directory>` before the atomic rename. The
+result contains `uv.lock` and uses `uv run --locked poe check`, while the
+default Copier path remains unchanged; see
+[ADR 0021](docs/adr/0021-client-finalises-engine-lockfiles.md).
 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
+`>=0.3.1,<0.4`, published to PyPI with `uv>=0.12,<0.13` 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

{create_forge-0.2.0 → create_forge-0.2.1}/README.md

@@ -127,13 +127,22 @@ it in the same `0.3.0` release, and
 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 Stage 08
+[composition architecture review](https://github.com/Sandsy09/forge-template/blob/main/docs/composition-architecture-review.md)
+is released in `forge-template 0.3.2`. On the engine-preview path,
+`create-forge 0.2.1` now finalises the validated in-memory render with
+`uv lock --directory <staging-directory>` before the atomic rename. The
+result contains `uv.lock` and uses `uv run --locked poe check`, while the
+default Copier path remains unchanged; see
+[ADR 0021](docs/adr/0021-client-finalises-engine-lockfiles.md).
 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
+`>=0.3.1,<0.4`, published to PyPI with `uv>=0.12,<0.13` 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

{create_forge-0.2.0 → create_forge-0.2.1}/docs/adr/README.md

@@ -21,6 +21,9 @@ format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
 - [0016 — Test the reference client end to end against the released template](0016-end-to-end-reference-client-tests.md)
 - [0017 — Expose the CLI Application archetype through discovery-driven selection](0017-cli-application-archetype-exposure.md)
 - [0018 — Publish to PyPI and assign the first bounded engine range](0018-pypi-distribution-and-the-first-engine-range.md)
+- [0019 — CLI archetype-parity review](0019-cli-archetype-parity-review.md)
+- [0020 — Test the public engine path end to end](0020-engine-path-end-to-end-tests.md)
+- [0021 — Finalise engine-generated lockfiles in the client](0021-client-finalises-engine-lockfiles.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.2.0 → create_forge-0.2.1}/docs/roadmap-v1/README.md

@@ -13,13 +13,17 @@ define the mandatory generated-project outcomes, while the
 defines which concerns may belong in that baseline. The
 [Library archetype contract](https://github.com/Sandsy09/forge-template/blob/main/docs/library-archetype.md)
 defines the first production archetype, implemented on
-`forge-template/main` and released at `0.3.0`. The
+`forge-template/main`, released at `0.3.0`, and included in the completed
+two-archetype [composition review](https://github.com/Sandsy09/forge-template/blob/main/docs/composition-architecture-review.md)
+released at `0.3.2`. The
 [CLI Application archetype contract](https://github.com/Sandsy09/forge-template/blob/main/docs/cli-application-archetype.md)
 selects the engine-owned, optionless `cli` archetype and derives its command
 from `ProjectSpec.project.repository_name`; FT-08.04 implemented it, and
 CF-08.02 exposes both archetypes behind `create-forge`'s hidden
 `--engine-preview` flag. Neither contract changes this repository's default
-`new` path or unassigned released engine range. The
+`new` path. `create-forge 0.2.1` keeps the released engine range unchanged and
+adds client-owned lock finalisation under
+[ADR 0021](../adr/0021-client-finalises-engine-lockfiles.md). The
 [Python support policy](https://github.com/Sandsy09/forge-template/blob/main/docs/python-support.md)
 defines the generated-project CPython window, defaults, and release lifecycle.
 The [editor integration strategy](https://github.com/Sandsy09/forge-template/blob/main/docs/editor-integration.md)
@@ -60,12 +64,8 @@ The canonical
 [generated-project validation contract](https://github.com/Sandsy09/forge-template/blob/main/docs/generated-project-validation.md)
 and [ADR 0030](https://github.com/Sandsy09/forge-template/blob/main/docs/adr/0030-generated-project-validation.md)
 complete the `forge-template` side of Stage 07 by validating rendered output
-in memory. The shared stage remains open for `create-forge` CLI orchestration,
-filesystem safety, and end-to-end coverage.
-`forge-template/main` now contains the Library production catalogue, while
-this repository's exact development pin still sees the earlier empty
-catalogue. CLI Application implementation and coordinated CLI discovery remain
-later work.
+in memory. Stage 07 and Stage 08 are now complete across both repositories;
+the default Copier-to-engine cutover remains separate future work.
 This roadmap links to the canonical sources rather than maintaining second
 definitions.
 

{create_forge-0.2.0 → create_forge-0.2.1}/docs/roadmap-v1/roadmap/07-forge-cli-integration/README.md

@@ -60,9 +60,15 @@ the *public engine* against a *released* engine-and-assets unit -- because
 neither exists yet: `forge-template` has no `0.2.x` release and its
 production catalogue stays empty until
 [FT-08.02 / forge-template#41](https://github.com/Sandsy09/forge-template/issues/41).
-Those two criteria carry forward verbatim to **CF-08.04**, filed under
+Those two criteria carried forward verbatim to **CF-08.04**, filed under
 [CF-EPIC-08](https://github.com/Sandsy09/create-forge/issues/39) and blocked
-on the same two things. See the canonical
+on the same two things at the time. Both blockers have since resolved --
+[FT-08.02 / forge-template#41](https://github.com/Sandsy09/forge-template/issues/41)
+shipped the production catalogue, and
+[#9](https://github.com/Sandsy09/create-forge/issues/9) published a released
+engine range -- and CF-08.04 is complete
+([ADR 0020](https://github.com/Sandsy09/create-forge/blob/main/docs/adr/0020-engine-path-end-to-end-tests.md)).
+See the canonical
 [end-to-end tests contract](https://github.com/Sandsy09/create-forge/blob/main/docs/end-to-end-tests.md).
 The atomic cutover that replaces both the v0.1.x registry seam and
 `--engine-preview` stays gated on

create_forge-0.2.1/docs/roadmap-v1/roadmap/08-reference-archetype-validation/README.md

@@ -0,0 +1,81 @@
+# Stage 08 — Reference Archetype Validation
+
+## Repository ownership
+
+### forge-template
+
+- ~~**FT-08.01 — Define Library archetype contract**~~ — complete via the
+  [canonical contract](https://github.com/Sandsy09/forge-template/blob/main/docs/library-archetype.md),
+  [ADR 0031](https://github.com/Sandsy09/forge-template/blob/main/docs/adr/0031-library-archetype-contract.md),
+  and [forge-template PR #79](https://github.com/Sandsy09/forge-template/pull/79).
+- ~~**FT-08.02 — Migrate the Library archetype to the composition contract**~~
+  — complete via [forge-template PR #81](https://github.com/Sandsy09/forge-template/pull/81).
+- ~~**FT-08.03 — Select and define the second reference archetype contract**~~
+  — CLI Application selected via the
+  [canonical contract](https://github.com/Sandsy09/forge-template/blob/main/docs/cli-application-archetype.md),
+  [ADR 0034](https://github.com/Sandsy09/forge-template/blob/main/docs/adr/0034-select-cli-application-reference-archetype.md),
+  and [forge-template PR #82](https://github.com/Sandsy09/forge-template/pull/82).
+- ~~**FT-08.04 — Implement the CLI Application reference archetype**~~ —
+  complete via
+  [forge-template PR #84](https://github.com/Sandsy09/forge-template/pull/84),
+  released at `forge-template` `0.3.0` alongside Library.
+- ~~**FT-08.05 — Run composition architecture review**~~ — complete via the
+  [canonical review](https://github.com/Sandsy09/forge-template/blob/main/docs/composition-architecture-review.md),
+  [ADR 0037](https://github.com/Sandsy09/forge-template/blob/main/docs/adr/0037-two-archetype-composition-review.md),
+  [forge-template PR #87](https://github.com/Sandsy09/forge-template/pull/87),
+  and `forge-template 0.3.2`. Its client-finalisation finding is implemented
+  by create-forge [ADR 0021](../../../adr/0021-client-finalises-engine-lockfiles.md)
+  for the `0.2.1` release.
+
+### create-forge
+
+- Epic: [CF-EPIC-08 / #39](https://github.com/Sandsy09/create-forge/issues/39)
+- ~~**CF-08.01 — Expose Library archetype through create-forge**~~ — completed before roadmap filing.
+- ~~**CF-08.02 — Expose CLI Application through create-forge**~~ — complete via
+  [ADR 0017](https://github.com/Sandsy09/create-forge/blob/main/docs/adr/0017-cli-application-archetype-exposure.md),
+  which moves this repository's exact development pin to `forge-template==0.3.0`
+  and adds a discovery-driven `--archetype` option and prompt behind
+  `--engine-preview`.
+- ~~**CF-08.03 — Run CLI archetype-parity review**~~ — complete via
+  [ADR 0019](https://github.com/Sandsy09/create-forge/blob/main/docs/adr/0019-cli-archetype-parity-review.md)
+  and [create-forge#52](https://github.com/Sandsy09/create-forge/issues/52).
+  The shared ProjectSpec/pipeline path and engine-owned discovery were
+  confirmed generic; the one archetype-specific branch found
+  (`pipeline._resolved_component_options`) is now gated by a discovered
+  descriptor rather than a hardcoded archetype id. The engine path's
+  Library-shaped prompt set was recorded, not fixed, and tracked by
+  [create-forge#91](https://github.com/Sandsy09/create-forge/issues/91).
+- ~~**CF-08.04 — Extend end-to-end generation to the public engine**~~ —
+  complete via
+  [ADR 0020](https://github.com/Sandsy09/create-forge/blob/main/docs/adr/0020-engine-path-end-to-end-tests.md)
+  and [create-forge#85](https://github.com/Sandsy09/create-forge/issues/85),
+  successor to [CF-07.06 / #51](https://github.com/Sandsy09/create-forge/issues/51).
+  `tests/test_e2e_engine_generation.py` generates both archetypes through
+  `--engine-preview` against the real installed engine, runs each generated
+  project's own checks, and proves the released-install compatibility
+  boundary (an out-of-range engine installed from a git tag, and no `engine`
+  extra at all) writes nothing. This closes
+  [CF-EPIC-08 / #39](https://github.com/Sandsy09/create-forge/issues/39).
+
+The Library decision records the legacy answer mapping into
+`component_options.library.packaging_mode`; CF-08.02 wires it on the engine
+path via `spec.legacy_library_answers` and
+`engine.map_legacy_library_options`. CLI Application is selected as
+engine-owned ID `cli`, has no component options, and derives its console
+command from `ProjectSpec.project.repository_name`; FT-08.04 implemented it
+and create-forge #10 exposes it, both landing in this stage.
+
+All repository-local children are complete. The two-archetype review removed
+archetype assumptions from Foundation without adding inheritance or a shared
+runtime layer, while create-forge now creates the dynamic lockfile in adjacent
+staging before atomic placement. Stage 08 is complete across both
+repositories.
+
+## Stage completion rule
+
+- [x] Repo-local issues are complete or explicitly deferred.
+- [x] Cross-repository blockers are resolved. -- #9/ADR 0018 was the last one.
+- [x] Public contracts changed by this stage are documented/versioned --
+  ADR 0017, ADR 0019, ADR 0020, ADR 0021, and forge-template ADR 0037.
+- [x] No implementation concern is duplicated across repositories -- CF-08.03
+  (ADR 0019) confirmed this directly.

{create_forge-0.2.0 → create_forge-0.2.1}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "create-forge"
-version = "0.2.0"
+version = "0.2.1"
 description = "Scaffold modern Python projects from maintained templates."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -44,7 +44,8 @@ dependencies = [
 # downloads an engine it doesn't 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.
-engine = ["forge-template>=0.3.1,<0.4"]
+# ADR 0021 adds bounded uv to finalise the engine render's dynamic lockfile.
+engine = ["forge-template>=0.3.1,<0.4", "uv>=0.12,<0.13"]
 
 [project.scripts]
 create-forge = "create_forge.cli:app"

{create_forge-0.2.0 → create_forge-0.2.1}/src/create_forge/cli.py

@@ -350,6 +350,7 @@ def _run_engine_preview(
 
 def _report_created(project_name: object, dst: Path, *, updatable: bool = True) -> None:
     """Print the success panel once a project has actually been written."""
+    check_command = "uv run poe check" if updatable else "uv run --locked poe check"
     update_line = (
         "[dim]Pull later template changes with: uvx create-forge update[/dim]"
         if updatable
@@ -360,7 +361,7 @@ def _report_created(project_name: object, dst: Path, *, updatable: bool = True)
         Panel(
             f"[bold]{project_name}[/bold] created at [dim]{dst}[/dim]\n\n"
             f"  cd {dst.name}\n"
-            "  uv run poe check\n\n"
+            f"  {check_command}\n\n"
             f"{update_line}",
             border_style="green",
         )

{create_forge-0.2.0 → create_forge-0.2.1}/src/create_forge/pipeline.py

@@ -2,7 +2,7 @@
 
 This is the one internal generation path CF-07.01 introduces (ADR 0014).
 It depends on `create_forge.engine` -- and therefore, transitively, on the
-development-only `forge-template` dependency -- but its own source never
+optional `forge-template` engine extra (ADR 0018) -- but its own source never
 imports `forge_template` directly: type annotations that need engine-owned
 types import them only under `TYPE_CHECKING`, so this module's runtime
 behaviour never requires the engine to be *type-checkable*, only to be
@@ -12,8 +12,8 @@ the only module whose source touches `forge_template` at runtime, per ADR
 
 `create_forge.cli` imports this module lazily, inside `--engine-preview`'s
 branch only, guarded by `try/except ImportError` -- see ADR 0014 for why:
-`forge-template` is not a runtime dependency of the released CLI, so no
-module reachable at `cli.py`'s own import time may depend on it.
+`forge-template` is not installed by a plain `pip install create-forge`, so
+no module reachable at `cli.py`'s own import time may depend on it.
 """
 
 from __future__ import annotations
@@ -57,24 +57,44 @@ def _resolved_component_options(
     answers: Mapping[str, object],
     archetype: str,
     component_options: Mapping[str, Mapping[str, object]] | None,
+    descriptors: Sequence[ComponentDescriptor],
 ) -> Mapping[str, Mapping[str, object]] | None:
     """Derive `component_options` when the caller supplied none.
 
-    The one archetype-specific branch in this codebase (CF-08.02): `library`
-    predates the engine, so its legacy `build_backend`/`versioning`
-    answers need translating into the production `packaging_mode` option or
-    a user's choice silently reverts to the engine's own default. `cli` has
-    no options and needs no translation -- every other archetype passes
-    through unchanged, keyed on the engine's own
-    `map_legacy_library_answers` naming rather than on a local archetype
-    list, so this does not grow into a per-archetype registry here.
+    `library` predates the engine, so its legacy `build_backend`/`versioning`
+    answers need translating into the production `packaging_mode` option or a
+    user's choice silently reverts to the engine's own default. CF-08.03's
+    archetype-parity review (ADR 0019) found this derivation keyed on a
+    hardcoded `archetype != "library"` check -- the one archetype-specific
+    branch in this codebase -- and generalised it: `engine.map_legacy_library_options`
+    already names the option it produces (`packaging_mode`), and the
+    selected archetype's own discovered `ComponentDescriptor.options` already
+    declares whether it accepts that name. Applying the mapping only when the
+    descriptor declares it needs no archetype id anywhere in this function,
+    so a future archetype that also wants the legacy mapping (or `library`
+    itself being renamed) needs no change here -- only in the engine's own
+    manifest.
+
+    The descriptor lookup runs before the mapping call, not after: an
+    archetype that declares no options at all (`cli`) never needs
+    `engine.map_legacy_library_options` invoked on its behalf, matching the
+    old code's behaviour of never calling it for a non-`library` archetype.
     """
-    if component_options is not None or archetype != "library":
+    if component_options is not None:
         return component_options
+    descriptor = next((d for d in descriptors if d.id == archetype), None)
+    if descriptor is None or not descriptor.options:
+        return None
     legacy = legacy_library_answers(answers)
     if legacy is None:
         return None
-    return {"library": engine.map_legacy_library_options(legacy)}
+    mapped = engine.map_legacy_library_options(legacy)
+    if not mapped:
+        return None
+    declared = {option.name for option in descriptor.options}
+    if not set(mapped) <= declared:
+        return None
+    return {archetype: mapped}
 
 
 def build_generation_request(
@@ -95,19 +115,20 @@ def build_generation_request(
     this pipeline mints no component identifiers of its own. An explicit
     `component_options` is likewise passed through unchanged; when the
     caller supplies none, `_resolved_component_options` derives the one
-    legacy mapping this repository still owns. `discover()` runs for its own
-    compatibility-ladder effect and to surface real descriptors to callers;
-    `discover_archetypes()` is what actually drives selection, from
-    `cli.py`.
+    legacy mapping this repository still owns, gated on the selected
+    archetype's own discovered descriptor rather than a hardcoded id
+    (CF-08.03, ADR 0019). `discover()`'s result is reused for exactly that
+    gate; `discover_archetypes()` is the separate, `kind`-filtered view that
+    actually drives selection, from `cli.py`.
 
     Every downstream call (`build_project_spec`, `validate`, `render`)
     independently re-checks package/protocol compatibility before doing its
     own work, so there is no side effect -- in-memory or otherwise -- before
     every check has passed.
     """
-    engine.discover()
+    descriptors = engine.discover()
     resolved_options = _resolved_component_options(
-        answers, archetype, component_options
+        answers, archetype, component_options, descriptors
     )
     payload = build_spec_payload(
         answers,
@@ -123,19 +144,23 @@ def build_generation_request(
 
 
 def finalise_generation_request(request: GenerationRequest, destination: Path) -> None:
-    """Stage and finalise `request`'s rendered files (ADR 0015).
+    """Stage, lock, and finalise `request`'s rendered files (ADR 0021).
 
     Renders them into a directory adjacent to `destination`, then moves that
-    directory into place atomically.
+    directory into place atomically. ``uv.lock`` is created after the reviewed
+    render is written and before the rename, so lock resolution cannot leave a
+    partial destination.
 
     `create-forge` does not call `forge_template.validate_rendered_project`
     itself -- `engine.render()` already did, as the last step inside
     `build_generation_request`. Reaching this function at all means that
     validation already passed; this function's only job is the filesystem
-    half create-forge owns: staging, target-safety, and an atomic rename.
+    half create-forge owns: staging, target-safety, lock finalisation, and an
+    atomic rename.
     """
     with staging.staged(destination) as staging_dir:
         staging.write_files(
             staging_dir,
             ((file.target, file.content) for file in request.rendered.files),
         )
+        staging.create_uv_lock(staging_dir)

{create_forge-0.2.0 → create_forge-0.2.1}/src/create_forge/staging.py

@@ -2,11 +2,12 @@
 
 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
+test suite with no optional `engine` extra (ADR 0018) 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
+[ADR 0015](../../docs/adr/0015-staged-filesystem-generation.md),
+[ADR 0021](../../docs/adr/0021-client-finalises-engine-lockfiles.md), and the
 canonical [filesystem generation contract](../../docs/filesystem-generation.md)
 for why the two paths differ and what each guarantees.
 """
@@ -15,6 +16,7 @@ from __future__ import annotations
 
 import contextlib
 import shutil
+import subprocess
 import tempfile
 import warnings
 from pathlib import Path, PurePosixPath
@@ -90,6 +92,41 @@ def write_files(root: Path, files: Iterable[tuple[str, bytes]]) -> None:
             raise StagingError(msg) from exc
 
 
+def create_uv_lock(root: Path) -> None:
+    """Resolve the staged project's committed lockfile before finalisation.
+
+    The engine render is deliberately side-effect free, so ``uv.lock`` is a
+    client-owned finalisation artefact. Run uv without a shell and translate
+    launch or resolution failures into the staging error surface; the
+    surrounding :func:`staged` context then removes the incomplete tree and
+    leaves the destination untouched.
+    """
+    command = ["uv", "lock", "--directory", str(root)]
+    try:
+        result = subprocess.run(  # noqa: S603 - reviewed fixed executable
+            command,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        msg = (
+            "could not create uv.lock because the uv executable is unavailable; "
+            "install uv>=0.12,<0.13 and retry"
+        )
+        raise StagingError(msg) from exc
+    except OSError as exc:
+        msg = f"could not launch uv to create uv.lock: {exc}"
+        raise StagingError(msg) from exc
+
+    if result.returncode != 0:
+        msg = (
+            f"uv lock failed with exit status {result.returncode}; check the "
+            "project's declared dependencies and package-index access, then retry"
+        )
+        raise StagingError(msg)
+
+
 def _on_rm_error(func: object, path: str, exc_info: object) -> None:
     """`shutil.rmtree` error handler: clear read-only and retry once.
 

create_forge-0.2.1/tests/conftest.py

@@ -0,0 +1,70 @@
+"""Shared pytest configuration for contributor-only test options and fixtures
+shared across the `e2e`-marked suites.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+
+import pytest
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """Register the local forge-template checkout used by drift tests."""
+    parser.addoption(
+        "--forge-template-root",
+        metavar="PATH",
+        help=(
+            "Read copier.yml from a local forge-template checkout instead of "
+            "cloning its latest release tag."
+        ),
+    )
+
+
+@pytest.fixture(scope="session")
+def create_forge_command() -> str:
+    """Resolve the real console script -- not `python -m create_forge`, and
+    not Typer's `CliRunner`. Both would skip the `[project.scripts]` entry
+    point users actually invoke. Shared by every `e2e`-marked module that
+    drives the real binary: `tests/test_e2e_generation.py` (Copier path) and
+    `tests/test_e2e_engine_generation.py` (engine path).
+    """
+    found = shutil.which("create-forge")
+    if found is None:  # pragma: no cover - packaging bug, not a test failure mode
+        pytest.fail(
+            "the 'create-forge' console script is not on PATH -- "
+            "run this suite via `uv run pytest`, which installs it"
+        )
+    return found
+
+
+@pytest.fixture(scope="session")
+def e2e_child_env() -> dict[str, str]:
+    """The subprocess environment for a real `create-forge` invocation.
+
+    Both e2e paths spawn a child `uv` of their own -- the Copier path's
+    `copier.yml` `_tasks` run `uv sync --all-groups` and `git commit` inside
+    the generated project; the engine path's tests run the generated
+    project's own `uv run poe check` directly. Two things must hold for that
+    child `uv` to target the generated project rather than this repository's
+    own environment: `VIRTUAL_ENV`, `UV_PROJECT_ENVIRONMENT`, `PYTHONHOME`,
+    and `PYTHONPATH` -- all set by `uv run` for *this* pytest process -- must
+    not leak into the child. And `git commit` (the Copier path only) needs an
+    identity CI does not have, which a plain `env=` argument supplies for the
+    whole subprocess tree with no plumbum-snapshot caveat (contrast
+    `tests/test_update_network.py`'s `_git_identity_for_template_tasks`
+    fixture, needed only because that test calls `scaffold()` in-process).
+    """
+    env = dict(os.environ)
+    for leak in ("VIRTUAL_ENV", "UV_PROJECT_ENVIRONMENT", "PYTHONHOME", "PYTHONPATH"):
+        env.pop(leak, None)
+    env.update(
+        {
+            "GIT_AUTHOR_NAME": "create-forge e2e",
+            "GIT_AUTHOR_EMAIL": "create-forge-e2e@example.invalid",
+            "GIT_COMMITTER_NAME": "create-forge e2e",
+            "GIT_COMMITTER_EMAIL": "create-forge-e2e@example.invalid",
+        }
+    )
+    return env