forgepy-cli 1.0.0__py3-none-any.whl

components/component_registry.py

@@ -0,0 +1,74 @@
+"""In-memory registration for component definitions."""
+
+from components.base_component import BaseComponent
+from components.component_manifest import ComponentManifest
+from components.component_metadata import ComponentMetadata
+from components.github_actions_component import GitHubActionsComponent
+from components.pytest_component import PytestComponent
+from components.ruff_component import RuffComponent
+
+
+class ComponentRegistry:
+    """Validate and store explicitly registered components."""
+
+    def __init__(self) -> None:
+        self._components: dict[str, BaseComponent] = {}
+        self.register(PytestComponent())
+        self.register(RuffComponent())
+        self.register(GitHubActionsComponent())
+
+    def register(self, component: BaseComponent) -> None:
+        """Register one component under its validated metadata name."""
+
+        if not isinstance(component, BaseComponent):
+            raise TypeError("Component must inherit from BaseComponent.")
+
+        component_name = component.name
+
+        if not isinstance(component_name, str):
+            raise TypeError("Component name must be a string.")
+
+        if not component_name.strip():
+            raise ValueError("Component name must not be empty.")
+
+        metadata = component.metadata
+
+        if not isinstance(metadata, ComponentMetadata):
+            raise TypeError(
+                "Component metadata must be ComponentMetadata."
+            )
+
+        if component_name != metadata.name:
+            raise ValueError(
+                "Component name and metadata name must match."
+            )
+
+        manifest = component.manifest
+
+        if not isinstance(manifest, ComponentManifest):
+            raise TypeError(
+                "Component manifest must be ComponentManifest."
+            )
+
+        if component_name in manifest.dependencies:
+            raise ValueError("A component must not depend on itself.")
+
+        if component_name in manifest.conflicts:
+            raise ValueError("A component must not conflict with itself.")
+
+        if component_name in self._components:
+            raise ValueError(
+                f"Component '{component_name}' is already registered."
+            )
+
+        self._components[component_name] = component
+
+    def get(self, name: str) -> BaseComponent:
+        """Return the component registered under ``name``."""
+
+        return self._components[name]
+
+    def list_components(self) -> tuple[BaseComponent, ...]:
+        """Return registered components in registration order."""
+
+        return tuple(self._components.values())

components/component_state.py

