API Reference¶

class ProtostarError(Exception):
    """Base class for all expected operational errors in Protostar."""

    def __init__(
        self,
        message: str,
        *,
        hint: str | None = None,
        docs_path: DocsPage | str | None = None,
        docs_anchor: str | None = None,
    ) -> None:
        super().__init__(message)
        self.hint = hint
        self.docs_path = docs_path
        self.docs_anchor = docs_anchor

    @property
    def docs_url(self) -> str | None:
        """Returns the full URL to the documentation page, or None if not set."""
        path = self.docs_path
        if path is None or path == "":
            path = DocsPage.GETTING_STARTED.value
        elif isinstance(path, DocsPage):
            path = path.value

        base = DOCS_BASE_URL if DOCS_BASE_URL.endswith("/") else f"{DOCS_BASE_URL}/"
        url = urllib.parse.urljoin(base, path.lstrip("/"))
        if self.docs_anchor:
            url = f"{url}#{self.docs_anchor.lstrip('#')}"
        return url

class ConfigurationError(ProtostarError):
    """Raised when a configuration file is malformed, invalid, or missing requirements."""

    def __init__(
        self,
        message: str,
        *,
        hint: str | None = None,
        docs_path: DocsPage | str | None = DocsPage.CONFIGURATION,
    ) -> None:
        super().__init__(message, hint=hint, docs_path=docs_path)

class NetworkFetchError(ProtostarError):
    """Raised when fetching a remote template or archive fails due to network or protocol issues."""

    def __init__(
        self,
        url: str,
        original: Exception | None = None,
        *,
        message: str | None = None,
        hint: str | None = None,
        docs_path: DocsPage | str | None = DocsPage.TEMPLATES,
    ) -> None:
        default_message = (
            f"Network failure: Could not fetch remote configuration from '{url}'."
        )
        default_hint = "Ensure you have an active internet connection and that the URL requires HTTPS, not HTTP."
        super().__init__(
            message or default_message, hint=hint or default_hint, docs_path=docs_path
        )
        self.url = url
        self.original = original

class TemplateResolutionError(ProtostarError):
    """Raised when a template is found but cannot be parsed, extracted, or resolved."""

    def __init__(
        self,
        target: str,
        detail: str,
        *,
        hint: str | None = None,
        docs_path: DocsPage | str | None = DocsPage.AUTHORING_TEMPLATES,
    ) -> None:
        message = f"Failed to resolve template '{target}': {detail}"
        super().__init__(message, hint=hint, docs_path=docs_path)
        self.target = target
        self.detail = detail

class MissingDependencyError(ProtostarError):
    """Raised during pre-flight checks when a system-level executable is absent."""

    def __init__(
        self,
        dependency: GlobalExecutable,
        purpose: str,
        *,
        docs_path: DocsPage | str | None = DocsPage.TROUBLESHOOTING_DEPS,
    ) -> None:
        message = f"Missing dependency: '{dependency.value}' is required for {purpose}."
        super().__init__(message, hint=None, docs_path=docs_path)
        self.dependency = dependency
        self.purpose = purpose

class CommandExecutionError(ProtostarError):
    """Raised when a managed subprocess exits with a non-zero status code."""

    def __init__(
        self,
        command: list[str],
        returncode: int,
        stdout: str = "",
        stderr: str = "",
        *,
        docs_path: DocsPage | str | None = None,
    ) -> None:
        message = f"Protostar failed to execute command: {' '.join(command)}"
        super().__init__(message, docs_path=docs_path)
        self.command = command
        self.returncode = returncode
        self.stdout = stdout
        self.stderr = stderr

    @property
    def output_detail(self) -> str | None:
        """Formats captured stdout/stderr into a display-ready block, or None if empty."""
        blocks = []
        if self.stdout:
            blocks.append(f"--- STDOUT ---\n{self.stdout.strip()}")
        if self.stderr:
            blocks.append(f"--- STDERR ---\n{self.stderr.strip()}")
        return "\n\n".join(blocks) or None

