create-forge 0.2.0__py3-none-any.whl

create_forge/compat.py

@@ -0,0 +1,47 @@
+"""Engine compatibility constants shared by shipped and engine-only modules.
+
+Deliberately engine-free: nothing here imports `forge_template`, not even
+under `TYPE_CHECKING`. That is what lets `cli.py`'s `doctor` command report
+the declared engine range and supported protocols unconditionally --
+independent of whether the `engine` extra is installed, and without
+importing `engine.py` itself, which would break ADR 0014's rule that no
+module reachable from `create-forge`'s shipped entry point may depend on
+`forge_template` at its own import time.
+`tests/test_engine_contract.py`'s `_SHIPPED_MODULES` AST guard covers this
+module for exactly that reason -- mirroring the role `staging.py` already
+plays for the same rule (ADR 0015). See
+[ADR 0018](../../docs/adr/0018-pypi-distribution-and-the-first-engine-range.md)
+and the canonical [engine resolution contract](../../docs/engine-resolution.md).
+"""
+
+from __future__ import annotations
+
+ENGINE_DISTRIBUTION = "forge-template"
+"""The PyPI distribution name `create-forge[engine]` declares."""
+
+SUPPORTED_ENGINE_RANGE = ">=0.3.1,<0.4"
+"""The first assigned, released compatibility range (ADR 0018).
+
+Pre-1.0, a supported range stays within one minor line -- see the
+[integration contract](../../docs/integration-contract.md)'s
+version-and-protocol-compatibility rule. `0.3.1` is the first PyPI release of
+`forge-template` (forge-template ADR 0036); `engine.py` checks an installed
+package against this range with `packaging.specifiers.SpecifierSet`,
+replacing the prior exact-pin development check.
+"""
+
+SUPPORTED_PROJECTSPEC_PROTOCOLS: tuple[int, ...] = (1,)
+"""ProjectSpec wire protocols this create-forge release has implemented
+against.
+
+Deliberately not read from the installed engine's own advertised protocols
+-- negotiation in `engine.py` compares the two sides rather than assuming
+they agree.
+"""
+
+SUPPORTED_COMPONENT_MANIFEST_PROTOCOLS: tuple[int, ...] = (1, 2)
+"""Component-manifest protocols this create-forge release understands.
+
+Independent from the installed engine's advertised protocols for the same
+reason as :data:`SUPPORTED_PROJECTSPEC_PROTOCOLS`.
+"""

create_forge/config.py

@@ -0,0 +1,126 @@
+"""User configuration.
+
+Purely a convenience layer: it remembers answers you would otherwise retype on
+every scaffold. It deliberately cannot change which template is cloned — that
+address is bundled with the release so the code being trusted is the code that
+was reviewed. Use `--template-url` for a one-off override.
+
+Resolution order, lowest to highest precedence:
+
+  1. built-in defaults
+  2. $XDG_CONFIG_HOME/create-forge/config.toml (or ~/.config/...)
+  3. FORGE_* environment variables
+  4. command line flags (applied by cli.py, not here)
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, ValidationError, model_validator
+
+_ENV_PREFIX = "FORGE_"
+_FILENAME = "config.toml"
+
+
+class UserConfig(BaseModel):
+    """Remembered answers, all optional."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    author_name: str | None = None
+    author_email: str | None = None
+    github_org: str | None = None
+    default_template: str | None = None
+
+    @model_validator(mode="after")
+    def _blank_is_unset(self) -> Self:
+        # A key present but empty in TOML should behave as absent rather than
+        # pre-filling a prompt with "".
+        cleaned = {
+            k: (v.strip() or None) if isinstance(v, str) else v
+            for k, v in self.__dict__.items()
+        }
+        if cleaned != self.__dict__:
+            return self.model_copy(update=cleaned)
+        return self
+
+    def as_answers(self) -> dict[str, object]:
+        """The subset usable as template answers."""
+        return {
+            key: value
+            for key, value in (
+                ("author_name", self.author_name),
+                ("author_email", self.author_email),
+                ("github_org", self.github_org),
+            )
+            if value is not None
+        }
+
+
+def config_path() -> Path:
+    """Where the config file is expected to live."""
+    base = os.environ.get("XDG_CONFIG_HOME")
+    root = Path(base) if base else Path.home() / ".config"
+    return root / "create-forge" / _FILENAME
+
+
+def load_config(path: Path | None = None) -> UserConfig:
+    """Read config from disk and environment.
+
+    A malformed config is the user's to fix, so it raises with the path rather
+    than being silently ignored — silently ignoring it produces the far more
+    confusing failure of settings that appear to do nothing.
+    """
+    target = path or config_path()
+    data: dict[str, object] = {}
+
+    if target.is_file():
+        try:
+            data = tomllib.loads(target.read_text("utf-8"))
+        except tomllib.TOMLDecodeError as exc:
+            msg = f"{target} is not valid TOML: {exc}"
+            raise ValueError(msg) from exc
+        except OSError as exc:
+            msg = f"Could not read {target}: {exc}"
+            raise ValueError(msg) from exc
+
+    data |= env_overrides()
+
+    try:
+        return UserConfig.model_validate(data)
+    except ValidationError as exc:
+        msg = f"Invalid configuration in {target}:\n{exc}"
+        raise ValueError(msg) from exc
+
+
+def env_overrides() -> dict[str, object]:
+    """Which `FORGE_*` environment variables are set, e.g. `FORGE_GITHUB_ORG`."""
+    return {
+        field: os.environ[key]
+        for field in UserConfig.model_fields
+        if (key := f"{_ENV_PREFIX}{field.upper()}") in os.environ
+    }
+
+
+def write_example(path: Path | None = None) -> Path:
+    """Write a commented starter config. Never overwrites."""
+    target = path or config_path()
+    if target.exists():
+        return target
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(
+        "# create-forge configuration.\n"
+        "# These pre-fill prompts; every value is optional.\n"
+        "\n"
+        '# author_name = "Your Name"\n'
+        '# author_email = "you@example.com"\n'
+        '# github_org = "your-org"\n'
+        '# default_template = "library"\n',
+        encoding="utf-8",
+    )
+    return target

