Skip to content

API Reference

Before diving into the raw interface signatures, it is helpful to visualize the architectural boundaries of Protostar.

The engine strictly isolates state definition from imperative execution. Rather than executing disjointed setup scripts, the Orchestrator evaluates a polymorphic array of module objects. These modules—whether core foundational layers (BootstrapModule) or domain-specific macros (PresetModule)—interact exclusively with a centralized state object, the EnvironmentManifest.

Think of the EnvironmentManifest as the nucleus of the scaffolding process. All modules revolve around this singular state object, mutating its properties and injecting AST payloads during their respective build() phases. Because modules never execute their own side-effects, the manifest safely aggregates the net declarative intent before the executor flushes it to disk.

classDiagram
    direction BT

    class EnvironmentManifest {
        +list[str] dependencies
        +set[str] directories
        +dict[str, str] file_injections
        +dict[str, list] file_appends
        +add_dependency(package: str)
        +add_file_append(path: str, content: str)
        +add_system_task(command: list)
    }

    class BootstrapModule {
        <<Abstract>>
        +tuple cli_flags
        +tuple required_languages
        +pre_flight()*
        +build(manifest: EnvironmentManifest)*
    }

    class PresetModule {
        <<Abstract>>
        +list default_dependencies
        +list default_directories
        +list default_ignores
        +build(manifest: EnvironmentManifest)*
    }

    BootstrapModule ..> EnvironmentManifest : Mutates state via build()
    PresetModule ..> EnvironmentManifest : Mutates state via build()

Class Definitions

Core Interface: Define the foundational environment footprint (languages, core tooling). Evaluated during protostar init.

protostar.modules.base.BootstrapModule

Bases: ABC

Appends module-specific requirements to the environment manifest.

Source code in src/protostar/modules/base.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
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

cli_flags class-attribute 

cli_flags = ()

The CLI flags to trigger this module (e.g., ('-p', '--python')).

cli_help class-attribute 

cli_help = ''

The help description for the CLI flag.

config_key class-attribute 

config_key = ''

The global configuration key used to evaluate if this module is active.

name abstractmethod property 

name

Returns the human-readable identifier for the module.

aliases property 

aliases

Returns a list of configuration aliases that map to this module.

Used for dynamic resolution from the global configuration file.

collision_markers property 

collision_markers

Returns a list of critical filesystem paths to evaluate for collisions during pre-flight.

Returns:

Type Description
list[Path]

A list of Path objects representing critical configuration files or directories
list[Path]

managed by this module. Defaults to an empty list.

pre_flight 

pre_flight()

Verifies system prerequisites before manifest building begins.

Raises:

Type Description
RuntimeError

If a critical dependency (e.g., 'uv', 'cargo') is missing.
Source code in src/protostar/modules/base.py 
48
49
50
51
52
53
54
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

build abstractmethod 

build(manifest)

Appends module-specific requirements to the environment manifest.

Parameters:

Name Type Description Default
manifest EnvironmentManifest

The centralized state object.

 required
Source code in src/protostar/modules/base.py 
56
57
58
59
60
61
62
63
@abc.abstractmethod
def build(self, manifest: "EnvironmentManifest") -> None:
    """Appends module-specific requirements to the environment manifest.

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

Domain-Specific Dependencies: PresetModule

Lighter wrappers that inject domain-specific dependencies and directories onto a bootstrap foundation.

protostar.presets.base.PresetModule

Bases: ABC

Appends module-specific requirements to the environment manifest.

Source code in src/protostar/presets/base.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
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)

cli_flags class-attribute 

cli_flags = ()

The CLI flags to trigger this preset (e.g., ('-a', '--astro')).

cli_help class-attribute 

cli_help = ''

The help description for the CLI flag.

name abstractmethod property 

name

Returns the human-readable identifier for the preset.

config_key property 

config_key

Returns the dictionary key used in config.toml for overrides.

default_dependencies property 

default_dependencies

Returns a list of default packages to inject for this preset.

default_directories property 

default_directories

Returns a list of default directories to scaffold for this preset.

default_ignores property 

default_ignores

Returns a list of default VCS ignore patterns for this preset.

build 

build(manifest)

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.

Parameters:

Name Type Description Default
manifest EnvironmentManifest

The centralized state object.

 required
Source code in src/protostar/presets/base.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
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)