@@ -0,0 +1,243 @@
+"""Project-local persistence for installed ForgePy component names."""
+
+import json
+import os
+import tempfile
+from collections.abc import Iterable, Mapping
+from json import JSONDecodeError
+from pathlib import Path
+
+from components.component_context import ComponentContext
+
+
+STATE_DIRECTORY_NAME = ".forgepy"
+STATE_FILENAME = "components.json"
+INSTALLED_KEY = "installed"
+
+
+class ForgePyComponentStateError(Exception):
+    """Base error for project-local component state operations."""
+
+
+class ComponentStateFormatError(ForgePyComponentStateError):
+    """Raised when persisted component state has an invalid format."""
+
+
+class ComponentStateIOError(ForgePyComponentStateError):
+    """Raised when component state cannot be read or written."""
+
+
+class ComponentStateStore:
+    """Load and persist installed component names under one project."""
+
+    def __init__(self, project_path: Path) -> None:
+        context = ComponentContext(project_path=project_path)
+        self.project_path = context.project_path
+        self.state_directory = self.project_path / STATE_DIRECTORY_NAME
+        self.state_path = self.state_directory / STATE_FILENAME
+
+    def load(self) -> frozenset[str]:
+        """Return installed names, or an empty set when state is absent."""
+
+        _, state_path = self._resolve_state_paths()
+
+        try:
+            content = state_path.read_text(encoding="utf-8")
+            data = json.loads(content)
+        except FileNotFoundError:
+            return frozenset()
+        except UnicodeDecodeError as error:
+            raise ComponentStateFormatError(
+                "ForgePy component state is not valid UTF-8 at "
+                f"'{self.state_path}'."
+            ) from error
+        except JSONDecodeError as error:
+            raise ComponentStateFormatError(
+                "ForgePy component state contains malformed JSON at "
+                f"'{self.state_path}' "
+                f"(line {error.lineno}, column {error.colno})."
+            ) from error
+        except OSError as error:
+            raise ComponentStateIOError(
+                "ForgePy could not read component state from "
+                f"'{self.state_path}': {error}"
+            ) from error
+
+        return self._normalize_document(data)
+
+    def save(self, installed_components: Iterable[str]) -> frozenset[str]:
+        """Validate and atomically persist installed component names."""
+
+        self.load()
+        installed = self._normalize_names(installed_components)
+        document = {INSTALLED_KEY: sorted(installed)}
+        serialized = json.dumps(
+            document,
+            indent=4,
+            ensure_ascii=False,
+        ) + "\n"
+
+        try:
+            self.state_directory.mkdir(parents=True, exist_ok=True)
+            state_directory, state_path = self._resolve_state_paths()
+            temporary_path: Path | None = None
+
+            try:
+                with tempfile.NamedTemporaryFile(
+                    mode="w",
+                    encoding="utf-8",
+                    newline="\n",
+                    dir=state_directory,
+                    prefix=f".{STATE_FILENAME}.",
+                    suffix=".tmp",
+                    delete=False,
+                ) as temporary_file:
+                    temporary_path = Path(temporary_file.name)
+                    resolved_temporary_path = temporary_path.resolve()
+                    self._require_confined(
+                        resolved_temporary_path,
+                        state_directory,
+                        "temporary component-state file",
+                    )
+                    temporary_file.write(serialized)
+                    temporary_file.flush()
+                    os.fsync(temporary_file.fileno())
+
+                temporary_path.replace(state_path)
+            finally:
+                if temporary_path is not None and temporary_path.exists():
+                    temporary_path.unlink()
+        except OSError as error:
+            raise ComponentStateIOError(
+                "ForgePy could not save component state to "
+                f"'{self.state_path}': {error}"
+            ) from error
+
+        return installed
+
+    def add(self, component_name: str) -> frozenset[str]:
+        """Add one installed name while preserving existing state."""
+
+        name = self._normalize_names((component_name,))
+        installed = self.load().union(name)
+        return self.save(installed)
+
+    def is_installed(self, component_name: str) -> bool:
+        """Return whether one valid component name is installed."""
+
+        name = next(iter(self._normalize_names((component_name,))))
+        return name in self.load()
+
+    def _resolve_state_paths(self) -> tuple[Path, Path]:
+        """Return state paths only when they remain inside the project."""
+
+        if self.state_directory.exists() and not self.state_directory.is_dir():
+            raise ComponentStateIOError(
+                "ForgePy component-state directory must be a directory: "
+                f"'{self.state_directory}'."
+            )
+
+        try:
+            project_root = self.project_path.resolve()
+            state_directory = self.state_directory.resolve(strict=False)
+            state_path = self.state_path.resolve(strict=False)
+        except (OSError, RuntimeError) as error:
+            raise ComponentStateIOError(
+                "ForgePy could not resolve component state paths below "
+                f"'{self.project_path}': {error}"
+            ) from error
+
+        self._require_confined(
+            state_directory,
+            project_root,
+            "component-state directory",
+        )
+        self._require_confined(
+            state_path,
+            state_directory,
+            "component-state file",
+        )
+
+        if state_path.parent != state_directory:
+            raise ComponentStateIOError(
+                "ForgePy component-state file must resolve directly below "
+                f"the state directory: '{state_path}'."
+            )
+
+        return state_directory, state_path
+
+    @staticmethod
+    def _require_confined(
+        path: Path,
+        parent: Path,
+        path_label: str,
+    ) -> None:
+        try:
+            path.relative_to(parent)
+        except ValueError as error:
+            raise ComponentStateIOError(
+                f"ForgePy {path_label} resolves outside its required "
+                f"location: '{path}'."
+            ) from error
+
+        if path == parent:
+            raise ComponentStateIOError(
+                f"ForgePy {path_label} must be below its required location: "
+                f"'{path}'."
+            )
+
+    @classmethod
+    def _normalize_document(cls, data: object) -> frozenset[str]:
+        if not isinstance(data, Mapping):
+            raise ComponentStateFormatError(
+                "ForgePy component state must contain a JSON object."
+            )
+
+        if set(data) != {INSTALLED_KEY}:
+            raise ComponentStateFormatError(
+                "ForgePy component state must contain only an "
+                f"'{INSTALLED_KEY}' field."
+            )
+
+        installed = data[INSTALLED_KEY]
+
+        if not isinstance(installed, list):
+            raise ComponentStateFormatError(
+                "ForgePy component state 'installed' field must be a list."
+            )
+
+        try:
+            return cls._normalize_names(installed)
+        except (TypeError, ValueError) as error:
+            raise ComponentStateFormatError(
+                "ForgePy component state contains an invalid installed "
+                f"component: {error}"
+            ) from error
+
+    @staticmethod
+    def _normalize_names(
+        installed_components: Iterable[str],
+    ) -> frozenset[str]:
+        if isinstance(installed_components, (str, bytes)):
+            raise TypeError(
+                "Installed components must be an iterable of strings."
+            )
+
+        try:
+            installed = tuple(installed_components)
+        except TypeError as error:
+            raise TypeError(
+                "Installed components must be an iterable of strings."
+            ) from error
+
+        for name in installed:
+            if not isinstance(name, str):
+                raise TypeError(
+                    "Installed components must contain only strings."
+                )
+            if not name.strip():
+                raise ValueError(
+                    "Installed component names must not be empty."
+                )
+
+        return frozenset(installed)

