create-forge 0.2.0__py3-none-any.whl

create_forge/prompts.py

@@ -0,0 +1,231 @@
+"""Interactive prompt flow.
+
+Prompts are driven entirely by the registry, so surfacing a new question is a
+data change rather than a code change. Anything not prompted here falls through
+to the template's own default in copier.yml.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Protocol
+
+import questionary
+from questionary import Choice as QChoice
+
+from create_forge.models import PromptKind
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from create_forge.models import PromptSpec, Template
+
+
+class ArchetypeChoice(Protocol):
+    """The engine's `ComponentDescriptor` shape this module actually needs.
+
+    Structural, not imported: `prompts.py` is one of the shipped modules
+    `tests/test_engine_contract.py::test_shipped_cli_modules_do_not_import_the_engine`
+    guards, so it may not import `forge_template` even under
+    `TYPE_CHECKING`. `ComponentDescriptor` satisfies this without either
+    module knowing about the other (CF-08.02). Read-only properties, not
+    plain attributes: `ComponentDescriptor`'s fields are frozen, and a
+    read-write Protocol attribute would reject it as non-conforming.
+    """
+
+    @property
+    def id(self) -> str:
+        """The canonical component identifier."""
+        ...
+
+    @property
+    def name(self) -> str:
+        """The display name shown in the prompt."""
+        ...
+
+    @property
+    def description(self) -> str:
+        """The one-line description shown alongside the name."""
+        ...
+
+
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+_STYLE = questionary.Style(
+    [
+        ("qmark", "fg:#5f819d bold"),
+        ("question", "bold"),
+        ("answer", "fg:#85678f"),
+        ("pointer", "fg:#5f819d bold"),
+        ("highlighted", "fg:#5f819d bold"),
+        ("selected", "fg:#5f819d"),
+        ("instruction", "fg:#888888"),
+    ]
+)
+
+
+class PromptAbortedError(Exception):
+    """The user pressed Ctrl-C or Ctrl-D."""
+
+
+def slugify(value: str) -> str:
+    """Turn a project name into a repository-safe slug."""
+    return _SLUG_RE.sub("-", value.lower()).strip("-")
+
+
+def choose_template(templates: list[Template], default_id: str) -> Template:
+    """Ask which archetype to scaffold. Skipped when only one is selectable."""
+    if len(templates) == 1:
+        return templates[0]
+
+    choices = [
+        QChoice(
+            title=f"{t.name}  —  {t.description}"
+            + ("  [preview]" if t.status == "preview" else ""),
+            value=t,
+        )
+        for t in templates
+    ]
+    default = next(
+        (c for c in choices if c.value is not None and c.value.id == default_id),
+        None,
+    )
+
+    answer: Template | None = questionary.select(
+        "What are you building?",
+        choices=choices,
+        default=default,
+        style=_STYLE,
+    ).ask()
+
+    if answer is None:
+        raise PromptAbortedError
+    return answer
+
+
+def choose_archetype(archetypes: Sequence[ArchetypeChoice]) -> ArchetypeChoice:
+    """Ask which engine archetype to build. Skipped when only one exists.
+
+    Mirrors `choose_template`'s shape for the engine-preview path (CF-08.02):
+    same skip-when-one behaviour, same `PromptAbortedError` on cancel.
+    `archetypes` is expected to be non-empty -- callers resolve an empty
+    catalogue as a compatibility failure before reaching here.
+    """
+    if len(archetypes) == 1:
+        return archetypes[0]
+
+    choices = [
+        QChoice(title=f"{a.name}  —  {a.description}", value=a) for a in archetypes
+    ]
+
+    answer: ArchetypeChoice | None = questionary.select(
+        "What are you building?",
+        choices=choices,
+        style=_STYLE,
+    ).ask()
+
+    if answer is None:
+        raise PromptAbortedError
+    return answer
+
+
+def ask_all(
+    template: Template,
+    *,
+    preset: dict[str, object] | None = None,
+    defaults: dict[str, object] | None = None,
+) -> dict[str, object]:
+    """Run every applicable prompt, returning the collected answers.
+
+    `preset` holds values supplied on the command line. Preset keys are not
+    re-asked, which is what makes `--data` usable alongside interactive mode.
+
+    `defaults` (e.g. from user config) pre-fills a prompt's answer without
+    suppressing it -- unlike `preset`, the question is still asked.
+    """
+    answers: dict[str, object] = dict(preset or {})
+
+    for spec in template.prompts:
+        if spec.key in answers:
+            continue
+        if not spec.should_ask(answers):
+            continue
+
+        value = _ask_one(spec, answers, defaults or {})
+        if value is None:
+            raise PromptAbortedError
+        answers[spec.key] = value
+
+    return answers
+
+
+def _ask_one(
+    spec: PromptSpec, answers: dict[str, object], defaults: dict[str, object]
+) -> object | None:
+    """Render a single prompt."""
+    default = _resolve_default(spec, answers, defaults)
+
+    match spec.kind:
+        case PromptKind.CONFIRM:
+            confirmed: bool | None = questionary.confirm(
+                spec.message,
+                default=bool(default),
+                style=_STYLE,
+            ).ask()
+            return confirmed
+
+        case PromptKind.SELECT:
+            choices = [
+                QChoice(
+                    title=c.label + (f"  ({c.hint})" if c.hint else ""),
+                    value=c.value,
+                )
+                for c in spec.choices
+            ]
+            chosen_default = next(
+                (c for c in choices if c.value == default), choices[0]
+            )
+            selected: str | None = questionary.select(
+                spec.message,
+                choices=choices,
+                default=chosen_default,
+                instruction=spec.help,
+                style=_STYLE,
+            ).ask()
+            return selected
+
+        case _:
+            text: str | None = questionary.text(
+                spec.message,
+                default=str(default or ""),
+                instruction=spec.help,
+                validate=_required_if(spec),
+                style=_STYLE,
+            ).ask()
+            return text
+
+
+def _resolve_default(
+    spec: PromptSpec, answers: dict[str, object], defaults: dict[str, object]
+) -> object | None:
+    """Derive a default from earlier answers, then config, then the template."""
+    if spec.key == "repo_name" and "project_name" in answers:
+        return slugify(str(answers["project_name"]))
+    if spec.key in defaults:
+        return defaults[spec.key]
+    return spec.default
+
+
+def _required_if(spec: PromptSpec) -> object:
+    """Reject empty input for keys the template cannot default."""
+    if spec.key != "project_name":
+        return lambda _: True
+
+    def _validate(text: str) -> bool | str:
+        if not text.strip():
+            return "Project name is required"
+        if not slugify(text):
+            return "Project name must contain letters or digits"
+        return True
+
+    return _validate

create_forge/registry.py

@@ -0,0 +1,36 @@
+"""Loads the bundled template registry.
+
+The registry is package data, not user configuration. It is read once, validated
+by Pydantic, and cached for the process lifetime. A malformed registry is a
+packaging bug, not a user error, so the failure is loud and unhandled.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from functools import cache
+from importlib import resources
+
+from pydantic import ValidationError
+
+from create_forge.models import Registry
+
+_REGISTRY_FILE = "templates.toml"
+
+
+@cache
+def load_registry() -> Registry:
+    """Read and validate the bundled registry."""
+    raw = resources.files("create_forge").joinpath(_REGISTRY_FILE).read_text("utf-8")
+
+    try:
+        data = tomllib.loads(raw)
+    except tomllib.TOMLDecodeError as exc:  # pragma: no cover - packaging bug
+        msg = f"Bundled {_REGISTRY_FILE} is not valid TOML: {exc}"
+        raise RuntimeError(msg) from exc
+
+    try:
+        return Registry.model_validate(data)
+    except ValidationError as exc:  # pragma: no cover - packaging bug
+        msg = f"Bundled {_REGISTRY_FILE} failed validation:\n{exc}"
+        raise RuntimeError(msg) from exc