create_forge/engine.py

@@ -0,0 +1,228 @@
+"""The single module that touches the `forge_template` engine.
+
+Mirrors `runner.py`'s role for Copier's Python API (invariant 4): the engine
+is imported in exactly one place, so it evolves without every module needing
+attention. Importing this module requires the `engine` extra
+(`uv sync --all-extras`, or `pip install 'create-forge[engine]'`) -- since
+[ADR 0018](../../docs/adr/0018-pypi-distribution-and-the-first-engine-range.md),
+`forge-template` is a real, PyPI-installable, range-bounded optional
+dependency rather than a `[tool.uv.sources]`-pinned development-only one. No
+module reachable from create-forge's shipped CLI entry point may import this
+module;
+`tests/test_engine_contract.py::test_shipped_cli_modules_do_not_import_the_engine`
+enforces that. `compat.py` holds the range and protocol constants this
+module checks against -- it is engine-free, so `cli.py`'s `doctor` command
+can report them without importing this module at all.
+
+`spec.py` builds the wire payload this module parses and validates, while this
+module also exposes the discovery adapter `pipeline.py` uses, reachable today
+via the hidden `new --engine-preview` flag -- see ADR 0013,
+docs/project-spec-construction.md, and docs/component-discovery.md for the
+full contracts.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from forge_template import (
+    ComponentDescriptor,
+    EngineInfo,
+    ProjectSpec,
+    RenderedProject,
+    get_engine_info,
+)
+
+# Explicit self-reexport: mypy strict's no_implicit_reexport otherwise blocks
+# `cli.py`'s lazy `except engine.ForgeEngineError` (a direct import of this
+# module, not merely an attribute chain) from typing against a name this
+# module only imported rather than defined.
+from forge_template import ForgeEngineError as ForgeEngineError  # noqa: PLC0414
+from forge_template import discover_components as _discover_components
+from forge_template import map_legacy_library_answers as _map_legacy_library_answers
+from forge_template import parse_project_spec as _parse_project_spec
+from forge_template import render_project as _render_project
+from forge_template import validate_project_spec as _validate_project_spec
+from packaging.specifiers import SpecifierSet
+from packaging.version import Version
+
+from create_forge.compat import (
+    ENGINE_DISTRIBUTION,
+    SUPPORTED_COMPONENT_MANIFEST_PROTOCOLS,
+    SUPPORTED_ENGINE_RANGE,
+    SUPPORTED_PROJECTSPEC_PROTOCOLS,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+_SUPPORTED_ENGINE_SPECIFIER = SpecifierSet(SUPPORTED_ENGINE_RANGE)
+
+
+class EngineCompatibilityError(Exception):
+    """An installed engine is outside the supported package/protocol range.
+
+    Carries exit status `3`'s meaning (docs/cli-conventions.md), reserved by
+    ADR 0011 for exactly this failure class. Reachable today only via the
+    hidden `new --engine-preview` flag (ADR 0014); the default `new` path
+    still cannot produce it.
+    """
+
+
+def _require_supported_package(info: EngineInfo) -> None:
+    """Reject an engine package outside the declared, released range."""
+    if Version(info.package_version) in _SUPPORTED_ENGINE_SPECIFIER:
+        return
+
+    msg = (
+        f"Detected forge-template {info.package_version}, but this "
+        f"create-forge release supports {ENGINE_DISTRIBUTION}"
+        f"{SUPPORTED_ENGINE_RANGE}. Run "
+        f"`pip install '{ENGINE_DISTRIBUTION}{SUPPORTED_ENGINE_RANGE}'` "
+        "(or the equivalent `uv add`/`uv sync` invocation) to install a "
+        "compatible version."
+    )
+    raise EngineCompatibilityError(msg)
+
+
+def _require_protocol_overlap(
+    info: EngineInfo,
+    *,
+    protocol_name: str,
+    supported: tuple[int, ...],
+    detected: tuple[int, ...],
+) -> None:
+    """Reject an engine with no protocol version in common with this CLI."""
+    supported_set = set(supported)
+    detected_set = set(detected)
+    if supported_set & detected_set:
+        return
+
+    msg = (
+        f"forge-template {info.package_version} supports {protocol_name} "
+        f"protocol(s) {sorted(detected_set)}, but this create-forge release "
+        f"supports {sorted(supported_set)}."
+    )
+    raise EngineCompatibilityError(msg)
+
+
+def _require_projectspec_protocol(info: EngineInfo) -> None:
+    """Require a shared ProjectSpec protocol for every engine operation."""
+    _require_protocol_overlap(
+        info,
+        protocol_name="ProjectSpec",
+        supported=SUPPORTED_PROJECTSPEC_PROTOCOLS,
+        detected=info.projectspec_protocols,
+    )
+
+
+def _require_component_manifest_protocol(info: EngineInfo) -> None:
+    """Require a shared component-manifest protocol before discovery."""
+    _require_protocol_overlap(
+        info,
+        protocol_name="component manifest",
+        supported=SUPPORTED_COMPONENT_MANIFEST_PROTOCOLS,
+        detected=info.component_manifest_protocols,
+    )
+
+
+def negotiate_protocol() -> None:
+    """Confirm the engine matches the supported package/ProjectSpec range.
+
+    Runs before any payload is parsed, validated, or rendered.
+    """
+    info = get_engine_info()
+    _require_supported_package(info)
+    _require_projectspec_protocol(info)
+
+
+def discover() -> tuple[ComponentDescriptor, ...]:
+    """Return engine-owned component descriptors after protocol negotiation.
+
+    ProjectSpec and component-manifest compatibility are checked before the
+    engine scans its installed catalogue. The descriptors are returned
+    unchanged: their identifiers, presentation metadata, compatibility,
+    relationships, and options remain owned and validated by `forge-template`.
+    """
+    info = get_engine_info()
+    _require_supported_package(info)
+    _require_projectspec_protocol(info)
+    _require_component_manifest_protocol(info)
+    return _discover_components()
+
+
+def build_project_spec(payload: Mapping[str, object]) -> ProjectSpec:
+    """Negotiate the protocol, then strictly parse a ProjectSpec payload.
+
+    Negotiation runs before `parse_project_spec` ever inspects `payload`,
+    satisfying #46's "negotiate the supported ProjectSpec protocol before any
+    side effect" criterion independent of what the payload itself contains.
+    """
+    negotiate_protocol()
+    return _parse_project_spec(payload)
+
+
+def validate(spec: ProjectSpec) -> ProjectSpec:
+    """Validate a parsed ProjectSpec against the installed component catalogue.
+
+    The installed `forge-template` catalogue is production: `library` and
+    `cli` are both real, validated archetypes.
+    """
+    info = get_engine_info()
+    _require_supported_package(info)
+    _require_projectspec_protocol(info)
+    _require_component_manifest_protocol(info)
+    return _validate_project_spec(spec)
+
+
+def render(spec: ProjectSpec) -> RenderedProject:
+    """Render one spec to immutable in-memory files after compatibility checks.
+
+    The public engine owns validation, composition, rendering, and
+    generated-project validation -- the `RenderedProject` returned here has
+    already passed `forge_template.validate_rendered_project`. This adapter
+    deliberately accepts no destination path and performs no filesystem
+    writes; `pipeline.finalise_generation_request` (ADR 0015) owns staging and
+    finalisation around the returned files.
+    """
+    info = get_engine_info()
+    _require_supported_package(info)
+    _require_projectspec_protocol(info)
+    _require_component_manifest_protocol(info)
+    return _render_project(spec)
+
+
+def map_legacy_library_options(
+    legacy_answers: Mapping[str, str],
+) -> Mapping[str, object]:
+    """Translate legacy Library answers into the `library` component option.
+
+    Thin wrapper around the public `map_legacy_library_answers` facade after
+    the same compatibility checks every other operation here runs, so this
+    stays the only module that touches the mapping's implementation. The
+    mapping itself -- `build_backend`/`versioning_resolved` to
+    `packaging_mode` -- is engine-owned; see
+    docs/library-archetype.md#legacy-copier-answer-mapping in forge-template.
+    `pipeline.build_generation_request` is the only caller, and only for the
+    `library` archetype (CF-08.02).
+    """
+    info = get_engine_info()
+    _require_supported_package(info)
+    _require_projectspec_protocol(info)
+    _require_component_manifest_protocol(info)
+    return _map_legacy_library_answers(legacy_answers)
+
+
+def explain(exc: ForgeEngineError) -> str:
+    """Translate a structured `ForgeEngineError` into terminal-ready text.
+
+    Mirrors `runner._explain()`'s job for Copier's freeform messages, but
+    from a structured source: `ForgeEngineError` already carries a stable
+    code and located details, so this formats them rather than pattern
+    matching on message text.
+    """
+    lines = [f"{exc.message} ({exc.code.value})"]
+    for detail in exc.details:
+        location = ".".join(str(part) for part in detail.path) or exc.operation
+        lines.append(f"  {location}: {detail.message}")
+    return "\n".join(lines)

create_forge/models.py

@@ -0,0 +1,142 @@
+"""Registry data models.
+
+The registry is bundled with the package, so adding a template means cutting a
+new CLI release. That is a deliberate MVP trade-off: no network call on start,
+no partial-failure states, and the registry is validated at build time by the
+test suite rather than at runtime by the user.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Annotated, Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl, model_validator
+
+
+class PromptKind(StrEnum):
+    """How a prompt is rendered."""
+
+    TEXT = "text"
+    SELECT = "select"
+    CONFIRM = "confirm"
+
+
+class Choice(BaseModel):
+    """One option in a select prompt."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    value: str
+    label: str
+    hint: str | None = None
+
+
+class PromptSpec(BaseModel):
+    """A question the CLI asks on behalf of a template.
+
+    This is UX metadata only. The authoritative declaration of every variable —
+    including its type, default and validation — lives in the template's own
+    `copier.yml`. Anything not listed here is left to the template default.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    key: Annotated[str, Field(pattern=r"^[a-z][a-z0-9_]*$")]
+    """Must match a question key in the template's copier.yml."""
+
+    kind: PromptKind
+    message: str
+    help: str | None = None
+    choices: list[Choice] = Field(default_factory=list)
+    default: str | bool | None = None
+    depends_on: dict[str, str] = Field(default_factory=dict)
+    """Only ask when these previously-answered keys hold these values."""
+
+    @model_validator(mode="after")
+    def _choices_match_kind(self) -> Self:
+        if self.kind is PromptKind.SELECT and not self.choices:
+            msg = f"prompt {self.key!r} is a select but declares no choices"
+            raise ValueError(msg)
+        if self.kind is not PromptKind.SELECT and self.choices:
+            msg = f"prompt {self.key!r} declares choices but is not a select"
+            raise ValueError(msg)
+        return self
+
+    def should_ask(self, answers: dict[str, object]) -> bool:
+        """Whether this prompt applies given what has been answered so far."""
+        return all(
+            str(answers.get(key)) == expected
+            for key, expected in self.depends_on.items()
+        )
+
+
+class Template(BaseModel):
+    """One archetype available to scaffold."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: Annotated[str, Field(pattern=r"^[a-z][a-z0-9-]*$")]
+    name: str
+    description: str
+    url: HttpUrl
+    status: Literal["stable", "preview", "deprecated"] = "stable"
+    deprecated_in_favour_of: str | None = None
+    prompts: list[PromptSpec] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _deprecation_has_successor(self) -> Self:
+        if self.status == "deprecated" and not self.deprecated_in_favour_of:
+            msg = f"template {self.id!r} is deprecated but names no successor"
+            raise ValueError(msg)
+        return self
+
+    @model_validator(mode="after")
+    def _prompt_keys_unique(self) -> Self:
+        keys = [p.key for p in self.prompts]
+        if len(keys) != len(set(keys)):
+            msg = f"template {self.id!r} has duplicate prompt keys"
+            raise ValueError(msg)
+        return self
+
+
+class Registry(BaseModel):
+    """The full set of templates this CLI release knows about."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    default_template: str
+    templates: list[Template]
+
+    @model_validator(mode="after")
+    def _default_exists_and_is_usable(self) -> Self:
+        match = next((t for t in self.templates if t.id == self.default_template), None)
+        if match is None:
+            msg = f"default_template {self.default_template!r} is not in the registry"
+            raise ValueError(msg)
+        if match.status == "deprecated":
+            msg = f"default_template {self.default_template!r} is deprecated"
+            raise ValueError(msg)
+        return self
+
+    @model_validator(mode="after")
+    def _ids_unique(self) -> Self:
+        ids = [t.id for t in self.templates]
+        if len(ids) != len(set(ids)):
+            msg = "duplicate template ids in registry"
+            raise ValueError(msg)
+        return self
+
+    def get(self, template_id: str) -> Template:
+        """Look up a template, raising a useful error when absent."""
+        for template in self.templates:
+            if template.id == template_id:
+                return template
+        available = ", ".join(sorted(t.id for t in self.templates))
+        msg = f"unknown template {template_id!r}. Available: {available}"
+        raise KeyError(msg)
+
+    @property
+    def selectable(self) -> list[Template]:
+        """Templates offered interactively (deprecated ones stay addressable)."""
+        return [t for t in self.templates if t.status != "deprecated"]