components/component_validation.py

@@ -0,0 +1,88 @@
+"""Stateless pre-install validation for component relationships."""
+
+from collections.abc import Iterable
+
+from components.base_component import BaseComponent
+
+
+class ComponentValidationError(ValueError):
+    """Report unsatisfied direct relationships for one component."""
+
+    def __init__(
+        self,
+        component_name: str,
+        missing_dependencies: tuple[str, ...] = (),
+        active_conflicts: tuple[str, ...] = (),
+    ) -> None:
+        self.component_name = component_name
+        self.missing_dependencies = missing_dependencies
+        self.active_conflicts = active_conflicts
+
+        failures: list[str] = []
+
+        if missing_dependencies:
+            failures.append(
+                "missing dependencies: "
+                f"{', '.join(missing_dependencies)}"
+            )
+
+        if active_conflicts:
+            failures.append(
+                "active conflicts: "
+                f"{', '.join(active_conflicts)}"
+            )
+
+        super().__init__(
+            f"Component '{component_name}' cannot be installed; "
+            f"{'; '.join(failures)}."
+        )
+
+
+def validate_component(
+    component: BaseComponent,
+    installed_components: Iterable[str],
+) -> None:
+    """Validate direct dependencies and conflicts against explicit state."""
+
+    installed = _installed_component_names(installed_components)
+    manifest = component.manifest
+    missing_dependencies = tuple(
+        name
+        for name in manifest.dependencies
+        if name not in installed
+    )
+    active_conflicts = tuple(
+        name
+        for name in manifest.conflicts
+        if name in installed
+    )
+
+    if missing_dependencies or active_conflicts:
+        raise ComponentValidationError(
+            component_name=component.name,
+            missing_dependencies=missing_dependencies,
+            active_conflicts=active_conflicts,
+        )
+
+
+def _installed_component_names(
+    installed_components: Iterable[str],
+) -> frozenset[str]:
+    if isinstance(installed_components, (str, bytes)):
+        raise TypeError(
+            "Installed components must be an iterable of strings."
+        )
+
+    try:
+        installed = tuple(installed_components)
+    except TypeError as error:
+        raise TypeError(
+            "Installed components must be an iterable of strings."
+        ) from error
+
+    if not all(isinstance(name, str) for name in installed):
+        raise TypeError(
+            "Installed components must contain only strings."
+        )
+
+    return frozenset(installed)

components/github_actions_component.py