class CommandTimeoutError(ProtostarError):
    """Raised when a managed subprocess exceeds its allocated runtime window."""

    def __init__(
        self,
        command: list[str],
        timeout: int,
        *,
        docs_path: DocsPage | str | None = DocsPage.TEMPLATES,
    ) -> None:
        message = f"Command timed out after {timeout} seconds: {' '.join(command)}"
        hint = "This is often caused by a stalled network request or an unresponsive registry."
        super().__init__(message, hint=hint, docs_path=docs_path)
        self.command = command
        self.timeout = timeout

class FileSystemError(ProtostarError):
    """Raised when a local disk mutation (write, read, mkdir) fails via an OSError or serialization fault."""

    def __init__(
        self,
        operation: str,
        path: str,
        original: Exception,
        *,
        docs_path: DocsPage | str | None = None,
    ) -> None:
        err_msg = getattr(original, "strerror", None) or str(original)
        message = f"Failed to {operation} '{path}': {err_msg}"
        super().__init__(message, docs_path=docs_path)
        self.operation = operation
        self.path = path
        self.original = original

class SecurityViolationError(ProtostarError):
    """Raised when a template attempts an unauthorized system or filesystem operation."""

    def __init__(
        self,
        message: str,
        *,
        hint: str | None = None,
        docs_path: DocsPage | str | None = DocsPage.TROUBLESHOOTING_SECURITY,
    ) -> None:
        super().__init__(message, hint=hint, docs_path=docs_path)

class ExecutionAbortedError(ProtostarError):
    """Raised when the user explicitly aborts the execution via an interactive prompt."""

    def __init__(
        self,
        message: str = "Execution aborted by user.",
        *,
        hint: str | None = None,
        docs_path: DocsPage | str | None = None,
    ) -> None:
        super().__init__(message, hint=hint, docs_path=docs_path)

class PartialExecutionAbortedError(ExecutionAbortedError):
    """Raised when execution is interrupted after disk mutations have begun."""

    def __init__(
        self, touched_paths: frozenset[str], *, docs_path: DocsPage | str | None = None
    ) -> None:
        """Initializes the exception with the frozenset of paths modified before the interrupt.

        Args:
            touched_paths: Immutable set of file and directory paths touched on disk.
            docs_path: Optional path to relevant documentation.
        """
        if touched_paths:
            paths_bulleted = "\n".join(f"- {p}" for p in sorted(touched_paths))
            message = (
                "Execution was interrupted before Protostar could finish setting up the environment.\n\n"
                "The following paths were modified or created before the abort:\n"
                f"{paths_bulleted}\n\n"
                "Note: External commands (e.g., uv, git) may have also modified workspace files."
            )
        else:
            message = (
                "Execution was interrupted before Protostar could finish setting up the environment.\n\n"
                "Note: External commands (e.g., uv, git) may have also modified workspace files."
            )
        hint = "Inspect the modified paths or clean up the workspace before re-running Protostar."
        super().__init__(message, hint=hint, docs_path=docs_path)
        self.touched_paths = touched_paths

class WorkspaceCollisionError(ProtostarError):
    """Raised by plan() when collision markers exist and no force flag was provided.

    Carries a structured set of conflicting paths so callers can programmatically
    present the collision details or decide a resolution strategy without re-scanning
    the filesystem.
    """

    def __init__(self, paths: frozenset[Path]) -> None:
        """Initializes the error with the set of conflicting workspace paths.

        Args:
            paths: The set of existing collision-marker paths detected on disk.
        """
        bulleted = "\n".join(f"  - {p}" for p in sorted(paths))
        message = (
            "Workspace collision detected: existing configuration files found in the workspace:\n"
            f"{bulleted}\n"
            "Use --force-merge or --force-replace to bypass, or resolve interactively."
        )
        super().__init__(message, docs_path=DocsPage.TROUBLESHOOTING_COLLISIONS)
        self.paths = paths

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."""

    required_metadata: ClassVar[tuple[MetadataKey | str, ...]] = ()
    """The metadata keys that MUST be resolved for this module to function."""

    optional_metadata: ClassVar[tuple[MetadataKey | str, ...]] = ()
    """The metadata keys that are nice to have but not strictly required."""

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

    @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