The Module Architecture¶

class BootstrapModule(abc.ABC):
    """Appends module-specific requirements to the environment manifest."""

    cli_flags: ClassVar[tuple[str, ...]] = ()
    """The CLI flags to trigger this module (e.g., ('-p', '--python'))."""

    cli_help: ClassVar[str] = ""
    """The help description for the CLI flag."""

    config_key: ClassVar[str] = ""
    """The global configuration key used to evaluate if this module is active."""

    @property
    @abc.abstractmethod
    def name(self) -> str:
        """Returns the human-readable identifier for the module."""
        pass

    @property
    def aliases(self) -> list[str]:
        """Returns a list of configuration aliases that map to this module.

        Used for dynamic resolution from the global configuration file.
        """
        return []

    @property
    def collision_markers(self) -> list[Path]:
        """Returns a list of critical filesystem paths to evaluate for collisions during pre-flight.

        Returns:
            A list of Path objects representing critical configuration files or directories
            managed by this module. Defaults to an empty list.
        """
        return []

    def pre_flight(self) -> None:  # noqa: B027
        """Verifies system prerequisites before manifest building begins.

        Raises:
            RuntimeError: If a critical dependency (e.g., 'uv', 'cargo') is missing.
        """
        pass

    @abc.abstractmethod
    def build(self, manifest: "EnvironmentManifest") -> None:
        """Appends module-specific requirements to the environment manifest.

        Args:
            manifest (EnvironmentManifest): The centralized state object.
        """
        pass

class PresetModule(abc.ABC):
    """Appends module-specific requirements to the environment manifest."""

    cli_flags: ClassVar[tuple[str, ...]] = ()
    """The CLI flags to trigger this preset (e.g., ('-a', '--astro'))."""

    cli_help: ClassVar[str] = ""
    """The help description for the CLI flag."""

    @property
    @abc.abstractmethod
    def name(self) -> str:
        """Returns the human-readable identifier for the preset."""
        pass

    @property
    def config_key(self) -> str:
        """Returns the dictionary key used in config.toml for overrides."""
        return self.__class__.__name__.replace("Preset", "").lower()

    def _apply_overrides(self, manifest: "EnvironmentManifest") -> bool:
        """Applies user-defined overrides from the global configuration if present.

        Returns:
            True if overrides were applied (and defaults should be skipped), False otherwise.
        """
        # Late import to prevent circular dependency at module initialization
        from protostar.config import ProtostarConfig

        config = ProtostarConfig.load()
        overrides = config.presets.get(self.config_key)

        if not isinstance(overrides, dict):
            return False

        logger.debug(f"Applying custom configuration overrides for {self.name} preset.")

        for dep in overrides.get("dependencies", []):
            manifest.add_dependency(dep)

        for dev_dep in overrides.get("dev_dependencies", []):
            manifest.add_dev_dependency(dev_dep)

        for directory in overrides.get("directories", []):
            manifest.add_directory(directory)

        return True

    @property
    def default_dependencies(self) -> list[str]:
        """Returns a list of default packages to inject for this preset."""
        return []

    @property
    def default_directories(self) -> list[str]:
        """Returns a list of default directories to scaffold for this preset."""
        return []

    @property
    def default_ignores(self) -> list[str]:
        """Returns a list of default VCS ignore patterns for this preset."""
        return []

    def build(self, manifest: "EnvironmentManifest") -> None:
        """Appends preset-specific dependencies and directories to the manifest.

        Automatically applies configuration overrides if present. Otherwise, injects
        the default packages, directories, and ignores defined by the preset subclass.

        Args:
            manifest (EnvironmentManifest): The centralized state object.
        """
        logger.debug(f"Building {self.name} preset layer.")

        if self._apply_overrides(manifest):
            return

        for dep in self.default_dependencies:
            manifest.add_dependency(dep)

        for directory in self.default_directories:
            manifest.add_directory(directory)

        for artifact in self.default_ignores:
            manifest.add_vcs_ignore(artifact)