create_forge/runner.py

@@ -0,0 +1,148 @@
+"""Thin wrapper over Copier's Python API.
+
+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.4,<10`) and this file is the only thing that needs
+attention on a major bump.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from copier import run_copy, run_update
+from copier.errors import CopierError
+
+from create_forge import staging
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+class ScaffoldError(Exception):
+    """A failure the user can act on, already phrased for display."""
+
+
+@dataclass(frozen=True, slots=True)
+class ScaffoldRequest:
+    """Everything needed to render a template."""
+
+    src: str
+    dst: Path
+    data: Mapping[str, object]
+    vcs_ref: str | None = None
+    """None means Copier resolves the latest PEP440 tag."""
+
+    dry_run: bool = False
+
+
+def scaffold(request: ScaffoldRequest) -> None:
+    """Render a template into a new directory.
+
+    `unsafe=True` is the API equivalent of `--trust` and is required because the
+    templates declare `_tasks`. This is a deliberate decision: the registry only
+    ever points at first-party repositories, so the code being trusted is code
+    the same team publishes. Never widen the registry to arbitrary URLs without
+    revisiting this.
+    """
+    try:
+        staging.ensure_available(request.dst)
+    except staging.DestinationConflictError as exc:
+        raise ScaffoldError(str(exc)) from exc
+
+    # Copier cannot be staged and moved into place the way the engine path
+    # is (ADR 0015): its templates declare `_tasks` that run `uv sync` and
+    # `pre-commit install`, baking dst's absolute path into `.venv/pyvenv.cfg`,
+    # console-script shims, and `.git/hooks/pre-commit`. Renaming a completed
+    # output afterward would silently break all three. So this only cleans up
+    # a failure at the path Copier already wrote to -- it never stages.
+    with staging.discard_on_failure(request.dst):
+        try:
+            run_copy(
+                src_path=request.src,
+                dst_path=request.dst,
+                data=dict(request.data),
+                vcs_ref=request.vcs_ref,
+                # Anything not answered by the CLI falls back to the
+                # template's own default, so copier.yml stays the source of
+                # truth.
+                defaults=True,
+                unsafe=True,
+                quiet=True,
+                pretend=request.dry_run,
+            )
+        except CopierError as exc:
+            raise ScaffoldError(_explain(exc)) from exc
+
+
+def update(project: Path, *, vcs_ref: str | None = None) -> None:
+    """Pull template changes into an existing project."""
+    answers = project / ".copier-answers.yml"
+    if not answers.is_file():
+        msg = (
+            f"No .copier-answers.yml in {project}. This project was not created "
+            "by forge, or the answers file was deleted."
+        )
+        raise ScaffoldError(msg)
+
+    try:
+        run_update(
+            dst_path=project,
+            vcs_ref=vcs_ref,
+            defaults=True,
+            unsafe=True,
+            quiet=True,
+            # Only ask about questions that did not exist last time.
+            skip_answered=True,
+            conflict="inline",
+            # Copier refuses to update without this. It is not the safety
+            # relaxation it looks like: `update` already requires the
+            # destination to be a clean git repo (checked above and by
+            # Copier itself), so the user reviews a diff before committing
+            # regardless. Copier's own CLI hardcodes this for `update` too.
+            overwrite=True,
+        )
+    except CopierError as exc:
+        raise ScaffoldError(_explain(exc)) from exc
+
+
+def _explain(exc: CopierError) -> str:
+    """Translate Copier's internal errors into something actionable.
+
+    Copier's messages assume familiarity with its model. Most users of this CLI
+    will not have any, so the common failures get rewritten.
+    """
+    text = str(exc)
+    lowered = text.lower()
+
+    if "dirty" in lowered or "uncommitted" in lowered:
+        return (
+            "The project has uncommitted changes. Copier needs a clean working "
+            "tree to merge template updates.\n"
+            "  Commit or stash first: git stash"
+        )
+    if "only supported in git-tracked subprojects" in lowered:
+        return (
+            "This project is not tracked by git. `update` needs it to be, so "
+            "you can review the merge before committing.\n"
+            "  Run: git init && git add -A && git commit -m 'initial'"
+        )
+    if "version from last update not detected" in lowered:
+        return (
+            "The version recorded in .copier-answers.yml isn't a released "
+            "template version, so there is nothing to update from.\n"
+            "  Check this project was created by create-forge, not hand-edited."
+        )
+    if "no valid version" in lowered or ("ref" in lowered and "not found" in lowered):
+        return (
+            "The template has no released version to use.\n"
+            "  The template repository needs a PEP440 git tag, e.g. v0.1.0"
+        )
+    if "authentication" in lowered or "permission denied" in lowered:
+        return (
+            "Could not access the template repository.\n"
+            "  Check you have read access and that your git credentials are set up."
+        )
+    return text

create_forge/spec.py

@@ -0,0 +1,192 @@
+"""Pure ProjectSpec wire-payload construction.
+
+This module places CLI answers into their canonical ProjectSpec position and
+omits values that are absent. It performs no validation and imports nothing
+from `forge_template` -- `engine.py` is the only module in this package that
+touches the engine, matching invariant 4's rule for `runner.py` and Copier.
+`spec.py` must stay importable and testable without the engine dependency
+installed.
+
+The one exception to "map, don't validate" is derivation: ProjectSpec's
+`package_name` and `repository_name` are wire-required fields the engine
+never derives, so create-forge derives them from `project_name` unless a
+`--data` override supplies the matching Copier-style key (`package_name`,
+`repo_name`). See docs/project-spec-construction.md for the full field
+mapping and its rationale.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from create_forge.prompts import slugify
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+PROJECT_SPEC_PROTOCOL_VERSION = 1
+"""Mirrors `forge_template.PROJECT_SPEC_PROTOCOL_VERSION` without importing
+the engine, since this module must stay importable without it installed.
+"""
+
+DEFAULT_PYTHON_MINIMUM = "3.11"
+DEFAULT_PYTHON_DEVELOPMENT = "3.13"
+"""Fallback `python` bounds, mirroring `copier.yml`'s own
+`python_min_version`/`python_version` defaults (CF-08.02).
+
+`ProjectSpec.python` is a required field, but `templates.toml` never prompts
+either key -- they're on the deliberately-unasked list in this file's
+sibling `templates.toml` header, same as every other question the Copier
+path lets fall through to its own default. The engine path has no template
+default to fall through to, so create-forge supplies the same values itself
+here rather than leaving `--engine-preview` unusable without `--data`.
+"""
+
+_PACKAGE_NAME_RE = re.compile(r"[^a-z0-9]+")
+
+
+def _derive_package_name(project_name: str) -> str:
+    """Lower-case, collapse non-alphanumeric runs to one underscore, trim ends.
+
+    Deliberately not copier.yml's exact
+    `{{ project_name | lower | replace(' ', '_') | replace('-', '_') }}` --
+    ProjectSpec's `package_name` pattern (`^[a-z][a-z0-9_]*$`) is stricter
+    than Copier's own default, and the two systems are allowed to diverge;
+    the engine, not this derivation, is authoritative for validity.
+    """
+    return _PACKAGE_NAME_RE.sub("_", project_name.strip().lower()).strip("_")
+
+
+def _string_answer(answers: Mapping[str, object], key: str) -> str | None:
+    """A non-blank string answer, or None if absent/blank."""
+    value = answers.get(key)
+    return value if isinstance(value, str) and value.strip() else None
+
+
+def _authors(answers: Mapping[str, object]) -> list[dict[str, object]]:
+    """Zero or one author -- today's registry collects at most one."""
+    name = _string_answer(answers, "author_name")
+    if name is None:
+        return []
+    author: dict[str, object] = {"name": name}
+    email = _string_answer(answers, "author_email")
+    if email is not None:
+        author["email"] = email
+    return [author]
+
+
+def _project_metadata(answers: Mapping[str, object]) -> dict[str, object]:
+    """Build the `project` sub-object, omitting fields with no source value.
+
+    A missing required field (`name`, `licence`, ...) is left out rather than
+    defaulted -- `engine.build_project_spec` reports it as a structured,
+    field-located validation error instead of this module guessing.
+    """
+    metadata: dict[str, object] = {}
+
+    project_name = _string_answer(answers, "project_name")
+    if project_name is not None:
+        metadata["name"] = project_name
+
+    package_name = _string_answer(answers, "package_name")
+    if package_name is None and project_name is not None:
+        package_name = _derive_package_name(project_name)
+    if package_name is not None:
+        metadata["package_name"] = package_name
+
+    repository_name = _string_answer(answers, "repo_name")
+    if repository_name is None and project_name is not None:
+        repository_name = slugify(project_name)
+    if repository_name is not None:
+        metadata["repository_name"] = repository_name
+
+    description = answers.get("project_description")
+    if isinstance(description, str):
+        metadata["description"] = description
+
+    licence = _string_answer(answers, "license")
+    if licence is not None:
+        metadata["licence"] = licence
+
+    authors = _authors(answers)
+    if authors:
+        metadata["authors"] = authors
+
+    return metadata
+
+
+def _python_selection(answers: Mapping[str, object]) -> dict[str, object]:
+    """Resolve both `python` bounds, falling back per-bound to the defaults.
+
+    `ProjectSpec.python` is required, so unlike `_project_metadata`'s
+    omit-if-absent fields, this always returns a value -- an explicit answer
+    for one bound does not require the other, it just leaves the missing one
+    at its own default (CF-08.02).
+    """
+    minimum = _string_answer(answers, "python_min_version") or DEFAULT_PYTHON_MINIMUM
+    development = (
+        _string_answer(answers, "python_version") or DEFAULT_PYTHON_DEVELOPMENT
+    )
+    return {"minimum": minimum, "development": development}
+
+
+def legacy_library_answers(answers: Mapping[str, object]) -> dict[str, str] | None:
+    """Resolve the legacy Library answer pair for `map_legacy_library_options`.
+
+    Returns `None` if `build_backend` was never answered. Mirrors
+    `copier.yml`'s own `versioning_resolved` computation: `static`
+    when `build_backend` is `uv_build`, else whatever `versioning` says,
+    defaulting to `static` when that question was skipped (CF-08.02). This
+    stays pure and engine-free -- `engine.map_legacy_library_options` is the
+    only caller that hands the result to `forge_template`.
+    """
+    build_backend = _string_answer(answers, "build_backend")
+    if build_backend is None:
+        return None
+    versioning = _string_answer(answers, "versioning") or "static"
+    versioning_resolved = "static" if build_backend == "uv_build" else versioning
+    return {
+        "build_backend": build_backend,
+        "versioning_resolved": versioning_resolved,
+    }
+
+
+def build_spec_payload(
+    answers: Mapping[str, object],
+    *,
+    archetype: str,
+    capabilities: Sequence[str] = (),
+    platforms: Sequence[str] = (),
+    component_options: Mapping[str, Mapping[str, object]] | None = None,
+) -> dict[str, object]:
+    """Build a ProjectSpec wire payload from collected CLI answers.
+
+    `archetype`/`capabilities`/`platforms`/`component_options` are always
+    caller-supplied: create-forge mints no component identifiers of its own
+    (ADR 0013). Until CF-06.02 supplies them from `discover_components`,
+    callers are responsible for passing values a real manifest will accept.
+
+    The same `answers` mapping produces the same payload regardless of
+    whether it was collected interactively or via `--data`/config, since both
+    paths already converge on one `dict[str, object]` before this function
+    runs (see `cli._collect_answers`).
+    """
+    payload: dict[str, object] = {
+        "protocol_version": PROJECT_SPEC_PROTOCOL_VERSION,
+        "project": _project_metadata(answers),
+        "python": _python_selection(answers),
+        "components": {
+            "archetype": archetype,
+            "capabilities": list(capabilities),
+            "platforms": list(platforms),
+        },
+    }
+
+    if component_options:
+        payload["component_options"] = {
+            component_id: dict(options)
+            for component_id, options in component_options.items()
+        }
+
+    return payload