@@ -0,0 +1,75 @@
+"""Built-in GitHub Actions CI component."""
+
+from pathlib import Path
+
+from components.base_component import BaseComponent
+from components.component_context import ComponentContext
+from components.component_manifest import ComponentManifest
+from components.component_metadata import ComponentMetadata
+
+
+class GitHubActionsComponent(BaseComponent):
+    """Add a minimal Python CI workflow to an existing project."""
+
+    _METADATA = ComponentMetadata(
+        name="github-actions",
+        description="GitHub Actions CI for an existing Python project.",
+        version="0.1.0",
+        author="ForgePy",
+        tags=("ci", "github-actions", "python"),
+    )
+    _MANIFEST = ComponentManifest(
+        files=(Path(".github/workflows/ci.yml"),),
+    )
+    _WORKFLOW = (
+        "name: CI\n"
+        "\n"
+        "on:\n"
+        "  push:\n"
+        "  pull_request:\n"
+        "\n"
+        "jobs:\n"
+        "  test:\n"
+        "    runs-on: ubuntu-latest\n"
+        "    steps:\n"
+        "      - uses: actions/checkout@v4\n"
+        "      - uses: actions/setup-python@v5\n"
+        "        with:\n"
+        '          python-version: "3.12"\n'
+        "      - name: Install CI tools\n"
+        "        run: python -m pip install pytest ruff\n"
+        "      - name: Run Ruff\n"
+        "        run: ruff check .\n"
+        "      - name: Run pytest\n"
+        "        run: pytest\n"
+    )
+
+    @property
+    def name(self) -> str:
+        return self._METADATA.name
+
+    @property
+    def metadata(self) -> ComponentMetadata:
+        return self._METADATA
+
+    @property
+    def manifest(self) -> ComponentManifest:
+        return self._MANIFEST
+
+    def install(self, context: ComponentContext) -> None:
+        target_path = context.project_path / self._MANIFEST.files[0]
+        project_root = context.project_path.resolve()
+        resolved_target = target_path.resolve(strict=False)
+
+        try:
+            resolved_target.relative_to(project_root)
+        except ValueError as error:
+            raise OSError(
+                "GitHub Actions workflow target resolves outside the "
+                f"project: '{resolved_target}'."
+            ) from error
+
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with target_path.open("x", encoding="utf-8", newline="\n") as file:
+            file.write(self._WORKFLOW)

components/pytest_component.py

@@ -0,0 +1,40 @@
+"""Built-in pytest project-support component."""
+
+from pathlib import Path
+
+from components.base_component import BaseComponent
+from components.component_context import ComponentContext
+from components.component_manifest import ComponentManifest
+from components.component_metadata import ComponentMetadata
+
+
+class PytestComponent(BaseComponent):
+    """Add an isolated pytest configuration to an existing project."""
+
+    _METADATA = ComponentMetadata(
+        name="pytest",
+        description="Pytest configuration for an existing Python project.",
+        version="0.1.0",
+        author="ForgePy",
+        tags=("testing", "pytest"),
+    )
+    _MANIFEST = ComponentManifest(files=(Path("pytest.ini"),))
+    _CONFIGURATION = "[pytest]\ntestpaths = tests\n"
+
+    @property
+    def name(self) -> str:
+        return self._METADATA.name
+
+    @property
+    def metadata(self) -> ComponentMetadata:
+        return self._METADATA
+
+    @property
+    def manifest(self) -> ComponentManifest:
+        return self._MANIFEST
+
+    def install(self, context: ComponentContext) -> None:
+        target_path = context.project_path / self._MANIFEST.files[0]
+
+        with target_path.open("x", encoding="utf-8", newline="\n") as file:
+            file.write(self._CONFIGURATION)

components/ruff_component.py

@@ -0,0 +1,40 @@
+"""Built-in Ruff project-support component."""
+
+from pathlib import Path
+
+from components.base_component import BaseComponent
+from components.component_context import ComponentContext
+from components.component_manifest import ComponentManifest
+from components.component_metadata import ComponentMetadata
+
+
+class RuffComponent(BaseComponent):
+    """Add an isolated Ruff configuration to an existing project."""
+
+    _METADATA = ComponentMetadata(
+        name="ruff",
+        description="Ruff configuration for an existing Python project.",
+        version="0.1.0",
+        author="ForgePy",
+        tags=("linting", "ruff"),
+    )
+    _MANIFEST = ComponentManifest(files=(Path("ruff.toml"),))
+    _CONFIGURATION = 'line-length = 88\ntarget-version = "py312"\n'
+
+    @property
+    def name(self) -> str:
+        return self._METADATA.name
+
+    @property
+    def metadata(self) -> ComponentMetadata:
+        return self._METADATA
+
+    @property
+    def manifest(self) -> ComponentManifest:
+        return self._MANIFEST
+
+    def install(self, context: ComponentContext) -> None:
+        target_path = context.project_path / self._MANIFEST.files[0]
+
+        with target_path.open("x", encoding="utf-8", newline="\n") as file:
+            file.write(self._CONFIGURATION)

config/default_structure.py

@@ -0,0 +1,18 @@
+DEFAULT_FOLDERS = [
+    "assets",
+    "config",
+    "database",
+    "models",
+    "services",
+    "ui",
+    "tests",
+    "logs",
+    "exports",
+]
+
+DEFAULT_FILES = [
+    "README.md",
+    ".gitignore",
+    "requirements.txt",
+    "app.py",
+]