create_forge/pipeline.py

@@ -0,0 +1,141 @@
+"""The shared create pipeline: discover, build, validate, render -- in memory.
+
+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
+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
+*installed* when one of its functions is actually called. `engine.py` remains
+the only module whose source touches `forge_template` at runtime, per ADR
+0013 and invariant 4.
+
+`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.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from create_forge import engine, staging
+from create_forge.spec import build_spec_payload, legacy_library_answers
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from pathlib import Path
+
+    from forge_template import ComponentDescriptor, ProjectSpec, RenderedProject
+
+
+@dataclass(frozen=True, slots=True)
+class GenerationRequest:
+    """One in-memory result of the shared create pipeline.
+
+    Ready for CF-07.04 to stage and finalise. No filesystem write happens
+    here or in anything this wraps -- `engine.render()` is in-memory only.
+    """
+
+    spec: ProjectSpec
+    rendered: RenderedProject
+
+
+def discover_archetypes() -> tuple[ComponentDescriptor, ...]:
+    """Engine-owned archetype descriptors, for `--engine-preview` selection.
+
+    Filters `engine.discover()` to `kind == "archetype"` so `cli.py` never
+    branches on engine-defined `kind` values itself (CF-08.02) -- discovery
+    stays the one place that interprets descriptor shape.
+    """
+    return tuple(d for d in engine.discover() if d.kind == "archetype")
+
+
+def _resolved_component_options(
+    answers: Mapping[str, object],
+    archetype: str,
+    component_options: Mapping[str, Mapping[str, object]] | None,
+) -> 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.
+    """
+    if component_options is not None or archetype != "library":
+        return component_options
+    legacy = legacy_library_answers(answers)
+    if legacy is None:
+        return None
+    return {"library": engine.map_legacy_library_options(legacy)}
+
+
+def build_generation_request(
+    answers: Mapping[str, object],
+    *,
+    archetype: str,
+    capabilities: Sequence[str] = (),
+    platforms: Sequence[str] = (),
+    component_options: Mapping[str, Mapping[str, object]] | None = None,
+) -> GenerationRequest:
+    """Run the shared pipeline: discover -> build -> validate -> render.
+
+    Interactive and non-interactive `new` invocations both converge here once
+    they've collected the same `answers` mapping `cli._collect_answers`
+    already produces today -- nothing about answer collection changes.
+
+    `archetype`/`capabilities`/`platforms` stay caller-supplied (ADR 0013):
+    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`.
+
+    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()
+    resolved_options = _resolved_component_options(
+        answers, archetype, component_options
+    )
+    payload = build_spec_payload(
+        answers,
+        archetype=archetype,
+        capabilities=capabilities,
+        platforms=platforms,
+        component_options=resolved_options,
+    )
+    spec = engine.build_project_spec(payload)
+    validated = engine.validate(spec)
+    rendered = engine.render(validated)
+    return GenerationRequest(spec=validated, rendered=rendered)
+
+
+def finalise_generation_request(request: GenerationRequest, destination: Path) -> None:
+    """Stage and finalise `request`'s rendered files (ADR 0015).
+
+    Renders them into a directory adjacent to `destination`, then moves that
+    directory into place atomically.
+
+    `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.
+    """
+    with staging.staged(destination) as staging_dir:
+        staging.write_files(
+            staging_dir,
+            ((file.target, file.content) for file in request.rendered.files),
+        )